Mod types
The "type" field in mod.json determines which backend Petrichor uses to load your mod. Each backend knows how to initialize and execute a specific kind of mod artifact.
luau, Luau scripting#
Backend for scripted mods. One shared Luau VM runs every luau mod. Your entry file runs once and must return a class from mod(). Petrichor calls new(), tick(delta), and shutdown() on the instance.
Use for Luau or TypeScript (compiled with ts-luau).
All mods share a single Lua state across the lifetime of the process. This means:
- Globals you set are visible to other mods (avoid polluting
_G). require()calls are cached, and each module loads once.- Hook registrations in one mod's entry point are permanent for the session.
The built-in require resolver understands the following module names:
| Module | Description |
|---|---|
| (globals from Petrichor.Standard) | newclass(), mod(), log(), Levels, see Petrichor.Standard |
"Petrichor.Mod" | Base for mod(), see Script entry point |
"Petrichor.Events" | In-memory pub/sub between mods (see Petrichor.Events) |
"Augment.Hook" | High-level hook builder (see Augment.Hook) |
"Augment.Mixin" | Low-level symbol/memory API (see Augment.Mixin) |
"Petrichor.Log" | Structured logging (see Petrichor.Log) |
"Petrichor.Task" | Cooperative async/await scheduler (see Petrichor.Task) |
"Petrichor.Timer" | Wall-clock and frame timers (see Petrichor.Timer) |
"Petrichor.Net" | TCP and UDP networking (see Petrichor.Net) |
"Petrichor.Json" | JSON encode/decode, preloaded (see Petrichor.Json) |
"Petrichor.Random" | PRNG helpers (see Petrichor.Random) |
"Petrichor.Hash" | MD5 / SHA-256 (see Petrichor.Hash) |
"Petrichor.Bits" | 6-bit bit packing (see Petrichor.Bits) |
"Petrichor.Storage" | Per-mod key/value store under mod_saves/ (see Petrichor.Storage) |
"Petrichor.Math" | Vector/matrix math helpers (see Petrichor.Math) |
"Courage.Shaders" | Register and toggle custom HLSL shaders (see Courage.Shaders) |
"Courage.Assets" | Resolve assets/ paths to logical shader names (see Courage.Assets) |
"Courage.Game" | Namespace: shaders, assets, world, player (see Courage.Game) |
"Courage.World" | Stage name and warp (alias of Courage.Game.world) |
"Courage.Player" | Player stats and position |
"Courage.Save" | Save data and items (see Courage.Save) |
"Courage.Hooks" | Reusable hook recipes (see Courage.Hooks) |
"Courage.Bmg" | Runtime message text overrides (see Courage.Bmg) |
"Courage.Settings" | Settings schema helpers (see Courage.Settings) |
"Courage.Config" | Read-only game configuration (see Courage.Config) |
"Courage.Timer" | Frame-based timers (see Courage.Timer) |
"Courage.Audio" | Audio file playback (see Courage.Audio) |
"Courage.UI" | CReact panels and popups (see CReact guides, Courage.UI) |
"Courage.Layout" | BLO screens rasterized to CReact assets (see Courage.Layout) |
"Augment.Class" | Actor subclassing in Luau (see Augment.Class) |
Entry scripts are documented in Script entry point.
Any other module name is resolved as a file path relative to the active mod directory, with . replaced by / and .luau appended.