Unit animation scripts

From authored motion to machine words

BOS is source code; COB is the program the engine loads. A unit script animates named 3DO pieces, starts cooperative threads, and answers engine queries. The file lives at scripts/<UnitName>.COB; the FBI unit definition selects that identity by convention.

piece base, turret;
Create() {
  turn turret to y-axis <90> now;
  return (0);
}

Scroll table horizontally to see all fields →

Two address spaces

file_byte = OffsetToScriptCode + 4 × code_word_index

The 44-byte header points to code and five tables. Their physical order is unrestricted; the fixture happens to place code immediately after the header. All stored words are little-endian. Stack cells are interpreted as signed 32-bit values.

From a command to visible motion

A turn starts motion and lets the script continue. Add wait-for-turn when the next statement must wait for that axis to become idle. The engine visits the script slots first, then updates the pieces; the two parts of a tick have different jobs.

Try these comparisons:

• Leave waiting on and reach the target. The piece clears its speed word during interpolation. The thread resumes on the next script drain; the beacon stays hidden until then.
• Turn waiting off. show and return run in the first drain, before the first movement pass. Returning does not cancel the piece’s motion.
• Double the angular speed. The piece arrives sooner, while the order of script drain, interpolation and wait resumption stays the same.
• Compare with the first bytecode example. Its turn-now changes the angle directly when the instruction executes, with no animated journey to the target.

Tick numbering starts at zero. The per-tick remainder is discarded, so the first setting leaves the piece just short after 30 passes: 546 × 30 = 16380, while the target is 16384. The traces deliberately use raw speeds 16384 and 32768. Their BOS labels follow the 65536-units-per-circle convention; actual compiler factor settings can change emitted constants, as explained in value scaling.

One script can start another

Both call-script and start-script allocate a child thread. A successful call-script blocks its parent until the child slot is released. start-script allows the parent to continue. These are cooperative threads: a runnable slot executes until it yields or ends, and then the scheduler moves to the next slot.

With start-script, the parent sets its flag and returns before slot 1 is visited. With call-script, the child sets its flag first. Its return wakes the parent, but slot 0 has already had its visit: the parent continues on the next drain. The returned 7 is discarded by the script call; it is not an expression result assigned to the parent.

Signals select threads by shared bits

A signal terminates matching threads. set-signal-mask replaces the current thread’s mask; signal checks all eight active slots using bitwise AND. A mask is a set of bits, so signal 2 matches masks 2 and 3.

Try signal 3 with the sender’s default mask 1: the sender terminates itself along with the workers sharing either bit. Change the sender mask to 0 and send the same signal; it survives. Clear every signal bit and no thread matches.

// This thread starts with mask 1.
set-signal-mask 0;
signal 2;            // terminate threads carrying bit 1
set-signal-mask 2;   // later signal 2 can terminate this thread

Order matters: setting mask 2 before sending signal 2 makes the sender one of its own victims. Signal termination releases matching slots and wakes callers waiting for those slots. It does not deliver a value to an engine completion receiver; an explicit return does so when a receiver is attached.

Byte layouts

Header · 44 bytes

Scroll table horizontally to see all fields →

Host-safety policy. NumberOfStatics is not bounded by any corresponding on-disk static-data span. Nanolathe therefore applies an explicit per-VM static-storage budget before parsing publishes a program and again before a VM or restore accepts an externally supplied program. This is a host-safety policy, not a retail limit; it prevents a small header from requesting an unbounded allocation. Established implementation behavior: internal/cob.Load also requires version 4, aligned nonempty code/name/index tables, in-range entry words and terminated nonempty names. The version-4 restriction is an explicit host compatibility policy; retail ignores that word [02 R-MALF-01 §8]. Duplicate script names are accepted: name lookup retains the first exact, case-sensitive match, while indexed calls retain every declared entry [04 R-COB-01 §1]. The loader does not predecode opcodes or validate instruction boundaries.

The trailing record table

