COB / BOS — bytecode dos scripts das unidades

Todas as unidades do Total Annihilation correm um script que anima as suas peças, emite os clarões das armas, toca efeitos sonoros e responde aos eventos do jogo. A linguagem de origem é o BOS ("Basic Object Script"); o bytecode compilado que o motor realmente executa é o COB ("Cobble", o trocadilho da Cavedog para "BOS compilado"). Um ficheiro por unidade, com o nome do ObjectName que a unidade tem no seu 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)
}

Duas linguagens, um formato de ficheiro#

O motor só vê o COB. O BOS é uma comodidade para os autores humanos: quando "edita o script de uma unidade", está na verdade a editar o código-fonte BOS, a recompilá-lo para COB e a distribuir o COB no complemento .ufo da unidade.

Um exemplo mínimo:

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

O kbot cob compile traduz isto para um blob binário. O kbot cob disassemble -a mostra o fluxo de opcodes lado a lado com setas de fluxo de controlo; o kbot cob decompile faz o inverso e recupera um BOS que, quase sempre, faz a ida e volta idêntico byte a byte (o kbot cob roundtrip confirma-o em todo o catálogo do jogo).

Um código-fonte compila como script do TA (COB versão 4), a não ser que comece por .version 6. O compilador recusa o que o TA 3.1c executaria mal, em vez de pôr algo provisório no lugar: as construções do TA: Kingdoms (play-sound, Mission-Command, __tak_math_*, .sound_name) e % são erros num script do TA (o TA não tem instrução de módulo, e 0x10037000, a palavra em que % se convertia, é o seu XOR bit a bit), tal como os identificadores desconhecidos e as funções que precisam de mais do que as 32 posições da pilha do jogo. O que ainda compila mas merece atenção — uma função definida duas vezes (cada chamada liga-se à primeira definição, como faz a procura de nomes do jogo) — é mostrado como aviso, juntamente com qualquer resultado das regras de lint de compatibilidade com o TA; --strict faz com que os avisos façam falhar o comando. O kbot cob assemble aplica as mesmas verificações às listagens escritas à mão.

Estrutura do COB no disco#

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;

Seguem-se, por esta disposição:

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

Resolver um script#

A tabela de índices de código contém deslocamentos em palavras uint32, e não em bytes. Para encontrar o bytecode do script número i:

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

O script termina onde começa o seguinte (ou, no caso do último script, no início da tabela de índices).

O fluxo de opcodes#

O COB é uma máquina virtual baseada em pilha. A maioria dos opcodes retira argumentos de uma pilha de dados própria de cada script, faz o seu trabalho e volta a pôr um resultado na pilha. Alguns opcodes têm operandos em linha (destinos de salto, números de peças).

Cada opcode é um uint32 com esta disposição:

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

O byte alto é sempre 0x10; a família, a operação e as flags variam de opcode para opcode. O jogo não compara a palavra inteira: escolhe a instrução por word & 0x100FF000, por isso os bits fora dessa máscara são ignorados e 0x10064001 é executado como JUMP (o desmontador do kbot escreve uma palavra destas como JUMP@0x10064001, para que volte a ser montada sem alterações). O PUSH (0x10021000) e o POP (0x10023000) leem depois a sua origem ou destino nos três bits baixos. O scripting/opcodes.go do kbot-io é o catálogo; scripting.Opcodes() lista todas as instruções com os seus operandos em linha e o seu efeito na pilha.

Famílias de opcodes#

Uma amostra pequena, mas representativa:

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

Modelo de concorrência#

Uma unidade pode ter muitos scripts a correr em simultâneo — Walk, Aim, SmokeUnit, MoveWatcher, etc. São escalonados de forma cooperativa:

• sleep <ticks> cede a vez durante N ticks (1/30 s cada).
• wait-for-turn <piece> around <axis> cede a vez até essa peça terminar a sua animação turn atual. O mesmo para wait-for-move.
• signal <n> mata todos os scripts cujo signal_mask & n != 0.
• set-signal-mask <n> declara em que sinais o script atual está interessado.

A máscara de sinais é a forma como os scripts implementam a preempção: o MoveWatcher define a máscara SIG_MOVE e vigia a velocidade; quando a unidade para, envia SIG_MOVE, o que mata as animações de marcha de forma limpa antes de começar a pose de repouso.

Como a preempção funciona na prática#

