Modificar uma unidade, do princípio ao fim

Este percurso leva-o de uma instalação original do Total Annihilation até um pequeno mod que acrescenta uma nova variante do tanque Flash do ARM: uma reskin com o dobro da velocidade. No fim terá um arquivo .ufo pronto a distribuir, que carrega quando é colocado na pasta do jogo, e uma ideia funcional de todos os formatos que o kbot suporta.

O exercício completo demora 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#

Vai editar ficheiros individuais; desempacote os arquivos uma vez para os poder ler com as ferramentas habituais.

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

Veja o que obteve:

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

A estrutura de pastas corresponde à forma do VFS; veja HPI para saber como os arquivos se sobrepõem em camadas durante a execução.

---

2. Criar uma pasta de trabalho para o mod#

Modificar o TA é aditivo: coloque um .ufo ao lado dos arquivos existentes e os seus ficheiros sobrepõem-se aos do jogo base. Construa o mod numa árvore espelhada:

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

---

3. Escolher uma unidade como base#

Vamos basear o nosso MYFLASH no Flash do ARM existente. Copie quatro ficheiros:

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

Porquê estes quatro? Todas as unidades precisam de:

Por convenção, os nomes dos ficheiros são o Objectname do FBI em minúsculas, com o próprio .fbi às vezes em maiúsculas. O motor não distingue maiúsculas de minúsculas em lado nenhum.

---

4. Reconfigurar o FBI#

Abra mymod/units/myflash.fbi. Os dois campos essenciais a alterar são UnitName (a chave de pesquisa) e Objectname (a referência à base dos nomes de ficheiro):

[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 alteração funciona, duplicando 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 dos campos. Tudo o que não for definido herda os valores por omissão do motor.

---

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

Uma unidade que existe mas não está acessível a partir de nenhum construtor não pode ser construída. A forma correta de acrescentar uma posição de construção para uma unidade nova é colocar um ficheiro download/<UNITNAME>.tdf no mod: a própria expansão Core Contingency da Cavedog distribui assim as suas unidades novas, e todos os complementos .ufo de uma só unidade que encontrar (AFark.ufo, AFlea.ufo, CorNecro.ufo, …) seguem 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 grelha de 2 colunas × 3 linhas por página, por isso BUTTON aceita valores de 0 a 5, distribuídos assim:

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

Escolha uma posição livre na disposição existente do construtor de destino; veja a referência da árvore de construção do TA para a disposição completa, página a página, de todos os construtores do jogo base.

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

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

Este é o ponto de extensão oficial da Cavedog: existe precisamente para que os complementos de uma só unidade não tenham de fazer uma cópia própria 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 secções [MENUENTRY<N>]. O download/Armfort.tdf da própria Cavedog (a Muralha de Fortificação ARM, incluída 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; }

— o que permite ao Kbot de Construção Avançado, ao Veículo de Construção Avançado e à Aeronave de Construção Avançada construírem o ARMFORT. 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 transferíveis em MENU=3 (ou numa página superior), para não colidirem com nada que a Cavedog distribua. 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 o Armfort.tdf, o Armmark.tdf, o 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)#

O MYFLASH.cob é uma cópia do ARMFLASH.cob e funciona tal como está. Se quiser afinar a animação, descompile, edite e volte a compilar:

# 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 comerciais da Cavedog; o kbot cob roundtrip confirma-o em todo o catálogo do jogo.

---

7. (Opcional) Mudar o aspeto do retrato#

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

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

Se a paleta ficou estragada, volte a importar a paleta canónica do TA (palettes/palette.pal) antes de guardar. Veja PCX para as armadilhas dos marcadores 0x0C e do preenchimento de BytesPerLine.

---

8. (Opcional) Mudar o aspeto do modelo 3D#

O objects3d/myflash.3do é uma malha hierárquica: vértices, primitivas, referências a texturas. O editor da Cavedog (3DO Builder) continua a ser 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 estiver a criar ferramentas.

---

9. Empacotar num .ufo#

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

Por omissão, o kbot usa compressão LZ77 por blocos com a chave de cabeçalho normal da Cavedog e o rodapé de direitos de autor da Cavedog que o jogo exige; ou seja, o motor aceita o ficheiro sem protestar. Confirme:

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#

Porquê um .ufo? O TA 3.1c monta rev31.gp3, depois todos os .ccx, todos os .ufo e só os dez primeiros .hpi, cada grupo por ordem do nome em maiúsculas ASCII, e lê cada ficheiro do primeiro arquivo que o contém (veja a ordem de carregamento do HPI). Um .ufo é sempre montado e fica acima de todos os .hpi; um mod .hpi competiria pelas dez posições *.hpi que uma instalação comercial já preencheu. Os ficheiros que o rev31.gp3 ou um .ccx também contêm (por exemplo units/ARMCOM.FBI ou gamedata/sidedata.tdf) continuam a vir desses arquivos: distribua essas substituições como ficheiros soltos na raiz da instalação. A caixa de diálogo Export mod… do estúdio lista-os para um espaço de trabalho antes de fazer a transferência.

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

cp myflash.ufo "$TA/"

Inicie 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, com o dobro da velocidade de um Flash normal.

---

Resolução de problemas#

---

Próximos passos#

• Acrescentar uma arma nova: copie um .tdf de weapons/, edite-o e refira-o no Weapon1= do seu FBI. Veja a referência do weapons.tdf.
• Acrescentar uma classe de movimento nova: acrescente-a ao moveinfo.tdf. Veja Gamedata.
• Criar um mapa personalizado: monte um .tnt a partir de secçõ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.
• Afinar 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 .ufo de terceiros. Estudar a forma como outros construíram os seus arquivos é a maneira mais rápida de interiorizar as convenções do modding.

---

Ver também#

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