TDF / FBI / OTA – Konfigurationsdateien im Textformat

TDF („Text Data File“), FBI („Feature/Building/Item“) und OTA („Online Total Annihilation“) teilen sich alle dasselbe INI-ähnliche Textformat. Mit ihnen hat Cavedog grundsätzlich alles deklariert, was nicht binär war – Einheitenwerte, Waffenparameter, Definitionen von Kartenobjekten, Missions-Metadaten, Soundkategorien, Hinweise für die KI.

Diese Dateien sind reines ASCII; du kannst sie in jedem Texteditor öffnen.

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

Syntax#

Eine TDF-Datei ist ein Baum aus Abschnitten. Jeder Abschnitt hat einen Namen in eckigen Klammern, danach einen Rumpf { ... } mit Schlüssel=Wert-Paaren und/oder verschachtelten Abschnitten.

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

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

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

Regeln:

• Abschnittsnamen stehen in eckigen Klammern; alles, was bis zur passenden } folgt, gehört zu diesem Abschnitt. Ein Abschnitt kann in einer Zeile stehen ([special0] { specialwhat=StartPos1; XPos=464; ZPos=216; }).
• Ein Wert reicht vom = bis zum nächsten ;, auch über Zeilenumbrüche hinweg: Nichts anderes beendet ihn; geschweifte und eckige Klammern und = innerhalb eines Werts sind also einfacher Text, und ein Wert kann nie ein ; enthalten. Leerzeichen, Tabs und Zeilenumbrüche an beiden Enden eines Schlüssels oder Werts werden abgeschnitten. Ein zweimal zugewiesener Schlüssel behält seinen letzten Wert.
• Schlüssel unterscheiden nicht zwischen Groß- und Kleinschreibung. UnitName, unitname und UNITNAME bezeichnen alle dasselbe Feld; Werkzeuge normalisieren beim Lesen üblicherweise auf Kleinbuchstaben. Auch Abschnittsnamen werden ohne Beachtung der Groß- und Kleinschreibung verglichen.
• Werte sind standardmäßig Strings. Zahlen werden wie in C aus den führenden Ziffern gelesen: 12abc wird als 12 gelesen und 56.8 als 56, wo das Spiel eine ganze Zahl erwartet (Felder wie killmul und tidalstrength werden als Kommazahlen gelesen). Listen sind durch Leerzeichen getrennt (z. B. Category=NOTSUB COMMANDER NOTAIR ...).
• Kommentare werden entfernt, bevor irgendetwas anderes gelesen wird: // bis zum Zeilenende und /* ... */-Blöcke, die über mehrere Zeilen gehen dürfen. Deshalb verliert missiondescription=See http://tauniverse.com; alles ab //, einschließlich seines ;, und der Wert läuft bis in die nächste Zeile weiter. kbot weigert sich, einen Wert zu schreiben, der ;, // oder /* enthält.
• Leerraum und Leerzeilen werden ignoriert.

Verschachtelte Abschnitte (wie [SOUNDS] innerhalb von [UNITINFO] oben) sind in FBI/OTA häufig. Die TDF-Spezifikation legt keine maximale Tiefe fest; in der Praxis wirst du nicht mehr als 3 Ebenen sehen.

FBI – Einheitendefinitionen#

Eine FBI ist die vollständige Sicht der Engine auf eine Einheit. Sie führt das 3D-Modell der Einheit, das Skript, die Waffenliste, die Soundbank, die Baukosten und das Kampfverhalten an einer Stelle zusammen. Ein gekürztes Beispiel am 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;
        ...
    }
}

Der FBI-Leitfaden der Community von 1998 (in den Quellmaterialien dieses Repos aufbewahrt) dokumentiert über hundert Felder. Die meisten erklären sich selbst; die nicht offensichtlichen sind meist diese:

TDF – Definitionen von Kartenobjekten, Waffen und Sounds#

Die Dateien features/**/*.tdf enthalten [FEATURE]-Abschnitte, einen pro statischem Kartenobjekt. Das TNT-Format (TNT) verweist über den Abschnittsnamen auf sie:

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

