TDF / FBI / OTA — Text Configuration Files

TDF ("Text Data File"), FBI ("Feature/Building/Item"), and OTA ("Online Total Annihilation") files all share the same INI-like text format. They are the canonical way Cavedog declared anything that wasn't binary — unit stats, weapon parameters, feature definitions, mission metadata, sound categories, AI hints.

These files are plain ASCII; you can open one in any text editor.

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

A TDF file is a tree of sections. Each section has a name in square brackets, then a { ... } body containing key=value pairs and/or nested sections.

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

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

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

Rules:

• Section names are in square brackets; everything that follows until the matching } belongs to that section. A section may sit on one line ([special0] { specialwhat=StartPos1; XPos=464; ZPos=216; }).
• A value runs from the = to the next ;, across line breaks: nothing else ends it, so braces, brackets and = inside a value are plain text, and a value can never contain a ;. Spaces, tabs and line breaks at either end of a key or value are trimmed. A key assigned twice keeps its last value.
• Keys are case-insensitive. UnitName, unitname and UNITNAME all refer to the same field; tools commonly canonicalise to lowercase on read. Section names are compared ignoring case too.
• Values are strings by default. Numbers are read the C way, from the leading digits: 12abc reads as 12 and 56.8 as 56 where the game wants a whole number (fields such as killmul and tidalstrength are read as fractions). Lists are space-separated (e.g. Category=NOTSUB COMMANDER NOTAIR ...).
• Comments are blanked out before anything else is read: // to the end of the line, and /* ... */ blocks, which may span lines. So missiondescription=See http://tauniverse.com; loses everything from // onwards, including its ;, and the value runs on into the next line. kbot refuses to write a value containing ;, // or /*.
• Whitespace and blank lines are ignored.

Nested sections (like [SOUNDS] inside [UNITINFO] above) are common in FBI/OTA. The TDF spec doesn't fix a maximum depth; in practice you won't see more than 3.

FBI — unit definitions#

An FBI is the engine's complete view of a unit. It pulls the unit's 3D model, the script, the weapon list, the sound bank, build costs, and combat behaviour together in one place. A trimmed Arm Commander example:

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

