Todas las páginas de formatos ↓
Referencia de formatos de archivo

Referencia de formatos de Total Annihilation y TA: Kingdoms

Fuente: coreprime/kbot @ 0ab97bf · Editar en GitHub

kbot

Una guía práctica de los formatos de archivo propietarios que Cavedog Entertainment incluyó en Total Annihilation (1997) y Total Annihilation: Kingdoms (1999), escrita desde la experiencia real de la ingeniería inversa. Cada página combina la estructura en disco byte a byte con un comando kbot de una línea, para que puedas examinar los archivos reales mientras lees.

Tip

¿Es tu primera visita? Lee el Inicio rápido: cinco comandos que muestran el kit de herramientas kbot en cinco minutos.

Note

Si aún no lo has hecho, instala primero el kit de herramientas kbot y registra un contexto:

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

Con un contexto activo, la mayoría de los comandos (kbot tnt preview …, kbot gaf list …, kbot mount --server) buscan los nombres de archivo sin ruta en todos los archivos comprimidos HPI/UFO/CCX/GP3 de la instalación: se acabó escribir rutas absolutas.

Catálogo de formatos

Contenedores y envoltorios

Página Extensiones Propósito ¿Soporte completo?
HPI / UFO / CCX / GP3 .hpi .ufo .ccx .gp3 Archivo cifrado y comprimido: el envoltorio de todo lo demás TA ✅   TA:K ✅

Gráficos y multimedia

Página Extensiones Propósito ¿Soporte completo?
GAF .gaf .taf Animaciones de sprites en color indexado (cursores, explosiones, gadgets de unidades, elementos del mapa) TA ✅   TA:K ✅
TAF / TSF .taf .tsf Animaciones truecolor (ARGB de 16 bits) de TA: Kingdoms (efectos de hechizos, explosiones, fondos de menú) y su forma de texto editable TA:K ✅
PCX .pcx Mapa de bits de ZSoft Paintbrush: retratos de unidades, paneles de la interfaz y archivos que aportan la paleta en TA:K TA ✅   TA:K ✅
PAL / ALP / LHT / SHD .pal .alp .lht .shd Paleta de 256 colores (1024 bytes) y tablas de consulta de color: .alp 256×256 (65 536 bytes), .shd / .lht 32×256 (8192 bytes) TA ✅   TA:K ✅
FNT .fnt Fuente de mapa de bits de ancho variable, 1 bit por píxel TA ✅
Smacker / ZRB .smk .zrb Vídeo de las cinemáticas (Smacker de RAD Game Tools, renombrado como .zrb) TA ✅
Bink .bik Vídeo de las cinemáticas de TA: Kingdoms (RAD Bink 1), el sucesor de Smacker TA:K ✅
WAV / Sonido .wav WAV normal y la asignación de los bancos de sonido en tres capas TA ✅   TA:K ✅

Mapas y terreno

Página Extensiones Propósito ¿Soporte completo?
SCT .sct Secciones de mapa reutilizables que se unen para construir mapas .tnt TA ✅
TNT .tnt Un mapa jugable completo (cuadrícula de casillas + mapa de alturas + minimapa + lista de elementos) TA ✅
Mapas de TA:K .tnt .ota .crt .kmp El sistema de mapas de TA: Kingdoms (terreno texturizado + render del minimapa) y el archivo de escenario .crt que acompaña a cada mapa (unidades colocadas, reglas, disparadores) TA:K 🟡

Unidades, scripts y configuración

