Modificar uma unidade do começo ao fim

Este passo a passo leva você de uma instalação original do Total Annihilation a um mod minúsculo que acrescenta uma nova variante do tanque Flash do ARM: uma versão retexturizada com o dobro da velocidade. No fim, você terá um arquivo compactado .ufo pronto para distribuir, que carrega quando colocado na pasta do jogo, e um modelo mental funcional de todos os formatos que o kbot suporta.

O exercício inteiro leva cerca de 20 minutos e passa por HPI, FBI, COB, 3DO, PCX, TDF e sidedata.tdf.

---

0. Pré-requisitos#

• Uma instalação completa do TA em $TA (GoG, Steam ou o CD original).
• O kbot instalado:

  go install github.com/coreprime/kbot/cmd/kbot@latest
  kbot ctx add "$TA" --alias ta --game totala

• Espaço em disco para uma cópia de trabalho desempacotada (~120 MB).

---

1. Desempacotar a instalação#

Você vai editar arquivos individuais; desempacote os arquivos compactados uma vez para poder lê-los com ferramentas comuns.

kbot mount "$TA" flatten --target ./ta-flat

Veja o que saiu:

ls ta-flat/                # ai/  anims/  features/ ... weapons/
ls ta-flat/units/ | head   # ARMCOM.FBI, ARMFLASH.FBI, ...

A estrutura das pastas corresponde à forma do VFS; veja HPI para saber como os arquivos compactados se sobrepõem durante o jogo.

---

2. Criar um diretório de trabalho para o mod#

Modificar o TA é um processo aditivo: coloque um .ufo ao lado dos arquivos compactados existentes, e os arquivos dele substituem os do jogo base. Monte o seu mod numa árvore espelhada:

mkdir -p mymod/{units,scripts,objects3d,unitpics,download}

---

3. Escolher uma unidade para servir de base#

Vamos basear o nosso MYFLASH no Flash do ARM que já existe. Copie quatro arquivos:

cp ta-flat/units/armflash.fbi      mymod/units/myflash.fbi
cp ta-flat/scripts/ARMFLASH.cob    mymod/scripts/MYFLASH.cob
cp ta-flat/objects3d/armflash.3do  mymod/objects3d/myflash.3do
cp ta-flat/unitpics/armflash.pcx   mymod/unitpics/myflash.pcx

Por que esses quatro? Toda unidade precisa de:

Por convenção, os nomes dos arquivos são o Objectname do FBI em minúsculas, e às vezes o próprio .fbi está em maiúsculas. O motor não diferencia maiúsculas de minúsculas em lugar nenhum.

---

4. Religar o FBI#

Abra mymod/units/myflash.fbi. Os dois campos essenciais a mudar são UnitName (a chave de busca) e Objectname (a referência ao nome base dos arquivos):

[UNITINFO]
{
    UnitName=MYFLASH;             // ← was ARMFLASH
    Objectname=myflash;           // ← was armflash
    Side=ARM;
    Designation=ARM-MV;
    Name=Super Flash;             // ← display name
    Description=Twice-as-fast Flash variant;
    ...
}

Depois aumente um atributo para provar que a mudança funciona, dobrando a velocidade:

    MaxVelocity=4.0;              // was 2.0
    Acceleration=0.30;            // was 0.15

Veja o Apêndice do FBI para o catálogo completo de campos. Tudo o que não for definido herda os valores padrão do motor.

---

5. Registrar a unidade no menu de construção#

Uma unidade que existe, mas que nenhum construtor alcança, não pode ser construída. O jeito certo de acrescentar uma posição de construção para uma unidade nova é colocar um arquivo download/<UNITNAME>.tdf no seu mod: a própria expansão Core Contingency da Cavedog traz suas unidades novas assim, e todo add-on .ufo de uma única unidade que você encontrar (AFark.ufo, AFlea.ufo, CorNecro.ufo, …) segue a mesma convenção.

Crie mymod/download/MYFLASH.tdf:

[MENUENTRY1]
{
    UNITMENU=ARMVP;       // The builder this unit appears under
    MENU=3;               // Build-menu page number (1-indexed)
    BUTTON=4;             // Slot within that page (0–5 in a 2×3 grid;
                          // 4 = bottom-left)
    UNITNAME=MYFLASH;     // The unit being placed (matches your FBI's UnitName)
}

O menu de construção do TA é uma grade de 2 colunas × 3 linhas por página, então BUTTON aceita valores de 0 a 5, dispostos assim:

┌─────┬─────┐
│  0  │  1  │   page N, top row
├─────┼─────┤
│  2  │  3  │   page N, middle row
├─────┼─────┤
│  4  │  5  │   page N, bottom row
└─────┴─────┘

Escolha uma posição vazia na disposição atual do construtor de destino; veja a referência da árvore de construção do TA para a disposição completa, página por página, de cada construtor do jogo base.

O motor lê todos os download/*.tdf na inicialização, analisa cada [MENUENTRY<N>] e mescla as entradas nos menus de construção que o sidedata.tdf declarou. Não é preciso editar o sidedata.tdf.

Por que isto é melhor do que editar o sidedata.tdf#

Este é o ponto de extensão oficial da Cavedog: ele existe justamente para que os add-ons de uma única unidade não precisem fazer um fork do sidedata.tdf.

Construir a partir de vários construtores#

Para que a unidade possa ser construída por vários construtores, basta acrescentar mais seções [MENUENTRY<N>]. O próprio download/Armfort.tdf da Cavedog (Muralha de Fortificação do ARM, lançada em ccdata.ccx) faz exatamente isso:

[MENUENTRY1] { UNITMENU=ARMACK; MENU=3; BUTTON=4; UNITNAME=ARMFORT; }
[MENUENTRY2] { UNITMENU=ARMACV; MENU=3; BUTTON=4; UNITNAME=ARMFORT; }
[MENUENTRY3] { UNITMENU=ARMACA; MENU=3; BUTTON=4; UNITNAME=ARMFORT; }

Com isso, o ARMFORT pode ser construído pelo Kbot de Construção Avançado, pelo Veículo de Construção Avançado e pela Aeronave de Construção Avançada. Uma entrada por construtor.

Escolher os valores de MENU e BUTTON#

O TA original reserva as duas primeiras páginas do menu (MENU=1, MENU=2) para as unidades do jogo base. A convenção da comunidade é pôr as unidades baixáveis em MENU=3 (ou acima), para que não colidam com nada que a Cavedog lançou. BUTTON é a posição dentro dessa página.

Na dúvida, copie os valores de um download/*.tdf existente que acrescente unidades ao mesmo construtor. Extraia os Armfort.tdf, Armmark.tdf, Cormort.tdf etc. da Cavedog para ter referências que funcionam:

kbot hpi extract /path/to/ccdata.ccx "*.tdf" -t /tmp/cc-downloads
ls /tmp/cc-downloads/download/

Veja TDF: [MENUENTRY] para a referência dos campos.

---

6. Recompilar o COB (opcional)#

MYFLASH.cob é uma cópia de ARMFLASH.cob e funciona como está. Se quiser ajustar a animação, descompile, edite e recompile:

# Decompile to readable BOS
kbot cob decompile mymod/scripts/MYFLASH.cob -t mymod/scripts/MYFLASH.bos

# Edit MYFLASH.bos in any text editor
# (See cob.md for the BOS language reference.)

# Compile back to bytecode
kbot cob compile  mymod/scripts/MYFLASH.bos -t mymod/scripts/MYFLASH.cob

# Lint for common issues
kbot cob lint     mymod/scripts/MYFLASH.cob

A ida e volta descompilar→compilar é idêntica byte a byte para todos os scripts da Cavedog da versão comercial; o kbot cob roundtrip confirma isso no catálogo inteiro do jogo.

---

7. (Opcional) Refazer o retrato#

unitpics/myflash.pcx é um PCX de 96×96 com paleta. Edite-o em qualquer editor de imagens que trabalhe com PCX de 8 bits (GIMP, Aseprite, Krita), preservando a paleta do TA. Para conferir se a paleta sobreviveu:

kbot pcx describe mymod/unitpics/myflash.pcx
# Expected: BitsPerPixel: 8, embedded palette present

Se a paleta se estragou, importe de novo a paleta canônica do TA (palettes/palette.pal) antes de salvar. Veja PCX para as armadilhas dos marcadores 0x0C e do preenchimento de BytesPerLine.

---

8. (Opcional) Retexturizar o modelo 3D#

objects3d/myflash.3do é uma malha hierárquica: vértices, primitivas, referências de texturas. O editor da Cavedog (3DO Builder) ainda é o editor de 3DO mais prático, apesar da idade. O kbot não edita .3do diretamente; a interface web só os renderiza para inspeção:

kbot mount $(kbot ctx path) --server
# → browse to objects3d/myflash.3do for the piece tree and textures

Veja 3DO para a estrutura no disco, se você estiver criando ferramentas.

---

9. Empacotar num .ufo#

kbot hpi pack ./mymod --target myflash.ufo

Por padrão, o kbot usa compressão LZ77 em chunks, com a chave de cabeçalho padrão da Cavedog e o trailer de copyright da Cavedog que o jogo exige, ou seja, o motor o aceita sem reclamar. Confira:

kbot hpi info  myflash.ufo
# Should show ~5–8 files, marker 0x49504148 (HAPI), decrypt key 0xBF,
# and "TA 3.1c would mount: yes". A "no" names the reason (for example
# a missing Cavedog trailer), and the game would silently skip the file.

kbot hpi list  myflash.ufo -v
# units/myflash.fbi, scripts/MYFLASH.cob, objects3d/myflash.3do, ...

---

10. Instalar e testar#

Por que um .ufo? O TA 3.1c monta rev31.gp3, depois todos os .ccx, todos os .ufo e só os dez primeiros .hpi, cada grupo na ordem ASCII dos nomes em maiúsculas, e lê cada arquivo do primeiro arquivo compactado que o contém (veja a ordem de carregamento do HPI). Um .ufo sempre é montado e fica acima de todos os .hpi; um mod em .hpi disputaria as dez vagas de *.hpi que uma instalação da versão comercial já ocupou. Os arquivos que rev31.gp3 ou um .ccx também contêm (por exemplo, units/ARMCOM.FBI ou gamedata/sidedata.tdf) continuam vindo desses arquivos compactados: distribua essas substituições como arquivos soltos na raiz da instalação. O diálogo Export mod… do studio lista esses arquivos de um workspace antes do download.

Coloque o .ufo na raiz da instalação do TA, ao lado de totala1.hpi:

cp myflash.ufo "$TA/"

Abra o TA. Comece uma escaramuça, construa uma Fábrica de Veículos ARM, e o seu Super Flash deve aparecer no menu de construção, duas vezes mais rápido que um Flash comum.

---

Solução de problemas#

---

Próximos passos#

• Acrescentar uma arma nova: copie um .tdf de weapons/, edite-o e referencie-o no Weapon1= do seu FBI. Veja a referência de weapons.tdf.
• Acrescentar uma classe de movimento nova: acrescente-a ao moveinfo.tdf. Veja Gamedata.
• Fazer um mapa próprio: monte um .tnt a partir de seções .sct (ou escreva o TNT diretamente à mão com kbot tnt pack). Veja TNT.
• Acrescentar sons novos: coloque WAVs em sounds/ e ligue-os em gamedata/sound.tdf. Veja Som.
• Ajustar a IA: acrescente regras Weight/Limit em ai/default.txt para a sua unidade nova. Veja IA.
• Examinar um mod existente: kbot hpi list e kbot hpi extract também funcionam com .ufos de terceiros. Estudar como os outros montaram seus arquivos compactados é o jeito mais rápido de absorver as convenções de modding.

---

Veja também#

• HPI: detalhes do empacotamento dos arquivos compactados.
• FBI / TDF: a linguagem de definição de unidades, com o dicionário completo de campos.
• COB / BOS: a linguagem de script.
• 3DO: o formato das malhas.
• Gamedata: referências de sidedata.tdf, moveinfo.tdf e weapons.tdf.
• Glossário: referência de terminologia.