COB / BOS — Unit Scripting Bytecode

Every unit in Total Annihilation runs a script that animates its pieces, emits weapon flashes, plays sound effects, and responds to game events. The source language is BOS ("Basic Object Script"); the compiled bytecode the engine actually runs is COB ("Cobble" — Cavedog's pun for "compiled BOS"). One file per unit, named after the unit's ObjectName from its FBI.

# Decompile a unit's bytecode back to readable BOS
kbot cob decompile scripts/ARMCOM.cob

# Disassemble to opcode-level assembly with control-flow arrows
kbot cob disassemble scripts/ARMCOM.cob -a

# Lint a whole directory for common script issues
kbot cob lint scripts/ -q

# Round-trip the entire scripts/ tree to verify byte-perfect compile
kbot cob roundtrip scripts/

import "github.com/coreprime/kbot-io/formats/scripting"

cob, _ := scripting.LoadFromFile("scripts/ARMCOM.cob")
fmt.Printf("%d scripts, %d pieces\n", cob.NumScripts, cob.NumPieces)
for i, name := range cob.ScriptNames {
    fmt.Printf("  [%d] %s\n", i, name)
}

Two languages, one file format#

The engine only ever sees COB. BOS is a convenience for human authors; when you "edit a unit's script" you're really editing the BOS source, recompiling to COB, and shipping the COB in the unit's add-on .ufo.

A minimal example:

// armcom.bos — fragment from the Arm Commander
piece base, pelvis, lthigh, lleg;

#define SIG_WALK 2

Create() {
    hide pelvis;
    set-signal-mask SIG_WALK;
}

Walk() {
    set-signal-mask SIG_WALK;
    while (1) {
        turn lthigh to x-axis  [-25] speed [50];
        turn lleg   to x-axis  [50]  speed [100];
        wait-for-turn lthigh around x-axis;
        sleep 100;
    }
}

kbot cob compile lowers this into a binary blob. kbot cob disassemble -a shows the opcode stream side-by-side with control-flow arrows; kbot cob decompile does the reverse, recovering BOS that almost always round-trips byte-identical (kbot cob roundtrip validates this across the entire game catalogue).

A source compiles as a TA script (COB version 4) unless it starts with .version 6. The compiler refuses what TA 3.1c would mis-run rather than writing a placeholder: the TA: Kingdoms constructs (play-sound, Mission-Command, __tak_math_*, .sound_name) and % are errors in a TA script (TA has no modulo instruction, and 0x10037000, the word % used to become, is its bitwise XOR), as are unknown identifiers and functions that need more than the game's 32 stack slots. What still compiles but deserves a look — a function defined twice (every call binds to the first definition, as the game's name lookup does) — is printed as a warning, together with any finding of the TA compatibility lint rules; --strict makes warnings fail the command. kbot cob assemble applies the same checks to hand-written listings.

COB on-disk layout#

typedef struct {                          // 44-byte header (11 × uint32)
    uint32 VersionSignature;              // 4 for TA, 6 for TA: Kingdoms
    uint32 NumScripts;                    // Number of functions (Create, Killed, …)
    uint32 NumPieces;                     // Number of named pieces
    uint32 LengthOfScripts;               // Total code size, in DWORDs
    uint32 NumberOfStaticVars;            // Static-variable count
    uint32 UKZero;                        // Always 0 in retail bytecode; purpose unknown
    uint32 OffsetToScriptCodeIndexArray;  // → uint32 × NumScripts: code-index per script
    uint32 OffsetToScriptNameOffsetArray; // → uint32 × NumScripts: absolute offsets into string pool
    uint32 OffsetToPieceNameOffsetArray;  // → uint32 × NumPieces: absolute offsets into string pool
    uint32 OffsetToScriptCode;            // → packed uint32 opcode stream
    uint32 OffsetToNameArray;             // Byte just past the piece-name offset array (= sound-name offset table start for TAK v6, or string-pool start for TA v4)
} COBHeader;

Then follow, in this layout:

┌─ Script code ─────────────────────────────┐  uint32 opcodes/operands, packed
├─ Script code-index table ─────────────────┤  uint32[NumScripts] — *not* byte offsets
├─ Script name offset table ────────────────┤  uint32[NumScripts]
├─ Piece name offset table ─────────────────┤  uint32[NumPieces]
└─ String pool ─────────────────────────────┘  NUL-terminated names, in order

