Riferimento ai formati di Total Annihilation e TA: Kingdoms

Una guida pratica ai formati di file proprietari che Cavedog Entertainment distribuì con Total Annihilation (1997) e Total Annihilation: Kingdoms (1999), scritta dal punto di vista di chi fa davvero reverse engineering. Ogni pagina affianca alla struttura dei byte su disco un comando kbot di una riga, così puoi esaminare i file reali mentre leggi il testo.

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

Catalogo dei formati#

Contenitori e involucri#

Grafica e media#

Mappe e terreno#

Unità, script, configurazioni#

Interfaccia di TA: Kingdoms#

Tutorial e riferimenti#

Legenda: ✅ supporto completo in kbot · 🟡 documentato ma oggi non analizzato da kbot.

Come si combinano i formati#

                                ┌───────────────────────────────┐
                                │   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
        └───────┘             └───────┘   └───────┘       └────────┘        └─────────┘

Quasi ogni sessione di reverse engineering comincia montando un HPI: anche le installazioni appiattite non sono altro che un HPI estratto. Da lì, le unità (FBI) puntano a mesh (3DO), script (COB), ritratti delle unità (PCX) e parti animate (GAF). Le mappe (TNT) sono assemblate a partire da sezioni (SCT) e da posizionamenti di elementi che rimandano alle definizioni degli elementi in TDF.

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

Ordine dei byte, set di caratteri e convenzioni sulle coordinate#

Queste convenzioni valgono per tutti i formati di questo documento, salvo quando una pagina le ridefinisce esplicitamente:

Come usare questa documentazione#

Ogni pagina dedicata a un formato ha la stessa struttura:

1. Che cos'è: scopo e dove compare in un'installazione di TA.
2. Struttura su disco: la struct dell'intestazione, poi le sezioni del payload, con gli offset dei byte indicati.
3. Ordine di lettura: la sequenza di seek e letture che permette di analizzare correttamente il file.
4. Esempio svolto: un vero file Cavedog sezionato byte per byte.
5. Esaminalo da te: comandi kbot da eseguire sulla tua installazione per vedere i dati dal vivo.
6. Insidie: casi limite non documentati, differenze tra versioni, byte residui lasciati dagli strumenti di Cavedog, ecc.

Se un riquadro ha questo aspetto:

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

…allora il comando si può eseguire così com'è, una volta impostato un contesto.

Riconoscimenti e fonti#

Questi documenti sintetizzano decenni di reverse engineering della comunità. Le pagine citano nel testo gli autori delle singole scoperte, ma le fondamenta vengono da:

• Joe D. — prima analisi del formato HPI (1997).
• Saruman & Bobban / dFR Engineering — prima descrizione dettagliata del formato TNT (1997).
• Scott "me22" McMurray — chiarimenti sul formato TNT (2003), basati sul sorgente di Annihilator di Kinboat.
• Kinboat — formato SCT, strumenti per GAF, editor di mappe Annihilator.
• Dan Melchione & Dark Rain — formato 3DO (1998, rivisto nel 2002).
• C_A_P, Switeck, KhalvKalash — reverse engineering degli opcode COB/BOS e la famiglia di strumenti Scriptor.
• Dark Rain — formato GUI di TA:K e le note sulle difficoltà dei formati di TA:K.
• Cavedog Entertainment — per aver creato un gioco che vale la pena tenere in vita a più di 25 anni di distanza.

Quando questa documentazione contraddice uno di quegli originali, fa fede il codice sorgente di kbot: i formati descritti qui sono verificati in round-trip (lettura e riscrittura) su migliaia di file Cavedog reali. Se trovi una discrepanza, apri una issue o una PR su https://github.com/coreprime/kbot.