Moddare un'unità, dall'inizio alla fine

Questa guida ti porta da un'installazione originale di Total Annihilation a una piccola mod che aggiunge una nuova variante del carro Arm Flash: una versione ridipinta e due volte più veloce. Alla fine avrai un archivio .ufo pronto da distribuire, che si carica appena lo metti nella cartella del gioco, e un'idea concreta di come funziona ogni formato supportato da kbot.

L'intero esercizio richiede ~20 minuti e tocca HPI, FBI, COB, 3DO, PCX, TDF e sidedata.tdf.

---

0. Prerequisiti#

• Un'installazione completa di TA in $TA (GoG, Steam o CD originale).
• kbot installato:

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

• Spazio su disco per una copia di lavoro appiattita (~120 MB).

---

1. Appiattire l'installazione#

Modificherai singoli file; appiattisci gli archivi una volta sola, così potrai leggerli con gli strumenti normali.

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

Guarda che cosa hai ottenuto:

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

La struttura delle cartelle corrisponde a quella del VFS: vedi HPI per come gli archivi si sovrappongono durante l'esecuzione.

---

2. Creare una directory di lavoro per la mod#

Moddare TA è un'operazione additiva: metti un .ufo accanto agli archivi esistenti e i suoi file sostituiscono quelli del gioco base. Costruisci la tua mod in un albero di cartelle che rispecchia quello del gioco:

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

---

3. Scegliere un'unità da cui partire#

Baseremo il nostro MYFLASH sull'Arm Flash esistente. Copia quattro file:

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

Perché proprio questi quattro? Ogni unità ha bisogno di:

Per convenzione i nomi dei file sono l'Objectname dell'FBI in minuscolo, con il .fbi stesso a volte in maiuscolo. Il motore non distingue mai tra maiuscole e minuscole.

---

4. Ricollegare l'FBI#

Apri mymod/units/myflash.fbi. I due campi fondamentali da cambiare sono UnitName (la chiave di ricerca) e Objectname (il nome di base dei file a cui rimanda):

[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;
    ...
}

Poi cambia una statistica per verificare che la modifica funzioni, per esempio raddoppiando la velocità:

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

Vedi l'Appendice sugli FBI per il catalogo completo dei campi. Tutto ciò che non è impostato eredita i valori predefiniti del motore.

---

5. Registrare l'unità nel menu di costruzione#

Un'unità che esiste ma che nessun costruttore può raggiungere non si può costruire. Il modo giusto per aggiungere uno slot di costruzione per una nuova unità è mettere un file download/<UNITNAME>.tdf nella tua mod: l'espansione Core Contingency di Cavedog distribuisce così le sue nuove unità, e ogni componente aggiuntivo .ufo per una singola unità che troverai (AFark.ufo, AFlea.ufo, CorNecro.ufo, …) segue la stessa convenzione.

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

Il menu di costruzione di TA è una griglia di 2 colonne × 3 righe per pagina, quindi BUTTON assume i valori 0–5, disposti così:

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

Scegli uno slot libero nella disposizione esistente del costruttore di destinazione: vedi il riferimento dell'albero di costruzione di TA per la disposizione completa, pagina per pagina, di ogni costruttore del gioco base.

All'avvio il motore legge ogni download/*.tdf, analizza ciascun [MENUENTRY<N>] e unisce le voci ai menu di costruzione dichiarati da sidedata.tdf. Non serve modificare sidedata.tdf.

Perché è meglio che modificare sidedata.tdf#

È il meccanismo di estensione previsto da Cavedog: esiste proprio perché i componenti aggiuntivi per una singola unità non debbano creare una propria versione di sidedata.tdf.

Costruire da più costruttori#

Per rendere l'unità costruibile da più costruttori, basta aggiungere altre sezioni [MENUENTRY<N>]. Il download/Armfort.tdf di Cavedog (Arm Fortification Wall, distribuito in ccdata.ccx) fa esattamente questo:

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

In questo modo ARMFORT si può costruire dall'Advanced Construction Kbot, dall'Advanced Construction Vehicle e dall'Advanced Construction Aircraft. Una voce per costruttore.

Scegliere i valori di MENU e BUTTON#

Il TA originale riserva le prime due pagine del menu (MENU=1, MENU=2) alle unità del gioco base. La convenzione della comunità è mettere le unità scaricabili su MENU=3 (o oltre), così da non entrare in collisione con nulla di ciò che distribuisce Cavedog. BUTTON è lo slot all'interno di quella pagina.

