You need CMake 3.20+, Ninja, a C compiler (clang on Windows, gcc or clang on Linux, Xcode's clang on a Mac), Python 3.11+ for packing, and a game with Modtopia installed to try it in.
1. Start from the template
Copy the mod template (the Modtopia kit's mdk folder) to a folder of your own, or make a repository from it. In mod.toml, change:
id: unique, and never changed once published;name,authors,description;affects:"visual"if it changes nothing other players would notice,"gameplay"otherwise.
2. Build it
cmake --preset windows-x64 # linux-x64, macos-arm64
cmake --build --preset windows-x64
The template fetches the SDK, which is headers only. build/windows-x64/stage is now an unpacked mod: mod.toml, bin/windows-x64/mod.dll
and your assets/.
3. Try it
Copy the stage folder into your game's mods folder under your mod's name (mods/my_first_mod/) and start the game from its launcher. The
game's log shows:
[modtopia] on my_first_mod 0.1.0 [code]
[modtopia] my_first_mod 0.1.0 started
[my_first_mod] loaded on Pokopia Native, game 2.0.1
[my_first_mod] hello at frame 600
F1 > Mods lists it, with its settings. The launcher asks before it runs new or changed code: that's the player's safety net, and it asks you too.
4. Do something
- Events:
host->subscribe(mod, "AreaEntered", MT_PRIORITY_NORMAL, fn, user). The hello-events example uses them all. - Settings: declare them in
mod.toml, read them withhost->config_number,config_bool,config_string, and hear changes withhost->on_config_changed. - Game memory:
host->mem_read(addr, &v, sizeof v). Find addresses by name withhost->resolve(mod, "GameMgr"). - Hooks: declare the point in
mod.toml, thenhost->hook(mod, "my_point", handler, user). The handler reads and writes registers withreg_get/reg_set, and returnsMT_CONTINUE, orMT_HANDLEDto return from the game function. - Files: put your own files in
assets/, at the path the game has them.
Finding a hook point means reading the game's code in your own dump. Prefer mapped names: they keep your manifest readable and are checked by the community.
5. Publish
cmake --build build/windows-x64 --target package_mod packs my_first_mod-0.1.0.pkmod and prints its checksum. The template's workflow builds
Windows, Linux and macOS into one .pkmod. Put it on GitHub as a release, with its sha256 in the notes, then
send us the link to be listed here. We take the file from your release ourselves: nothing is uploaded to us.
Good to know
- Threads: hooks run on the game's threads, sometimes several at once. Keep handlers short and use atomics for counters.
- Hook points: adding or changing them makes the player's launcher update the game before its next start (a minute or two). Changing only your code doesn't.
- Several game versions: give each its own set of hooks with the same point names. The code stays the same.
- No raw pointers into the game: always go through
mem_read/mem_write. - The legal line: ship your own work only, never the game's files, its code or its DLC, and nothing that unlocks paid content.