Check, pack and publish a brain

Pack and check

A brain is packed and checked with oa-tool brain pack and oa-tool brain check. oa-tool pack and oa-tool check are the commands for a .oamap or a .oamod. The guide's help lists the three brain commands:

oa-tool brain pack FOLDER [--out FILE] [--force]
    Pack a brain folder as a .oabrain.
oa-tool brain check FILE --game-dir DIR [--mod FOLDER] [--level LEVEL] [--side N] [--json]
    Load a brain against a game and report how it started.
oa-tool brain net MODEL.onnx --calibrate DATA [--out FILE] [--weights int8|int16] [--max-difference X] [--force] [--json]
    Convert an ONNX model to a .oann.

Pack from outside the folder. Check loads a .oabrain, or a folder whose top holds oabrain.yaml, against a game. It seats the brain on a flat stand-in map and never ticks that match. A phase that did not run says not run. These two commands are the guide's run for Steady Commander, and the report that followed:

build/oa-tool brain pack brains/examples/steady-commander --out /tmp/brain-scratch/steady-commander.oabrain

build/oa-tool brain check /tmp/brain-scratch/steady-commander.oabrain --game-dir "$OA_GAME_DIR"

brain: steady-commander 1.0 level easy
game: totala
mod: none
load: ok, 0 instructions
fits: ok, 0 instructions
start: ok, 15 instructions
lua: 1231655 bytes
networks: 0 bytes
result: ok

The check exits 0. result: ok is that run. fits: ok is the script's fits returning true. --json prints one object. --mod names a mod folder. --level picks a level id, and the first level when it is left out.

What pack refuses

Left alone, pack writes the id, a hyphen and the version, ending .oabrain. --force replaces a file that is already there. --game-dir on brain pack is a usage error. brain check takes --game-dir. Pack refuses a broken manifest, a file outside the layout, Lua that is not source, a network whose bytes are not the digest the manifest names, and an icon that is not a square PNG within the limits. Lua is compiled and not run. A .oann file is hashed and not interpreted.

A headless match

--brain-match plays two computer seats. Each seat is an installed brain id, a folder, or builtin. It needs --headless-check, --match-ticks and --brain-map. The guide's match of Steady Commander against Classic is:

open-annihilation --skip-intro --mute --headless-check --game-dir "$OA_GAME_DIR" \
  --user-folder /tmp/brain-user --data-dir /tmp/brain-scratch/data \
  --brain-match brains/examples/steady-commander,brains/classic \
  --brain-levels medium,medium \
  --brain-map "Painted Desert" --seed 4242 --match-ticks 1800 \
  --brain-record /tmp/brain-scratch/record.txt

It exits 0. Every line starts with brain match. winner none and reason time mean both seats still had units when the tick count was spent. In that Classic match Steady Commander's built count is 6. status playing means the brain was still being called. The same folder against the built-in player, whose built count for Steady Commander is 7, is the run whose trace shows the script's own orders:

open-annihilation --skip-intro --mute --headless-check --game-dir "$OA_GAME_DIR" \
  --user-folder /tmp/brain-user --data-dir /tmp/brain-scratch/data \
  --brain-match brains/examples/steady-commander,builtin \
  --brain-levels medium,hard \
  --brain-map "Painted Desert" --seed 4242 --match-ticks 2400 \
  --brain-trace /tmp/brain-scratch/trace-play.txt \
  --brain-record /tmp/brain-scratch/record-play.txt

A trace

--brain-trace and --brain-record ride on a match. Both need --headless-check and --match-ticks. The trace of the built-in match begins:

brain log 1
tick 0 seat 0 brain
call fits
tick 0 seat 0 brain
call start

A timer is a line call timer. Report seat 1 is log seat 0. own-draw is brain.random. Steady Commander never calls brain.record, so its record file has no sample line.

CHECK WITH THIS MOD, and the log

CHECK WITH THIS MOD is a button on an installed brain in the Library, shown when a verdict is set. It loads that copy and runs fits. It does not seat the brain. It is off during a game and while the check is running.

The app writes the seat log at logs/brains/seat- and the player index plus one, under the account's data folder. The file starts anew for each brain seated there. The first line is the manifest name, the version, the id, the level, the seat and the match seed. A printed line is appended as the tick and the text. The file stops at 1 MiB.

The catalogue's oabrain kind

On Core Prime the catalogue kind is oabrain. The package installs into Brains/ and the id. A game that does not know a catalogue kind skips that entry, so an older game does not list the package. This site's AI Enhancements section stays marked coming soon until the catalogue is serving the kind.

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 brain listed:

1. Open an issue on the Open Annihilation repository with the .oabrain (or a link to it), its author and licence.
2. A maintainer runs the checks against the game folder and adds it to the library's package records.
3. The next publish uploads the file by its hash, signs the new catalogue and raises its sequence.
4. Minutes later it is in every player's Library and, once this site lists the kind, on this site.

A map pack, a mod or a mutator is offered the same way. See Publishing to Core Prime.