Página Extensiones Propósito ¿Soporte completo?
3DO .3do Malla 3D jerárquica de unidades y elementos, con caras en color indexado de la paleta TA ✅
COB / BOS .cob .bos Bytecode de animación y scripting basado en pila que controla cada unidad TA ✅   TA:K ✅
TDF / FBI / OTA .tdf .fbi .ota Árboles de configuración al estilo INI: estadísticas de unidades, armas, metadatos de mapas. Incluye el diccionario completo de campos FBI. TA ✅   TA:K ✅
TDF de gamedata gamedata/*.tdf Clases de movimiento, datos de bandos, asignaciones de sonido, referencia de armas TA ✅
Perfiles de IA ai/*.txt Pesos de la IA y límites de unidades por dificultad, en texto plano (los perfiles de TAK no tienen plan; ver la nota sobre TAK) TA ✅   TA:K ✅

Interfaz de TA: Kingdoms

Página Extensiones Propósito ¿Soporte completo?
Interfaz de TA:K .gui Árbol de widgets separados por espacios para los menús de TA: Kingdoms TA:K ✅

Tutoriales y referencia

Página Contenido
Inicio rápido Cinco comandos para empezar.
Modificar una unidad Tutorial completo: extraer → editar → reempaquetar → probar (TA).
Escollos Chuleta de una página con todos los escollos que recogen los documentos de formatos.
Formatos de TA y TA:K Tabla de una página: qué se comparte, qué se parece y qué es exclusivo de un juego.
Catálogos de referencia Repositorios independientes: coreprime/reference-ta, con 278 unidades / 199 armas / 45 constructores; coreprime/reference-tak, con 203 unidades / 198 armas / 32 constructores.
Glosario Términos comunes (piece, axis, sealevel, signal mask, …).
Galería de imágenes Todas las figuras de la documentación, con el comando que las genera.

Leyenda: ✅ soporte completo en kbot · 🟡 documentado, pero kbot todavía no lo analiza.

Cómo encajan los formatos

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

Casi todas las sesiones de ingeniería inversa empiezan montando un HPI; incluso las instalaciones desempaquetadas no son más que un HPI extraído. A partir de ahí, las unidades (FBI) apuntan a mallas (3DO), scripts (COB), retratos de unidades (PCX) y gadgets animados (GAF). Los mapas (TNT) se ensamblan a partir de secciones (SCT) y de elementos colocados cuyas definiciones están en archivos TDF.

Note

Monta toda la instalación de una vez. En lugar de examinar los archivos comprimidos de uno en uno, apunta kbot mount a la raíz de la instalación. Recorre todos los HPI/UFO/CCX de la carpeta y superpone su contenido en un único sistema de archivos virtual, de modo que puedes explorar units/ARMCOM.fbi sin que importe de qué archivo comprimido procede.

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

Orden de bytes, juego de caracteres y convenciones de coordenadas

Estas convenciones valen para todos los formatos de este documento, salvo que una página indique explícitamente lo contrario:

Propiedad Convención
Orden de bytes Little-endian (Intel x86).
Codificación de cadenas ASCII / CP-437, terminadas en NUL. TA:K añadió soporte parcial de Windows-1252, pero nunca UTF-8.
Anchos numéricos uint8 (char), uint16 (short), uint32 (long). No aparecen valores de 64 bits.
Origen de coordenadas Imágenes, cuadrículas de casillas, cuadrículas de atributos: (0, 0) es la esquina superior izquierda. Las mallas 3DO usan Y como eje vertical (hacia arriba).
Escala de coma fija 3D Los modelos 3DO usan coma fija con 16 bits fraccionarios: value / 65536.0 ≈ unidades del espacio del mundo.
Frecuencia de ticks del juego 30 ticks por segundo. La mayoría de los campos de tiempo de COB y GAF se miden en ticks.
Color transparente No existe un índice transparente común a toda la paleta. Cada fotograma GAF indica su propio color clave (a menudo 9, a veces 0), y los píxeles omitidos de un fotograma comprimido son transparentes; el terreno, los minimapas, los fondos y las texturas de los modelos dibujan todos los índices, incluido el índice 0 de la paleta (negro).

Important

Valida siempre los números mágicos antes de fiarte de un desplazamiento. Varios formatos (HPI, COB, GAF, TNT, SCT) llevan una firma de 32 bits en el primer campo. Si el valor no coincide, el archivo está dañado, procede de un mod que usa un formato privado o, en TA:K, es una variante .taf/.tsf con otra palabra de versión.

Cómo usar esta documentación

Todas las páginas de formatos siguen la misma estructura:

  1. Qué es: su propósito y dónde aparece en una instalación de TA.
  2. Estructura en disco: la estructura de la cabecera y después las secciones de datos, con los desplazamientos en bytes indicados.
  3. Orden de lectura: la secuencia de saltos y lecturas que permite analizar el archivo correctamente.
  4. Ejemplo desarrollado: un archivo real de Cavedog diseccionado byte a byte.
  5. Examínalo tú mismo: comandos de kbot que puedes ejecutar sobre tu propia instalación para ver los datos en directo.
  6. Escollos: casos límite no documentados, diferencias entre versiones, bytes de trabajo que dejaron las herramientas de Cavedog, etc.

Si un recuadro tiene este aspecto:

Tip

Pruébalo tú mismo.

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

…el comando está pensado para ejecutarse tal cual una vez definido un contexto.

Créditos y materiales de origen

Esta documentación reúne décadas de trabajo de ingeniería inversa de la comunidad. Las páginas atribuyen cada hallazgo concreto en el propio texto, pero las bases proceden de:

  • Joe D.: la disección original del formato HPI (1997).
  • Saruman & Bobban / dFR Engineering: el primer recorrido por el formato TNT (1997).
  • Scott «me22» McMurray: aclaraciones sobre el formato TNT (2003), basadas en el código fuente de Annihilator de Kinboat.
  • Kinboat: el formato SCT, herramientas para GAF y el editor de mapas Annihilator.
  • Dan Melchione & Dark Rain: el formato 3DO (1998, revisado en 2002).
  • C_A_P, Switeck, KhalvKalash: la ingeniería inversa de los opcodes de COB/BOS y la familia de herramientas Scriptor.
  • Dark Rain: el formato de interfaz de TA:K y las notas sobre los retos de los formatos de TA:K.
  • Cavedog Entertainment: por hacer un juego que merece seguir vivo más de 25 años después.

Cuando esta documentación contradiga alguno de esos originales, manda el código fuente de kbot: los formatos descritos aquí se prueban con viajes de ida y vuelta sobre miles de archivos reales de Cavedog. Si encuentras una discrepancia, abre una issue o un PR en https://github.com/coreprime/kbot.