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.