Established. Header words 0x14 and 0x28 are a count/pointer pair for a fifth table, not a reserved word and a redundant string-pool offset. The loader reads the file whole, records its content checksum in the script cache, and then relocates exactly five table pointers — script entry points (pointer only; the entries are word indexes into the code array and are not relocated), script names (pointer plus every entry), piece names (pointer plus every entry), the code array (pointer only) and this trailing table (pointer, plus the second dword of each record counted by header word 0x14, each record being 8 bytes). Document 02’s “Compiled script archive (COB)” and [02 R-MALF-01 §8] describe the same five-table relocation from the loader side; this entry is what fixes the two words to the two slots.

In the recorded 835-file census the count is zero and the table offset equals the first script-name string offset. A zero count does not require that coincidence; both fields retain their table roles.

Established (bounded compiler source): the inspected Scriptor v1 (RC1) writer emits a zero trailing-record count for both its TA and Kingdoms outputs. It places the zero-count pointer at the start of the string pool. This writer therefore supplies no example of the nonempty record layout.

Unknown. What an 8-byte record means. Its second dword is a file offset (it is relocated); the first is not. The surveyed scripts carry none, and the recorded reader search found no consumer after relocation. That is a bounded negative observation, not proof that every authored use is inert. Decider: a modded or Kingdoms-era COB that authors a non-zero count, or a reader of the relocated table elsewhere in the image. Nanolathe validates the table’s span but neither interprets the records nor validates the target of each second-word offset; Program does not retain this table. That is an implementation limitation for nonempty tables.

Offsets below are relative to an individual trailing record, not the file header.

Scroll table horizontally to see all fields →

Names and indexes

• Script n’s code starts at word ScriptCodeIndexArray[n] of the code section (byte offset OffsetToScriptCode + index*4).
• Pieces are referenced from code by zero-based index into the piece name array. Piece names correspond (case-insensitively) to 3DO piece names.
• The file records names but no callback classification. BOS/COB may reach any stored entry by call-script or start-script; the retail engine’s fixed name producers and lookup behavior are specified by [04 R-CB-01 §1–§2].

The virtual machine

At the bytecode level, instructions push and pop signed 32-bit cells; alloc-local adds a local cell; statics are addressed by indexes from 0 to NumberOfStatics-1; and start-script/call-script, signal, sleep, and piece wait instructions encode cooperative control flow. The laboratories above illustrate selected motion and scheduling cases. The complete contracts for runtime allocation, initial values, signal masks, failure edges, tick conversion, wake order, and piece-motion timing are specified by [04 §4.1–§4.6], [04 R-COB-01 §1], and [04 R-COB-04 §7].

Value scaling conventions

Established — sampled scale relationships: the recorded comparison of ARMFLASH.BOS with ARMFLASH.COB supports the scales below. Exact compiler quantization used to produce these shipped constants remains Unknown.

Established (bounded compiler source): Scriptor v1 (RC1)’s numeric converter scales a parsed number using configurable floating-point linear or angular factors, then converts the result to a signed integer. For representable results that conversion truncates toward zero; it does not round to nearest. The settings store both factors as single-precision values. The application’s default linear factor is 163840.0, but its default angular factor is 182.0, not the exact ratio 65536/360. Consequently this release’s default settings do not reproduce every angle in the sampled table.

Unknown: which compiler release, factor settings and intermediate precision produced each shipped COB’s fractional constants. The RC1 source settles that converter’s final integer conversion, not the provenance of retail bytecode. A matched compiler build/settings record or a reproduced boundary-value compilation would settle the remainder. This is a BOS authoring question, not a runtime COB-decoding ambiguity.

The table states compiler constant encoding only. Runtime callback argument units and coordinate transforms are owned by [04 R-CB-01 §2] and [04 §4.4].

Instruction set

Each instruction is one opcode word, optionally followed by inline operand words. Notation: piece and axis (0=X, 1=Y, 2=Z) are inline operands; stack effects are shown as ( before -- after ) with the top of stack on the right.

Piece animation

Scroll table horizontally to see all fields →

The opcode numbers, inline operands, and stack shapes above are file/bytecode facts. Per-tick arithmetic, busy-state transitions, wait wake-up, and immediate commit behavior are the runtime contract in [04 §4.6].

Flow control, threads, signals

Every engine-started root thread begins with signal mask 1, and start-script and call-script give the child the parent’s current mask. The community report of a zero root starting mask is wrong [04 R-P0-10]. Signal termination delivers nothing to a completion receiver [04 §4.2].

