File Formats in TA

Total Annihilation is full of quirky but well-documented formats. Here’s the overview:

Containers

• HPI (Hapi Image File) — the main container format. Everything (units, maps, sounds, graphics) lives inside HPI archives. Third-party content is added as extra HPI files in the TA folder.
• UFO — essentially an HPI archive with a different extension. Typical for third-party units and maps (“Flash.ufo” = one packed archive).

Maps

• TNT — contains the actual map: terrain heightmap, textures (32×32-pixel cells), features, water. A map “8x8” means 8×8 map units of 512×512 px = 128×128 cells.
• OTA — companion file: mission parameters, start positions, wind, gravity, water properties, script references for single-player missions.

Units

• FBI — text file with the unit definitions: name, weapons, armor, cost (metal/energy), buildtime, movement, sound. The heart of every unit.
• 3DO — TA’s 3D model format (Cavedog-proprietary). Community tools can build/convert 3DO.
• BOS / COB — unit scripts (COB = compiled BOS). Controls animations, weapon behavior, special effects (e.g. D-Gun). BOS is the source language, compiled to COB.

Misc

• TDF — text definition format: features (rocks, trees, wrecks), weapon definitions, download lists.
• GAF — animation/graphics frames (interface graphics).
• PCX/BMP — textures and images.
• Sound files — usually WAV, packed inside HPI.

TNT heights: one elevation per 16×16 cell

The height data lives in the map attributes array, pointed to by PtrMapAttr (header offset 0x10). Each entry is 4 bytes and covers one 16×16-pixel cell of terrain:

• Byte 0: elevation, unsigned char (0–255)
• Bytes 1–2: unsigned short feature index — 0xFFFF = no feature, 0xFFFC = void (impassable), 0xFFFE appears on some early Cavedog maps (meaning unknown)
• Byte 3: unused / padding

The header’s Width/Height fields are in 16-pixel units, exactly the resolution of this array, so there are Width × Height height values. The 32×32-pixel texture tiles are twice that size — 4 height cells per tile.

Notes:

• SeaLevel (header offset 0x24): any height below it is treated as underwater.
• Heights are quantized to 0–255; the engine interpolates between cells for rendering and pathfinding, which is why slopes look smooth.

Source: the classic TNT format write-up by Saruman & Bobban (DFR), updated by me22 with Kinboat’s findings — ta-tnt-fmt-v2.txt.

Playing with third-party content

Just drop the files into the TA folder (or ...\Cavedog\Total Annihilation) — TA reads every HPI/UFO archive in that directory. For units, also watch the .unit list / side patch (see the Knowledgebase on unit building).

Fun fact: the embedded minimap

Every TNT file contains a built-in 252×252 pixel minimap (pointer in the TNT header, offset 0x28). That’s the preview image TA shows in its map selection screen — and the very same images used on this site’s map cards. How to extract them yourself: Reverse Engineering TA Files.