快速开始

Estimated reading time: 4 minutes

本文介绍如何让你的 Mod 依赖并使用 maplebirchFramework。

安装框架

从 GitHub Releases 下载框架资产（当前推荐 maplebirch-0.5.9.7-v3.2.5.modpack 或同版本的 .mod.zip）
通过 ModLoader 的 Mod 管理器上传安装，确保框架及其所有依赖（ModLoader、ModLoaderGui、BeautySelectorAddon 等）均已正确加载

与「简易框架」(Simple Frameworks) 共存

框架在 package.json 中声明别名为 Simple Frameworks。若玩家仍安装旧版简易框架，maplebirch 会在启动时自动禁用该 Mod 以避免冲突。

自 v3.2.5 起（在 游戏版本 >= 0.5.9.7 下），为降低维护成本，仅保留与旧版兼容所必需的全局入口：window.simpleFrameworks.addto（映射到 maplebirch.tool.addTo）以及 TimeEvent 类（内部桥接到 maplebirch.dynamic.regTimeEvent）。其余旧版全局快捷方法已移除，新 Mod 请直接使用 maplebirch 命名空间 API。

此外，框架将 GameVersion 硬依赖提升至 >=0.5.9.7，请在自身 boot.json 中同步声明对 GameVersion 与 maplebirch 的版本约束（建议 >=3.2.5）。

若你的 Mod 需要内容保护，框架本体不加密；请使用 dol-mod-protection-tools 生成 .modpack，详见模组保护与凭证。

声明依赖

在你的 Mod 的 boot.json 中通过 dependenceInfo 声明对 maplebirch 的版本约束：

{
  "name": "MyMod",
  "version": "1.0.0",
  "dependenceInfo": [
    {
      "modName": "GameVersion",
      "version": ">=0.5.9.7"
    },
    {
      "modName": "maplebirch",
      "version": ">=3.2.5"
    }
  ]
}

ModLoader 会在加载时检查版本约束，如果未满足则阻止 Mod 加载。

注册到框架

通过 boot.json 的 addonPlugin 字段将你的 Mod 注册到 maplebirch 的 AddonPlugin 系统：

{
  "addonPlugin": [
    {
      "modName": "maplebirch",
      "addonName": "maplebirchAddon",
      "modVersion": "^3.2.0",
      "params": {
        "script": ["mymod_framework.js"]
      }
    }
  ]
}

params 中支持以下配置项：

参数	类型	说明
`module`	`string[]`	在 `inject_early` 完成后立即执行的 JS 文件，非必要不推荐使用
`script`	`string[]`	在 AddonPlugin 处理完成后执行的 JS 文件（推荐）
`language`	`boolean \| string[] \| object`	语言文件配置，详见 AddonPlugin 系统
`audio`	`boolean \| string[]`	音频文件配置
`npc`	`object`	NPC 配置（命名 NPC、侧边栏、服装等）
`framework`	`object \| object[]`	框架级配置（特质、区域部件等）

最小示例

以下是一个依赖 maplebirch 的完整 boot.json 示例：

{
  "name": "MyFirstMod",
  "version": "1.0.0",
  "scriptFileList": [],
  "styleFileList": [],
  "tweeFileList": [],
  "imgFileList": [],
  "additionFile": ["readme.txt"],
  "dependenceInfo": [
    {
      "modName": "GameVersion",
      "version": ">=0.5.9.7"
    },
    {
      "modName": "maplebirch",
      "version": ">=3.2.5"
    }
  ],
  "addonPlugin": [
    {
      "modName": "maplebirch",
      "addonName": "maplebirchAddon",
      "modVersion": "^3.2.0",
      "params": {
        "script": ["mymod.js"],
        "language": true
      }
    }
  ]
}

Info

language: true 表示自动导入 translations/ 目录下的所有语言文件。你需要按如下结构放置翻译文件：

MyFirstMod

boot.json

mymod.js

translations

cn.json

en.json

`module` 与 `script` 的区别

module 中的文件在 inject_early 阶段完成后立即执行，此时框架本身可能还未完全初始化，适用于需要在极早期注册模块的场景
script 中的文件在所有 Mod 注册到 AddonPlugin 之后执行，此时框架已完成初始化，推荐绝大多数场景使用

验证框架加载

在你的脚本中检查框架是否可用：

if (window.maplebirch) {
  console.log("maplebirch 框架版本:", window.maplebirch.meta.version);
  // 框架已就绪，可以使用其 API
} else {
  console.error("maplebirch 框架未加载");
}

下一步

版本历史 — v3.2.5 及更早版本变更摘要
核心架构 — 深入了解 MaplebirchCore 与模块系统
AddonPlugin 系统 — 了解 params 各配置项的详细用法
变量与游戏状态 — 管理 V.maplebirch 命名空间

#快速开始

#安装框架

#声明依赖

#注册到框架

#最小示例

#module 与 script 的区别

#验证框架加载

#下一步