TDF de gamedata: tablas de configuración del motor

Los archivos de gamedata/ son archivos de texto TDF que configuran el propio motor: clases de movimiento, categorías de daño de las armas, datos de los bandos (disposición de la interfaz, menús de construcción, unidades iniciales), asignaciones de sonido y un puñado de pequeñas tablas de consulta. Los mods que cambian las reglas del juego (en lugar de añadir unidades) casi siempre actúan aquí.

Esta página documenta los archivos de gamedata más útiles. Todos usan la gramática TDF al estilo INI; consulta TDF para los detalles a nivel de analizador.

ls $(kbot ctx path)/gamedata/
# The web UI renders these as collapsible section trees
kbot mount $(kbot ctx path) --server
# → browse to gamedata/sidedata.tdf, then sidedata > [CANBUILD]

Los archivos de un vistazo#

Los tres grandes para el modding son sidedata.tdf (menús de construcción, bandos), moveinfo.tdf (clases de movimiento) y weapons.tdf (que es documentación, no datos: las armas de verdad están en weapons/*.tdf).

moveinfo.tdf: clases de movimiento#

El FBI de una unidad declara su MovementClass=KBOTSS2 (o similar); el motor busca esa clase en moveinfo.tdf para decidir por qué terreno puede desplazarse.

TA 3.1c solo lee las secciones [CLASS0] a [CLASS31] (la primera sección con cada uno de esos nombres) y encuentra una clase por su Name=, sin distinguir mayúsculas y empezando por la posición más baja. Cuando la clase de la unidad se resuelve, los valores de la clase sustituyen por completo a las claves FootprintX/FootprintZ, MaxWaterDepth, MinWaterDepth y de pendiente de la propia unidad (el MaxSlope=20 del comandante cede ante el 32 de TANKDS2), y una clave que la clase omite toma el valor por defecto del juego que se indica abajo, no el valor del FBI. Una unidad sin clase, o que nombra una que el juego no encuentra, lee sus propias claves del FBI con los mismos valores por defecto. Los metadatos de unidad, el sandbox y las partidas alojadas de KBot Studio resuelven el movimiento de esta manera.

[CLASS0]
{
    Name=KBOTSS2;        // Class name referenced from FBIs
    FootprintX=2;        // Cells wide (16-px units)
    FootprintZ=2;        // Cells deep
    MaxWaterDepth=12;    // Deepest water it can enter
    MaxSlope=32;         // Steepest land slope it can climb
}

[CLASS3]
{
    Name=TANKDH3;
    FootprintX=3;
    FootprintZ=3;
    MaxWaterDepth=100;   // Heavy tank — can ford deep water
    MaxWaterSlope=30;    // Slope limit *underwater* (separate from MaxSlope)
    MaxSlope=15;
}

Campos#

Convenciones de nombres#

El nombre de la clase codifica su forma en una etiqueta corta, según la convención de Cavedog:

Después viene un sufijo SS / SF / DS / DH / SH (pequeño/profundo/pesado/etc.) y una cifra de huella. Los nombres son solo una convención: el motor trata Name= como una clave opaca.

sidedata.tdf: configuración de cada bando#

Es el archivo más largo de gamedata/ porque reúne tres asuntos distintos:

1. Declaraciones de bando: nombre, prefijo, comandante, fuentes, colores.
2. Disposición del HUD: coordenadas en píxeles de cada barra de estado, etiqueta y botón de la interfaz de la partida.
3. Menús de construcción: la sección [CANBUILD], que enumera lo que puede construir cada constructor.

Bloque de bando#

[SIDE0]
{
    name=ARM;
    nameprefix=ARM;
    commander=ARMCOM;          // UnitName of the commander unit
    intgaf=ARMINT;             // GAF used for intro screen

    font=console;              // FNT for general text
    fontgui=armbutt;           // FNT for buttons
    energycolor=208;           // Palette index for energy bars
    metalcolor=224;            // Palette index for metal bars

    // …followed by ~60 HUD coordinate sub-sections
    [LOGO]      { x1=132; y1=5;   x2=152; y2=25; }
    [ENERGYBAR] { x1=471; y1=12;  x2=598; y2=14; }
    [METALBAR]  { x1=218; y1=12;  x2=345; y2=14; }
    ...
}

[SIDE1] { name=CORE; ... }

TA 3.1c lee los bandos [SIDE0], [SIDE1], … en orden, y se detiene en el primer número que falta y después del quinto. Una sección con cualquier otro nombre ([SIDE01], un [SIDE3] tras la falta de [SIDE2], un sexto bando) no se lee nunca, y cada bando que lee necesita todos los rectángulos del HUD que se indican abajo (ta.SideRectangles de kbot-io); si no, el juego no carga ningún bando. El selector de bando del sandbox del studio ofrece los mismos bandos.

Subsecciones de coordenadas del HUD#

Cada elemento visible del HUD es un bloque [NAME] con coordenadas en píxeles x1/y1/x2/y2. Son relativas a la resolución base de 640×480; en los modos superiores, el motor las escala.

[ENERGYBAR] { x1=471; y1=12; x2=598; y2=14; }

Para recolocar la barra de energía, edita los cuatro números. Para cambiar su aspecto, sustituye el GAF que usa el HUD para dibujar en esa posición (se define en unitview.tdf).

Menús de construcción [CANBUILD]#

La definición estática de los menús de construcción. Cada constructor enumera lo que puede construir al empezar la partida:

[CANBUILD]
{
    [ARMCOM]
    {
        canbuild1=ARMSOLAR;    // Slot 1 on the build menu
        canbuild2=ARMWIN;
        canbuild3=ARMESTOR;
        canbuild4=ARMMSTOR;
        canbuild5=ARMMEX;
        ...
    }
    [ARMLAB]
    {
        canbuild1=ARMCK;
        canbuild2=ARMPW;
        ...
    }
}

El número de hueco es la posición en la página del menú de construcción. El menú de construcción de TA es una cuadrícula de 2 columnas × 3 filas, así que cada página tiene 6 huecos: canbuild1–canbuild6 son la página 1, canbuild7–canbuild12 la página 2, y así sucesivamente.

Cómo lee TA 3.1c la tabla (CanBuildBuilder.BuildList de kbot-io; kbot document, el visor de unidades y el menú de construcción del sandbox la siguen):

• Solo recibe una lista la unidad cuyo FBI define Builder=1; la subsección de cualquier otra unidad se ignora.
• El juego lee la primera sección [CANBUILD] y, dentro de ella, la primera subsección con el nombre del constructor (sin distinguir mayúsculas).
• Lee canbuild1, canbuild2, … y se detiene en el primer número que falta: canbuild1=ARMSOLAR; canbuild3=ARMLAB; da una sola entrada.
• Un nombre que no coincide con ninguna unidad se omite, y una lista admite como máximo 30 unidades. Las entradas de download (abajo) pueden llevar el menú de un constructor hasta 31. (Alguna documentación antigua afirmaba que había 12 huecos por página; la cuadrícula real del juego es de 6.) Consulta la referencia del árbol de construcción de TA para ver la disposición por páginas de cada constructor del juego base.

weapons.tdf: referencia de los TDF de armas#

Pese a su nombre, gamedata/weapons.tdf son casi todo comentarios: es la referencia que publicó Cavedog sobre la gramática de los TDF de armas, y el juego nunca lo carga. Las definiciones reales de las armas están en weapons/*.tdf, con una sección por arma (consulta TDF). kbot document no enumera como armas las secciones de gamedata/weapons.tdf.

La tabla de armas#

TA 3.1c construye una tabla de 256 posiciones de armas a partir de los archivos .tdf que están directamente en weapons/ (no en sus subdirectorios), en el orden en que los lista:

• Una sección va a la posición que indica su ID=, de 0 a 255. Una sección sin ID, o con uno fuera de ese rango, se omite.
• Una sección posterior con el mismo ID (en el mismo archivo o en uno posterior) sustituye a la anterior.
• Los Weapon1/Weapon2/Weapon3, ExplodeAs y SelfDestructAs de una unidad nombran una sección; el nombre (sin distinguir mayúsculas) se resuelve en la posición más baja que contiene una sección con ese nombre.
• Los valores se leen como prefijos numéricos: weaponacceleration=13O; es 13, y un valor incorrecto nunca hace que se descarte el resto del archivo.
• Una estructura rota hace que el juego rechace el archivo entero, así que no se carga ninguna de sus armas, incluidas las secciones anteriores al fallo: una cabecera de sección sin ] o sin {, un texto sin = o un valor sin ; antes del final del archivo, un archivo que termina dentro de una sección, o un archivo vacío. Los demás archivos no se ven afectados. (Una } suelta fuera de cualquier sección no provoca el rechazo: el juego deja de leer ahí y conserva lo anterior.)
• Si falta range, vale 32767; si falta minbarrelangle, vale -11.25 grados; reloadtime cuenta en ticks enteros (30 por segundo, reloadtime*30 truncado: 0.35 recarga tras 10 ticks, 0,333 s); turnrate va en unidades de ángulo por segundo (65 536 = una vuelta completa).

KBot Studio, los paquetes y kbot host resuelven todos las armas a través de esta tabla. Los archivos que el juego rechaza y las secciones que omite o sustituye se señalan como avisos (kbot pack los muestra; el studio los sirve en /api/studio/weapons/warnings).

Sprites de rendertype=4#

Un arma rendertype=4 dispara un sprite 2D de anims/fx.gaf, y su color= elige cuál: 0 cannonshell, 1 plasmasm, 2 plasmamd, 3 ultrashell, 4 otra vez plasmasm; cualquier otro valor (como el color=255 de EARTHQUAKE) no dibuja ningún sprite. El sprite avanza un fotograma por tick de juego desde el momento del disparo, sean cuales sean las duraciones que lleven los fotogramas del GAF.

Los comentarios de referencia documentan:

• Tres arquetipos de arma: ballistic, lineofsight y dropped. Todo TDF de arma debe poner uno de ellos a 1.
• Alcance, velocidad, aceleración: en píxeles y píxeles/s.
• Área de efecto: radio en píxeles, con edgeeffectiveness como fracción de atenuación (p. ej., 0.5 = la mitad del daño en el borde).
• Ráfagas y dispersión: burst, burstrate, sprayangle.
• Armas de dos fases: twophase, weapontype2, flighttime para proyectiles de tipo starburst.
• Tipo de renderizado: rendertype=N elige modelo 3D, mapa de bits con paleta, rayo, etc.

La subsección [DAMAGE] es donde están los modificadores de daño por categoría de objetivo:

[FLAMETHROWER] {
    ...
    [DAMAGE]
    {
        default=10;     // Damage applied to anything not listed
        corpyro=2;      // Pyros are nearly fire-proof
    }
}

Las claves de [DAMAGE] son nombres de unidad: una unidad de la lista recibe ese daño en lugar de default=, y todas las demás reciben default=. Los valores se limitan a 16 bits. Las explosiones al morir (ExplodeAs, SelfDestructAs) usan la misma tabla: CORPYRO_BLAST hace 60 de daño por defecto, pero 15 a un Pyro.

category.tdf: descripciones de las categorías de unidades#

Una lista plana y puramente estética que asocia los tokens de categoría con un texto legible. El motor los muestra en el panel de información de la unidad:

[Plant]      { description = Unit Creation plant; }
[KBOT]       { description = Some type of units; }
[Tank]       { description = Some type of units; }
[Metal]      { description = Some type of units; }

Los guiones en lugar de descripciones son texto de relleno de Cavedog que se quedó ahí sin querer. La mayoría de los mods no tocan este archivo; algunos sustituyen las descripciones por un texto de ambientación en condiciones. Cambiarlo no afecta a la jugabilidad.

sound.tdf y allsound.tdf#

Se tratan en WAV / Sonido. En resumen:

• sound.tdf: asignaciones de sonido por categoría de unidad (las secciones [ARM_COM], [ARM_KBOT]). Las referencia el SoundCategory= del FBI. El juego lee 23 eventos, cada uno como KEY y después KEY1, KEY2, … hasta el primer número que falta.
• allsound.tdf: asignaciones globales de sonidos de la interfaz ([BIGBUTTON], [SKIRMISH], [BGM]).

Ejemplo desarrollado: añadir una clase de movimiento#

Para crear una clase de «barco capaz de vadear aguas muy poco profundas»:

1. Añade al final de gamedata/moveinfo.tdf:

   [CLASS20]
   {
       Name=AMPHIB3;
       FootprintX=3;
       FootprintZ=3;
       MaxWaterDepth=100;    // Deep water OK
       MaxSlope=20;          // Reasonable land climbing
       MaxWaterSlope=200;    // Smooth underwater movement
   }

2. En el FBI de tu unidad:

   MovementClass=AMPHIB3;

   La huella y los límites de la clase sustituyen a los del propio FBI, así que las claves FootprintX/FootprintZ/MaxWaterDepth de la unidad dejan de importar.

3. Empaqueta:

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

Ahora la unidad se desplazará sin problemas tanto por tierra como por agua.

Tamaños habituales#

Escollos#

• Las posiciones de las clases de movimiento son fijas. Solo se leen [CLASS0] a [CLASS31]; los huecos en la numeración dentro de ese rango no son problema.
• Los comentarios usan //, no /*…*/, en la mayoría de los archivos, pero weapons.tdf usa ambos. Los analizadores de prueba toleran los dos; algunas herramientas de terceros no.
• Las coordenadas del HUD de sidedata.tdf parten de una base de 640×480, y el motor las escala para resoluciones mayores. No escribas coordenadas en resoluciones modernas.
• La numeración de [CANBUILD] no puede tener huecos. El juego deja de leer la lista de un constructor en el primer canbuildN que falta, así que un canbuild11 seguido de un canbuild14 pierde la entrada 14 y todas las siguientes, sin dar error.
• Una MovementClass que el juego no encuentra no es un error. La unidad usa sin avisar sus propias claves del FBI, con los valores por defecto del juego para las que falten; así, una unidad sin MaxWaterDepth vadea hasta una profundidad de 10 000.

Véase también#

• TDF: la gramática a nivel de analizador que comparten FBI y OTA.
• Sonido: cómo se asignan los sonidos de sound.tdf y allsound.tdf.
• FBI: las unidades hacen referencia a MovementClass, SoundCategory y nombres de TDF de armas.
• Glosario: movement class, footprint, side.