COB / BOS — bytecode de script das unidades

Toda unidade do Total Annihilation roda um script que anima suas peças, emite os clarões das armas, toca efeitos sonoros e responde aos eventos do jogo. A linguagem-fonte é o BOS ("Basic Object Script"); o bytecode compilado que o motor de fato executa é o COB ("Cobble" — trocadilho da Cavedog para "BOS compilado"). Um arquivo por unidade, com o nome do ObjectName do FBI da unidade.

# 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 arquivo#

O motor só enxerga COB. O BOS é uma conveniência para os autores humanos: quando você "edita o script de uma unidade", na verdade está editando o código-fonte BOS, recompilando para COB e distribuindo o COB no add-on .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;
    }
}

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

Um código-fonte é compilado como script do TA (COB versão 4), a menos que comece com .version 6. O compilador recusa o que o TA 3.1c executaria errado, em vez de gravar um marcador provisório: as construções do TA: Kingdoms (play-sound, Mission-Command, __tak_math_*, .sound_name) e o % são erros num script do TA (o TA não tem instrução de módulo, e 0x10037000, a palavra em que o % costumava se transformar, é o seu XOR bit a bit), assim como identificadores desconhecidos e funções que precisam de mais do que as 32 posições de pilha do jogo. O que ainda compila, mas merece atenção — uma função definida duas vezes (toda chamada se liga à primeira definição, como faz a busca de nomes do jogo) — é impresso como aviso, junto com qualquer ocorrência das regras de verificação de compatibilidade com o TA; --strict faz os avisos falharem o comando. 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;

Depois vêm, nesta 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

Localizar um script#

A tabela de índices de código contém offsets em palavras uint32, e não offsets 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 próximo (ou, no caso do último, no início da tabela de índices).

O fluxo de opcodes#

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

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

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

O byte mais alto é sempre 0x10; família/op/flags variam de opcode para opcode. O jogo não compara a palavra inteira: ele despacha por word & 0x100FF000, então os bits fora dessa máscara são ignorados e 0x10064001 é executado como JUMP (o desmontador do kbot escreve essa palavra como JUMP@0x10064001 para que ela seja montada de volta sem alterações). PUSH (0x10021000) e POP (0x10023000) leem então 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 seus operandos embutidos e 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 vários scripts rodando ao mesmo tempo — Walk, Aim, SmokeUnit, MoveWatcher etc. Eles são escalonados de forma cooperativa:

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

A máscara de sinais (signal mask) é como os scripts implementam a preempção: o MoveWatcher define a máscara SIG_MOVE e acompanha a velocidade; quando a unidade para de se mover, ele envia SIG_MOVE, matando de forma limpa as animações de caminhada antes de começar a pose de repouso.

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

Um padrão comum: MoveUnit dispara um script de animação Walk; quando o movimento para, o motor envia SIG_MOVE para fazer uma limpeza organizada antes de 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 — inclusive o próprio MoveUnit (não tem importância; o trabalho dele já terminou).
2. O script que sinaliza (MoveUnit) sobrevive o bastante para enviar o sinal antes de ser morto; o runtime verifica as máscaras depois que o opcode signal retorna.
3. Idle não define SIG_MOVE, então o próximo signal SIG_MOVE não o afeta.

