中文 | English

SCML-DOL-maplebirchFramework

maplebirchFramework is a SugarCube2 ModLoader framework for Degrees of Lewdity mods. It provides helper APIs for script loading, language and audio import, UI zone injection, NPC registration, combat actions, character layers, transformations, dynamic events, and general utility functions.

The framework is designed around additive mod development: instead of directly replacing large parts of vanilla passages or widgets, a mod can register content through stable framework APIs and let the framework merge it at the appropriate loading stage.

Contents

• Overview
• Installation
• Script Loading
• Mod Encryption
• Recommended Structure
• Type Package
• Documentation
• boot.json Quick Reference
• Links

Overview

Use this framework when your mod needs to:

• Load framework-dependent JavaScript files through boot.json.
• Import translation files and audio folders.
• Add widgets to existing UI zones such as options, status bar, menus, and link areas.
• Register SugarCube macros or reusable text builders.
• Register time, state, and weather events.
• Add named NPCs, NPC stats, schedules, clothes, sidebar displays, NPC transformations, and NPC pregnancy extensions.
• Add character layers, face styles, and transformations.
• Add custom combat actions.
• Use shared helpers such as source.clone(), Object.merge(), list.contains(), list.either(), and Math.clamp().

English documentation is organized under docs/EN and mirrors the Chinese documentation structure.

Installation

Download the framework from Releases and load it as a ModLoader mod.

Mods depending on this framework should declare the dependency:

"dependenceInfo": [
  {
    "modName": "maplebirch",
    "version": ">=required framework version"
  }
]

Script Loading

Use maplebirchAddon to load JavaScript files that depend on the framework:

"addonPlugin": [
  {
    "modName": "maplebirch",
    "addonName": "maplebirchAddon",
    "modVersion": "^required framework version",
    "params": {
      "script": ["framework.js"]
    }
  }
]

Most mod logic should use script. Use module only when you intentionally need an earlier module-extension stage.

Mod Encryption

The framework itself is not encrypted. Other mods that depend on the framework can use the companion author tools to build an encrypted shell .modpack. The shell asks the framework to verify a credential during earlyload, decrypts the real mod, then injects it through ModLoader lazy loading.

Author tools: DOL Mod Protection Tools

The generated .modpack only exposes a shell boot.json, an earlyload decryptor, and .crypt chunks. The original boot.json, auth.json, scripts, and assets are stored inside the encrypted payload. On first load, the player enters a credential; after successful verification, the password is cached. Closing the dialog or failing verification disables that encrypted mod.

auth.json is generated by the author tools or placed in the original zip root before conversion. It is not left in the shell package as plaintext. Minimal example:

{
  "key": "main",
  "publicKey": "BASE64_SPKI_PUBLIC_KEY"
}

Optional fields include subject, name, prompt, and date. See the companion author tools README for the full configuration.

Recommended Structure

For a small mod:

framework.js

For a larger mod:

framework.js
modules/options.js
modules/events.js
modules/npc.js
modules/combat.js
modules/sidebar.js

Example:

maplebirch.tool.addTo('Options', 'MyModOptions');

maplebirch.dynamic.regTimeEvent('onDay', 'myMod.dailyCheck', {
  cond: () => V.myMod?.enabled,
  event: () => '<<run setup.myMod.dailyCheck()>>'
});

maplebirch.npc.addStats({
  trust: {
    min: 0,
    max: 100,
    default: 0,
    position: 1
  }
});

Type Package

If your mod uses TypeScript, or if you want editor completion for the global maplebirch APIs, install the framework type package:

npm install -D @scml-maplebirch/types

Then add it to tsconfig.json:

{
  "compilerOptions": {
    "types": ["@types/twine-sugarcube", "@scml-maplebirch/types"],
    "skipLibCheck": true
  }
}

This package only provides TypeScript declarations. It does not include runtime framework code, so players still need to load the actual maplebirchFramework mod through ModLoader. Keep the type package version close to the framework version your mod depends on.

Documentation

Start here:

• English documentation index
• boot.json configuration
• Utilities
• Event emitter
• Language manager
• SugarCube macros
• Audio manager
• Module system

Feature areas:

• Dynamic events
• State events
• Weather events
• Zone manager
• Random system
• Data migration
• Text builder
• Traits
• Location config
• Bodywriting
• Foodstuff
• Antiques
• Character layers
• Transformation system
• Named NPC
• NPC stats
• NPC schedule
• NPC clothes
• NPC sidebar
• NPC transformation
• NPC pregnancy
• Combat actions
• Cloud save services

Complete Chinese docs:

• 中文文档目录

boot.json Quick Reference

"addonPlugin": [
  {
    "modName": "maplebirch",
    "addonName": "maplebirchAddon",
    "modVersion": "^required framework version",
    "params": {
      "language": ["CN", "EN"],
      "audio": ["audio"],
      "framework": {
        "addto": "Options",
        "widget": "MyModOptions"
      },
      "npc": {
        "NamedNPC": [],
        "Stats": {},
        "Sidebar": {
          "image": [],
          "clothes": [],
          "config": []
        }
      },
      "script": ["framework.js"]
    }
  }
]

Links

• Game Author $\color{purple} {Vrelnir}$
• Vrelnir's blog
• English game wiki
• Chinese game wiki
• Degrees of Lewdity source
• ModLoader documentation
• Chinese localization repository