Jump targets are word indexes relative to the code section start. Compiler-generated control flow targets instruction boundaries; the retail interpreter has no separate boundary table. Failed starts leave arguments on the caller’s stack, and a failed call-script still blocks [04 §4.3].

Values and variables

0x10044000 and 0x10045000 — encoded interpreter slots absent from Cavedog’s toolchain and retail content. Neither value appears in Scriptor’s Compiler.cfg, Decompiler.cfg, or Defs.h, so no known BOS syntax emits it. A census of all 841 COB copies in the retail archives finds zero instances. Their one-pop/one-push and zero-pop/one-push shapes are established by the interpreter, and their cargo-list semantics by [04 R-COB-03 §5], which also owns the linkage they read (a carrier back-pointer plus a singly linked cargo list, new cargo pushed at the head). The names above are conventional labels, not authored names.

Arithmetic, comparison, logic

All are pure stack operations ( a b -- result ) unless noted.

Scroll table horizontally to see all fields →

Compiler emission and reserved slots

Cavedog’s own Scriptor compiler (Compiler.cfg) and decompiler (Decompiler.cfg, Defs.h) — recovered from the Scriptor v1 (RC1) source release, the actual Cavedog COB toolchain, not a third-party clean-room guess — enumerate every operator their compiler can emit. Cross-checked against those files:

Established runtime: 0x10063000 is a dispatched TA opcode. It has two inline words: an ignored first operand and a signed count. It discards that many stack values (none for a nonpositive count), then advances by three words. Its bounds and malformed-input outcomes are [04 R-COB-04 §6]. No instance occurs in the recorded shipped-script census.

Scriptor also reuses this number as an internal decompiler jump marker. That tool convention does not remove the retail interpreter’s reserved pop-N arm. The historical note’s call-script assignment is wrong: real call-script is 0x10062000, and start-script is 0x10061000.

TAK-only opcodes (not used by TA)

Scriptor’s grammar gates a few opcodes with Flag=NOTA (“not available in TA”) — they compile only for Total Annihilation: Kingdoms (COB version signature 6, detected as Header.VersionSignature == 6 in the decompiler). Documented here only so the numbers aren’t mistaken for unknown TA opcodes:

The discard word 0x10024000 can follow a TAK play-sound expression, but is also implemented by TA and is listed under “Values and variables” above.

TAK also extends the header: past the 11 TA words it appends OffsetToSoundNameArray: u32 and NumberOfSounds: u32 (a 52-byte, 13-word header) to name the sounds play-sound can reference. TA’s header is unaffected — confirmed 44 bytes / 11 words, matching the established container layout; the decompiler’s in-memory struct is simply the 13-word TAK superset, with the trailing two fields left unread/ignored (if(TAK) gated) for version-4 files.

The BOS language

BOS is compiler input rather than the runtime-loaded format; some retail archives also ship sources. Summary of the language, composited from stock scripts (scripts/ARMFLASH.BOS and the BOS guide’s excerpts of armbats, armsilo, armcarry):

Declarations and preprocessor

Established: the piece list order defines zero-based bytecode indexes. Index 0 denotes the first declared piece; index 1 denotes the second. A piece-name expression compiles to the same index domain as an explicitly authored numeric piece index.

Standard headers shipped with Scriptor — and, importantly, shipped inside totala1.hpi itself (scripts/EXPTYPE.H, SFXTYPE.H, SMOKEUNIT.H, STATECHG.H, HITWEAP.H, ROCKUNIT.H, YARD.H, STDSCRPT.H, STDTANK.H, HELP.H, alongside all 157 stock .bos sources): exptype.h (explosion flags and sysvar IDs), sfxtype.h (SFX types), smokeunit.h (damage smoke helper SmokeUnit()), statechg.h (activation state machine; expects ACTIVATECMD/DEACTIVATECMD defines and is included twice around them), hitweap.h, rockunit.h, yard.h (OpenYard/CloseYard). The retail archive is therefore the authoritative source for both the constants and idiomatic BOS.

Statements

Axis keywords: x-axis, y-axis, z-axis. The common −Z-forward asset convention is discussed in 3do.md; it is not a bytecode restriction. Turns around Y are headings, around X are pitches. 0 position/angle means the piece’s authored rest pose.