Exemplo comentado: cortruck.cob (Caminhã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 setas de JUMP_IF_FALSE/JUMP atravessando os corpos dos while/if — útil quando a saída do descompilador é ambígua.

Verificação (lint)#

kbot cob lint (e a aba Lint do explorador de recursos) roda o conjunto de regras padrão do kbot-io: regras de estilo tiradas de bugs reais nos próprios scripts da Cavedog e em patches de mods enviados pela comunidade, duas verificações no nível do arquivo e — para todo COB que não declare 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 apontam o que faz o TA 3.1c falhar ou se comportar de outro jeito. Elas são erros, aparecem na saída SARIF de --ci como as demais e ignoram os arquivos 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→verificar→corrigir→compilar destaque os mods que precisam de manutenção.

Armadilhas#

• Todos os offsets do cabeçalho do COB são offsets absolutos no arquivo, mas as entradas de ScriptCodeIndexArray são offsets em palavras dentro da seção de código. É fácil confundi-los.
• Os números de peças nos opcodes são índices na tabela de nomes de peças, e não strings. O COB traz os nomes num pool de strings; o runtime usa índices por questão de velocidade.
• Os opcodes get UNIT_VALUE variam sutilmente entre o TA e o TA: Kingdoms. O TA: Kingdoms acrescentou IDs de valores para regeneração de magia, pontos de comando etc.; a tabela de valores do TA é mais compacta. O descompilador do kbot hoje rotula o conjunto do TA; as portas do TAK ≥ 21 saem como literais numéricos (que continuam fazendo a ida e volta pelo montador). Veja TA: Kingdoms — diferenças do COB v6 para todas as diferenças.
• As variáveis vêm em dois tipos: local_N (posição de pilha local da função) e global_N (estática por unidade, que persiste entre as chamadas). O descompilador emite local_N / global_N por padrão; renomeie-as no código-fonte para facilitar a leitura.
• A ferramenta Scriptor da Cavedog às vezes embute CURRENT_SPEED como o literal 29, o que quebra scripts no estilo de MoveWatcher depois de uma ida e volta. O descompilador do kbot restaura o nome simbólico; se você precisar 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 arquivo 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 (fim do cabeçalho canônico de 11 DWORDs, no byte 44) e o início da seção de código (OffsetToScriptCode, normalmente 0x34 = 52). Ele traz dois uint32 little-endian:

Cada entrada da tabela de offsets de nomes de sons é um offset absoluto no arquivo de uma string terminada em NUL no pool de strings — coisas como "SetMission o 1, s", "create ARASWORD", "ARROW10". O bytecode se refere a elas pelo índice (não pelo offset) por meio do opcode MISSION_COMMAND (veja o Apêndice C). A tabela se chama array de nomes de sons porque o compilador canônico, o Scriptor, registra strings nela pela ação ADDSOUND; o conteúdo real são strings de comando do motor, e não nomes de arquivos de áudio.

A representação no kbot#

scripting.COB guarda os nomes de sons num campo estruturado []string — sem preservar bytes opacos. Todo o resto (os valores do subcabeçalho, a tabela de offsets, os offsets de cada string no pool) é reconstruído a partir dessa lista na gravação:

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

Nos arquivos v4, a slice é sempre nil, e tanto o subcabeçalho quanto a tabela de offsets de nomes de sons são omitidos da saída.

O desmontador e o descompilador emitem cada string como uma diretiva .sound_name, para que elas 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 arquivos .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 no-op (sem efeito). A semântica exata deles no jogo não está documentada, mas o formato binário (tamanho + quantidade de parâmetros embutidos) é conhecido a partir de todos os .cob comerciais do TAK, o que basta para que a ida e volta desmontar→montar recupere os bytes originais exatamente. Veja o Apêndice C para a referência completa.

Situação da ida e volta#

A sintaxe BOS das extensões do TAK#

O descompilador emite estas pseudochamadas para que os COBs 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 no-op). 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 (ele os rotula como ?? e ????), então o kbot mantém os marcadores 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 do som como string entre aspas — o compilador o procura na tabela de nomes de sons (por isso a diretiva .sound_name correspondente precisa aparecer antes no arquivo). Os demais argumentos são empilhados, e o motor os consome.

Duas diretivas no topo do arquivo carregam o restante dos metadados do v6:

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

.version é sempre emitida (para que os arquivos v4 do TA façam a ida e volta de forma idêntica pelo mesmo processo). Cada .sound_name é uma entrada na tabela de nomes de sons do COB; o gravador reconstrói o subcabeçalho de 8 bytes e a tabela de offsets de nomes de sons a partir de len(SoundNames) e da ordem em que as entradas aparecem.