Resolving a script#

The code-index table contains uint32 word offsets, not byte offsets. To find the bytecode for script number i:

uint32 first_instr_word = ScriptCodeIndexArray[i];
uint32 byte_offset      = OffsetToScriptCode + first_instr_word * 4;

The script ends where the next script begins (or at the start of the index table, for the last script).

The opcode stream#

COB is a stack-based virtual machine. Most opcodes pop arguments from a per-script data stack, do their thing, and push a result back. Some opcodes have inline operands (jump targets, piece numbers).

Each opcode is one uint32 with the layout:

       MSB                          LSB
  ┌─────────┬─────────┬─────────┬─────────┐
  │   0x10  │ family  │ op      │ flags   │
  └─────────┴─────────┴─────────┴─────────┘

The high byte is always 0x10; family/op/flags vary per opcode. The game does not compare the whole word: it dispatches on word & 0x100FF000, so bits outside that mask are ignored and 0x10064001 runs as JUMP (kbot's disassembler writes such a word JUMP@0x10064001 so it assembles back unchanged). PUSH (0x10021000) and POP (0x10023000) then read their source or destination from the low three bits. kbot-io's scripting/opcodes.go is the catalogue; scripting.Opcodes() lists every instruction with its inline operands and stack effect.

Opcode families#

A small but representative sampler:

0x10021001 PUSH_CONST     <value>      ( -- v )
0x10021002 PUSH_LOCAL     <var#>       ( -- v )
0x10023002 POP_LOCAL      <var#>       ( v -- )
0x10033000 MUL                         ( a b -- a*b )
0x10051000 LESS_THAN                   ( a b -- a<b )
0x10066000 JUMP_IF_FALSE <byteOffset>  ( v -- )    pops; falls through if v != 0
0x10064000 JUMP          <byteOffset>  ( -- )
0x10065000 RETURN                      ( v -- )    pops the return value
0x10001000 MOVE          <piece> <axis> ( speed distance -- )
0x10003000 SPIN          <piece> <axis> ( speed -- )
0x1000F000 EMIT_SFX      <piece>       ( flags -- )
0x10068000 SET_SIGNAL_MASK              ( mask -- )

Concurrency model#

A unit can have many scripts running concurrently — Walk, Aim, SmokeUnit, MoveWatcher, etc. They're cooperatively scheduled:

• sleep <ticks> yields for N ticks (1/30 s each).
• wait-for-turn <piece> around <axis> yields until that piece finishes its current turn animation. Same for wait-for-move.
• signal <n> kills every script whose signal_mask & n != 0.
• set-signal-mask <n> declares which signals the current script is interested in.

The signal mask is how scripts implement preemption: MoveWatcher sets mask SIG_MOVE and watches velocity; when the unit stops moving it sends SIG_MOVE, killing the walk animations cleanly before starting the idle pose.

How preemption actually plays out#

A common pattern: MoveUnit triggers a Walk animation script; when movement stops the engine sends SIG_MOVE to clean up cleanly before Idle starts. The sequence:

   Engine                 MoveUnit script        Walk script        Idle script
     │                          │                     │                  │
     │  unit ordered to move    │                     │                  │
     ├─ start-script MoveUnit──▶│                     │                  │
     │                          ├─ set-signal-mask    │                  │
     │                          │   SIG_MOVE          │                  │
     │                          ├─ start-script Walk─▶│                  │
     │                          │                     ├─ set-signal-mask │
     │                          │                     │   SIG_MOVE       │
     │                          │                     │ (loops:          │
     │                          │                     │   turn pieces,   │
     │                          │                     │   sleep, repeat) │
     │                          │                     │                  │
     │  movement completes      │                     │                  │
     ├─ engine sets velocity=0  │                     │                  │
     │                          ├─ signal SIG_MOVE ──┐│                  │
     │                          │                    ││                  │
     │   ◀─── KILLED ──────────────────────────────  ◀┤                  │
     │   ◀─── KILLED ──────────┤                     │                  │
     │                                                                   │
     ├─ start-script Idle ─────────────────────────────────────────────▶│
     │                                                                   │ (loops)

Three things to notice:

1. Both scripts that set SIG_MOVE are killed when the signal fires — including MoveUnit itself (it doesn't matter; its work is done).
2. The signalling script (MoveUnit) survives long enough to send the signal before being killed; the runtime checks masks after the signal opcode returns.
3. Idle doesn't set SIG_MOVE, so the next signal SIG_MOVE won't touch it.

Worked example — cortruck.cob (Core Construction Truck)#

kbot cob decompile scripts/cortruck.cob:

piece base;

SmokeUnit() {
    var local_0, local_1, local_2;

    while (get BUILD_PERCENT_LEFT) { sleep 400; }

    while (1) {
        local_0 = get HEALTH;
        if (local_0 < 66) {
            local_2 = (256 | 2);
            if (rand(1, 66) < local_0) { local_2 = (256 | 1); }
            emit-sfx local_2 from base;
        }
        local_1 = (local_0 * 50);
        if (local_1 < 200) { local_1 = 200; }
        sleep local_1;
    }
    return 0;
}

Create() { return 0; }

Killed() {
    var severity;
    if (severity <= 25) { explode base type (32 | 256); return 0; }
    if (severity <= 50) { explode base type (32 | 256); return 0; }
    if (severity <= 99) { explode base type (32 | 256); return 0; }
    explode base type (32 | 256);
}

The corresponding disassembly (kbot cob disassemble -a -s SmokeUnit) shows the actual opcode stream, with JUMP_IF_FALSE/JUMP arrows threaded through the while/if bodies — useful when the decompiler output is ambiguous.

Linting#

kbot cob lint (and the asset explorer's Lint tab) runs kbot-io's default rule set: style rules drawn from real-world bugs in Cavedog's own scripts and from community-submitted mod patches, two file-level checks, and — for every COB that does not declare version 6 — the TA 3.1c compatibility rules. The style catalogue:

The TA compatibility rules report what TA 3.1c faults on or runs differently. They are errors, appear in --ci SARIF output like the others, and skip TA: Kingdoms (version 6) files:

The full rule descriptions are in the kbot README. The decompiler deliberately preserves the original variable and piece numbering so that a decompile→lint→fix→compile cycle highlights mods needing maintenance.

Gotchas#

• All offsets in the COB header are absolute file offsets, but the ScriptCodeIndexArray entries are word offsets within the code section. Easy to confuse them.
• Piece numbers in opcodes are indices into the piece name table, not strings. The COB carries the names as a string pool; the runtime uses indices for speed.
• get UNIT_VALUE opcodes vary subtly between TA and TA: Kingdoms. TA: Kingdoms added value IDs for magic regen, command-points, etc.; TA's value table is more compact. kbot's decompiler currently labels the TA set; TAK port numbers ≥ 21 are emitted as numeric literals (which still round-trip through the assembler). See TA: Kingdoms — COB v6 deltas for the full delta.
• Variables come in two flavours: local_N (function-local stack slot) and global_N (per-unit static persisting across calls). The decompiler emits local_N / global_N by default; rename them in source for readability.
• The Cavedog Scriptor tool occasionally inlines CURRENT_SPEED as a literal 29, breaking MoveWatcher-style scripts after a round trip. kbot's decompiler restores the symbolic name; if you must round-trip through Scriptor, parenthesise: (get CURRENT_SPEED) > 5.

Typical sizes#

TA: Kingdoms — COB v6 deltas#

v6 file layout#

┌─ 44-byte v4 header ──────────────────────────────────┐
│ VersionSignature == 6, NumScripts, NumPieces, …      │
├─ Sub-header (8 bytes, TAK-only) ─────────────────────┤  (soundNameOffsetTableStart, soundNameCount)
├─ Script code (uint32 opcode stream) ─────────────────┤  same encoding as v4
├─ ScriptCodeIndexArray (uint32 × NumScripts) ─────────┤  unchanged
├─ ScriptNameOffsetArray (uint32 × NumScripts) ────────┤  unchanged
├─ PieceNameOffsetArray (uint32 × NumPieces) ──────────┤  unchanged
├─ SoundNameOffsetArray (uint32 × Count) ──────────────┤  TAK-only — count from sub-header[1]
└─ String pool ────────────────────────────────────────┘  script names → piece names → sound names (in that order)

The 8-byte sub-header sits between OffsetToNameArray (end of the canonical 11-DWORD header at byte 44) and the start of the code section (OffsetToScriptCode, typically 0x34 = 52). It carries two little-endian uint32s:

Each entry in the sound-name offset table is an absolute file offset of a NUL-terminated string in the string pool — things like "SetMission o 1, s", "create ARASWORD", "ARROW10". The bytecode references them by index (not by offset) via the MISSION_COMMAND opcode (see Appendix C). The table is called the sound-name array because the canonical Scriptor compiler registers strings into it via the ADDSOUND action; the actual contents are engine command strings rather than audio filenames.

kbot's representation#

scripting.COB carries the sound names as a structured []string field — no opaque-byte preservation. Everything else (the sub-header values, the offset table, the per-string offsets in the pool) is reconstructed from this list on write:

type COB struct {
    // …canonical TA fields…
    SoundNames []string // TAK-only; nil for v4
}

For v4 files the slice is always nil and both the sub-header and sound-name offset table are omitted from the output.

The disassembler / decompiler emit each string as a .sound_name directive so they survive a round-trip through .coba and .bos:

.version 6
.statics 6
.sound_name "create NPCEMEN"
.sound_name "SetMission o 1, s"
.sound_name "ARROW10"
.script Start
…

New opcodes#

TAK .cob files use instructions TA 3.1c has no handler for (PLAY_SOUND, MISSION_COMMAND and the TAK_MATH_* operators) plus DONT_SHADOW, which TA runs as a no-op. Their exact game-side semantics are not documented, but their binary layout (size + inline parameter count) is known from every retail TAK .cob, which is enough for the disassemble→assemble round-trip to recover the original bytes verbatim. See Appendix C for the full reference.

Round-trip status#

BOS surface for TAK extensions#

The decompiler emits these pseudo-calls so TAK COBs round-trip through BOS. The compiler accepts the same syntax, but only after .version 6 (dont-shadow excepted — TA runs it as a no-op). dont-shadow and Mission-Command use Scriptor's canonical TAK keywords; the math opcodes have no documented name in Scriptor (it labels them ?? and ????), so kbot keeps the __tak_math_* placeholders:

// Statement-level (emitted on their own line):
dont-shadow(<piece>);                                  // DONT_SHADOW — disables shadow casting for one piece
Mission-Command("sound name", arg1, arg2, …);          // MISSION_COMMAND — engine call (statement form drops the return value)
return_val = Mission-Command("sound name", args…);     // assignment form keeps the pushed result

// Expression-level (binary operators: two values popped, one pushed):
local_x = __tak_math_09(a, b);   // TAK_MATH_09
local_x = __tak_math_0a(a, b);   // TAK_MATH_0A
local_x = __tak_math_0b(a, b);   // TAK_MATH_0B

Mission-Command's first argument is the sound name as a quoted string — the compiler looks it up in the sound-name table (so the corresponding .sound_name directive must appear earlier in the file). The remaining arguments are pushed onto the stack and the engine consumes them.

Two top-of-file directives carry the rest of the v6 metadata:

.version 6
.sound_name "create NPCEMEN"
.sound_name "SetMission o 1, s"
.sound_name "ARROW10"

.version is always emitted (so v4 TA files round-trip identically through the same pipeline). Each .sound_name is one entry in the per-COB sound-name table; the writer rebuilds the 8-byte sub-header and the sound-name offset table from len(SoundNames) and the order the entries appear.

The TAK STACK_ALLOC ; RETURN epilogue every value-less return; emits in v6 is handled by the compiler: return; lowers to STACK_ALLOC ; RETURN when .version 6, return <expr>; lowers to <expr> ; RETURN without a prefix (matching Cavedog's compiler).

Reproduce on your own install:

kbot ctx use kingdoms  # or wherever you registered TAK
kbot cob roundtrip

Port symbols beyond port 20#

TA: Kingdoms scripts use get_unit_value ports up to 46 (CURRENT_SPEED, VETERAN_LEVEL, magic-pool fields, etc.). kbot's decompiler currently labels only ports 1–20 symbolically (see Appendix B); TAK ports ≥ 21 are emitted as numeric literals. The bytecode stores them as integers either way, so round-trips are unaffected — only the BOS readability suffers. Adding TAK port names is tracked separately.

Appendix A — Full opcode reference#

Every instruction TA or TA: Kingdoms runs. Source of truth is kbot-io's formats/scripting/opcodes.go. Stack notation uses Forth-style ( before -- after ). Inline columns show how many uint32 words follow the opcode word itself (consumed during decode, not from the stack).

Animation — piece manipulation (0x100x)#

Wait operations (0x101x)#

Stack manipulation (0x102x)#

Arithmetic (0x103x)#

TA has no modulo instruction: % is a compile error in a TA script. 0x10039000–0x1003B000 are the TA: Kingdoms TAK_MATH_* operators (Appendix C); TA faults on them.

Engine queries (0x104x)#

See Appendix B for the port catalogue.

Comparison & logical (0x105x)#

Control flow & concurrency (0x106x)#

offset for JUMP / JUMP_IF_FALSE is a byte offset relative to OffsetToScriptCode, not relative to the current instruction.

Effects (0x107x)#

Set operations (0x108x)#

Opcode encoding#

Every opcode word is 0x10CCSSFF, where:

• CC = the category byte (animation, math, control flow, …).
• SS = the sub-command nibble in the high nibble of the second byte from the top.
• FF = the flags byte.

The game dispatches on word & 0x100FF000 and ignores the other bits, so a word such as 0x10064001 runs as JUMP; the disassembler writes it JUMP@0x10064001 and the assembler reads that back to the same word. PUSH and POP read their source or destination from the low three bits: PUSH accepts 1 (constant), 2 (local) and 4 (static), POP accepts 2 and 4, and any other value faults the script.

Words no game runs are rendered as UNKNOWN_0x10xxxxxx by the disassembler (and reported by ta-unknown-opcode); if you find one in a real file, please open an issue with the COB sample.

Appendix B — get_unit_value port table#

The 20 ports kbot's decompiler currently labels symbolically. Real TA has ~80; TA: Kingdoms adds another ~15 for magic-related quantities. Anything above port 20 is rendered as a numeric literal in the decompiler output today.

Higher ports include CURRENT_SPEED (29 — famously inlined as a literal by the Cavedog Scriptor; see Gotchas above), MAX_ID, UNIT_TEAM, UNIT_BUILD_PERCENT, BUILDER, UNIT_ALLIED, and many more. The full list lives in Cavedog's internal documentation; the community wiki at the TAUniverse forums has the most comprehensive public catalogue.

TA: Kingdoms extends the port range. The TAK-only ports kbot recognises (decompiler renders the symbolic name; compiler accepts it as input) are taken from Scriptor's [UNITVLAUES] table:

Appendix C — TA: Kingdoms opcodes#

Encoding (recap)#

Every COB opcode word is 0x10CCSSFF where CC is the category and SS is the sub-command — these TAK opcodes simply occupy previously-unused CC:SS slots inside the existing categories rather than introducing a new category byte. DONT_SHADOW lives in the animation category alongside DONT_CACHE/DONT_SHADE, and MISSION_COMMAND in the effect category alongside EXPLODE and PLAY_SOUND.

kbot ctx use tak-30bb-flat
kbot cob disassemble scripts/araat.cob -a | grep -E 'DONT_SHADOW|MISSION|TAK_MATH|PLAY_SOUND'

Live examples in the reference catalogue#

Real units exercising the format extremes — open these to see actual script complexity rather than worked-in-text examples:

• CORKROG — Krogoth (Core) — one of the largest COBs in the game (~25 KB, 30+ scripts, complex multi-piece animations).
• ARMCOM — Arm Commander — representative "rich" unit: walk/aim/idle/build cycles, multiple weapons, D-gun handling.
• CORTRUCK — Construction Truck — near-minimal COB used as the walkthrough on this page (3 scripts: SmokeUnit, Create, Killed).
• ARMSAM — Samson — good example of a turret unit (turret1 rotate-to-aim, recoil animation, wait-for-turn synchronisation).

Decompile any locally with kbot cob decompile scripts/<name>.cob once a kbot context is set.

See also#

• 3DO — the piece names referenced by COB scripts live in the unit's .3do.
• FBI — the unit's metadata file. ObjectName there ties the COB to a 3DO; Sounds define the audio bank the script can play.
• The kbot CLI's cob lint rules table.
• Glossary — piece, axis, signal mask, tick.