Runtime coordinate boundary. Angle words are composed with the unit’s heading, pitch and bank in [03 §2.4]’s model space after the persistent half-turn of authored X and Z. The subsequent world-offset mapping is [03 R-RAST-01 §8]. Axis signs must follow those contracts; an observation of a single animation does not establish a different file import transform.

Two quirks visible throughout the stock sources: Scriptor has no unary minus in expressions — negation is written 0 - x (turn sleeves to x-axis (0 - pitch), attach-unit unitid to 0-1;) — and the sea-transport pickup idiom relies on attach-unit to piece -1: attach the cargo to the crane piece (link), swing the crane aboard, then re-attach to piece -1 so the cargo rides the transport without following any piece (scripts/ARMTSHIP.BOS, TransportPickup).

Engine ports (system variables)

Read with get NAME / get NAME(args…), written with set NAME to V. The numeric IDs are authoritative: Cavedog’s own scripts/EXPTYPE.H ships inside totala1.hpi and defines them (the comments below are Cavedog’s):

The Access column is Cavedog’s authored intent from that header, not a claim about which retail engine switch arms exist. Read arithmetic, write effects, defaults, packing, timing, and failure edges are runtime behavior in [04 §4.4], [04 §4.7], and [04 R-COB-03 §1–§6].

Retail packs and unpacks the packed x,z argument with the signed-add packing and negative-Z borrow correction established in [04 R-COB-03 §3]; this format document does not restate that runtime arithmetic.

Retail bytecode usage confirms the table: zero-argument reads (get-unit-value) use 17, 4, and 18; multi-argument reads (get) use 7–16 with their argument counts; set-unit-value writes 1, 5, 6, 18, 19, 20 (yard scripts always toggle YARD_OPEN and BUGGER_OFF together, per YARD.H).

Explosion type flags (explode ... type ...)

Authoritative values from the retail scripts/EXPTYPE.H:

The retail meaning and tested-bit set are runtime behavior in [04 §4.5] and [04 R-COB-04 §1].

Flags are OR-ed. Retail Killed() bodies overwhelmingly use BITMAPONLY | BITMAPn for light damage and EXPLODE_ON_HIT | FALL | SMOKE | FIRE | BITMAPn (mask 0x?1E) for heavy damage, matching the BOS guide’s examples.

SFX types (emit-sfx N from piece)

Authoritative authored values from the retail scripts/SFXTYPE.H. Its vector-class constants are SFXTYPE_VTOL = 0, SFXTYPE_THRUST = 1, SFXTYPE_WAKE1 = 2, SFXTYPE_WAKE2 = 3, SFXTYPE_REVERSEWAKE1 = 4, SFXTYPE_REVERSEWAKE2 = 5. Its point-class constants are SFXTYPE_POINTBASED = 256, SFXTYPE_WHITESMOKE = 256|1, SFXTYPE_BLACKSMOKE = 256|2, SFXTYPE_SUBBUBBLES = 256|3. Runtime geometry, visibility gates, dispatch, and presentation effects are owned by [04 R-COB-03 §6] and [03 R-FX-01 §3].

Engine callbacks

COB stores ordinary named functions; it has no callback table or per-function callback bit. Three distinct facts must therefore remain separate:

1. Authored convention: stock BOS scripts use familiar names and helper bodies.
2. Compiler vocabulary: Scriptor’s COMMON_FUNC table recognizes some names and argument counts for diagnostics/decompilation.
3. Retail invocation: only an executable producer proves that the engine starts a name. The complete producer, argument, mode, timing, and side-effect contract is [04 R-CB-01 §1–§8].

The retail executable’s fixed-name producer census contains exactly these forty case-sensitive names:

Activate · AimFromPrimary · AimFromSecondary · AimFromTertiary · AimPrimary · AimSecondary · AimTertiary · BeginTransport · Create · Deactivate · EndTransport · FirePrimary · FireSecondary · FireTertiary · HitByWeapon · Killed · MoveRate1 · MoveRate2 · MoveRate3 · QueryBuildInfo · QueryLandingPad · QueryNanoPiece · QueryPrimary · QuerySecondary · QueryTertiary · QueryTransport · RockUnit · SetDirection · SetMaxReloadTime · SetSpeed · SweetSpot · StartBuilding · StartMoving · StopBuilding · StopMoving · TakeDamage · TargetCleared · TransportDrop · TransportPickup · setSFXoccupy.

