TDF / FBI / OTA: archivos de configuración de texto

Los archivos TDF («Text Data File»), FBI («Feature/Building/Item») y OTA («Online Total Annihilation») comparten el mismo formato de texto al estilo INI. Son la forma canónica con la que Cavedog declaraba todo lo que no era binario: estadísticas de unidades, parámetros de armas, definiciones de elementos, metadatos de misiones, categorías de sonido, pistas para la IA.

Son archivos ASCII normales; puedes abrirlos con cualquier editor de texto.

# The web UI renders FBI/TDF/OTA as collapsible section trees
kbot mount ~/games/totala --server
# → browse to units/ARMCOM.FBI

import "github.com/coreprime/kbot/formats/tdf"

doc, _ := tdf.ParseFile("units/ARMCOM.FBI")
info := doc.Section("UNITINFO")
fmt.Println(info.String("UnitName"), info.Int("MaxDamage"))

Sintaxis#

Un archivo TDF es un árbol de secciones. Cada sección tiene un nombre entre corchetes y después un cuerpo { ... } que contiene pares clave=valor, secciones anidadas o ambas cosas.

[UNITINFO]
{
    UnitName=ARMCOM;
    Designation=Commander;
    Description=Commander, Arm;
    Side=ARM;
    Objectname=armcom;

    BuildCostEnergy=2500;
    BuildCostMetal=2500;
    MaxDamage=3000;

    [SOUNDS]
    {
        canselect=cmdsel1;
        select1=cmdok1;
    }
}

Reglas:

• Los nombres de sección van entre corchetes; todo lo que sigue hasta la } correspondiente pertenece a esa sección. Una sección puede ocupar una sola línea ([special0] { specialwhat=StartPos1; XPos=464; ZPos=216; }).
• Un valor va desde el = hasta el siguiente ;, aunque haya saltos de línea por medio: ninguna otra cosa lo termina, así que las llaves, los corchetes y los = dentro de un valor son texto normal, y un valor nunca puede contener un ;. Los espacios, tabuladores y saltos de línea en los extremos de una clave o de un valor se recortan. Una clave asignada dos veces conserva el último valor.
• Las claves no distinguen mayúsculas de minúsculas. UnitName, unitname y UNITNAME se refieren al mismo campo; las herramientas suelen normalizarlas a minúsculas al leer. Los nombres de sección también se comparan sin distinguir mayúsculas.
• Los valores son cadenas por defecto. Los números se leen a la manera de C, a partir de los dígitos iniciales: 12abc se lee como 12 y 56.8 como 56 allí donde el juego espera un número entero (campos como killmul y tidalstrength se leen como fracciones). Las listas van separadas por espacios (p. ej., Category=NOTSUB COMMANDER NOTAIR ...).
• Los comentarios se borran antes de leer cualquier otra cosa: // hasta el final de la línea, y los bloques /* ... */, que pueden ocupar varias líneas. Así, missiondescription=See http://tauniverse.com; pierde todo desde // en adelante, incluido su ;, y el valor continúa en la línea siguiente. kbot se niega a escribir un valor que contenga ;, // o /*.
• Los espacios en blanco y las líneas vacías se ignoran.

Las secciones anidadas (como [SOUNDS] dentro de [UNITINFO] en el ejemplo de arriba) son habituales en los FBI y los OTA. La especificación de TDF no fija una profundidad máxima; en la práctica no verás más de 3 niveles.

FBI: definiciones de unidades#

Un FBI es todo lo que el motor sabe de una unidad. Reúne en un solo lugar el modelo 3D de la unidad, el script, la lista de armas, el banco de sonido, los costes de construcción y el comportamiento en combate. Un ejemplo recortado del Arm Commander:

[UNITINFO]
{
    // === Identification ===
    UnitName=ARMCOM;          // Internal lookup key
    Objectname=armcom;        // → objects3d/armcom.3do, scripts/armcom.cob
    Side=ARM;                 // ARM or CORE
    Designation=Commander;    // Mouseover label
    Description=Commander, Arm;

    // === Economy & build ===
    BuildCostMetal=2500;
    BuildCostEnergy=2500;
    BuildTime=89400;          // Build-power × seconds (engine units)
    WorkerTime=300;           // How fast it builds other things

    // === Combat ===
    MaxDamage=3000;           // Hit points
    Weapon1=COMMANDER_WEAPON; // → weapons/commander_weapon.tdf [COMMANDER_WEAPON]
    Weapon2=disintegrator;    // The dreaded D-gun
    candgun=1;                // Allowed to fire weapon2 on demand

    // === Movement ===
    MaxVelocity=1.15;
    Acceleration=0.075;
    BrakeRate=0.0825;
    TurnRate=510;
    MovementClass=COMMANDER_TANK3;  // → gamedata/movinfo.tdf

    // === Senses ===
    SightDistance=520;
    RadarDistance=585;

    // === Tags & categories ===
    Category=COMMANDER SURFACE MOBILE WEAPON ...;
    NoChaseCategory=AIR;

    [SOUNDS] {
        canselect=cmdsel1;
        select1=cmdok1;
        ...
    }
}

La guía de FBI de la comunidad de 1998 (conservada en los materiales de origen de este repositorio) documenta más de un centenar de campos. La mayoría se explican solos; los que no son evidentes suelen ser estos:

TDF: definiciones de elementos, armas y sonidos#

Los archivos features/**/*.tdf contienen secciones [FEATURE], una por cada objeto estático del mapa. El formato TNT (TNT) hace referencia a ellas por el nombre de sección:

[ArmTree01]
{
    description=Arm Tree;
    category=trees;
    object=arm_tree01;       // → objects3d/arm_tree01.3do
    footprintx=1;
    footprintz=1;
    height=20;
    blocking=1;              // Pathing obstacle
    flamable=1;
    burnmin=10;
    burnmax=20;
    burntime=30;
    feature_reclamate=ArmTree01_Heap; // Recursive: what's left when reclaimed
    damage=15;
    reclaimable=1;
    energy=0;
    metal=2;
    seqname=arm_tree01;      // GAF sequence to draw (for animated features)
}

