Rustic Engine supports Psych Engine-compatible mods out of the box. If you have a mod that runs in Psych Engine, the same assets, charts, character files, stage files, and Lua scripts are the target format for Rustic Engine mods.Documentation Index
Fetch the complete documentation index at: https://mintlify.com/Quiet-Wolfe/Rustic-Engine/llms.txt
Use this file to discover all available pages before exploring further.
How mod loading works
Rustic Engine uses a priority-ordered search path to resolve assets. When the engine needs a file, it walks through a list of search roots and returns the first match it finds. Your mod directory is inserted at the front of that list, so any file in your mod automatically overrides the corresponding base game file.The engine does not merge JSON files — whichever file is found first wins entirely. If you want to change one field in a character JSON, you must supply the complete character JSON in your mod.
What a mod can contain
| Component | Description |
|---|---|
| Charts | Psych Engine JSON chart files defining notes, events, and song metadata |
| Characters | JSON files mapping animation prefixes to atlas frames, with offsets and camera data |
| Stages | JSON files defining background/foreground sprite layers, character positions, and zoom |
| Lua scripts | Song scripts and stage scripts exposing the Psych Engine Lua API |
| Images | PNG spritesheets with matching Sparrow XML atlases |
| Sounds & music | OGG audio files for song instrumentals, vocals, and sound effects |
Development phases
Modding support is Phase 5 in the development roadmap. The phases build on each other and must be completed in order:| Phase | Focus |
|---|---|
| Phase 1 | Core + Rendering Foundation — chart parsing, asset loading, atlas rendering, camera |
| Phase 2 | Gameplay + Audio + HUD — notes, input, scoring, audio sync, countdown |
| Phase 3 | Characters & Stage — animated sprites, stage backgrounds, camera follow |
| Phase 4 | Menus — title, main menu, freeplay, story mode |
| Phase 5 | Mods + Lua + Modcharts — mod directory loading, Lua VM, custom events, modcharts |
The integration test target
The VS Retrospecter Part 2 mod is used as the ultimate integration test for modding support. It exercises custom events, modcharts, and complex Lua scripts. When this mod runs correctly, Phase 5 is complete.Explore the modding guides
Mod structure
Directory layout, asset placement, and how the engine discovers mod files.
Asset formats
Sparrow XML atlases, Psych Engine chart JSON, character files, and stage files.
Custom events
Define and handle chart events in Lua, including the Wildcard event type.