Modificar una unidad, de principio a fin

Este recorrido te lleva de una instalación original de Total Annihilation a un mod diminuto que añade una nueva variante del tanque Arm Flash: una versión con otra apariencia y el doble de velocidad. Al final tendrás un archivo comprimido .ufo listo para distribuir, que se carga con solo dejarlo en la carpeta del juego, y una idea práctica de todos los formatos que admite kbot.

El ejercicio completo lleva unos 20 minutos y pasa por HPI, FBI, COB, 3DO, PCX, TDF y sidedata.tdf.

---

0. Requisitos previos#

• Una instalación completa de TA en $TA (GoG, Steam o el CD original).
• kbot instalado:

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

• Espacio en disco para una copia de trabajo desempaquetada (~120 MB).

---

1. Desempaquetar la instalación#

Vas a editar archivos individuales; desempaqueta una vez los archivos comprimidos para poder leerlos con herramientas normales.

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

Echa un vistazo a lo que has obtenido:

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

La estructura de carpetas coincide con la forma del sistema de archivos virtual: consulta HPI para ver cómo se superponen por capas los archivos comprimidos durante la ejecución.

---

2. Crear un directorio de trabajo para el mod#

Modificar TA es aditivo: deja un .ufo junto a los archivos comprimidos existentes y sus archivos tendrán prioridad sobre los del juego base. Crea tu mod en un árbol que reproduzca esa estructura:

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

---

3. Elegir la unidad de partida#

Basaremos nuestro MYFLASH en el Arm Flash existente. Copia cuatro archivos:

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

¿Por qué estos cuatro? Toda unidad necesita:

Por convención, los nombres de archivo son el Objectname del FBI en minúsculas, aunque a veces el propio .fbi va en mayúsculas. El motor no distingue mayúsculas de minúsculas en ningún sitio.

---

4. Adaptar el FBI#

Abre mymod/units/myflash.fbi. Los dos campos fundamentales que hay que cambiar son UnitName (la clave de búsqueda) y Objectname (la referencia al nombre base de los archivos):

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

Después sube una estadística para comprobar que el cambio funciona; duplica la velocidad:

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

Consulta el apéndice de FBI para ver el catálogo completo de campos. Lo que no se indica toma los valores por defecto del motor.

---

5. Registrar la unidad en el menú de construcción#

Una unidad que existe pero a la que no se llega desde ningún constructor no se puede construir. La forma correcta de añadir un hueco de construcción para una unidad nueva es dejar un archivo download/<UNITNAME>.tdf en tu mod: la propia expansión Core Contingency de Cavedog distribuye así sus unidades nuevas, y todos los complementos .ufo de una sola unidad que encontrarás (AFark.ufo, AFlea.ufo, CorNecro.ufo, …) siguen la misma convención.

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

El menú de construcción de TA es una cuadrícula de 2 columnas × 3 filas por página, así que BUTTON toma valores de 0 a 5, distribuidos así:

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

Elige un hueco libre en la disposición actual del constructor de destino: consulta la referencia del árbol de construcción de TA para ver la disposición completa, página a página, de todos los constructores del juego base.

