TDF / FBI / OTA — fichiers de configuration texte

Les fichiers TDF (« Text Data File »), FBI (« Feature/Building/Item ») et OTA (« Online Total Annihilation ») partagent tous le même format texte de style INI. C'est sous cette forme que Cavedog déclarait, par principe, tout ce qui n'était pas binaire : caractéristiques des unités, paramètres des armes, définitions des éléments de décor, métadonnées des missions, catégories de sons, indications pour l'IA.

Ces fichiers sont en ASCII brut ; on peut les ouvrir dans n'importe quel éditeur de texte.

# 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"))

Syntaxe#

Un fichier TDF est un arbre de sections. Chaque section a un nom entre crochets, puis un corps { ... } qui contient des paires clé=valeur et/ou des sections imbriquées.

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

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

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

Règles :

• Les noms de sections sont entre crochets ; tout ce qui suit jusqu'à l'accolade } correspondante appartient à cette section. Une section peut tenir sur une ligne ([special0] { specialwhat=StartPos1; XPos=464; ZPos=216; }).
• Une valeur va du = jusqu'au ; suivant, par-delà les sauts de ligne : rien d'autre ne la termine, donc les accolades, les crochets et les = à l'intérieur d'une valeur sont du texte ordinaire, et une valeur ne peut jamais contenir de ;. Les espaces, tabulations et sauts de ligne aux deux extrémités d'une clé ou d'une valeur sont supprimés. Une clé affectée deux fois garde sa dernière valeur.
• Les clés sont insensibles à la casse. UnitName, unitname et UNITNAME désignent tous le même champ ; les outils les ramènent couramment en minuscules à la lecture. Les noms de sections sont eux aussi comparés sans tenir compte de la casse.
• Les valeurs sont des chaînes par défaut. Les nombres sont lus à la manière du C, à partir des premiers chiffres : 12abc se lit 12 et 56.8 se lit 56 là où le jeu attend un entier (des champs comme killmul et tidalstrength sont lus comme des nombres décimaux). Les listes sont séparées par des espaces (par ex. Category=NOTSUB COMMANDER NOTAIR ...).
• Les commentaires sont effacés avant toute autre lecture : // jusqu'à la fin de la ligne, et les blocs /* ... */, qui peuvent s'étendre sur plusieurs lignes. Ainsi, missiondescription=See http://tauniverse.com; perd tout à partir de //, y compris son ;, et la valeur se prolonge sur la ligne suivante. kbot refuse d'écrire une valeur qui contient ;, // ou /*.
• Les blancs et les lignes vides sont ignorés.

Les sections imbriquées (comme [SOUNDS] dans [UNITINFO] ci-dessus) sont courantes dans les FBI et les OTA. La spécification TDF ne fixe pas de profondeur maximale ; en pratique, on n'en voit pas plus de 3.

FBI — définitions d'unités#

Un FBI est la vision complète qu'a le moteur d'une unité. Il rassemble en un seul endroit le modèle 3D de l'unité, son script, la liste de ses armes, sa banque de sons, ses coûts de construction et son comportement au combat. Exemple abrégé du commandant Arm :

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

Le guide FBI rédigé par la communauté en 1998 (conservé parmi les documents sources de ce dépôt) documente plus d'une centaine de champs. La plupart se comprennent d'eux-mêmes ; les moins évidents sont en général :

TDF — définitions d'éléments de décor, d'armes et de sons#

Les fichiers features/**/*.tdf contiennent des sections [FEATURE], une par élément de décor statique de la carte. Le format TNT (TNT) y fait référence par nom de section :

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