Um padrão comum: o MoveUnit lança um script de animação Walk; quando o movimento para, o motor envia SIG_MOVE para limpar tudo antes de o Idle começar. A sequência:

   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)

Três coisas a notar:

1. Os dois scripts que definem SIG_MOVE são mortos quando o sinal é disparado, incluindo o próprio MoveUnit (não faz mal; o seu trabalho está feito).
2. O script que sinaliza (MoveUnit) sobrevive o tempo suficiente para enviar o sinal antes de ser morto; o runtime verifica as máscaras depois de o opcode signal regressar.
3. O Idle não define SIG_MOVE, por isso o próximo signal SIG_MOVE não lhe toca.

Exemplo comentado — cortruck.cob (Camião de Construção 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);
}

A desmontagem correspondente (kbot cob disassemble -a -s SmokeUnit) mostra o fluxo real de opcodes, com as setas JUMP_IF_FALSE/JUMP a atravessar os corpos dos while/if: útil quando o resultado do descompilador é ambíguo.

Lint#

O kbot cob lint (e o separador Lint do explorador de recursos) aplica o conjunto de regras predefinido do kbot-io: regras de estilo tiradas de erros reais nos próprios scripts da Cavedog e de correções de mods enviadas pela comunidade, duas verificações ao nível do ficheiro e — em todos os COB que não declarem a versão 6 — as regras de compatibilidade com o TA 3.1c. O catálogo de estilo:

As regras de compatibilidade com o TA assinalam aquilo em que o TA 3.1c falha ou que executa de outra maneira. São erros, aparecem na saída SARIF de --ci como as outras e ignoram os ficheiros do TA: Kingdoms (versão 6):

As descrições completas das regras estão no README do kbot. O descompilador preserva de propósito a numeração original das variáveis e das peças, para que um ciclo descompilar→lint→corrigir→compilar destaque os mods que precisam de manutenção.

Armadilhas#

• Todos os deslocamentos do cabeçalho do COB são deslocamentos absolutos no ficheiro, mas as entradas de ScriptCodeIndexArray são deslocamentos em palavras dentro da secção de código. É fácil confundi-los.
• Os números das peças nos opcodes são índices na tabela de nomes das peças, e não cadeias. O COB guarda as cadeias dos nomes todas juntas (o conjunto de nomes); o runtime usa índices por rapidez.
• Os opcodes get UNIT_VALUE variam subtilmente entre o TA e o TA: Kingdoms. O TA: Kingdoms acrescentou IDs de valores para a regeneração de magia, os pontos de comando, etc.; a tabela de valores do TA é mais compacta. Por agora, o descompilador do kbot dá nomes ao conjunto do TA; as portas do TAK ≥ 21 são escritas como literais numéricos (que continuam a fazer a ida e volta pelo montador). Todas as diferenças estão em TA: Kingdoms — diferenças do COB v6.
• As variáveis são de dois tipos: local_N (posição da pilha local à função) e global_N (variável estática de cada unidade, que persiste entre chamadas). Por omissão, o descompilador escreve local_N / global_N; mude-lhes o nome no código-fonte para facilitar a leitura.
• A ferramenta Scriptor da Cavedog às vezes substitui CURRENT_SPEED pelo literal 29, o que estraga os scripts do tipo MoveWatcher depois de uma ida e volta. O descompilador do kbot repõe o nome simbólico; se tiver mesmo de fazer a ida e volta pelo Scriptor, use parênteses: (get CURRENT_SPEED) > 5.

Tamanhos típicos#

TA: Kingdoms — diferenças do COB v6#

Estrutura do ficheiro 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)

O subcabeçalho de 8 bytes fica entre OffsetToNameArray (o fim do cabeçalho canónico de 11 DWORD, no byte 44) e o início da secção de código (OffsetToScriptCode, normalmente 0x34 = 52). Contém dois uint32 little-endian:

Cada entrada da tabela de deslocamentos dos nomes de sons é o deslocamento absoluto no ficheiro de uma cadeia terminada em NUL no conjunto de nomes — coisas como "SetMission o 1, s", "create ARASWORD", "ARROW10". O bytecode refere-as pelo índice (e não pelo deslocamento) através do opcode MISSION_COMMAND (veja o Apêndice C). A tabela chama-se vetor de nomes de sons porque o compilador canónico Scriptor regista cadeias nela através da ação ADDSOUND; o conteúdo real são cadeias de comandos do motor, e não nomes de ficheiros de áudio.

