COB / BOS — байткод скриптов юнитов

Каждый юнит в Total Annihilation выполняет скрипт, который анимирует его детали (pieces), выпускает вспышки выстрелов, проигрывает звуковые эффекты и реагирует на игровые события. Исходный язык называется BOS («Basic Object Script»), а скомпилированный байткод, который на самом деле выполняет движок, — COB («Cobble», каламбур Cavedog: «скомпилированный BOS»). На каждый юнит приходится один файл, названный по ObjectName юнита из его 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)
}

Два языка, один формат файла#

Движок видит только COB. BOS существует для удобства людей: когда вы «правите скрипт юнита», на самом деле вы правите исходник BOS, перекомпилируете его в COB и кладёте COB в дополнение .ufo с этим юнитом.

Минимальный пример:

// 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 превращает это в двоичный блоб. kbot cob disassemble -a показывает поток опкодов со стрелками потока управления сбоку, а kbot cob decompile делает обратное и восстанавливает BOS, который почти всегда проходит round-trip побайтно идентично (kbot cob roundtrip проверяет это на всём каталоге игры).

Исходник компилируется как скрипт TA (COB версии 4), если он не начинается с .version 6. Компилятор не записывает заглушку там, где TA 3.1c выполнила бы код неправильно, а отказывается компилировать: конструкции TA: Kingdoms (play-sound, Mission-Command, __tak_math_*, .sound_name) и % в скрипте TA — ошибки (в TA нет инструкции взятия остатка, а 0x10037000, слово, в которое раньше превращался %, у неё означает побитовый XOR). Ошибками считаются и неизвестные идентификаторы, и функции, которым нужно больше 32 ячеек стека, предусмотренных игрой. То, что компилируется, но заслуживает внимания, — функция, определённая дважды (каждый вызов привязывается к первому определению, как и при поиске имён в игре), — выводится как предупреждение вместе со всеми срабатываниями правил совместимости с TA. С --strict предупреждения приводят к ошибке команды. kbot cob assemble применяет те же проверки к листингам, написанным вручную.

Структура COB на диске#

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;

Дальше идут, в таком порядке:

┌─ 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

Поиск кода скрипта#

Таблица индексов кода содержит смещения в словах uint32, а не в байтах. Чтобы найти байткод скрипта номер i:

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

Скрипт заканчивается там, где начинается следующий (а последний — в начале таблицы индексов).

Поток опкодов#

COB — это стековая виртуальная машина. Большинство опкодов снимают аргументы со стека данных скрипта (у каждого скрипта он свой), делают свою работу и кладут результат обратно. У некоторых опкодов есть встроенные операнды (адреса переходов, номера деталей).

Каждый опкод — один uint32 такого вида:

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

Старший байт всегда 0x10, а семейство, операция и флаги у каждого опкода свои. Игра не сравнивает слово целиком: она выбирает обработчик по word & 0x100FF000, поэтому биты вне этой маски игнорируются, и 0x10064001 выполняется как JUMP (дизассемблер kbot записывает такое слово как JUMP@0x10064001, чтобы оно собиралось обратно без изменений). Затем PUSH (0x10021000) и POP (0x10023000) берут источник или приёмник из трёх младших битов. Каталог опкодов — scripting/opcodes.go в kbot-io: scripting.Opcodes() перечисляет все инструкции с их встроенными операндами и действием на стек.

Семейства опкодов#

Небольшая, но показательная подборка:

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 -- )

Модель параллельного выполнения#

У юнита может одновременно выполняться много скриптов — Walk, Aim, SmokeUnit, MoveWatcher и т. д. Они переключаются кооперативно:

• sleep <ticks> уступает управление на N тиков (по 1/30 с).
• wait-for-turn <piece> around <axis> уступает управление, пока деталь не закончит текущую анимацию turn. С wait-for-move так же.
• signal <n> завершает все скрипты, у которых signal_mask & n != 0.
• set-signal-mask <n> объявляет, какие сигналы интересуют текущий скрипт.

С помощью маски сигналов скрипты реализуют вытеснение: MoveWatcher устанавливает маску SIG_MOVE и следит за скоростью. Когда юнит останавливается, он посылает SIG_MOVE и аккуратно завершает анимации ходьбы, прежде чем начнётся поза бездействия.