Caveats on the list above. MotionControl(moving, aiming, justmoved) is a compiler-recognized signature and an authored convention, but the whole-image census finds no MotionControl occurrence and no retail engine producer. MoveRate1/MoveRate2/MoveRate3 are engine-invoked, but document 04 traces them to the general movement-tier classifier, not an aircraft-only family. Names such as SmokeUnit, RestoreAfterDelay, OpenYard, CloseYard, and Demo may be authored helpers or script-to-script entries; appearing in BOS or Scriptor vocabulary does not make them fixed retail callbacks.

Retail corpus notes

Established (bounded asset observation). The recorded decode of 835 COB files from totala1.hpi, rev31.gp3, CCDATA.CCX and btdata.ccx reports the following. The separate transport-read census above counts 841 copies; Unknown: the exact enumeration difference between these two recorded totals. Repeating the 841-copy enumeration with archive/copy provenance would settle it. Neither total is a universal format limit.

Established (repeatable header census): a fresh independent enumeration of each installed archive, without overlay deduplication, reproduces 835 copies: totala1.hpi 157, rev31.gp3 200, ccdata.ccx 265 and btdata.ccx 213. These represent 272 distinct logical paths and 258 distinct file-content hashes. Every copy has version 4, zero trailing records, and no exact duplicate script names. This recount checks headers and names; it does not repeat the historical instruction decode below. Duplicate-name handling and nonempty trailing tables therefore concern custom inputs, not a missing path through these stock scripts.

Including the installed AFark.ufo, AFlea.ufo, AScarab.ufo, CorNecro.ufo, Cormabm.ufo and corplas.ufo adds one COB copy apiece, reproducing a total of 841 under that explicit scope. Each added script also has version 4, zero trailing records and no duplicate names. This explains how the two totals can arise from different archive sets without asserting that the unrecorded historical enumeration used exactly that set.

• Version signature is always 4; the trailing-record count at 0x14 is always 0 (see “The trailing record table” — the word is a count, not a reserved word); the recorded instruction decode covers this corpus with no unknown opcodes and no misaligned instruction stream.
• Static-variable counts are small (0–7 covers nearly everything).
• The recorded census reports no occurrences of these nine opcodes: dont-shadow (0x1000A000), bitwise AND/XOR/NOT (0x10035000/7000/8000), word XOR (0x10059000), greater/greater-or-equal (0x10053000, 0x10054000), and the two transport reads 0x10044000 / 0x10045000 documented under “Values and variables”. Their absence from this corpus cannot establish whether the interpreter implements them; [04 §4.3] provides that evidence. (greater=0x10053000, greater-or-equal=0x10054000 per Scriptor’s own Compiler.cfg operator table; community tables often swap the two.)
• Common helper-script conventions (script names that are not engine callbacks but appear across many units): Go/Stop (activation bodies), activatescr/deactivatescr (authored animation includes), InitState/RequestState(requestedstate[, currentstate]) (from STATECHG.H; both a 1-arg and 2-arg overload are recognized), walk/ walklegs/walkscr/stand/swim (Kbot locomotion), RestorePosition, Open/Close/StartDoorOpen (door animations), ProcessFlames, BoomCalc(posxz, posy)/BoomExtend(posxz, posy)/ BoomReset/BoomToPad (crane transports; BoomCalc/BoomExtend signatures confirmed from Scriptor’s COMMON_FUNC table).
• Typical sleep arguments are 40–1500 ms, supporting the milliseconds reading.

Unknowns and caveats