A representação no kbot#

O scripting.COB guarda os nomes de sons num campo estruturado []string, sem preservar bytes opacos. Tudo o resto (os valores do subcabeçalho, a tabela de deslocamentos, o deslocamento de cada cadeia no conjunto) é reconstruído a partir desta lista na escrita:

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

Nos ficheiros v4, a slice é sempre nil, e tanto o subcabeçalho como a tabela de deslocamentos dos nomes de sons são omitidos na saída.

O desmontador e o descompilador escrevem cada cadeia como uma diretiva .sound_name, para que sobrevivam a uma ida e volta por .coba e .bos:

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

Opcodes novos#

Os ficheiros .cob do TAK usam instruções para as quais o TA 3.1c não tem tratamento (PLAY_SOUND, MISSION_COMMAND e os operadores TAK_MATH_*), além de DONT_SHADOW, que o TA executa como uma operação nula. A sua semântica exata no jogo não está documentada, mas a sua estrutura binária (tamanho + número de parâmetros em linha) é conhecida a partir de todos os .cob comerciais do TAK, o que chega para que a ida e volta desmontar→montar recupere os bytes originais tal e qual. A referência completa está no Apêndice C.

Estado da ida e volta#

Superfície BOS para as extensões do TAK#

O descompilador escreve estas pseudochamadas para que os COB do TAK façam a ida e volta pelo BOS. O compilador aceita a mesma sintaxe, mas só depois de .version 6 (exceto dont-shadow, que o TA executa como operação nula). dont-shadow e Mission-Command usam as palavras-chave canónicas do TAK no Scriptor; os opcodes matemáticos não têm nome documentado no Scriptor (que lhes chama ?? e ????), por isso o kbot mantém os nomes provisórios __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

O primeiro argumento de Mission-Command é o nome de som como cadeia entre aspas: o compilador procura-o na tabela de nomes de sons (por isso a diretiva .sound_name correspondente tem de aparecer antes no ficheiro). Os restantes argumentos são postos na pilha e o motor consome-os.

Duas diretivas no início do ficheiro trazem o resto dos metadados v6:

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

A .version é sempre escrita (para que os ficheiros v4 do TA façam a ida e volta idênticos pelo mesmo processo). Cada .sound_name é uma entrada na tabela de nomes de sons do COB; o escritor reconstrói o subcabeçalho de 8 bytes e a tabela de deslocamentos dos nomes de sons a partir de len(SoundNames) e da ordem pela qual as entradas aparecem.

O epílogo STACK_ALLOC ; RETURN do TAK, que cada return; sem valor produz na v6, é tratado pelo compilador: return; traduz-se em STACK_ALLOC ; RETURN quando há .version 6, e return <expr>; traduz-se em <expr> ; RETURN sem prefixo (como faz o compilador da Cavedog).

Reproduza-o na sua instalação:

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

Símbolos das portas acima da porta 20#

Os scripts do TA: Kingdoms usam portas de get_unit_value até à 46 (CURRENT_SPEED, VETERAN_LEVEL, campos da reserva de magia, etc.). Por agora, o descompilador do kbot só dá nomes simbólicos às portas 1–20 (veja o Apêndice B); as portas do TAK ≥ 21 são escritas como literais numéricos. O bytecode guarda-as sempre como inteiros, por isso as idas e voltas não são afetadas: só a legibilidade do BOS sofre. A adição dos nomes das portas do TAK é acompanhada à parte.

Apêndice A — referência completa de opcodes#

Todas as instruções que o TA ou o TA: Kingdoms executam. A fonte de referência é o formats/scripting/opcodes.go do kbot-io. A notação da pilha segue o estilo do Forth, ( before -- after ) (antes -- depois). As colunas Em linha mostram quantas palavras uint32 se seguem à própria palavra do opcode (consumidas durante a descodificação, e não retiradas da pilha).

Animação — manipulação das peças (0x100x)#

Operações de espera (0x101x)#

Manipulação da pilha (0x102x)#

Aritmética (0x103x)#

O TA não tem instrução de módulo: % é um erro de compilação num script do TA. 0x10039000–0x1003B000 são os operadores TAK_MATH_* do TA: Kingdoms (Apêndice C); o TA falha com eles.