Как вытеснение происходит на деле#

Распространённая схема: MoveUnit запускает скрипт анимации Walk, а когда движение прекращается, движок посылает SIG_MOVE, чтобы аккуратно всё убрать до запуска Idle. Последовательность:

   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)

Обратите внимание на три вещи:

1. Когда срабатывает сигнал, завершаются оба скрипта, установившие SIG_MOVE, включая сам MoveUnit (это неважно: свою работу он уже сделал).
2. Посылающий скрипт (MoveUnit) живёт достаточно долго, чтобы отправить сигнал, прежде чем будет завершён: среда выполнения проверяет маски после возврата из опкода signal.
3. Idle не устанавливает SIG_MOVE, поэтому следующий signal SIG_MOVE его не затронет.

Разбор примера — cortruck.cob (строительная машина CORE)#

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);
}

Соответствующий листинг дизассемблера (kbot cob disassemble -a -s SmokeUnit) показывает реальный поток опкодов со стрелками JUMP_IF_FALSE/JUMP, проходящими через тела while/if. Это полезно, когда вывод декомпилятора неоднозначен.

Линтинг#

kbot cob lint (и вкладка Lint в обозревателе ресурсов) запускает стандартный набор правил kbot-io: правила стиля, выведенные из реальных ошибок в скриптах самой Cavedog и в патчах модов от сообщества, две проверки на уровне файла и — для каждого COB, который не объявляет версию 6, — правила совместимости с TA 3.1c. Каталог правил стиля:

Правила совместимости с TA сообщают о том, на чём TA 3.1c даёт сбой или что она выполняет иначе. Это ошибки, они попадают в вывод SARIF при --ci, как и остальные, и пропускают файлы TA: Kingdoms (версии 6):

Полные описания правил — в README kbot. Декомпилятор намеренно сохраняет исходную нумерацию переменных и деталей, чтобы цикл декомпиляция→линтинг→исправление→компиляция высвечивал моды, которым нужно сопровождение.

Подводные камни#

• Все смещения в заголовке COB — абсолютные смещения в файле, а записи ScriptCodeIndexArray — смещения в словах внутри секции кода. Их легко перепутать.
• Номера деталей в опкодах — это индексы в таблице имён деталей, а не строки. COB хранит имена в пуле строк, а среда выполнения ради скорости работает с индексами.
• Опкоды get UNIT_VALUE в TA и TA: Kingdoms немного различаются. TA: Kingdoms добавила ID значений для восстановления магии, очков командования и т. д., а таблица значений TA компактнее. Декомпилятор kbot сейчас подписывает набор TA, а номера портов TAK ≥ 21 выводит числовыми литералами (которые всё равно проходят round-trip через ассемблер). Все отличия — в разделе TA: Kingdoms — отличия COB v6.
• Переменные бывают двух видов: local_N (ячейка стека, локальная для функции) и global_N (статическая переменная юнита, которая сохраняется между вызовами). По умолчанию декомпилятор выводит local_N / global_N; для читаемости переименуйте их в исходнике.
• Инструмент Cavedog Scriptor иногда подставляет вместо CURRENT_SPEED литерал 29, из-за чего после round-trip ломаются скрипты в духе MoveWatcher. Декомпилятор kbot восстанавливает символьное имя; если round-trip через Scriptor неизбежен, ставьте скобки: (get CURRENT_SPEED) > 5.

Типичные размеры#

TA: Kingdoms — отличия COB v6#

Структура файла v6#

┌─ 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)

8-байтовый подзаголовок находится между OffsetToNameArray (концом канонического заголовка из 11 DWORD на байте 44) и началом секции кода (OffsetToScriptCode, обычно 0x34 = 52). В нём два uint32 в little-endian:

Каждая запись таблицы смещений имён звуков — абсолютное смещение в файле строки, завершённой NUL, в пуле строк. Это строки вроде "SetMission o 1, s", "create ARASWORD", "ARROW10". Байткод ссылается на них по индексу (а не по смещению) через опкод MISSION_COMMAND (см. приложение C). Таблица называется массивом имён звуков, потому что канонический компилятор Scriptor регистрирует в ней строки через действие ADDSOUND, но на самом деле там лежат командные строки движка, а не имена звуковых файлов.