Nel dubbio, copia i valori da un download/*.tdf esistente che aggiunge unità allo stesso costruttore. Estrai Armfort.tdf, Armmark.tdf, Cormort.tdf, ecc. di Cavedog da usare come esempi funzionanti:

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

Vedi TDF: [MENUENTRY] per il riferimento dei campi.

---

6. Ricompilare il COB (facoltativo)#

MYFLASH.cob è una copia di ARMFLASH.cob: funziona così com'è. Se vuoi ritoccare l'animazione, decompila, modifica e ricompila:

# 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

Il round-trip decompilazione→compilazione è identico byte per byte per ogni script originale di Cavedog: kbot cob roundtrip lo verifica sull'intero catalogo del gioco.

---

7. (Facoltativo) Ridisegnare il ritratto#

unitpics/myflash.pcx è un PCX 96×96 con palette. Modificalo in qualsiasi editor di immagini che gestisca i PCX a 8 bit (GIMP, Aseprite, Krita), conservando la palette di TA. Per controllare che la palette sia rimasta intatta:

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

Se la palette si è rovinata, reimporta la palette canonica di TA (palettes/palette.pal) prima di salvare. Vedi PCX per le insidie legate ai marcatori 0x0C e al riempimento di BytesPerLine.

---

8. (Facoltativo) Ridisegnare il modello 3D#

objects3d/myflash.3do è una mesh gerarchica: vertici, primitive, riferimenti alle texture. L'editor di Cavedog (3DO Builder) resta, nonostante l'età, l'editor di 3DO più pratico. kbot non modifica direttamente i .3do; l'interfaccia web li disegna solo per esaminarli:

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

Vedi 3DO per la struttura su disco, se stai scrivendo degli strumenti.

---

9. Impacchettare in un .ufo#

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

Per impostazione predefinita kbot usa la compressione LZ77 a chunk con la chiave d'intestazione standard di Cavedog e il trailer di copyright di Cavedog che il gioco richiede: in altre parole, il motore lo accetta senza lamentarsi. Verifica:

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. Installare e provare#

Perché un .ufo? TA 3.1c monta rev31.gp3, poi ogni .ccx, ogni .ufo e solo i primi dieci .hpi, ogni gruppo in ordine di nome ASCII maiuscolo, e legge ogni file dal primo archivio che lo contiene (vedi l'ordine di caricamento degli HPI). Un .ufo viene sempre montato e ha la precedenza su ogni .hpi; una mod .hpi si troverebbe a contendersi i dieci slot *.hpi che un'installazione originale ha già occupato. I file contenuti anche in rev31.gp3 o in un .ccx (per esempio units/ARMCOM.FBI o gamedata/sidedata.tdf) arrivano comunque da quegli archivi: distribuisci sostituzioni del genere come file sciolti nella radice dell'installazione. La finestra Export mod… dello studio elenca questi file per il workspace, prima che tu scarichi la mod.

Metti il .ufo nella radice dell'installazione di TA, accanto a totala1.hpi:

cp myflash.ufo "$TA/"

Avvia TA. Comincia una schermaglia, costruisci un Arm Vehicle Plant e il tuo Super Flash dovrebbe comparire nel menu di costruzione, due volte più veloce di un Flash normale.

---

Risoluzione dei problemi#

---

Per proseguire#

• Aggiungere una nuova arma: copia un .tdf da weapons/, modificalo e richiamalo dal Weapon1= del tuo FBI. Vedi il riferimento di weapons.tdf.
• Aggiungere una nuova classe di movimento: aggiungila in fondo a moveinfo.tdf. Vedi Gamedata.
• Creare una mappa personalizzata: assembla un .tnt a partire da sezioni .sct (oppure scrivi il TNT direttamente a mano con kbot tnt pack). Vedi TNT.
• Aggiungere nuovi suoni: metti i WAV in sounds/ e collegali in gamedata/sound.tdf. Vedi Audio.
• Mettere a punto l'IA: aggiungi regole Weight/Limit in ai/default.txt per la tua nuova unità. Vedi IA.
• Esaminare una mod esistente: kbot hpi list più kbot hpi extract funzionano anche sui .ufo di terze parti. Studiare come altri hanno costruito i loro archivi è il modo più rapido per assimilare le convenzioni del modding.

---

Vedi anche#

• HPI: dettagli sull'impacchettamento degli archivi.
• FBI / TDF: il linguaggio di definizione delle unità, con il dizionario completo dei campi.
• COB / BOS: il linguaggio di scripting.
• 3DO: il formato delle mesh.
• Gamedata: riferimenti di sidedata.tdf, moveinfo.tdf e weapons.tdf.
• Glossario: riferimento terminologico.