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

Кожен юніт у Total Annihilation виконує скрипт, який анімує його частини (pieces), випускає спалахи пострілів, відтворює звукові ефекти й реагує на ігрові події. Мова вихідного коду — BOS («Basic Object Script»); скомпільований байткод, який насправді виконує рушій, — це COB («Cobble» — каламбур Cavedog на «compiled 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; family/op/flags залежать від опкоду. Гра не порівнює слово цілком: вона диспетчеризує за 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 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);
}

Відповідний дизасембльований код (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 додала ідентифікатори значень для відновлення магії, очок команд тощо; таблиця значень TA компактніша. Декомпілятор kbot наразі підписує набір TA; номери портів TAK ≥ 21 виводяться як числові літерали (які все одно проходять round-trip через асемблер). Повний перелік відмінностей див. у розділі TA: Kingdoms — відмінності COB v6.
• Змінні бувають двох видів: local_N (комірка стека, локальна для функції) і global_N (статична змінна юніта, що зберігається між викликами). Декомпілятор за замовчуванням виводить local_N / global_N; для читабельності перейменуйте їх у вихідному коді.
• Інструмент Cavedog Scriptor іноді вбудовує CURRENT_SPEED як літерал 29, що ламає скрипти на кшталт MoveWatcher після round-trip. Декомпілятор 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 виконує як no-op). 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) і порядку, в якому з'являються елементи.

Епілог TAK STACK_ALLOC ; RETURN, який у v6 генерує кожен return; без значення, обробляє компілятор: return; перетворюється на STACK_ALLOC ; RETURN за .version 6, а 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: ( before -- after ). Стовпець «Вбуд.» показує, скільки слів 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 — Krogoth (Core) — один із найбільших COB у грі (~25 КБ, понад 30 скриптів, складні анімації з багатьма частинами).
• ARMCOM — Arm Commander — типовий «насичений» юніт: цикли ходьби, наведення, спокою й будівництва, кілька видів зброї, обробка D-gun.
• CORTRUCK — Construction Truck — майже мінімальний COB, розібраний на цій сторінці (3 скрипти: SmokeUnit, Create, Killed).
• ARMSAM — Samson — добрий приклад юніта з турелью (turret1 повертається для наведення, анімація віддачі, синхронізація через wait-for-turn).

Будь-який із них можна декомпілювати локально командою kbot cob decompile scripts/<name>.cob, щойно задано контекст kbot.

Див. також#

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