• English

      • Getting Started

      Estimated reading time: 3 minutes

      This guide explains how to add maplebirchFramework as a dependency to your Mod and use it.

      Installing the Framework

      1. Download the framework from GitHub Releases (current recommended asset: maplebirch-0.5.9.7-v3.2.5.modpack or the matching .mod.zip)
      2. Install it via ModLoader's Mod manager. Ensure the framework and all its dependencies (ModLoader, ModLoaderGui, BeautySelectorAddon, etc.) are loaded correctly
      Coexisting with “Simple Frameworks”

      The framework declares the alias Simple Frameworks. If players still have the legacy Simple Framework mod installed, maplebirch disables it at startup to avoid conflicts.

      From v3.2.5 onward (on game version >= 0.5.9.7) only two compatibility globals remain: window.simpleFrameworks.addto (mapped to maplebirch.tool.addTo) and the TimeEvent helper class (internally bridged to maplebirch.dynamic.regTimeEvent). Other legacy shortcut globals were removed—new mods should call the maplebirch APIs directly.

      The framework also pins GameVersion to >=0.5.9.7. Mirror both GameVersion and maplebirch constraints in your own boot.json (prefer >=3.2.5).

      The framework itself is not encrypted. Package your mod as .modpack with dol-mod-protection-tools—see Mod protection & credentials.

      Declaring Dependencies

      Declare the version constraint for maplebirch in your Mod's boot.json through dependenceInfo:

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

      ModLoader will check the version constraint when loading; if it is not satisfied, the Mod will not be loaded.

      Registering with the Framework

      Register your Mod with maplebirch's AddonPlugin system via the addonPlugin field in boot.json:

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

      The following configuration options are supported in params:

      ParameterTypeDescription
      modulestring[]JS files executed immediately after inject_early completes; not recommended unless necessary
      scriptstring[]JS files executed after AddonPlugin processing completes (recommended)
      languageboolean | string[] | objectLanguage file configuration; see AddonPlugin System for details
      audioboolean | string[]Audio file configuration
      npcobjectNPC configuration (named NPCs, sidebar, clothing, etc.)
      frameworkobject | object[]Framework-level configuration (traits, region parts, etc.)

      Minimal Example

      The following is a complete boot.json example that depends on maplebirch:

      {
  "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 means all language files under the translations/ directory are imported automatically. Place your translation files in the following structure:

      MyFirstMod
      boot.json
      mymod.js
      translations
      cn.json
      en.json

      Difference Between module and script

      • module — Files are executed immediately after the inject_early phase completes. The framework itself may not be fully initialized at this point. Use for scenarios that require very early module registration
      • script — Files are executed after all Mods have registered with AddonPlugin. The framework is fully initialized at this point. Recommended for most use cases

      Verifying Framework Load

      Check whether the framework is available in your script:

      if (window.maplebirch) {
  console.log("maplebirch framework version:", window.maplebirch.meta.version);
  // Framework is ready, you can use its API
} else {
  console.error("maplebirch framework not loaded");
}

      Next Steps