The 1998 community FBI guide (preserved in this repo's source materials) documents over a hundred fields. Most are self-explanatory; the non-obvious ones tend to be:

TDF — feature, weapon, sound definitions#

features/**/*.tdf files contain [FEATURE] sections, one per static map prop. The TNT format (TNT) references these by section name:

[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 follow the same pattern, with [WEAPON_NAME] sections. The FBI's Weapon1=COMMANDER_WEAPON field resolves to the [COMMANDER_WEAPON] section in some TDF in weapons/, through the game's ID-indexed weapon table: each section needs an ID= in 0–255, a later section with the same ID replaces an earlier one, and a name resolves to the lowest slot holding it (see Gamedata: the weapon table). The community weapons guide documents about 60 distinct fields; the meaty ones are ballistic/lineofsight/dropped (the weapon archetype), weapontimer, weaponvelocity, areaofeffect, edgeeffectiveness, burst/burstrate, and the [DAMAGE] sub-section (per-category damage modifiers).

[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] — Build-menu extension#

Files in download/*.tdf register a unit with the build menus of one or more constructors without modifying sidedata.tdf. This is the mechanism Cavedog's Core Contingency expansion uses to add its units, and the convention every single-unit .ufo add-on follows.

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

File-naming convention. The file is conventionally download/<UNITNAME>.tdf (matching the UNITNAME= of the first entry), but the engine reads every *.tdf in download/, so the filename is purely a hint to the modder. One unit per file is the norm.

Multiple entries. A single file can hold several entries — Cavedog's download/Armfort.tdf uses three to make the Arm Fortification Wall buildable from ACK, ACV, and ACA. TA 3.1c reads the first five sections of each file, whatever their names ([MENUENTRY1] is the convention, [ENTRY0] works as well); a sixth section is never read. An entry whose UNITMENU names no unit, or no unit with Builder=1, is ignored, as is one whose UNITNAME names no unit. MENU and BUTTON are kept to 8 bits, and a builder's menu — its [CANBUILD] list plus the download additions — holds at most 31 units.

This is the additive mod hook that lets you ship a single .ufo without forking the 50 KB sidedata.tdf. See the modding tutorial for end-to-end usage.

OTA — map metadata#

.ota ships alongside every .tnt and carries everything the engine needs to play the map (as opposed to render its 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 reads the matching .ota and draws numbered markers at each start position of the chosen schema.

How the game reads the schemas and start positions (every kbot view — the studio map editor, the sandbox, the asset explorer, kbot tnt preview, kbot tnt lint and the Quality Checker — reads them the same way, through kbot-io's OTA game view):

• Schemas are found by name, Schema 0, Schema 1, … up to the first missing number. Names are compared ignoring case ([schema 1] counts), but the number must be written plainly: [Schema0] or [Schema 01] is never found, and a schema after a gap (Schema 0, Schema 1, Schema 3) is never read. SCHEMACOUNT is ignored.
• Skirmish and multiplayer games pick a schema by Type and start count, not by position. Only Network 1 to Network 4 schemas (compared ignoring case) with at least one start position qualify. For N players the game prefers the last qualifying schema with exactly N start positions, otherwise the one with the most. A campaign mission picks by difficulty (Easy, Medium, Hard). numplayers is only text shown in the lobby (2, 4, 2-8 and Any all load).
• Start positions are the [specials] entries whose specialwhat starts with StartPos (ignoring case). StartPosN is player slot N-1, StartPos0 is slot 0 too, and an entry with no number after StartPos takes the next number of its own (the first is 1). XPos and ZPos are map pixels, kept to 16 bits.
• Missing keys have defaults, not zeros: a missing missiondescription shows "No description available", a missing maxunits (campaigns only) means 200, and a pre-placed feature ([features]) with no XPos or ZPos is skipped, so one at column or row 0 needs an explicit 0.

Worked example — minimal unit#

A complete, working "fake" FBI for a stationary turret:

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

To make this a complete unit add-on you'd ship:

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

…then HPI-pack the directory:

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

Gotchas#

• Keys are case-insensitive, values are not. Side=arm will match unit-classification logic for ARM, but mods that switch sides on the fly with if (Side == "ARM") against string-equality lookups will break.
• List values are space-separated (Category=COMMANDER MOBILE WEAPON) — not comma-separated. The engine splits on any whitespace.
• Some OTA fields use commas, however: numplayers=2,4,6,8,10. There isn't a single list-delimiter convention, and the game never parses numplayers at all — it only shows the text.
• Nested sections have no formal depth limit, but Cavedog never shipped anything more than 3 deep. Editors that assume 2-deep will fail on a handful of weapon TDFs with [WEAPON][DAMAGE][category]- style nesting.
• Boolean fields are integers (canmove=1, canstop=0), not true/false. The engine accepts 1/0 only.
• .ota files routinely have UTF-8 mojibake in mission descriptions (smart-quotes from Word, etc.). The engine renders them with the Windows-1252 codepage and will tofu anything outside it.

Typical sizes#

Appendix A — FBI field dictionary#

Every field commonly found in units/*.fbi. Grouped by purpose. Type column key: str = identifier/string; int = integer; float = float; bool = 0/1; list = whitespace-separated tokens; enum = small integer with documented meanings.

Fields not listed here are either editor scratch (UnitNumber, Copyright) or undocumented. The engine ignores unknown keys silently.

Identity & display#

Economy & construction#

Combat & survivability#

Movement#

Senses#

Build menu & footprint#

Audio#

Misc / poorly-understood#

Live examples in the reference catalogue#

Field usage is best learned from real FBIs. The reference repos catalogue every shipped unit:

• TA — every FBI: good "rich" examples are ARMCOM (commander with Commander=1, CloakCost, MaxDamage=3000), ARMSAM (turret with Weapon1/2/3 filled), ARMBRAWL (aircraft with CanFly, crusisealt, BankScale), ARMMEX (metal extractor with ExtractsMetal).
• TA — every weapon TDF: [FLAMETHROWER] for burst/burstrate/firestarter, [NUCLEAR_MISSILE] for two-phase guided missiles, [LIGHTNING] for a beam weapon.
• TA — feature & weapon build-tree — every [MENUENTRY] registration in the install.
• TA: Kingdoms units — the different field set (buildcost= single resource, damagecategory=, inline [WEAPONn]). ARAKING (Aramon's monarch Elsin) and ARAARCH (Archer) are good entry-points.

See also#

• TNT — references feature names that resolve to [FEATURE] TDF sections.
• 3DO, COB — referenced from FBI Objectname.
• GAF — referenced from feature seqname and weapon explosiongaf.
• Gamedata TDFs — moveinfo.tdf, sound.tdf, sidedata.tdf referenced from FBI fields.
• Sound — how SoundCategory resolves to WAV files.
• Glossary — side, footprint, yardmap, schema.