Представление в kbot#

scripting.COB хранит имена звуков в структурированном поле []string, без сохранения непрозрачных байтов. Всё остальное (значения подзаголовка, таблица смещений, смещения отдельных строк в пуле) при записи восстанавливается из этого списка:

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

Для файлов v4 срез всегда nil, а подзаголовок и таблица смещений имён звуков в вывод не попадают.

Дизассемблер и декомпилятор выводят каждую строку директивой .sound_name, чтобы строки переживали round-trip через .coba и .bos:

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

Новые опкоды#

Файлы .cob из TAK используют инструкции, для которых в TA 3.1c нет обработчика (PLAY_SOUND, MISSION_COMMAND и операторы TAK_MATH_*), а также DONT_SHADOW, который TA выполняет как пустую операцию (no-op). Их точная семантика в игре не задокументирована, но двоичная структура (размер + число встроенных параметров) известна по всем оригинальным .cob из TAK, и этого достаточно, чтобы round-trip дизассемблирование→ассемблирование восстанавливал исходные байты в точности. Полный справочник — в приложении C.

Состояние round-trip#

Синтаксис BOS для расширений TAK#

Декомпилятор выводит эти псевдовызовы, чтобы COB из TAK проходили round-trip через BOS. Компилятор принимает тот же синтаксис, но только после .version 6 (кроме dont-shadow: TA выполняет его как пустую операцию). dont-shadow и Mission-Command — канонические ключевые слова TAK из Scriptor, а у математических опкодов в Scriptor нет задокументированного имени (он обозначает их ?? и ????), поэтому kbot оставляет заглушки __tak_math_*:

// 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 — имя звука в виде строки в кавычках: компилятор ищет его в таблице имён звуков (поэтому соответствующая директива .sound_name должна стоять в файле раньше). Остальные аргументы кладутся на стек, и их забирает движок.

Остальные метаданные v6 передаются двумя директивами в начале файла:

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

.version выводится всегда (чтобы файлы TA v4 проходили round-trip через тот же конвейер без изменений). Каждая .sound_name — одна запись в таблице имён звуков этого COB; программа записи заново строит 8-байтовый подзаголовок и таблицу смещений имён звуков по len(SoundNames) и порядку, в котором идут записи.

Эпилог STACK_ALLOC ; RETURN, который в TAK порождает в v6 каждый return; без значения, обрабатывается компилятором: при .version 6 return; превращается в STACK_ALLOC ; RETURN, а return <expr>; — в <expr> ; RETURN без префикса (как у компилятора Cavedog).

Проверьте на своей установке:

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

Символьные имена портов после 20-го#

Скрипты TA: Kingdoms используют порты get_unit_value вплоть до 46 (CURRENT_SPEED, VETERAN_LEVEL, поля запаса магии и т. д.). Декомпилятор kbot сейчас подписывает символьными именами только порты 1–20 (см. приложение B), а порты TAK ≥ 21 выводит числовыми литералами. В байткоде они в любом случае хранятся как целые числа, поэтому на round-trip это не влияет — страдает только читаемость BOS. Добавление имён портов TAK отслеживается отдельно.

Приложение A — полный справочник опкодов#

Все инструкции, которые выполняет TA или TA: Kingdoms. Эталонный источник — formats/scripting/opcodes.go в kbot-io. Действие на стек записано в нотации Forth ( до -- после ). Столбец Inline показывает, сколько слов uint32 следует за самим словом опкода (они читаются при декодировании, а не снимаются со стека).

Анимация — работа с деталями (0x100x)#

Операции ожидания (0x101x)#

Работа со стеком (0x102x)#

Арифметика (0x103x)#

В TA нет инструкции взятия остатка: % в скрипте TA — ошибка компиляции. 0x10039000–0x1003B000 — операторы TA: Kingdoms TAK_MATH_* (приложение C), на которых TA даёт сбой.

Запросы к движку (0x104x)#

Каталог портов — в приложении B.

