Mods sample¶
Samples/Mods is a small game made only of packages, with mods that change its data and run scripts, shown by two panels. It is also what CI
runs end to end: the package loader, definitions with schemas and patches, the sandbox, packs, and a rendered image.
Apogee.Runtime --game Samples/Mods/game --user /tmp/mods-user # a window with the panels
Apogee.Runtime --game Samples/Mods/game --user /tmp/mods-user --watch # and edit while it runs (see Hot reload)
game/ is the game's folder (res://): packages/base_game is its one base package, and dev_mods/ holds the mods of a development build (a player's mods go in user://mods, the same
layout). --user is where user:// is; mods may write only user://moddata/<their id>/.
| Package | Shows |
|---|---|
base_game |
a schema for Crate (an enumeration, a default, a repeated Tag, a map of prices), two crates, a module (lib/util.luau) and a script with the two panels |
bigger_crates |
a dependency on base_game (^1.0) and gameVersion; a patch of the wooden crate (weight, size, and <Tag append="true">) and a new crate (gold); require("@base_game/lib/util"); writing its own data folder |
broken_mod |
a script with a bug: the error is logged with its file and line, the package is marked failed, and the game goes on |
needs_ghost |
a dependency on a mod that is not there: it does not load, and packages.list() says why |
The Packages panel is packages.list(): which packages loaded, in load order, and for those that did not, why. The Crates panel is defs.all("Crate") after every package's content was
merged: the wooden crate is 20 kg and large with three tags (the base game's two and the mod's), and the gold crate is the mod's. Delete bigger_crates and run again, and the panel shows the base game's
numbers: nothing else changes.
Things to try¶
--watch, then changeweightindev_mods/bigger_crates/data/crates.xml, or a line inlib/util.luau: the panel changes without a restart.- Misspell an attribute in
crates.xml: the schema reports it (defs.problems(), and the log) with the file and line, and the crate is still there. - Make
needs_ghostload by adding aghost_modpackage next to it; makebigger_cratesstop loading with<Dependency id="base_game" version=">=2.0"/>.
Tests¶
Samples/Mods/tests/util.test.luau: the module's functions, with--luau-test(run by hand).- Nothing in CI runs this sample. What it shows is tested on a fixture game of its own:
Tests/Fixtures/ShippedGame(a package, a mod, a UI document with a script and a data model, and an ImGui panel) runs headless, from a pack and rendered on lavapipe in CI, andTests/Apogee.Runtime.TestsandTests/Apogee.Mods.Testscover the loading, patching, dependency and failure rules.