• Established opcode distinctions: 0x10063000 has both a Scriptor internal-marker use and a real retail reserved pop-N arm. call-script is 0x10062000. 0x1005A000 is logical NOT and 0x10038000 is bitwise NOT [04 §4.3] [04 R-COB-04 §6]. Compiler emission and retail dispatch are separate evidence sources.
• Established runtime, limited compiler emission. AND, both word-XOR slots and bitwise NOT are traced interpreter operations [04 §4.3]. Their absence or placeholder spelling in Scriptor does not make their runtime behavior unknown; the compiler limitations are listed above.
• attach-unit / drop-unit stack shapes are established from retail bytecode (see the instruction table): all 48 retail call sites are uniform, including the piece = -1 idiom, and the compiler-supplied third value is always zero. It is not inert: the shared attach/drop commit writes its low two bits into the cargo’s committed mover-mode pair (0 attached, 1 grounded, 2 airborne) — [04 R-COB-03 §5].
• Sleep and wait runtime behavior is established in [04 §4.2] and [04 §4.6]. This file retains only the opcode and authored-duration encoding.
• Established header layout: file word 0x28 points to the trailing record table counted by word 0x14; it is not a first-script-name pointer. The record meaning and any runtime reader remain Unknown, as described in “The trailing record table” above; a nonempty authored table or a traced reader would settle that residual.
• Loader edges. The file is read whole; a missing or zero-length script is a null script pointer and the first unit created from the definition crashes ([04 R-COB-04 §8]). The five table pointers and the entries of the script-name, piece-name and trailing tables are biased by their declared counts with no bound, so a truncated file faults at load or at first execution. Full outcome table: [02 R-MALF-01 §2].
• Embedded comments (community Cobbler compiler only). Scriptor’s decompiler special-cases a code word 0x6C697542 (“cobbler crap” in its own source, #define COBBLER_CRAP) as a marker for 45 inline words of ASCII text — the community Cobbler compiler apparently embedded original BOS comments in the bytecode stream itself so round-tripping through decompile/recompile could restore them. Not a real instruction; any disassembler that walks retail bytecode won’t hit it (Cavedog’s own Scriptor never emits it), but a from-scratch COB reader could trip over it if ever fed a Cobbler-compiled community .cob.

Historical sources

• TA COB format note — container layout with the worked CorTruck.cob listing.
• COB commands note — opcode meanings and stack effects.
• BOS File Content Description, TA Design Guide — the BOS language, callbacks, sysvars and explosion flags.
• Historical community opcode cross-check only, not retail evidence: the tables in Spring (rts/Sim/Units/Scripts/CobThread.cpp, https://github.com/spring/spring) and kbot-io (formats/scripting/opcodes.go, https://github.com/coreprime/kbot-io).
• Cavedog’s own scripts/EXPTYPE.H and scripts/SFXTYPE.H (plus SMOKEUNIT.H, YARD.H, STATECHG.H, and all stock .bos sources), shipped inside totala1.hpi — the authoritative constants above.
• Scriptor v1 (RC1) source release — Cavedog’s own official BOS compiler/decompiler (not a third-party clean-room tool): Defs.h, CobCodec.cpp/.h (decompiler), CobScriptCode.cpp, BosCmdParse.cpp/ .h (compiler), and the shipped Compiler.cfg/Decompiler.cfg operator and callback-signature tables. Used above to resolve several opcode ambiguities (the reserved/unassigned slots, call-script’s real opcode, logical-vs-bitwise NOT) and to confirm MotionControl/SmokeUnit/ BoomCalc/BoomExtend/RequestState parameter signatures. Cross-checked against a second, independent community opcode table (commands.txt from a VB6 “COBBuilder” tool in Kinboat’s 1998 TA-formats source archive), which agrees on every opcode it lists.
• The same RC1 release’s BosCmdParse.cpp numeric converter and output writer, plus Scriptor.cpp settings defaults, establish the bounded conversion and zero-trailing-table observations above. Configurable defaults are not evidence of the settings used for shipped assets.
• Scaling constants verified against the retail ARMFLASH.BOS/ARMFLASH.COB pair from totala1.hpi; container examples from CORTRUCK.COB; corpus statistics from decoding all 835 retail COBs.

Pinned research and implementation

This page adapts the owning COB research at commit 72dcc02. The complete source snapshot preserves the original research, evidence IDs and confidence labels. All illustrative assets on this page are original authored examples; none are extracted retail assets.

Evidence labels distinguish established behavior, bounded observations, supported inferences, unknowns and Nanolathe host policy. A field appearing in an authored file does not by itself establish a runtime consumer.