#框架概述

Estimated reading time: 7 minutes

maplebirchFramework（包名：maplebirch，中文名：秋枫白桦框架）是基于 Sugarcube2 ModLoader 为 Degrees of Lewdity (DOL) 设计的模块化模组开发框架。它在 ModLoader 和具体模组之间提供了一层结构化的中间层，为模组开发者提供生命周期管理、共享服务和可复用工具。

#生态位

ELK not loaded. Ensure /elk.bundled.js is loaded before the app.

框架以 .mod.zip 形式分发，由 ModLoader 在启动时加载。入口编译为 dist/inject_early.js，通过 scriptFileList_inject_early 机制注入。运行时暴露全局实例 window.maplebirch，即 MaplebirchCore 类的单例。

#运行时依赖

框架声明了以下硬依赖，全部需在 maplebirch 之前加载：

#核心能力

框架提供以下核心功能模块：

• AddonPlugin 系统 — 与 ModLoader 生命周期集成，处理脚本、NPC、音频、框架配置的自动加载
• 变量管理 — 统一的 V.maplebirch 命名空间，支持默认值与版本迁移
• 角色渲染 — body / head / face / clothing 图层系统，发色渐变、遮罩生成
• 命名 NPC — NPC 注册与数据管理、侧边栏模型渲染、服装系统、日程安排
• 战斗系统 — 战斗动作、反应、语音注册，战斗按钮生成
• 动态事件 — 时间、状态、天气事件管理与时间旅行
• 音频管理 — 基于 Howler.js 的音频播放、播放列表管理
• 工具集合 — 控制台、随机系统、宏定义、HTML 工具、区域管理等实用工具
• GUI 控制 — AngularJS 设置 UI、模块启用/禁用控制
• 国际化 — 多语言支持（EN/CN），翻译文件自动导入
• 事件总线 — on / off / once / after / trigger 事件系统
• 持久化存储 — IndexedDB 设置持久化
• 日志系统 — 分级日志（DEBUG / INFO / WARN / ERROR）

#全局访问路径

所有功能均通过 window.maplebirch 单例访问：

此外还暴露了以下便捷属性：

#模块与功能

• 工具函数 — 日志、事件与语言等核心服务（含 maplebirch.tool.utils）
• 事件发射器 — 事件发布/订阅系统
• 语言管理 — 国际化与翻译
• 模块系统 — 模块注册与生命周期 API
• SugarCube 宏 — 多语言宏扩展
• 音频管理 — 背景音乐、音效与播放列表
• 角色管理（侧边栏图层、转化管理）
• NPC 管理（NPC 注册、NPC 状态、NPC 日程、NPC 服装、NPC 侧边栏）
• 战斗管理（战斗按钮、战斗反应、战斗语音）
• 动态事件（动态事件）
  • 状态事件
  • 时间事件
  • 天气事件
• 工具合集（工具集合）
  • 工具函数
  • 变量迁移
  • 随机数系统
  • 文本工具
  • 区域管理
  • 特质注册
  • 地点配置
  • 纹身注册

#功能要点

• 数值修整 — number() 工具函数，支持范围、取整、步进、百分比（工具函数）
• 遮罩旋转 — 角色与 NPC 侧边栏遮罩支持角度旋转（mask 的 rotation 与选项配置）
• 战斗多部位 — 战斗按钮可指定多个 actionType，一次注册在多个部位显示（战斗按钮）
• 区域注入 — 使用 MobileStats 等键向移动端状态等区域注入内容（区域管理）
• 属性与恩惠显示 — macro 提供 statChange、grace 等数值片段输出（SugarCube 宏）
• 代词与 ModI18N — 与 ModI18N 同用时，原版 NPC 的性别代词（his/hers）由框架统一修正（NPC 注册）

#下一步

• 快速开始 — 如何让你的 Mod 依赖并使用框架
• 核心架构 — 深入了解 MaplebirchCore 与模块系统
• AddonPlugin 系统 — 生命周期钩子与配置加载详解