Сравнения и логические операции (0x105x)#

Поток управления и параллельное выполнение (0x106x)#

offset у JUMP / JUMP_IF_FALSE — смещение в байтах относительно OffsetToScriptCode, а не относительно текущей инструкции.

Эффекты (0x107x)#

Операции установки (0x108x)#

Кодирование опкодов#

Каждое слово опкода имеет вид 0x10CCSSFF, где:

• CC — байт категории (анимация, математика, поток управления, …).
• SS — полубайт подкоманды в старшем полубайте второго сверху байта.
• FF — байт флагов.

Игра выбирает обработчик по word & 0x100FF000 и игнорирует остальные биты, так что слово вроде 0x10064001 выполняется как JUMP. Дизассемблер записывает его как JUMP@0x10064001, а ассемблер читает обратно в то же слово. PUSH и POP берут источник или приёмник из трёх младших битов: PUSH принимает 1 (константа), 2 (локальная) и 4 (статическая), POP — 2 и 4, а при любом другом значении скрипт падает.

Слова, которые не выполняет ни одна игра, дизассемблер выводит как UNKNOWN_0x10xxxxxx (и о них сообщает ta-unknown-opcode). Если вы встретите такое в настоящем файле, пожалуйста, откройте issue и приложите образец COB.

Приложение B — таблица портов get_unit_value#

20 портов, которые декомпилятор kbot сейчас подписывает символьными именами. В настоящей TA их ~80, TA: Kingdoms добавляет ещё ~15 для величин, связанных с магией. Всё выше порта 20 декомпилятор пока выводит числовыми литералами.

Среди портов с бо́льшими номерами — CURRENT_SPEED (29, тот самый, который Cavedog Scriptor печально известным образом подставляет литералом; см. «Подводные камни» выше), MAX_ID, UNIT_TEAM, UNIT_BUILD_PERCENT, BUILDER, UNIT_ALLIED и многие другие. Полный список есть во внутренней документации Cavedog, а самый полный публичный каталог — в вики сообщества на форумах TAUniverse.

TA: Kingdoms расширяет диапазон портов. Порты, которые есть только в TAK и которые распознаёт kbot (декомпилятор выводит символьное имя, компилятор принимает его на входе), взяты из таблицы [UNITVLAUES] в Scriptor:

Приложение C — опкоды TA: Kingdoms#

Кодирование (кратко)#

Каждое слово опкода COB имеет вид 0x10CCSSFF, где CC — категория, а SS — подкоманда. Эти опкоды TAK просто занимают ранее не использованные слоты CC:SS внутри существующих категорий и не вводят нового байта категории. DONT_SHADOW находится в категории анимации рядом с DONT_CACHE/DONT_SHADE, а MISSION_COMMAND — в категории эффектов рядом с EXPLODE и PLAY_SOUND.

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

Живые примеры в справочном каталоге#

Настоящие юниты, на которых видны крайние случаи формата. Откройте их, чтобы увидеть реальную сложность скриптов, а не учебные примеры из текста:

• CORKROG — Крогот (CORE) — один из самых больших COB в игре (~25 КБ, 30+ скриптов, сложные анимации из множества деталей).
• ARMCOM — Командир ARM — типичный «насыщенный» юнит: циклы ходьбы, прицеливания, бездействия и строительства, несколько видов оружия, работа с D-пушкой.
• CORTRUCK — строительная машина — почти минимальный COB, который разобран на этой странице (3 скрипта: SmokeUnit, Create, Killed).
• ARMSAM — Самсон — хороший пример юнита с турелью (поворот turret1 для наведения, анимация отдачи, синхронизация через wait-for-turn).

Любой из них можно декомпилировать локально командой kbot cob decompile scripts/<name>.cob, когда контекст kbot задан.

См. также#

• 3DO — имена деталей, на которые ссылаются скрипты COB, хранятся в .3do юнита.
• FBI — файл метаданных юнита. Его ObjectName связывает COB с 3DO, а Sounds задают звуковой банк, который может проигрывать скрипт.
• Таблица правил cob lint в описании командной строки kbot.
• Глоссарий — деталь (piece), ось (axis), маска сигналов (signal mask), тик.