weapons/*.tdf folgen demselben Muster, mit Abschnitten [WEAPON_NAME]. Das FBI-Feld Weapon1=COMMANDER_WEAPON wird zum Abschnitt [COMMANDER_WEAPON] in irgendeiner TDF in weapons/ aufgelöst, und zwar über die nach ID indizierte Waffentabelle des Spiels: Jeder Abschnitt braucht ein ID= im Bereich 0–255, ein späterer Abschnitt mit derselben ID ersetzt einen früheren, und ein Name wird zum niedrigsten Platz aufgelöst, der ihn enthält (siehe Gamedata: die Waffentabelle). Der Waffen-Leitfaden der Community dokumentiert etwa 60 verschiedene Felder; die wichtigsten sind ballistic/lineofsight/dropped (der Grundtyp der Waffe), weapontimer, weaponvelocity, areaofeffect, edgeeffectiveness, burst/burstrate und der Unterabschnitt [DAMAGE] (Schadensmodifikatoren pro Kategorie).

[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] – Erweiterung des Baumenüs#

Dateien in download/*.tdf tragen eine Einheit in die Baumenüs einer oder mehrerer Baueinheiten ein, ohne sidedata.tdf zu verändern. Über diesen Mechanismus fügt Cavedogs Erweiterung Core Contingency ihre Einheiten hinzu, und jedes .ufo-Add-on mit einer einzelnen Einheit folgt dieser Konvention.

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

Namenskonvention für Dateien. Die Datei heißt üblicherweise download/<UNITNAME>.tdf (passend zum UNITNAME= des ersten Eintrags), aber die Engine liest jede *.tdf in download/, der Dateiname ist also nur ein Hinweis für den Modder. Eine Einheit pro Datei ist die Regel.

Mehrere Einträge. Eine einzelne Datei kann mehrere Einträge enthalten – Cavedogs download/Armfort.tdf verwendet drei, damit die Arm Fortification Wall von ACK, ACV und ACA gebaut werden kann. TA 3.1c liest die ersten fünf Abschnitte jeder Datei, unabhängig von ihren Namen ([MENUENTRY1] ist die Konvention, [ENTRY0] funktioniert ebenso); ein sechster Abschnitt wird nie gelesen. Ein Eintrag, dessen UNITMENU keine Einheit nennt oder keine Einheit mit Builder=1, wird ignoriert, ebenso einer, dessen UNITNAME keine Einheit nennt. MENU und BUTTON werden auf 8 Bit beschränkt, und das Menü einer Baueinheit – ihre [CANBUILD]-Liste plus die Ergänzungen aus download – fasst höchstens 31 Einheiten.

Das ist der additive Mod-Hook, mit dem du eine einzelne .ufo ausliefern kannst, ohne eine eigene Fassung der 50 KB großen sidedata.tdf zu pflegen. Die Anwendung von Anfang bis Ende zeigt das Modding-Tutorial.

OTA – Karten-Metadaten#

Eine .ota liegt jeder .tnt bei und enthält alles, was die Engine braucht, um die Karte zu spielen (anders als zum Rendern ihres Geländes):

[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 liest die passende .ota und zeichnet nummerierte Markierungen an jeder Startposition des gewählten Schemas.

Wie das Spiel die Schemata und Startpositionen liest (jede Ansicht in kbot – der Karteneditor des Studios, die Sandbox, der Asset-Explorer, kbot tnt preview, kbot tnt lint und der Quality Checker – liest sie auf dieselbe Weise, über die OTA-Spielsicht von kbot-io):

• Schemata werden über ihren Namen gefunden, Schema 0, Schema 1, … bis zur ersten fehlenden Nummer. Namen werden ohne Beachtung der Groß- und Kleinschreibung verglichen ([schema 1] zählt), aber die Nummer muss schlicht geschrieben sein: [Schema0] oder [Schema 01] wird nie gefunden, und ein Schema nach einer Lücke (Schema 0, Schema 1, Schema 3) wird nie gelesen. SCHEMACOUNT wird ignoriert.
• Skirmish- und Mehrspielerpartien wählen ein Schema nach Type und Anzahl der Startpositionen, nicht nach seiner Position. Infrage kommen nur Schemata Network 1 bis Network 4 (ohne Beachtung der Groß- und Kleinschreibung verglichen) mit mindestens einer Startposition. Bei N Spielern bevorzugt das Spiel das letzte infrage kommende Schema mit genau N Startpositionen, andernfalls das mit den meisten. Eine Kampagnenmission wählt nach Schwierigkeitsgrad (Easy, Medium, Hard). numplayers ist nur Text, der in der Lobby angezeigt wird (2, 4, 2-8 und Any laden alle).
• Startpositionen sind die Einträge in [specials], deren specialwhat mit StartPos beginnt (ohne Beachtung der Groß- und Kleinschreibung). StartPosN ist der Spielerplatz N-1, StartPos0 ist ebenfalls Platz 0, und ein Eintrag ohne Nummer hinter StartPos bekommt die nächste eigene Nummer (die erste ist 1). XPos und ZPos sind Kartenpixel, auf 16 Bit beschränkt.
• Fehlende Schlüssel haben Standardwerte, nicht Nullen: Fehlt missiondescription, wird „No description available“ angezeigt, ein fehlendes maxunits (nur Kampagnen) bedeutet 200, und ein vorab platziertes Kartenobjekt ([features]) ohne XPos oder ZPos wird übersprungen; ein Objekt in Spalte oder Zeile 0 braucht also eine ausdrückliche 0.

Beispiel im Detail – minimale Einheit#

Eine vollständige, funktionierende „Fake“-FBI für einen stationären Geschützturm:

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

Um daraus ein vollständiges Einheiten-Add-on zu erstellen, würdest du Folgendes ausliefern:

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

…und das Verzeichnis dann als HPI packen:

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

Stolperfallen#

• Schlüssel unterscheiden nicht zwischen Groß- und Kleinschreibung, Werte schon. Side=arm passt zur Logik, die Einheiten ARM zuordnet, aber Mods, die mit if (Side == "ARM") per String-Gleichheit zur Laufzeit die Seite wechseln, gehen kaputt.
• Listenwerte sind durch Leerzeichen getrennt (Category=COMMANDER MOBILE WEAPON) – nicht durch Kommas. Die Engine trennt an beliebigem Leerraum.
• Manche OTA-Felder verwenden allerdings Kommas: numplayers=2,4,6,8,10. Es gibt keine einheitliche Konvention für Listentrennzeichen, und das Spiel parst numplayers überhaupt nicht – es zeigt nur den Text an.
• Verschachtelte Abschnitte haben keine formale Tiefengrenze, aber Cavedog hat nie etwas ausgeliefert, das tiefer als 3 Ebenen ist. Editoren, die von 2 Ebenen ausgehen, scheitern an einer Handvoll Waffen-TDFs mit Verschachtelung im Stil von [WEAPON][DAMAGE][category].
• Boolesche Felder sind Ganzzahlen (canmove=1, canstop=0), nicht true/false. Die Engine akzeptiert nur 1/0.
• .ota-Dateien enthalten regelmäßig UTF-8-Mojibake in Missionsbeschreibungen (typografische Anführungszeichen aus Word usw.). Die Engine stellt sie mit der Codepage Windows-1252 dar und macht aus allem außerhalb davon Tofu-Kästchen.

Typische Größen#

Anhang A – FBI-Feldverzeichnis#

Jedes Feld, das häufig in units/*.fbi vorkommt, nach Zweck gruppiert. Legende der Spalte Typ: str = Bezeichner/String; int = Ganzzahl; float = Gleitkommazahl; bool = 0/1; list = durch Leerraum getrennte Tokens; enum = kleine Ganzzahl mit dokumentierten Bedeutungen.

Felder, die hier nicht aufgeführt sind, sind entweder Hilfsfelder des Editors (UnitNumber, Copyright) oder undokumentiert. Die Engine ignoriert unbekannte Schlüssel stillschweigend.

Identität und Anzeige#

Wirtschaft und Bau#

Kampf und Überlebensfähigkeit#

Bewegung#

Wahrnehmung#

Baumenü und Grundfläche#

Audio#

Sonstiges / wenig verstanden#

Echte Beispiele im Referenzkatalog#

Wie die Felder verwendet werden, lernt man am besten an echten FBIs. Die Referenz-Repos katalogisieren jede ausgelieferte Einheit:

• TA – jede FBI: gute „reichhaltige“ Beispiele sind ARMCOM (Commander mit Commander=1, CloakCost, MaxDamage=3000), ARMSAM (Geschützturm mit gefüllten Weapon1/2/3), ARMBRAWL (Flugzeug mit CanFly, crusisealt, BankScale), ARMMEX (Metallextraktor mit ExtractsMetal).
• TA – jede Waffen-TDF: [FLAMETHROWER] für burst/burstrate/firestarter, [NUCLEAR_MISSILE] für zweiphasige Lenkraketen, [LIGHTNING] für eine Strahlwaffe.
• TA – Baubaum von Kartenobjekten und Waffen – jede [MENUENTRY]-Registrierung der Installation.
• Einheiten von TA: Kingdoms – der andere Feldsatz (buildcost= als einzige Ressource, damagecategory=, inline [WEAPONn]). ARAKING (Aramons Monarch Elsin) und ARAARCH (Archer) sind gute Einstiegspunkte.

Siehe auch#

• TNT – verweist auf Namen von Kartenobjekten, die zu [FEATURE]-Abschnitten in TDFs aufgelöst werden.
• 3DO, COB – werden über Objectname in der FBI referenziert.
• GAF – wird über seqname von Kartenobjekten und über explosiongaf von Waffen referenziert.
• Gamedata-TDFs – moveinfo.tdf, sound.tdf, sidedata.tdf, auf die FBI-Felder verweisen.
• Sound – wie SoundCategory zu WAV-Dateien aufgelöst wird.
• Glossar – side, footprint, yardmap, schema.