TDF / FBI / OTA——文本配置文件

TDF（“Text Data File”）、FBI（“Feature/Building/Item”）和 OTA（“Online Total Annihilation”）文件都采用同一种类 INI 的文本格式。Cavedog 用它们以规范的方式声明一切非二进制的内容——单位属性、武器参数、地图物件定义、任务元数据、音效类别、AI 提示。

这些文件都是纯 ASCII 文本，可以用任何文本编辑器打开。

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

语法#

TDF 文件是一棵由节（section）组成的树。每个节先是方括号中的名称，然后是一个 { ... } 主体，其中包含 key=value 键值对和/或嵌套的节。

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

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

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

规则：

• 节名写在方括号中；其后直到匹配的 } 为止的所有内容都属于该节。一个节可以写在一行里（[special0] { specialwhat=StartPos1; XPos=464; ZPos=216; }）。
• 值从 = 一直延续到下一个 ;，可以跨越换行：除此之外没有任何东西能结束它，所以值中的花括号、方括号和 = 都只是普通文本，而值永远不能包含 ;。键或值两端的空格、制表符和换行都会被去掉。同一个键赋值两次时，保留最后一个值。
• 键不区分大小写。 UnitName、unitname 和 UNITNAME 都指同一个字段；工具通常在读取时统一转成小写。节名的比较同样忽略大小写。
• 值默认是字符串。数字按 C 语言的方式读取，只取开头的数字部分：在游戏需要整数的地方，12abc 读作 12，56.8 读作 56（killmul 和 tidalstrength 之类的字段按小数读取）。列表以空格分隔（例如 Category=NOTSUB COMMANDER NOTAIR ...）。
• 注释在读取任何内容之前就会被清除：// 到行尾，以及可以跨行的 /* ... */ 块。因此 missiondescription=See http://tauniverse.com; 会丢掉从 // 开始的所有内容，包括其中的 ;，于是这个值会一直延续到下一行。kbot 拒绝写出包含 ;、// 或 /* 的值。
• 空白和空行会被忽略。

嵌套的节（比如上面 [UNITINFO] 中的 [SOUNDS]）在 FBI/OTA 中很常见。TDF 规范没有规定最大深度；实际上不会超过 3 层。

FBI——单位定义#

FBI 是引擎眼中一个单位的完整面貌。它把单位的 3D 模型、脚本、武器列表、音效库、建造成本和战斗行为集中到一处。下面是一个删减过的 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;
        ...
    }
}

1998 年的社区 FBI 指南（保存在本仓库的源资料中）记录了一百多个字段。大多数一看就懂；不那么直观的通常是这些：

TDF——地图物件、武器、音效定义#

features/**/*.tdf 文件包含 [FEATURE] 节，每节对应一个静态地图摆设。TNT 格式（TNT）按节名引用它们：

