#Getting Started

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

#Installing the Framework

1. Download the framework .mod.zip file from GitHub Releases
2. Install it via ModLoader's Mod manager. Ensure the framework and all its dependencies (ModLoader, ModLoaderGui, BeautySelectorAddon, etc.) are loaded correctly

#Declaring Dependencies

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

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

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.1.0",
      "params": {
        "script": ["mymod_framework.js"]
      }
    }
  ]
}

The following configuration options are supported in params:

#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": "maplebirch",
      "version": ">=3.0.0"
    }
  ],
  "addonPlugin": [
    {
      "modName": "maplebirch",
      "addonName": "maplebirchAddon",
      "modVersion": "^3.1.0",
      "params": {
        "script": ["mymod.js"],
        "language": true
      }
    }
  ]
}

#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

• Core Architecture — Deep dive into MaplebirchCore and module system
• AddonPlugin System — Detailed usage of each params configuration option
• Variables and Game State — Managing the V.maplebirch namespace