TDF / FBI / OTA — File di configurazione testuali

I file TDF ("Text Data File"), FBI ("Feature/Building/Item") e OTA ("Online Total Annihilation") condividono tutti lo stesso formato testuale in stile INI. Sono il modo canonico con cui Cavedog dichiarava tutto ciò che non era binario: statistiche delle unità, parametri delle armi, definizioni degli elementi, metadati delle missioni, categorie dei suoni, suggerimenti per l'IA.

Sono semplici file di testo ASCII: puoi aprirli con qualsiasi editor di testo.

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

Sintassi#

Un file TDF è un albero di sezioni. Ogni sezione ha un nome tra parentesi quadre, seguito da un corpo { ... } che contiene coppie chiave=valore e/o sezioni annidate.

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

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

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

Regole:

• I nomi delle sezioni stanno tra parentesi quadre; tutto ciò che segue fino alla } corrispondente appartiene a quella sezione. Una sezione può stare su una sola riga ([special0] { specialwhat=StartPos1; XPos=464; ZPos=216; }).
• Un valore va dal = fino al ; successivo, anche su più righe: nient'altro lo chiude, quindi graffe, parentesi quadre e = dentro un valore sono testo normale, e un valore non può mai contenere un ;. Spazi, tabulazioni e a capo alle estremità di una chiave o di un valore vengono rimossi. Una chiave assegnata due volte mantiene l'ultimo valore.
• Le chiavi non distinguono tra maiuscole e minuscole. UnitName, unitname e UNITNAME indicano tutte lo stesso campo; gli strumenti di solito le normalizzano in minuscolo durante la lettura. Anche i nomi delle sezioni vengono confrontati ignorando maiuscole e minuscole.
• I valori sono stringhe per impostazione predefinita. I numeri vengono letti alla maniera del C, dalle cifre iniziali: 12abc vale 12 e 56.8 vale 56 dove il gioco si aspetta un numero intero (campi come killmul e tidalstrength vengono letti come frazioni). Le liste sono separate da spazi (ad es. Category=NOTSUB COMMANDER NOTAIR ...).
• I commenti vengono cancellati prima di leggere qualsiasi altra cosa: // fino alla fine della riga, e i blocchi /* ... */, che possono estendersi su più righe. Perciò missiondescription=See http://tauniverse.com; perde tutto da // in poi, compreso il suo ;, e il valore prosegue nella riga successiva. kbot si rifiuta di scrivere un valore che contenga ;, // o /*.
• Spazi bianchi e righe vuote vengono ignorati.

Le sezioni annidate (come [SOUNDS] dentro [UNITINFO] qui sopra) sono comuni negli FBI e negli OTA. La specifica TDF non fissa una profondità massima; in pratica non ne vedrai più di 3.

FBI — definizioni delle unità#

Un FBI è la visione completa che il motore ha di un'unità. Riunisce in un unico posto il modello 3D dell'unità, lo script, l'elenco delle armi, il banco sonoro, i costi di costruzione e il comportamento in combattimento. Un esempio ridotto dell'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 guida agli FBI scritta dalla comunità nel 1998 (conservata tra le fonti di questo repository) documenta più di cento campi. La maggior parte si spiega da sé; quelli meno ovvi sono di solito:

TDF — definizioni di elementi, armi e suoni#

I file features/**/*.tdf contengono sezioni [FEATURE], una per ogni oggetto statico della mappa. Il formato TNT (TNT) vi fa riferimento tramite il nome della sezione:

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

