Todas as páginas de formatos ↓
Referência de formatos de arquivo

Referência de formatos do Total Annihilation e do TA: Kingdoms

Fonte: coreprime/kbot @ 0ab97bf · Editar no GitHub

kbot

Um guia de campo dos formatos de arquivo proprietários que a Cavedog Entertainment lançou no Total Annihilation (1997) e no Total Annihilation: Kingdoms (1999), escrito do ponto de vista de quem faz engenharia reversa na prática. Cada página traz a estrutura dos bytes no disco ao lado de um comando kbot de uma linha, para você examinar os arquivos reais enquanto lê o texto.

Tip

Primeira vez aqui? Leia o Início rápido: cinco comandos que mostram o kit de ferramentas em cinco minutos.

Note

Se ainda não fez isso, instale o kit de ferramentas e registre um contexto:

go install github.com/coreprime/kbot/cmd/kbot@latest
kbot ctx add ~/games/totala --alias ta --game totala

Com um contexto ativo, a maioria dos comandos (kbot tnt preview …, kbot gaf list …, kbot mount --server) procura nomes de arquivo sem caminho em todos os arquivos compactados HPI/UFO/CCX/GP3 da instalação. Nada de digitar caminhos absolutos.

Catálogo de formatos

Contêineres e invólucros

Página Extensões Finalidade Suporte completo?
HPI / UFO / CCX / GP3 .hpi .ufo .ccx .gp3 Arquivo compactado e criptografado: o invólucro de todo o resto TA ✅   TA:K ✅

Gráficos e mídia

Página Extensões Finalidade Suporte completo?
GAF .gaf .taf Animações de sprites em cores indexadas (cursores, explosões, peças de unidades, elementos do mapa) TA ✅   TA:K ✅
TAF / TSF .taf .tsf Animações truecolor (ARGB de 16 bits) do TA: Kingdoms (efeitos de feitiços, explosões, fundos de menu) e sua forma em texto editável TA:K ✅
PCX .pcx Bitmap do ZSoft Paintbrush: retratos de unidades, painéis da interface e arquivos que trazem a paleta no TA:K TA ✅   TA:K ✅
PAL / ALP / LHT / SHD .pal .alp .lht .shd Paleta de 256 cores (1.024 bytes) e tabelas de consulta de cores: .alp 256×256 (65.536 bytes), .shd / .lht 32×256 (8.192 bytes) TA ✅   TA:K ✅
FNT .fnt Fonte bitmap de largura variável, 1 bit por pixel TA ✅
Smacker / ZRB .smk .zrb Vídeo das cinemáticas (Smacker da RAD Game Tools, renomeado como .zrb) TA ✅
Bink .bik Vídeo das cinemáticas do TA: Kingdoms (RAD Bink 1), o sucessor do Smacker TA:K ✅
WAV / Som .wav WAV comum, e como os bancos de som se ligam em três camadas TA ✅   TA:K ✅

Mapas e terreno

Página Extensões Finalidade Suporte completo?
SCT .sct Seções de mapa reutilizáveis que se juntam para montar mapas .tnt TA ✅
TNT .tnt Um mapa jogável completo (grade de blocos + mapa de altura + minimapa + lista de elementos) TA ✅
Mapas do TA:K .tnt .ota .crt .kmp O sistema de mapas do TA: Kingdoms (terreno texturizado + renderização do minimapa) e o arquivo de cenário .crt que acompanha cada mapa (unidades posicionadas, regras, gatilhos) TA:K 🟡

Unidades, scripts e configurações

