Check, pack and publish
oa-tool mutator check and pack, a dry run, what the catalogue page shows, the icon, and how to offer the package to Core Prime.
This chapter summarises docs/mutators/authoring.md and docs/mutators/oamut-standard.md.
Check the .oamut
A mutator is packed and checked with oa-tool mutator pack and oa-tool mutator check. oa-tool pack and oa-tool check are the commands for a .oamap or a .oamod. check reads a .oamut, not a folder. It compiles the Lua and parses each .sm, and it does not run them. The last line is result: ok or result: refused.
$ oa-tool mutator pack commander-radar
$ oa-tool mutator check commander-radar-1.oamut
A refusal names the file and the line. Fix it before you offer the package. Commander Radar's packed name is commander-radar-1.oamut, and that check ends with result: ok.
Pack from outside the folder
Run pack with the folder's name, from outside it. Left alone, it writes <id>-<version>.oamut in the current folder. --out must name a .oamut: any other ending is refused. --force replaces a file that is already there. Do not pack . from inside the folder, and do not leave the .oamut inside it: a package may not hold that file. --game-dir is a usage error on this command.
The dry run
oa-tool mutator diff runs a package folder through the game's mutation pipeline on a game folder, and lists what changed. Options follow the last colon, as in strength=lite on uber-comm. A maps hook runs only with --map NAME. On 3.1c with no mod, the report's lines after its # header are these:
$ oa-tool mutator diff --game-dir DIR --mutator ./uber-comm:strength=lite
field units/armcom.fbi [unitinfo] acceleration: 0.15 -> 0.3375 by uber-comm
field units/armcom.fbi [unitinfo] brakerate: 0.3 -> 0.675 by uber-comm
field units/armcom.fbi [unitinfo] builddistance: 60 -> 120 by uber-comm
field units/armcom.fbi [unitinfo] maxdamage: 3000 -> 4500 by uber-comm
field units/armcom.fbi [unitinfo] maxvelocity: 1.2 -> 1.8 by uber-comm
field units/armcom.fbi [unitinfo] turnrate: 1044 -> 1566 by uber-comm
field units/armcom.fbi [unitinfo] workertime: 300 -> 900 by uber-comm
field units/corcom.fbi [unitinfo] acceleration: 0.16 -> 0.36 by uber-comm
field units/corcom.fbi [unitinfo] brakerate: 0.32 -> 0.72 by uber-comm
field units/corcom.fbi [unitinfo] builddistance: 60 -> 120 by uber-comm
field units/corcom.fbi [unitinfo] maxdamage: 3000 -> 4500 by uber-comm
field units/corcom.fbi [unitinfo] maxvelocity: 1.07 -> 1.605 by uber-comm
field units/corcom.fbi [unitinfo] turnrate: 1030 -> 1545 by uber-comm
field units/corcom.fbi [unitinfo] workertime: 300 -> 900 by uber-comm
The Library's dry run is the same pipeline on a store of its own, with no match. It sets no map, so a maps hook does not run there. The Library remembers the answer, and its Checked line is one of these. check does not apply the mutator. The dry run and the diff do.
| Verdict | What the Library shows |
|---|---|
compatible | It plays with that mod, and the line carries a summary of what changed. |
no-effect | It plays, and it changes nothing the check counts. |
incompatible | It does not play with that mod. The reason follows. |
failed | It stopped. The reason follows. |
| still running | The check with that mod is still running. |
| not run yet | Not checked with that mod yet. |
What the catalogue page shows
The page shows the icon, or, when the manifest names none, the first tag's icon when that tag is one of the eight. Then the name, the author, the version and the release, the summary (the first line of description), the tags, and an engine pill from requires.engine. Needs lists requires.mutators. Options lists each option. What it changes lists the layers. Plays with lists works-with. A releases table follows, then Get it in the game. This site never links the package file. Downloads happen in the game.
The icon
A square PNG, at least 1 pixel on a side, at most 256 pixels and 256 KiB. Draw it at 128 pixels. The manifest's icon names the path, and that name ends in .png. With no icon, the badge uses the first tag's icon when that id is one of the eight. A later tag is not tried.
Offer it to Core Prime
Core Prime's content library is published from a maintainer's machine: the catalogue is signed with a key that never leaves it. To have a mutator listed:
- Open an issue on the Open Annihilation repository with the .oamut (or a link to it), its author and licence.
- A maintainer runs the checks against the game folder and adds it to the library's package records.
- The next publish uploads the file by its hash, signs the new catalogue and raises its sequence.
- Minutes later it is in every player's Library and on this site.
A map pack or a mod is offered the same way. See Publishing to Core Prime.