I file weapons/*.tdf seguono lo stesso schema, con sezioni [WEAPON_NAME]. Il campo Weapon1=COMMANDER_WEAPON dell'FBI si risolve nella sezione [COMMANDER_WEAPON] di uno dei TDF in weapons/, tramite la tabella delle armi del gioco, indicizzata per ID: ogni sezione ha bisogno di un ID= compreso tra 0 e 255, una sezione successiva con lo stesso ID sostituisce la precedente, e un nome si risolve nello slot più basso che lo contiene (vedi Gamedata: la tabella delle armi). La guida alle armi della comunità documenta circa 60 campi distinti; i più importanti sono ballistic/lineofsight/dropped (l'archetipo dell'arma), weapontimer, weaponvelocity, areaofeffect, edgeeffectiveness, burst/burstrate e la sottosezione [DAMAGE] (modificatori del danno per categoria).

[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] — Estensione del menu di costruzione#

I file in download/*.tdf registrano un'unità nei menu di costruzione di uno o più costruttori senza modificare sidedata.tdf. È il meccanismo che l'espansione Core Contingency di Cavedog usa per aggiungere le sue unità, e la convenzione seguita da ogni componente aggiuntivo .ufo per una singola 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;
}

Convenzione per i nomi dei file. Per convenzione il file si chiama download/<UNITNAME>.tdf (come lo UNITNAME= della prima voce), ma il motore legge ogni *.tdf in download/, quindi il nome del file è solo un'indicazione per il modder. La norma è un'unità per file.

Più voci. Un singolo file può contenere più voci: il download/Armfort.tdf di Cavedog ne usa tre per rendere l'Arm Fortification Wall costruibile da ACK, ACV e ACA. TA 3.1c legge le prime cinque sezioni di ogni file, qualunque sia il loro nome ([MENUENTRY1] è la convenzione, ma anche [ENTRY0] funziona); una sesta sezione non viene mai letta. Una voce il cui UNITMENU non nomina alcuna unità, o nessuna unità con Builder=1, viene ignorata, così come una il cui UNITNAME non nomina alcuna unità. MENU e BUTTON sono limitati a 8 bit, e il menu di un costruttore (la sua lista [CANBUILD] più le aggiunte da download/) contiene al massimo 31 unità.

È questo il punto d'aggancio additivo per le mod: ti permette di distribuire un singolo .ufo senza creare una tua copia modificata del sidedata.tdf da 50 KB. Vedi il tutorial sul modding per un esempio completo, dall'inizio alla fine.

OTA — metadati della mappa#

Un .ota accompagna ogni .tnt e contiene tutto ciò che serve al motore per far svolgere una partita sulla mappa (anziché per disegnarne il 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 legge il .ota corrispondente e disegna indicatori numerati in ogni posizione di partenza dello schema scelto.

Ecco come il gioco legge gli schemi e le posizioni di partenza. Tutte le viste di kbot (l'editor di mappe dello studio, la sandbox, l'esploratore di asset, kbot tnt preview, kbot tnt lint e il Quality Checker) li leggono allo stesso modo, tramite la vista di gioco degli OTA di kbot-io:

• Gli schemi vengono cercati per nome, Schema 0, Schema 1, … fino al primo numero mancante. I nomi vengono confrontati ignorando maiuscole e minuscole ([schema 1] conta), ma il numero va scritto in modo semplice: [Schema0] o [Schema 01] non vengono mai trovati, e uno schema dopo un buco nella numerazione (Schema 0, Schema 1, Schema 3) non viene mai letto. SCHEMACOUNT viene ignorato.
• Le partite in schermaglia e in multigiocatore scelgono uno schema in base a Type e al numero di posizioni di partenza, non alla posizione nel file. Sono idonei solo gli schemi da Network 1 a Network 4 (confrontati ignorando maiuscole e minuscole) con almeno una posizione di partenza. Per N giocatori il gioco preferisce l'ultimo schema idoneo con esattamente N posizioni di partenza, altrimenti quello che ne ha di più. Una missione della campagna sceglie in base alla difficoltà (Easy, Medium, Hard). numplayers è solo testo mostrato nella lobby (2, 4, 2-8 e Any si caricano tutti).
• Le posizioni di partenza sono le voci di [specials] il cui specialwhat inizia con StartPos (ignorando maiuscole e minuscole). StartPosN è lo slot del giocatore N-1, anche StartPos0 è lo slot 0, e una voce senza numero dopo StartPos prende per sé il numero successivo (il primo è 1). XPos e ZPos sono pixel della mappa, limitati a 16 bit.
• Le chiavi mancanti hanno valori predefiniti, non zeri: un missiondescription mancante mostra "No description available", un maxunits mancante (solo nelle campagne) significa 200, e un elemento piazzato in anticipo ([features]) senza XPos o ZPos viene saltato, quindi uno nella colonna o nella riga 0 ha bisogno di uno 0 esplicito.

Esempio svolto — unità minima#

Un FBI "finto", completo e funzionante, per una torretta fissa:

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

Per farne un componente aggiuntivo completo dovresti distribuire:

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

…e poi impacchettare la directory in un HPI:

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

Insidie#

• Le chiavi non distinguono tra maiuscole e minuscole, i valori sì. Side=arm corrisponde alla logica di classificazione delle unità per ARM, ma le mod che cambiano fazione al volo con if (Side == "ARM") tramite ricerche per uguaglianza di stringhe si rompono.
• I valori delle liste sono separati da spazi (Category=COMMANDER MOBILE WEAPON), non da virgole. Il motore spezza la lista a ogni carattere di spaziatura.
• Alcuni campi degli OTA usano però le virgole: numplayers=2,4,6,8,10. Non c'è un'unica convenzione per il separatore delle liste, e il gioco non analizza affatto numplayers: ne mostra solo il testo.
• Le sezioni annidate non hanno un limite formale di profondità, ma Cavedog non ha mai distribuito nulla con più di 3 livelli. Gli editor che presuppongono 2 livelli falliscono su una manciata di TDF delle armi con annidamenti in stile [WEAPON][DAMAGE][category].
• I campi booleani sono interi (canmove=1, canstop=0), non true/false. Il motore accetta solo 1/0.
• I file .ota hanno spesso mojibake UTF-8 nelle descrizioni delle missioni (virgolette tipografiche di Word, ecc.). Il motore li visualizza con la codepage Windows-1252 e mostrerà come quadratini ("tofu") qualsiasi carattere al di fuori di essa.

Dimensioni tipiche#

Appendice A — Dizionario dei campi FBI#

Ogni campo che si trova comunemente in units/*.fbi, raggruppato per scopo. Legenda della colonna Tipo: str = identificatore/stringa; int = intero; float = numero in virgola mobile; bool = 0/1; list = token separati da spazi bianchi; enum = piccolo intero con significati documentati.

I campi non elencati qui sono residui dell'editor (UnitNumber, Copyright) oppure non sono documentati. Il motore ignora silenziosamente le chiavi sconosciute.

Identità e visualizzazione#

Economia e costruzione#

Combattimento e sopravvivenza#

Movimento#

Sensori#

Menu di costruzione e ingombro#

Audio#

Varie / poco chiari#

Esempi reali nel catalogo di riferimento#

L'uso dei campi si impara meglio dagli FBI reali. I repository di riferimento catalogano ogni unità distribuita:

• TA — tutti gli FBI: buoni esempi "ricchi" sono ARMCOM (comandante con Commander=1, CloakCost, MaxDamage=3000), ARMSAM (torretta con Weapon1/2/3 tutti impostati), ARMBRAWL (aereo con CanFly, crusisealt, BankScale), ARMMEX (estrattore di metallo con ExtractsMetal).
• TA — tutti i TDF delle armi: [FLAMETHROWER] per burst/burstrate/firestarter, [NUCLEAR_MISSILE] per i missili guidati a due fasi, [LIGHTNING] per un'arma a raggio.
• TA — albero di costruzione di elementi e armi: ogni registrazione [MENUENTRY] dell'installazione.
• Unità di TA: Kingdoms: il diverso insieme di campi (buildcost= con una sola risorsa, damagecategory=, [WEAPONn] inline). ARAKING (Elsin, il monarca di Aramon) e ARAARCH (Archer) sono buoni punti di partenza.

Vedi anche#

• TNT: fa riferimento a nomi di elementi che si risolvono in sezioni TDF [FEATURE].
• 3DO, COB: richiamati dall'Objectname dell'FBI.
• GAF: richiamato dal seqname degli elementi e dall'explosiongaf delle armi.
• TDF di gamedata: moveinfo.tdf, sound.tdf, sidedata.tdf, richiamati dai campi dell'FBI.
• Audio: come SoundCategory si risolve in file WAV.
• Glossario: fazione (side), ingombro (footprint), yardmap, schema.