Al arrancar, el motor lee todos los download/*.tdf, analiza cada [MENUENTRY<N>] y fusiona las entradas con los menús de construcción que declaraba sidedata.tdf. No hace falta editar sidedata.tdf.

Por qué es mejor que editar sidedata.tdf#

Es el punto de extensión que el propio Cavedog dejó previsto: existe precisamente para que los complementos de una sola unidad no tengan que hacer su propia copia de sidedata.tdf.

Construir desde varios constructores#

Para que la unidad se pueda construir desde varios constructores, basta con añadir más secciones [MENUENTRY<N>]. El propio download/Armfort.tdf de Cavedog (Arm Fortification Wall, distribuido en ccdata.ccx) hace exactamente eso:

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

Así, ARMFORT se puede construir desde el Advanced Construction Kbot, el Vehicle y el Aircraft. Una entrada por constructor.

Cómo elegir los valores de MENU y BUTTON#

El TA original reserva las dos primeras páginas del menú (MENU=1, MENU=2) para las unidades del juego base. La convención de la comunidad es poner las unidades descargables en MENU=3 (o más) para que no choquen con nada de lo que distribuye Cavedog. BUTTON es el hueco dentro de esa página.

Si tienes dudas, copia los valores de un download/*.tdf existente que añada unidades al mismo constructor. Extrae los Armfort.tdf, Armmark.tdf, Cormort.tdf, etc. de Cavedog para tener ejemplos que funcionan:

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

Consulta TDF: [MENUENTRY] para la referencia de los campos.

---

6. Recompilar el COB (opcional)#

MYFLASH.cob es una copia de ARMFLASH.cob: funcionará tal cual. Si quieres retocar la animación, descompílalo, edítalo y vuelve a compilarlo:

# 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

El viaje de ida y vuelta descompilar→compilar es idéntico byte a byte en todos los scripts de Cavedog de la versión comercial: kbot cob roundtrip lo comprueba en todo el catálogo del juego.

---

7. (Opcional) Cambiar la apariencia del retrato#

unitpics/myflash.pcx es un PCX de 96×96 con paleta. Edítalo con cualquier editor de imágenes que maneje PCX de 8 bits (GIMP, Aseprite, Krita), conservando la paleta de TA. Para comprobar que la paleta ha sobrevivido:

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

Si la paleta se ha estropeado, vuelve a importar la paleta canónica de TA (palettes/palette.pal) antes de guardar. Consulta PCX para ver los escollos de las marcas 0x0C y del relleno de BytesPerLine.

---

8. (Opcional) Cambiar la apariencia del modelo 3D#

objects3d/myflash.3do es una malla jerárquica: vértices, primitivas, referencias a texturas. El editor de Cavedog (3DO Builder) sigue siendo, pese a su edad, el editor de 3DO más práctico. kbot no edita .3do directamente; la interfaz web solo los renderiza para inspeccionarlos:

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

Consulta 3DO para ver la estructura en disco si estás creando herramientas.

---

9. Empaquetar en un .ufo#

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

Por defecto, kbot usa compresión LZ77 por chunks con la clave de cabecera estándar de Cavedog y el trailer de copyright de Cavedog que exige el juego; es decir, el motor lo acepta sin protestar. Compruébalo:

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. Instalar y probar#

¿Por qué un .ufo? TA 3.1c monta rev31.gp3, después todos los .ccx, todos los .ufo y solo los diez primeros .hpi, cada grupo ordenado por nombre en mayúsculas según el orden ASCII, y lee cada archivo del primer archivo comprimido que lo contiene (consulta el orden de carga de HPI). Un .ufo siempre se monta y queda por encima de todos los .hpi; un mod .hpi competiría por las diez plazas *.hpi que una instalación comercial ya tiene ocupadas. Los archivos que también contienen rev31.gp3 o un .ccx (por ejemplo, units/ARMCOM.FBI o gamedata/sidedata.tdf) se siguen tomando de esos archivos comprimidos: distribuye esas sustituciones como archivos sueltos en la raíz de la instalación. El diálogo Export mod… del studio te los muestra para cada espacio de trabajo antes de descargar el mod.

Deja el .ufo en la raíz de la instalación de TA, junto a totala1.hpi:

cp myflash.ufo "$TA/"

Inicia TA. Empieza una escaramuza, construye una Arm Vehicle Plant y tu Super Flash debería aparecer en el menú de construcción, el doble de rápido que un Flash normal.

---

Solución de problemas#

---

Siguientes pasos#

• Añadir un arma nueva: copia un .tdf de weapons/, edítalo y haz referencia a él desde el Weapon1= de tu FBI. Consulta la referencia de weapons.tdf.
• Añadir una clase de movimiento nueva: añádela al final de moveinfo.tdf. Consulta Gamedata.
• Crear un mapa propio: ensambla un .tnt a partir de secciones .sct (o crea el TNT directamente a mano con kbot tnt pack). Consulta TNT.
• Añadir sonidos nuevos: deja los WAV en sounds/ y asígnalos en gamedata/sound.tdf. Consulta Sonido.
• Ajustar la IA: añade reglas Weight/Limit para tu unidad nueva en ai/default.txt. Consulta IA.
• Inspeccionar un mod existente: kbot hpi list y kbot hpi extract también funcionan con los .ufo de terceros. Estudiar cómo han construido otros sus archivos comprimidos es la forma más rápida de interiorizar las convenciones del modding.

---

Véase también#

• HPI: detalles del empaquetado de archivos comprimidos.
• FBI / TDF: el lenguaje de definición de unidades, con el diccionario completo de campos.
• COB / BOS: el lenguaje de scripting.
• 3DO: el formato de mallas.
• Gamedata: referencias de sidedata.tdf, moveinfo.tdf y weapons.tdf.
• Glosario: referencia de terminología.