O epílogo STACK_ALLOC ; RETURN que todo return; sem valor emite no v6 do TAK é tratado pelo compilador: return; vira STACK_ALLOC ; RETURN quando há .version 6, e return <expr>; vira <expr> ; RETURN sem prefixo (como faz o compilador da Cavedog).

Reproduza na sua própria instalação:

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

Símbolos de portas acima da porta 20#

Os scripts do TA: Kingdoms usam portas de get_unit_value até a 46 (CURRENT_SPEED, VETERAN_LEVEL, campos da reserva de magia etc.). O descompilador do kbot hoje só rotula simbolicamente as portas 1–20 (veja o Apêndice B); as portas do TAK ≥ 21 saem como literais numéricos. O bytecode as guarda como inteiros de qualquer forma, então as idas e voltas não são afetadas — só a legibilidade do BOS sofre. O acréscimo dos nomes das portas do TAK é acompanhado à parte.

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

Todas as instruções que o TA ou o TA: Kingdoms executam. A fonte de verdade é o formats/scripting/opcodes.go do kbot-io. A notação de pilha usa o estilo do Forth, ( before -- after ). A coluna Embutidos mostra quantas palavras uint32 vêm depois da própria palavra do opcode (consumidas na decodificação, não da pilha).

Animação — manipulação de 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)#

Veja o Apêndice B para o catálogo de portas.

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

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

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

Efeitos (0x107x)#

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

Codificação dos opcodes#

Toda palavra de opcode é 0x10CCSSFF, em que:

• CC = o byte de categoria (animação, matemática, fluxo de controle, …).
• SS = o nibble de subcomando, no nibble alto do segundo byte a partir do topo.
• FF = o byte de flags.

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

Palavras que nenhum jogo executa aparecem como UNKNOWN_0x10xxxxxx no desmontador (e são apontadas por ta-unknown-opcode); se você encontrar uma num arquivo real, abra uma issue com a amostra do COB.

Apêndice B — tabela de portas de get_unit_value#

As 20 portas que o descompilador do kbot hoje rotula simbolicamente. O TA real tem ~80; o TA: Kingdoms acrescenta mais ~15 para grandezas relacionadas à magia. Qualquer porta acima da 20 aparece hoje como literal numérico na saída do descompilador.

Entre as portas mais altas estão CURRENT_SPEED (29 — famosa por ser embutida como literal pelo Scriptor da Cavedog; veja Armadilhas acima), MAX_ID, UNIT_TEAM, UNIT_BUILD_PERCENT, BUILDER, UNIT_ALLIED e muitas outras. 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 amplia a faixa de portas. As portas exclusivas do TAK que o kbot reconhece (o descompilador exibe o nome simbólico; o compilador o aceita como entrada) vêm da tabela [UNITVLAUES] do Scriptor:

Apêndice C — opcodes do TA: Kingdoms#

Codificação (recapitulação)#

Toda palavra de opcode do COB é 0x10CCSSFF, em que CC é a categoria e SS é o subcomando — esses opcodes do TAK simplesmente ocupam posições CC:SS antes não usadas dentro das categorias existentes, em vez de introduzir um novo byte de categoria. DONT_SHADOW fica na categoria de animação, junto com DONT_CACHE/DONT_SHADE, e MISSION_COMMAND na categoria de efeitos, junto com 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 montados no texto:

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

Descompile qualquer um localmente com kbot cob decompile scripts/<name>.cob depois de definir um contexto do kbot.

Veja também#

• 3DO — os nomes de peças referenciados pelos scripts COB ficam no .3do da unidade.
• FBI — o arquivo de metadados da unidade. O ObjectName dele 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 comando do kbot.
• Glossário — peça, eixo, máscara de sinais, tick.