Los weapons/*.tdf siguen el mismo patrón, con secciones [WEAPON_NAME]. El campo Weapon1=COMMANDER_WEAPON del FBI se resuelve en la sección [COMMANDER_WEAPON] de algún TDF de weapons/, a través de la tabla de armas del juego indexada por ID: cada sección necesita un ID= entre 0 y 255, una sección posterior con el mismo ID sustituye a una anterior, y un nombre se resuelve en la posición más baja que lo contiene (consulta Gamedata: la tabla de armas). La guía de armas de la comunidad documenta unos 60 campos distintos; los más sustanciosos son ballistic/lineofsight/dropped (el arquetipo del arma), weapontimer, weaponvelocity, areaofeffect, edgeeffectiveness, burst/burstrate y la subsección [DAMAGE] (modificadores de daño por categoría).

[FLAMETHROWER] {
    ID=1;
    name=Flame Thrower;
    rendertype=5;
    ballistic=1;
    turret=1;
    range=160;
    reloadtime=1.2;
    weapontimer=1;
    weaponvelocity=188;
    areaofeffect=32;
    burst=17;
    burstrate=.04;
    [DAMAGE] {
        default=10;
        corpyro=2;          // Pyros are nearly fireproof
    }
}

[MENUENTRY]: ampliación del menú de construcción#

Los archivos de download/*.tdf registran una unidad en los menús de construcción de uno o varios constructores sin modificar sidedata.tdf. Es el mecanismo con el que la expansión Core Contingency de Cavedog añade sus unidades, y la convención que sigue todo complemento .ufo de una sola unidad.

[MENUENTRY1]
{
    UNITMENU=ARMVP;       // Builder's UnitName
    MENU=3;               // Menu page (row)
    BUTTON=4;             // Slot within the page
    UNITNAME=MYFLASH;     // Unit being placed
}

[MENUENTRY2]              // Additional builders for the same unit
{
    UNITMENU=ARMACV;
    MENU=3;
    BUTTON=4;
    UNITNAME=MYFLASH;
}

Convención de nombres de archivo. Por convención, el archivo es download/<UNITNAME>.tdf (igual que el UNITNAME= de la primera entrada), pero el motor lee todos los *.tdf de download/, así que el nombre del archivo es solo una pista para el modder. Lo normal es una unidad por archivo.

Varias entradas. Un solo archivo puede contener varias entradas: el download/Armfort.tdf de Cavedog usa tres para que el Arm Fortification Wall se pueda construir desde ACK, ACV y ACA. TA 3.1c lee las cinco primeras secciones de cada archivo, se llamen como se llamen ([MENUENTRY1] es la convención, pero [ENTRY0] también funciona); una sexta sección no se lee nunca. Se ignora la entrada cuyo UNITMENU no corresponda a ninguna unidad (o a ninguna con Builder=1), igual que la que tenga un UNITNAME que no corresponda a ninguna unidad. MENU y BUTTON se limitan a 8 bits, y el menú de un constructor (su lista [CANBUILD] más los añadidos de download) admite como máximo 31 unidades.

Este es el mecanismo aditivo que te permite distribuir un mod en un único .ufo sin hacer una copia propia del sidedata.tdf de 50 KB. Consulta el tutorial de modding para ver el proceso completo.

OTA: metadatos del mapa#

El .ota acompaña a cada .tnt y contiene todo lo que el motor necesita para jugar el mapa (a diferencia de renderizar su terreno):

[GlobalHeader]
{
    missionname=Metal Heck;
    missiondescription=A small, brutal metal map.;
    planet=metal;
    tidalstrength=0;
    solarstrength=20;
    lavaworld=0;
    killmul=50;
    waterdoesdamage=0;
    minwindspeed=100;
    maxwindspeed=2500;
    gravity=112;
    numplayers=2,4,6,8,10;

    [Schema 0] {
        Type=Network 1;
        aiprofile=DEFAULT;
        SurfaceMetal=10;
        MohoMetal=125;
        HumanMetal=1000;
        ComputerMetal=1000;
        HumanEnergy=1000;
        ComputerEnergy=1000;
        [specials] {
            [special0] { specialwhat=StartPos1; XPos=464; ZPos=216; }
            [special1] { specialwhat=StartPos2; XPos=3408; ZPos=216; }
            ...
        }
    }
}

kbot tnt preview lee el .ota correspondiente y dibuja marcadores numerados en cada posición de inicio del esquema elegido.

Cómo lee el juego los esquemas y las posiciones de inicio (todas las vistas de kbot, es decir, el editor de mapas del studio, el sandbox, el explorador de recursos, kbot tnt preview, kbot tnt lint y el Quality Checker, los leen de la misma manera, a través de la vista de juego de OTA de kbot-io):

• Los esquemas se buscan por nombre, Schema 0, Schema 1, … hasta el primer número que falte. Los nombres se comparan sin distinguir mayúsculas ([schema 1] cuenta), pero el número debe estar escrito tal cual: [Schema0] o [Schema 01] no se encuentran nunca, y un esquema después de un hueco (Schema 0, Schema 1, Schema 3) no se lee nunca. SCHEMACOUNT se ignora.
• Las escaramuzas y las partidas multijugador eligen un esquema por Type y número de posiciones de inicio, no por su posición en el archivo. Solo cuentan los esquemas Network 1 a Network 4 (comparados sin distinguir mayúsculas) con al menos una posición de inicio. Para N jugadores, el juego prefiere el último esquema válido con exactamente N posiciones de inicio y, si no lo hay, el que tenga más. Una misión de campaña elige por dificultad (Easy, Medium, Hard). numplayers es solo un texto que se muestra en el lobby (2, 4, 2-8 y Any cargan todos).
• Las posiciones de inicio son las entradas de [specials] cuyo specialwhat empieza por StartPos (sin distinguir mayúsculas). StartPosN es la plaza de jugador N-1, StartPos0 también es la plaza 0, y una entrada sin número tras StartPos toma el siguiente número de su propia serie (el primero es 1). XPos y ZPos son píxeles del mapa, limitados a 16 bits.
• Las claves que faltan tienen valores por defecto, no ceros: si falta missiondescription se muestra «No description available», si falta maxunits (solo en campañas) se usan 200, y un elemento colocado de antemano ([features]) sin XPos o ZPos se omite, así que uno en la columna o la fila 0 necesita un 0 explícito.

Ejemplo desarrollado: una unidad mínima#

Un FBI «de prueba» completo y funcional para una torreta fija:

[UNITINFO]
{
    UnitName=MYTURRET;
    Objectname=myturret;
    Side=ARM;
    Designation=Test Turret;
    Description=Bare-minimum turret for format testing.

    BuildCostMetal=200;
    BuildCostEnergy=400;
    BuildTime=2400;
    MaxDamage=600;

    Category=NOTSUB SURFACE WEAPON NOTAIR;
    TEDClass=LASER;
    Builder=0;
    canattack=1;
    onoffable=0;
    ActivateWhenBuilt=1;

    Weapon1=LIGHTLASER;

    FootprintX=2;
    FootprintZ=2;
    YardMap=cccc;
    MaxSlope=15;
    MaxWaterDepth=0;
    SightDistance=300;

    Corpse=MyTurret_Dead;

    [SOUNDS] {
        select1=corselect1;
        ok1=corok1;
    }
}

Para convertirlo en un complemento de unidad completo, distribuirías:

mymod/
├── units/myturret.fbi
├── objects3d/myturret.3do
├── scripts/MYTURRET.cob
├── features/corpses/myturret.tdf       # contains [MyTurret_Dead]
└── unitpics/MYTURRET.PCX

…y después empaquetarías el directorio como HPI:

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

Escollos#

• Las claves no distinguen mayúsculas de minúsculas; los valores sí. Side=arm funcionará con la lógica que clasifica las unidades de ARM, pero fallarán los mods que cambian de bando sobre la marcha con if (Side == "ARM") y comparaciones de cadenas exactas.
• Los valores de lista van separados por espacios (Category=COMMANDER MOBILE WEAPON), no por comas. El motor separa por cualquier espacio en blanco.
• Algunos campos de OTA usan comas, eso sí: numplayers=2,4,6,8,10. No hay una única convención para separar listas, y el juego ni siquiera analiza numplayers: solo muestra el texto.
• Las secciones anidadas no tienen un límite de profundidad formal, pero Cavedog nunca distribuyó nada con más de 3 niveles. Los editores que suponen 2 niveles fallarán con un puñado de TDF de armas que anidan al estilo de [WEAPON][DAMAGE][category].
• Los campos booleanos son enteros (canmove=1, canstop=0), no true/false. El motor solo acepta 1/0.
• Los archivos .ota tienen a menudo mojibake de UTF-8 en las descripciones de las misiones (comillas tipográficas de Word, etc.). El motor los muestra con la página de códigos Windows-1252 y pinta un recuadro vacío en lugar de todo lo que quede fuera de ella.

Tamaños habituales#

Apéndice A: diccionario de campos FBI#

Todos los campos que suelen aparecer en units/*.fbi, agrupados por finalidad. Claves de la columna Tipo: str = identificador/cadena; int = entero; float = coma flotante; bool = 0/1; list = tokens separados por espacios en blanco; enum = entero pequeño con significados documentados.

Los campos que no figuran aquí son datos de trabajo del editor (UnitNumber, Copyright) o no están documentados. El motor ignora sin avisar las claves desconocidas.

Identidad y presentación#

Economía y construcción#

Combate y supervivencia#

Movimiento#

Sentidos#

Menú de construcción y huella#

Audio#

Varios / poco conocidos#

Ejemplos reales en el catálogo de referencia#

El uso de los campos se aprende mejor con FBI reales. Los repositorios de referencia catalogan todas las unidades distribuidas:

• TA: todos los FBI: buenos ejemplos «ricos» son ARMCOM (comandante con Commander=1, CloakCost, MaxDamage=3000), ARMSAM (torreta con Weapon1/2/3 rellenos), ARMBRAWL (aeronave con CanFly, crusisealt, BankScale) y ARMMEX (extractor de metal con ExtractsMetal).
• TA: todos los TDF de armas: [FLAMETHROWER] para burst/burstrate/firestarter, [NUCLEAR_MISSILE] para los misiles guiados de dos fases y [LIGHTNING] para un arma de rayo.
• TA: árbol de construcción de elementos y armas, con todos los registros [MENUENTRY] de la instalación.
• Unidades de TA: Kingdoms, con un conjunto de campos distinto (buildcost= con un único recurso, damagecategory=, [WEAPONn] en línea). ARAKING (Elsin, el monarca de Aramon) y ARAARCH (Archer) son buenos puntos de partida.

Véase también#

• TNT: hace referencia a nombres de elementos que se resuelven en secciones TDF [FEATURE].
• 3DO, COB: referenciados desde el Objectname del FBI.
• GAF: referenciado desde el seqname de los elementos y el explosiongaf de las armas.
• TDF de gamedata: moveinfo.tdf, sound.tdf y sidedata.tdf, referenciados desde campos del FBI.
• Sonido: cómo se resuelve SoundCategory en archivos WAV.
• Glosario: side, footprint, yardmap, schema.