#ModuleSystem API

#Overview

ModuleSystem handles module registration, dependency ordering, and lifecycle scheduling. Most content mods should not register framework modules—use addonPlugin script entries instead. Only use maplebirch.register when you intentionally extend internal framework capabilities.

For architecture and boot flow see Core Architecture.

#Registering modules

#register(name, module, dependencies?)

Registers a module (delegates to ModuleSystem.register).

• @return boolean — true on success; false if the name already exists.

Extension modules get a source (owning mod name) recorded automatically when AddonPlugin loads your module scripts—no fourth source argument or runWithSource wrapper required.

maplebirch.register("myModule", {
  Init() {
    console.log("initialized");
  },
});

maplebirch.register(
  "myModule2",
  {
    dependencies: ["tool"],
    Init() {
      console.log("depends on tool and npc");
    },
  },
  ["npc"],
);

#get(name)

Returns a registered module instance.

const npcModule = maplebirch.get("npc");

#dependencyGraph

Dependency metadata per module:

const graph = maplebirch.dependencyGraph;
console.log(graph.npc);

#Exposed modules (EXPOSED)

Set exposed: true on the module object. After registration the state is EXPOSED and the object is mounted at maplebirch[name].

maplebirch.register("myApi", {
  exposed: true,
  hello() {
    return "Hello";
  },
});

maplebirch.myApi.hello();

#Module states

Pre-init completion is tracked separately in an internal preInitialized set; modules move to MOUNTED after main init.

#Lifecycle methods

class MyModule {
  dependencies = ["tool"];

  async preInit() {
    this.cache = new Map();
  }

  async Init() {
    this.setup();
  }

  async loadInit() {
    this.restoreFromSave();
  }

  async postInit() {
    this.refreshPassageState();
  }

  setup() {}
  restoreFromSave() {}
  refreshPassageState() {}
}

maplebirch.register("myModule", new MyModule(), ["npc"]);

#Dependency rules

1. A module initializes only after all dependencies are satisfied (transitive closure applies).
2. EXPOSED modules count as satisfied dependencies.
3. If a dependency is ERROR or DISABLED, dependents do not initialize.
4. Circular dependencies are detected at registration time.

#Notes

1. Prefer script over framework module registration for content mods (v3.2.5 simplified registration—see changelog).
2. Use mod-prefixed names to avoid clashes with built-ins or other mods.
3. A failed module does not block others.
4. Protected modules (protected) cannot be disabled from the UI; extension modules remain toggleable when source is tracked by the framework.