Les weapons/*.tdf suivent le même schéma, avec des sections [WEAPON_NAME]. Le champ Weapon1=COMMANDER_WEAPON du FBI se résout vers la section [COMMANDER_WEAPON] d'un TDF de weapons/, par l'intermédiaire de la table des armes du jeu, indexée par ID : chaque section a besoin d'un ID= entre 0 et 255, une section ultérieure de même ID remplace la précédente, et un nom se résout vers l'emplacement le plus bas qui le contient (voir Gamedata : la table des armes). Le guide des armes de la communauté documente une soixantaine de champs distincts ; les plus importants sont ballistic/lineofsight/dropped (l'archétype de l'arme), weapontimer, weaponvelocity, areaofeffect, edgeeffectiveness, burst/burstrate et la sous-section [DAMAGE] (modificateurs de dégâts par catégorie).

[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] — extension du menu de construction#

Les fichiers download/*.tdf inscrivent une unité dans les menus de construction d'un ou plusieurs constructeurs sans modifier sidedata.tdf. C'est le mécanisme qu'utilise l'extension Core Contingency de Cavedog pour ajouter ses unités, et la convention que suit chaque extension .ufo à une seule unité.

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

Convention de nommage. Le fichier s'appelle par convention download/<UNITNAME>.tdf (d'après le UNITNAME= de la première entrée), mais le moteur lit tous les *.tdf de download/ : le nom de fichier n'est donc qu'une indication pour le moddeur. Une unité par fichier est la norme.

Entrées multiples. Un même fichier peut contenir plusieurs entrées : le download/Armfort.tdf de Cavedog en utilise trois pour rendre le mur de fortification Arm constructible par l'ACK, l'ACV et l'ACA. TA 3.1c lit les cinq premières sections de chaque fichier, quels que soient leurs noms ([MENUENTRY1] est la convention, [ENTRY0] fonctionne aussi) ; une sixième section n'est jamais lue. Une entrée dont UNITMENU ne désigne aucune unité, ou aucune unité avec Builder=1, est ignorée, tout comme une entrée dont UNITNAME ne désigne aucune unité. MENU et BUTTON sont tronqués à 8 bits, et le menu d'un constructeur — sa liste [CANBUILD] plus les ajouts de download — contient au plus 31 unités.

C'est ce point d'extension additif qui permet de livrer un seul .ufo sans dériver le sidedata.tdf de 50 Ko. Le tutoriel de modding le met en œuvre de bout en bout.

OTA — métadonnées de carte#

Un .ota accompagne chaque .tnt et contient tout ce dont le moteur a besoin pour faire tourner la carte (par opposition au rendu de son terrain) :

[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 lit le .ota correspondant et dessine des marqueurs numérotés à chaque position de départ du schéma choisi.

Comment le jeu lit les schémas et les positions de départ (toutes les vues de kbot — l'éditeur de cartes du studio, le bac à sable, l'explorateur de ressources, kbot tnt preview, kbot tnt lint et le Quality Checker — les lisent de la même façon, par la vue de jeu OTA de kbot-io) :

• Les schémas sont trouvés par leur nom, Schema 0, Schema 1, … jusqu'au premier numéro manquant. Les noms sont comparés sans tenir compte de la casse ([schema 1] compte), mais le numéro doit être écrit simplement : [Schema0] ou [Schema 01] ne sont jamais trouvés, et un schéma situé après un trou (Schema 0, Schema 1, Schema 3) n'est jamais lu. SCHEMACOUNT est ignoré.
• Les parties en escarmouche et en multijoueur choisissent un schéma selon son Type et son nombre de positions de départ, pas selon sa place dans le fichier. Seuls les schémas Network 1 à Network 4 (comparés sans tenir compte de la casse) ayant au moins une position de départ sont retenus. Pour N joueurs, le jeu préfère le dernier schéma retenu qui a exactement N positions de départ, sinon celui qui en a le plus. Une mission de campagne choisit selon la difficulté (Easy, Medium, Hard). numplayers n'est qu'un texte affiché dans le salon (2, 4, 2-8 et Any se chargent tous).
• Les positions de départ sont les entrées de [specials] dont specialwhat commence par StartPos (sans tenir compte de la casse). StartPosN correspond à l'emplacement de joueur N-1, StartPos0 correspond lui aussi à l'emplacement 0, et une entrée sans numéro après StartPos prend le numéro suivant dans sa propre série (qui commence à 1). XPos et ZPos sont en pixels de carte, tronqués à 16 bits.
• Les clés manquantes ont des valeurs par défaut, pas des zéros : un missiondescription absent affiche « No description available », un maxunits absent (campagnes uniquement) vaut 200, et un élément de décor pré-placé ([features]) sans XPos ou ZPos est ignoré : celui qui se trouve en colonne ou en ligne 0 a donc besoin d'un 0 explicite.

Exemple commenté — unité minimale#

Un FBI « factice » complet et fonctionnel pour une tourelle fixe :

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

Pour en faire une extension d'unité complète, il faudrait livrer :

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

…puis empaqueter le répertoire en HPI :

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

Pièges#

• Les clés sont insensibles à la casse, les valeurs non. Side=arm correspondra bien à la logique de classification des unités pour ARM, mais les mods qui changent de camp à la volée en testant if (Side == "ARM") par égalité stricte de chaînes ne fonctionneront plus.
• Les valeurs de liste sont séparées par des espaces (Category=COMMANDER MOBILE WEAPON), pas par des virgules. Le moteur découpe à chaque blanc, quel qu'il soit.
• Certains champs OTA utilisent pourtant des virgules : numplayers=2,4,6,8,10. Il n'existe pas de convention unique de séparateur de liste, et le jeu n'analyse jamais numplayers : il ne fait qu'en afficher le texte.
• Les sections imbriquées n'ont pas de limite de profondeur formelle, mais Cavedog n'a jamais rien livré au-delà de 3 niveaux. Les éditeurs qui supposent 2 niveaux échoueront sur une poignée de TDF d'armes avec une imbrication du type [WEAPON][DAMAGE][category].
• Les champs booléens sont des entiers (canmove=1, canstop=0), pas true/false. Le moteur n'accepte que 1/0.
• Les fichiers .ota contiennent souvent du mojibake UTF-8 dans les descriptions de missions (guillemets typographiques venus de Word, etc.). Le moteur les affiche avec la page de code Windows-1252 et transforme en carrés vides tout ce qui en sort.

Tailles typiques#

Annexe A — dictionnaire des champs FBI#

Tous les champs que l'on trouve couramment dans units/*.fbi, regroupés par fonction. Légende de la colonne Type : str = identifiant/chaîne ; int = entier ; float = nombre à virgule flottante ; bool = 0/1 ; list = jetons séparés par des blancs ; enum = petit entier aux significations documentées.

Les champs qui ne figurent pas ici sont soit des données de travail de l'éditeur (UnitNumber, Copyright), soit non documentés. Le moteur ignore silencieusement les clés inconnues.

Identité et affichage#

Économie et construction#

Combat et survie#

Déplacement#

Perception#

Menu de construction et emprise#

Audio#

Divers / mal compris#

Exemples concrets dans le catalogue de référence#

L'usage des champs s'apprend mieux sur de vrais FBI. Les dépôts de référence cataloguent chaque unité livrée :

• TA — tous les FBI : de bons exemples « riches » sont ARMCOM (commandant avec Commander=1, CloakCost, MaxDamage=3000), ARMSAM (tourelle avec Weapon1/2/3 remplis), ARMBRAWL (aéronef avec CanFly, crusisealt, BankScale), ARMMEX (extracteur de métal avec ExtractsMetal).
• TA — tous les TDF d'armes : [FLAMETHROWER] pour burst/burstrate/firestarter, [NUCLEAR_MISSILE] pour les missiles guidés en deux phases, [LIGHTNING] pour une arme à rayon.
• TA — arbre de construction des éléments et des armes — chaque inscription [MENUENTRY] de l'installation.
• Unités de TA: Kingdoms — l'autre jeu de champs (buildcost= à ressource unique, damagecategory=, [WEAPONn] en ligne). ARAKING (Elsin, le monarque d'Aramon) et ARAARCH (Archer) sont de bons points d'entrée.

Voir aussi#

• TNT — fait référence à des noms d'éléments de décor qui se résolvent vers des sections TDF [FEATURE].
• 3DO, COB — référencés par le champ Objectname du FBI.
• GAF — référencé par le seqname des éléments de décor et l'explosiongaf des armes.
• TDF de gamedata — moveinfo.tdf, sound.tdf et sidedata.tdf, référencés par des champs du FBI.
• Son — comment SoundCategory se résout en fichiers WAV.
• Glossaire — camp, emprise, yardmap, schéma.