ModLoader
SugarCube-2 Mod Loading Framework

Mod loading and management framework designed for the SugarCube2 interactive fiction engine

📦

Multi-Source Mod Loading

Load Mods from four sources—HTML-embedded, remote servers, localStorage, and IndexedDB. Later-loaded Mods with the same name automatically override earlier ones.

⚡

Four-Stage Script Loading

Four script loading stages—inject_early, earlyload, preload, and scriptFileList—let Mod authors precisely control game data at different moments.

🔀

Passage / Style / Script Merging

Mod's tweeFileList, styleFileList, and scriptFileList are merged into the tw-storydata node before SugarCube2 reads the data.

🔗

Inter-Mod Communication

Via the AddonPlugin system and ModInfo.modRef mechanism, Mods can expose APIs to each other and interact.

✅

Dependency Checking

Mods can declare dependencies on other Mods, ModLoader version, and game version in boot.json; they are validated automatically during load.

🛡️

Safe Mode

After three consecutive load failures, safe mode is entered automatically, disabling all Mods for recovery and preventing broken Mods from blocking game startup.