Make a brain

What a brain is

The engine's own computer player stays the default and stays in the engine. A brain plays one computer seat, and only a seat a player set to it. An empty brain id is that built-in player. A seat with no brain, a brain that does not fit, and a brain that stops are all played by that same player. Classic is written in Lua and plays as that player does. It is documentation of that player, not a replacement.

Only the machine that seats the computer player runs the script, so the other players need nothing installed. Their machines mirror the seat's units. A recording played back does not run the script. A brain is Lua source and data. It has no native code, no file, no network and no clock. Full awareness is a flag on the manifest. A brain may set it, may play with it in a network game, and the seat shows the flag.

The package

A brain is one .oabrain file, or the folder that file unpacks to. The manifest is the strict YAML a mod profile uses: one document, one top-level mapping, no anchors and no block scalars. The top of the package holds oabrain.yaml. Beside it, a file is one of these. A file outside that list is refused.

The comparison ignores the case of ASCII letters, except where the standard says the bytes must match. brain.lua is outside when entry names some other file. One Lua file is at most 1 MiB. The icon is a square PNG, each side at most 256 pixels, at most 256 KiB. OA installs a brain into Brains/ and the id from the manifest.

The manifest

The reader collects every broken rule and leaves the manifest unchanged when any rule is broken. A key the standard does not list is refused. A profile key belongs in a mod. A mutator key is refused as a mutator's key. Quote a version, because a bare 1.0 is a number, and quote a star, because a bare star is a YAML alias.

The nine tags

A tag is one of these nine, compared byte for byte. More than four, when the shared tag rule has already passed, is its own problem. A tag that is not one of the nine is refused.

Levels and difficulty

levels is a list of 1 to 6 mappings. Each is exactly id, name and difficulty, all required. id is lower-case kebab-case of 1 to 32 bytes, and no id is repeated. name is 1 to 64 bytes with no control character. difficulty is easy, medium or hard, byte for byte.

Those three names are the values 0, 1 and 2. A seat that picks the level uses that value as its income rules, the same difficulty the game already uses.

Full awareness

fullAwareness is true or false. Absent means false. A brain with the flag sees units a seat in the fog would not, the way the built-in computer player does, and its site checks do not need a placing player. The flag is allowed in a network game. The Library shows Sees every unit on the map, as Total Annihilation's own computer player does. The flag is the manifest's own. It is not granted by the package id, and it is not one of the things only Classic is given.

Where a brain runs

Only the machine that seats the computer player needs the package, and only that machine runs the script. A seat is a computer player of this machine. A human seat is refused. game.mode is skirmish, campaign or network.

The brain a seat plays is not an input of the simulation hash. Two matches that differ only in which brain is seated keep the same match state hash. The mod's ai.* hack values are part of the mod profile that hash covers, so they still reach every machine.

The runtime's budgets

A brain runs as Lua in one sandbox. Two brains share no modules, no globals and no budgets. The script has no file, no clock, no environment, no process and no network. Every chunk is loaded as text. pcall and xpcall cannot keep a spent phase alive. A turn is one banked call, at the seat's controller point, after the unit sweep. Orders a hook gives take effect in the next tick.

When a brain fails

A brain stops for an error in a hook or a timer, a spent instruction allowance, the real-time backstop, the Lua memory cap, a string past 65,536 bytes, or a load the seat refuses. A failed turn closes the sandbox and clears the hooks before that turn returns. The failing turn still counts as played. The next order tick has no hooks, so the built-in computer player takes it. A brain that is refused, fails to start, or does not fit never has hooks, so that player plays from the start. The notice uses the manifest name and the reason, cut to 160 bytes:

- `{brain} stopped ({reason}); the engine plays this seat on`
- `{brain} could not start ({reason}); the engine plays this seat`
- `{brain} does not fit this game ({reason}); the engine plays this seat`

When the seat has no reason of its own, the reason is the brain could not be seated. A defeated player is simply no longer called. The sandbox closes with the match.