[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 遵循同样的模式，使用 [WEAPON_NAME] 节。FBI 中的 Weapon1=COMMANDER_WEAPON 字段，会经由游戏以 ID 为索引的武器表，解析到 weapons/ 中某个 TDF 里的 [COMMANDER_WEAPON] 节：每个节都需要一个取值在 0–255 之间的 ID=，ID 相同时后出现的节取代先出现的节，而一个名称解析到持有它的最低槽位（见 Gamedata：武器表）。社区的武器指南记录了大约 60 个不同的字段；最要紧的是 ballistic/lineofsight/dropped（武器原型）、weapontimer、weaponvelocity、areaofeffect、edgeeffectiveness、burst/burstrate，以及 [DAMAGE] 子节（按类别的伤害修正）。

[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]——建造菜单扩展#

download/*.tdf 中的文件可以把一个单位注册到一个或多个建造者的建造菜单中，而无需修改 sidedata.tdf。Cavedog 的 Core Contingency 资料片就是用这种机制加入其单位的，每个只含一个单位的 .ufo 附加包也都遵循这一约定。

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

文件命名约定。 按惯例，文件名为 download/<UNITNAME>.tdf（与第一个条目的 UNITNAME= 一致），但引擎会读取 download/ 中的每个 *.tdf，所以文件名纯粹是给模组作者的提示。通常一个文件只放一个单位。

多个条目。 一个文件可以包含多个条目——Cavedog 的 download/Armfort.tdf 用了三个条目，让 Arm 防御工事墙（Fortification Wall）可以由 ACK、ACV 和 ACA 建造。TA 3.1c 读取每个文件的前五个节，不论它们叫什么名字（[MENUENTRY1] 是惯例，[ENTRY0] 也同样可用）；第六个节永远不会被读取。如果某个条目的 UNITMENU 不指向任何单位，或者指向的单位没有 Builder=1，该条目会被忽略；UNITNAME 不指向任何单位的条目同样会被忽略。MENU 和 BUTTON 只保留 8 位，而一个建造者的菜单——它的 [CANBUILD] 列表加上 download 中添加的条目——最多容纳 31 个单位。

有了这个增量式的模组钩子，你只需发布一个 .ufo，而不必另外复制一份 50 KB 的 sidedata.tdf 来修改。端到端的用法见模组制作教程。

OTA——地图元数据#

每个 .tnt 都附带一个 .ota，其中包含引擎游玩这张地图所需的一切（而不是渲染其地形所需的内容）：

[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 会读取对应的 .ota，并在所选方案（schema）的每个起始位置绘制带编号的标记。

游戏读取方案和起始位置的方式如下（kbot 的每一个视图——studio 地图编辑器、沙盒、资源浏览器、kbot tnt preview、kbot tnt lint 以及 Quality Checker——都通过 kbot-io 的 OTA 游戏视图，以同样的方式读取它们）：

• 方案按名称查找：Schema 0、Schema 1……直到第一个缺失的编号为止。 名称比较时忽略大小写（[schema 1] 也算），但编号必须直接写出：[Schema0] 或 [Schema 01] 永远找不到，而编号断档之后的方案（Schema 0、Schema 1、Schema 3）永远不会被读取。SCHEMACOUNT 会被忽略。
• 遭遇战和多人游戏按 Type 和起始位置数量挑选方案，而不是按位置先后。 只有 Type 为 Network 1 到 Network 4（比较时忽略大小写）、且至少有一个起始位置的方案才符合条件。对于 N 名玩家，游戏优先选择最后一个恰好有 N 个起始位置的合格方案，否则选择起始位置最多的那个。战役任务则按难度（Easy、Medium、Hard）挑选。numplayers 只是显示在大厅中的文本（2, 4、2-8 和 Any 都能加载）。
• 起始位置是 [specials] 中 specialwhat 以 StartPos 开头的条目（忽略大小写）。StartPosN 是玩家槽位 N-1，StartPos0 也是槽位 0，StartPos 后面不带数字的条目则自行取下一个编号（第一个为 1）。XPos 和 ZPos 以地图像素为单位，保留 16 位。
• 缺失的键有默认值，而不是零： 缺少 missiondescription 时显示“No description available”，缺少 maxunits（仅用于战役）时取 200，而没有 XPos 或 ZPos 的预置地图物件（[features]）会被跳过，因此位于第 0 列或第 0 行的地图物件需要显式写出 0。

实例解析——最小单位#

一个完整可用的“假”FBI，描述一座固定炮塔：

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

要把它做成一个完整的单位附加包，你需要发布：

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

……然后把这个目录打包成 HPI：

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

坑点#

• 键不区分大小写，值区分。 Side=arm 能匹配针对 ARM 的单位分类逻辑，但那些用 if (Side == "ARM") 这类字符串相等比较来动态切换阵营的模组就会出问题。
• 列表值以空格分隔（Category=COMMANDER MOBILE WEAPON）——而不是逗号。引擎按任意空白字符拆分。
• 不过，有些 OTA 字段使用逗号：numplayers=2,4,6,8,10。并没有统一的列表分隔符约定，而且游戏根本不解析 numplayers——只是显示这段文本。
• 嵌套的节没有正式的深度限制，但 Cavedog 发布的内容从未超过 3 层。假定只有 2 层的编辑器，会在少数带有 [WEAPON][DAMAGE][category] 式嵌套的武器 TDF 上出错。
• 布尔字段是整数（canmove=1、canstop=0），而不是 true/false。引擎只接受 1/0。
• .ota 文件的任务描述中经常出现 UTF-8 乱码（来自 Word 的智能引号等）。引擎用 Windows-1252 代码页渲染它们，超出该代码页的字符都会显示成方块。

典型大小#

附录 A——FBI 字段词典#

units/*.fbi 中常见的每个字段，按用途分组。类型列的含义：str = 标识符/字符串；int = 整数；float = 浮点数；bool = 0/1；list = 以空白分隔的记号；enum = 含义有文档说明的小整数。

这里没有列出的字段，要么是编辑器的临时数据（UnitNumber、Copyright），要么尚无文档记载。引擎会悄悄忽略未知的键。

身份与显示#

经济与建造#

战斗与生存#

移动#

侦测#

建造菜单与占地#

音频#

杂项 / 尚未弄清的字段#

参考目录中的实际示例#

字段的用法最好从真实的 FBI 中学习。参考仓库收录了每一个发行的单位：

• TA——全部 FBI：“丰富”的好例子有 ARMCOM（指挥官，带 Commander=1、CloakCost、MaxDamage=3000）、ARMSAM（炮塔，Weapon1/2/3 都已填写）、ARMBRAWL（飞机，带 CanFly、crusisealt、BankScale）、ARMMEX（金属提取器，带 ExtractsMetal）。
• TA——全部武器 TDF：[FLAMETHROWER] 展示 burst/burstrate/firestarter，[NUCLEAR_MISSILE] 展示两阶段制导导弹，[LIGHTNING] 展示光束武器。
• TA——地图物件与武器建造树——游戏文件中的每一条 [MENUENTRY] 注册。
• 横扫千军：王国单位——不同的字段集（单一资源的 buildcost=、damagecategory=、内联的 [WEAPONn]）。ARAKING（Aramon 的君主 Elsin）和 ARAARCH（Archer）是不错的切入点。

另见#

• TNT——其中引用的地图物件名称解析为 TDF 中的 [FEATURE] 节。
• 3DO、COB——由 FBI 的 Objectname 引用。
• GAF——由地图物件的 seqname 和武器的 explosiongaf 引用。
• gamedata TDF 文件——FBI 字段引用的 moveinfo.tdf、sound.tdf、sidedata.tdf。
• 音效——SoundCategory 如何解析到 WAV 文件。
• 术语表——side、footprint、yardmap、schema。