Pokopia Native

Modtopia

Make your first mod

From the template to a mod in your game in an evening: build it, try it, publish it.

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 with host->config_number, config_bool, config_string, and hear changes with host->on_config_changed.
  • Game memory: host->mem_read(addr, &v, sizeof v). Find addresses by name with host->resolve(mod, "GameMgr").
  • Hooks: declare the point in mod.toml, then host->hook(mod, "my_point", handler, user). The handler reads and writes registers with reg_get / reg_set, and returns MT_CONTINUE, or MT_HANDLED to 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.