Total Annihilation & TA: Kingdoms Format Reference

A field guide to the proprietary file formats Cavedog Entertainment shipped in Total Annihilation (1997) and Total Annihilation: Kingdoms (1999), written from a working reverse-engineering perspective. Every page pairs the on-disk byte layout with a one-line kbot command so you can poke at the real files alongside the prose.

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

Format catalogue#

Container & wrapper formats#

Graphics & media#

Maps & terrain#

Units, scripts, configs#

TA: Kingdoms GUI#

Tutorials & reference#

Legend: ✅ first-class kbot support · 🟡 documented but not parsed by kbot today.

How the formats fit together#

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

Almost every reverse-engineering session begins by mounting an HPI — even flattened installs are just an HPI extraction. From there, units (FBI) point at meshes (3DO), scripts (COB), unit portraits (PCX), and animation gadgets (GAF). Maps (TNT) are assembled from sections (SCT) and feature placements that resolve into TDF feature definitions.

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

Endianness, character set & coordinate conventions#

These hold across every format in this document unless a page explicitly overrides them:

Working with this documentation#

Every per-format page is structured the same way:

1. What it is — purpose and where it appears in a TA install.
2. On-disk layout — header struct, then payload sections, with byte offsets called out.
3. Reading order — the sequence of seeks/reads that successfully parse the file.
4. Worked example — a real Cavedog file dissected byte-by-byte.
5. Inspect it yourself — kbot commands you can run against your own install to see the data live.
6. Gotchas — undocumented edge cases, version differences, scratch bytes left in by Cavedog tools, etc.

If a callout looks like this:

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

…then the command is meant to be runnable verbatim once a context is set.

Credits & source materials#

These docs synthesise decades of community reverse-engineering work. Pages attribute specific findings inline, but the foundations come from:

• Joe D. — original HPI format dissection (1997).
• Saruman & Bobban / dFR Engineering — first TNT walkthrough (1997).
• Scott "me22" McMurray — TNT format clarifications (2003), drawing on Kinboat's Annihilator source.
• Kinboat — SCT format, GAF tooling, Annihilator map editor.
• Dan Melchione & Dark Rain — 3DO format (1998, revised 2002).
• C_A_P, Switeck, KhalvKalash — COB/BOS opcode reverse engineering and the Scriptor tool family.
• Dark Rain — TA:K GUI format and the TA:K format-challenges notes.
• Cavedog Entertainment — for making a game worth keeping alive 25+ years later.

When this documentation conflicts with one of those originals, the kbot source code is the source of truth — the formats here are tested round-trip against thousands of real Cavedog files. If you find a discrepancy, open an issue or PR at https://github.com/coreprime/kbot.