#Framework Overview

Estimated reading time: 5 minutes

maplebirchFramework (package name: maplebirch, Chinese name: 秋枫白桦框架) is a modular mod development framework designed for Degrees of Lewdity (DOL) based on Sugarcube2 ModLoader. It provides a structured middle layer between ModLoader and individual mods, offering mod developers lifecycle management, shared services, and reusable tools.

#Niche

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

The framework is distributed as .mod.zip and loaded by ModLoader at startup. The entry point is compiled to dist/inject_early.js and injected via the scriptFileList_inject_early mechanism. At runtime, it exposes the global instance window.maplebirch, a singleton of the MaplebirchCore class.

#Runtime Dependencies

The framework declares the following hard dependencies, all of which must be loaded before maplebirch:

#Core Capabilities

The framework provides the following core modules:

• AddonPlugin System — Integrated with ModLoader lifecycle, handles automatic loading of scripts, NPCs, audio, and framework configuration
• Variable Management — Unified V.maplebirch namespace with default values and version migration support
• Character Rendering — body / head / face / clothing layer system, hair color gradients, mask generation
• Named NPCs — NPC registration and data management, sidebar model rendering, clothing system, scheduling
• Combat System — Combat actions, reactions, voice registration, combat button generation
• Dynamic Events — Time, state, weather event management and time travel
• Audio Management — Howler.js-based audio playback, playlist management
• Tool Collection — Console, random system, macros, HTML utilities, region management and other practical tools
• GUI Control — AngularJS settings UI, module enable/disable control
• Internationalization — Multi-language support (EN/CN), automatic translation file import
• Event Bus — on / off / once / after / trigger event system
• Persistent Storage — IndexedDB settings persistence
• Logging System — Leveled logging (DEBUG / INFO / WARN / ERROR)

#Global Access Paths

All features are accessed through the window.maplebirch singleton:

The following convenience properties are also exposed:

#Modules & Features

• Utilities — Core services: logging, events, language (includes maplebirch.tool.utils)
• Event Emitter — Event publish/subscribe system
• Language Manager — Internationalization and translation
• Module System — Module registration and lifecycle API
• SugarCube Macros — Multi-language and stat/grace macros
• Combat System (Combat) — Combat actions, reactions, speech, buttons
• Dynamic Events (Dynamic Events)
  • State Events
  • Time Events
  • Weather Events
• Tool Collection (Tool Collection)
  • Utilities
  • Variable Migration
  • Random System
  • HTML Tools
  • Zones Manager
  • Traits Registration
  • Location Config
  • Bodywriting

#Feature highlights

• Numeric clamping — number() utility for range, rounding, step, and percent (Utilities)
• Mask rotation — Character and NPC sidebar masks support rotation angle (mask and options)
• Combat multi-slot — Combat buttons can use an array of actionType to show in multiple slots (Combat)
• Zone injection — Use keys such as MobileStats to inject into mobile stats and other areas (Zones Manager)
• Stat and grace display — Macros such as statChange and grace for numeric output (SugarCube macros)
• Pronouns with ModI18N — When used with ModI18N, the framework corrects pronoun (his/hers) display for vanilla NPCs (Named NPC)

#Next Steps

• Getting Started — How to add framework dependency to your Mod and use it
• Core Architecture — Deep dive into MaplebirchCore and module system
• AddonPlugin System — Lifecycle hooks and configuration loading in detail