Consultas ao motor (0x104x)#

O catálogo das portas está no Apêndice B.

Comparação e lógica (0x105x)#

Fluxo de controlo e concorrência (0x106x)#

O offset de JUMP / JUMP_IF_FALSE é um deslocamento em bytes relativo a OffsetToScriptCode, e não à instrução atual.

Efeitos (0x107x)#

Operações de definição (0x108x)#

Codificação dos opcodes#

Cada palavra de opcode é 0x10CCSSFF, em que:

• CC = o byte da categoria (animação, matemática, fluxo de controlo, …).
• SS = o nibble do subcomando, no nibble alto do segundo byte a contar de cima.
• FF = o byte das flags.

O jogo escolhe a instrução por word & 0x100FF000 e ignora os outros bits, por isso uma palavra como 0x10064001 é executada como JUMP; o desmontador escreve-a JUMP@0x10064001 e o montador volta a lê-la como a mesma palavra. O PUSH e o POP leem a sua origem ou destino nos três bits baixos: o PUSH aceita 1 (constante), 2 (local) e 4 (estática), o POP aceita 2 e 4, e qualquer outro valor faz o script falhar.

As palavras que nenhum jogo executa são mostradas pelo desmontador como UNKNOWN_0x10xxxxxx (e assinaladas por ta-unknown-opcode); se encontrar uma num ficheiro real, abra uma issue com o COB de exemplo.

Apêndice B — tabela de portas de get_unit_value#

As 20 portas a que o descompilador do kbot dá, por agora, nomes simbólicos. O TA real tem ~80; o TA: Kingdoms acrescenta mais ~15 para grandezas ligadas à magia. Tudo o que estiver acima da porta 20 aparece hoje como literal numérico no resultado do descompilador.

As portas mais altas incluem CURRENT_SPEED (29 — que o Scriptor da Cavedog ficou famoso por substituir por um literal; veja as Armadilhas acima), MAX_ID, UNIT_TEAM, UNIT_BUILD_PERCENT, BUILDER, UNIT_ALLIED e muitas mais. A lista completa está na documentação interna da Cavedog; a wiki da comunidade nos fóruns do TAUniverse tem o catálogo público mais completo.

O TA: Kingdoms alarga o intervalo de portas. As portas exclusivas do TAK que o kbot reconhece (o descompilador mostra o nome simbólico; o compilador aceita-o como entrada) foram tiradas da tabela [UNITVLAUES] do Scriptor:

Apêndice C — opcodes do TA: Kingdoms#

Codificação (resumo)#

Cada palavra de opcode do COB é 0x10CCSSFF, em que CC é a categoria e SS o subcomando: estes opcodes do TAK limitam-se a ocupar posições CC:SS até então livres dentro das categorias existentes, em vez de introduzirem um byte de categoria novo. O DONT_SHADOW vive na categoria de animação, ao lado de DONT_CACHE/DONT_SHADE, e o MISSION_COMMAND na categoria de efeitos, ao lado de EXPLODE e PLAY_SOUND.

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

Exemplos reais no catálogo de referência#

Unidades reais que levam o formato aos extremos: abra-as para ver a complexidade real dos scripts, em vez de exemplos escritos no texto.

• CORKROG — Krogoth (CORE) — um dos maiores COB do jogo (~25 KB, mais de 30 scripts, animações complexas com várias peças).
• ARMCOM — Comandante ARM — unidade "rica" representativa: ciclos de marcha/pontaria/repouso/ construção, várias armas, tratamento do D-gun.
• CORTRUCK — Camião de Construção — COB quase mínimo, usado como exemplo nesta página (3 scripts: SmokeUnit, Create, Killed).
• ARMSAM — Samson — bom exemplo de uma unidade com torre (turret1 roda para apontar, animação de recuo, sincronização com wait-for-turn).

Depois de definir um contexto do kbot, descompile qualquer uma localmente com kbot cob decompile scripts/<name>.cob.

Ver também#

• 3DO — os nomes das peças referidos pelos scripts COB estão no .3do da unidade.
• FBI — o ficheiro de metadados da unidade. O ObjectName que lá está liga o COB a um 3DO; Sounds define o banco de áudio que o script pode tocar.
• A tabela de regras de cob lint da linha de comandos do kbot.
• Glossário — piece, axis, signal mask, tick.