Página Extensões Finalidade Suporte completo?
3DO .3do Malha 3D hierárquica de unidades e elementos, com faces em cores indexadas da paleta TA ✅
COB / BOS .cob .bos Bytecode de animação e script baseado em pilha que controla cada unidade TA ✅   TA:K ✅
TDF / FBI / OTA .tdf .fbi .ota Árvores de configuração no estilo INI: atributos de unidades, armas, metadados de mapas. Inclui o dicionário completo de campos FBI. TA ✅   TA:K ✅
TDFs do gamedata gamedata/*.tdf Classes de movimento, dados de cada lado, associações de som, referência de armas TA ✅
Perfis de IA ai/*.txt Pesos da IA e limites de unidades por dificuldade, em texto simples (os perfis do TAK não têm plan, veja a nota sobre o TAK) TA ✅   TA:K ✅

Interface do TA: Kingdoms

Página Extensões Finalidade Suporte completo?
Interface do TA:K .gui Árvore de widgets separada por espaços para os menus do TA: Kingdoms TA:K ✅

Tutoriais e referência

Página Conteúdo
Início rápido Cinco comandos para começar.
Modificar uma unidade Tutorial completo: extrair → editar → reempacotar → testar (TA).
Armadilhas Resumo de uma página com todas as armadilhas dos documentos de formatos.
Formatos do TA e do TA:K Tabela de uma página: o que é compartilhado, o que é parecido e o que é exclusivo de um jogo.
Catálogos de referência Repositórios independentes: coreprime/reference-ta, com 278 unidades / 199 armas / 45 construtores, e coreprime/reference-tak, com 203 unidades / 198 armas / 32 construtores.
Glossário Termos comuns (piece, axis, sealevel, signal mask, …).
Galeria de imagens Todas as figuras dos documentos, com o comando que gera cada uma.

Legenda: ✅ suporte completo no kbot · 🟡 documentado, mas o kbot ainda não lê.

Como os formatos se encaixam

                                ┌───────────────────────────────┐
                                │   HPI / UFO / CCX / GP3       │
                                │   (encrypted, compressed VFS) │
                                └──────────────┬────────────────┘
                                               │ contains
            ┌──────────────────────┬───────────┼───────────────┬──────────────────┐
            ▼                      ▼           ▼               ▼                  ▼
        ┌───────┐             ┌───────┐   ┌───────┐       ┌────────┐        ┌─────────┐
        │  FBI  │ unit stats  │  COB  │   │  3DO  │ mesh  │  GAF   │ sprites│   TNT   │ map
        └───┬───┘             └───┬───┘   └───┬───┘       └────┬───┘        └────┬────┘
            │ references          │ runs on   │ textured by    │ used by         │ built from
            ▼                     ▼           ▼                ▼                 ▼
        ┌───────┐             ┌───────┐   ┌───────┐       ┌────────┐        ┌─────────┐
        │  TDF  │ weapons     │ piece │   │  PCX  │ skins │  PAL   │ colour │   SCT   │ tiles
        │ /OTA  │ /features   │ tree  │   │  unitpic│      │ /ALP/LHT/SHD   │ + heights
        └───────┘             └───────┘   └───────┘       └────────┘        └─────────┘

Quase toda sessão de engenharia reversa começa montando um HPI. Até as instalações desempacotadas são só um HPI extraído. A partir dele, as unidades (FBI) apontam para malhas (3DO), scripts (COB), retratos de unidades (PCX) e peças animadas (GAF). Os mapas (TNT) são montados a partir de seções (SCT) e de posições de elementos que remetem às definições de elementos em TDF.

Note

Monte a instalação inteira de uma vez. Em vez de examinar um arquivo compactado de cada vez, aponte o kbot mount para a raiz da instalação. Ele percorre todos os HPI/UFO/CCX da pasta e sobrepõe o conteúdo em um único sistema de arquivos virtual, para você navegar até units/ARMCOM.fbi sem se preocupar com o arquivo compactado de onde ele veio.

kbot mount ~/games/totala --server   # opens at http://localhost:8090

Ordem dos bytes, conjunto de caracteres e convenções de coordenadas

Estas regras valem para todos os formatos deste documento, a não ser que uma página diga explicitamente o contrário:

Propriedade Convenção
Ordem dos bytes Little-endian (Intel x86).
Codificação de strings ASCII / CP-437, terminadas em NUL. O TA:K trouxe suporte parcial a Windows-1252, mas nunca a UTF-8.
Larguras numéricas uint8 (char), uint16 (short), uint32 (long). Valores de 64 bits não aparecem.
Origem das coordenadas Imagens, grades de blocos, grades de atributos: (0, 0) é o canto superior esquerdo. As malhas 3DO usam Y como eixo vertical (para cima).
Escala de ponto fixo 3D Os modelos 3DO usam ponto fixo com parte fracionária de 16 bits: value / 65536.0 ≈ unidades do espaço do mundo.
Taxa de ticks do jogo 30 ticks por segundo. A maioria dos campos de tempo em COB e GAF usa ticks.
Cor transparente Não existe um índice transparente para a paleta inteira. Cada quadro GAF define sua própria cor-chave (muitas vezes 9, às vezes 0), e os pixels pulados de um quadro comprimido são transparentes. Terreno, minimapas, fundos e texturas de modelos desenham todos os índices, inclusive o índice 0 da paleta (preto).

Important

Sempre valide os números mágicos antes de confiar em um offset. Vários formatos (HPI, COB, GAF, TNT, SCT) trazem uma assinatura de 32 bits no primeiro campo. Se o valor não bater, o arquivo está corrompido, vem de um mod que usa um formato próprio ou, no TA:K, é uma variante .taf/.tsf com outra palavra de versão.

Como usar esta documentação

Todas as páginas de formato seguem a mesma estrutura:

  1. O que é: a finalidade e onde o formato aparece em uma instalação do TA.
  2. Estrutura no disco: a estrutura do cabeçalho e depois as seções de dados, com os offsets em bytes indicados.
  3. Ordem de leitura: a sequência de seeks e leituras que analisa o arquivo corretamente.
  4. Exemplo comentado: um arquivo real da Cavedog dissecado byte a byte.
  5. Veja você mesmo: comandos kbot para rodar na sua própria instalação e ver os dados ao vivo.
  6. Armadilhas: casos-limite não documentados, diferenças entre versões, bytes de lixo deixados pelas ferramentas da Cavedog etc.

Se um destaque tiver esta cara:

Tip

Experimente você mesmo.

kbot pal swatch palettes/palette.pal --target out.png --cell 24

…o comando foi feito para rodar exatamente como está escrito, desde que haja um contexto definido.

Créditos e fontes

Estes documentos reúnem décadas de engenharia reversa feita pela comunidade. As páginas atribuem descobertas específicas no próprio texto, mas a base vem de:

  • Joe D.: a dissecação original do formato HPI (1997).
  • Saruman & Bobban / dFR Engineering: o primeiro passo a passo do TNT (1997).
  • Scott "me22" McMurray: esclarecimentos sobre o formato TNT (2003), com base no código-fonte do Annihilator de Kinboat.
  • Kinboat: o formato SCT, ferramentas para GAF e o editor de mapas Annihilator.
  • Dan Melchione & Dark Rain: o formato 3DO (1998, revisado em 2002).
  • C_A_P, Switeck, KhalvKalash: a engenharia reversa dos opcodes COB/BOS e a família de ferramentas Scriptor.
  • Dark Rain: o formato de interface do TA:K e as notas sobre os desafios dos formatos do TA:K.
  • Cavedog Entertainment: por fazer um jogo que vale a pena manter vivo mais de 25 anos depois.

Quando esta documentação contradiz um desses originais, quem manda é o código-fonte do kbot: os formatos descritos aqui são testados em ida e volta com milhares de arquivos reais da Cavedog. Se encontrar alguma discrepância, abra uma issue ou um PR em https://github.com/coreprime/kbot.