TDF / FBI / OTA — текстовые файлы конфигурации

Файлы TDF («Text Data File»), FBI («Feature/Building/Item») и OTA («Online Total Annihilation») используют один и тот же текстовый формат в духе INI. Именно так Cavedog описывала всё, что не было двоичным: характеристики юнитов, параметры оружия, описания объектов, метаданные миссий, звуковые категории, подсказки для ИИ.

Это обычный текст в 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 — это дерево секций. У каждой секции есть имя в квадратных скобках, за которым идёт тело { ... } с парами ключ=значение и/или вложенными секциями.

[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 обозначают одно и то же поле, и инструменты обычно приводят ключи к нижнему регистру при чтении. Имена секций тоже сравниваются без учёта регистра.
• По умолчанию значения — это строки. Числа читаются по-сишному, по начальным цифрам: 12abc читается как 12, а 56.8 — как 56 там, где игре нужно целое (такие поля, как killmul и tidalstrength, читаются как дробные). Элементы списков разделяются пробелами (например, Category=NOTSUB COMMANDER NOTAIR ...).
• Комментарии затираются раньше, чем читается всё остальное: // до конца строки и блоки /* ... */, которые могут занимать несколько строк. Поэтому missiondescription=See http://tauniverse.com; теряет всё, начиная с //, включая свою ;, и значение продолжается на следующей строке. kbot отказывается записывать значение, содержащее ;, // или /*.
• Пробельные символы и пустые строки игнорируются.

Вложенные секции (как [SOUNDS] внутри [UNITINFO] выше) — обычное дело в FBI/OTA. Спецификация TDF не задаёт предельной глубины, на практике больше 3 уровней не встречается.

FBI — описания юнитов#

FBI — это полное представление движка о юните. В нём в одном месте сведены 3D-модель юнита, скрипт, список оружия, звуковой банк, стоимость постройки и поведение в бою. Сокращённый пример — Командир ARM (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;
        ...
    }
}

Руководство сообщества по FBI 1998 года (оно сохранено среди исходных материалов этого репозитория) описывает больше сотни полей. Назначение большинства понятно из названия, а неочевидными обычно оказываются эти:

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 указывает на секцию [COMMANDER_WEAPON] в одном из TDF в weapons/ через таблицу оружия игры, проиндексированную по ID. Каждой секции нужен ID= в диапазоне 0–255, более поздняя секция с тем же 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= первой записи), но движок читает все *.tdf в download/, так что имя файла — лишь подсказка для моддера. Обычно в одном файле описывают один юнит.

Несколько записей. В одном файле может быть несколько записей: в download/Armfort.tdf от Cavedog их три, чтобы оборонительную стену ARM (Arm Fortification Wall) можно было строить с ACK, ACV и ACA. TA 3.1c читает первые пять секций каждого файла, как бы они ни назывались ([MENUENTRY1] — общепринятое имя, но [ENTRY0] тоже работает), а шестая секция не читается никогда. Запись, в которой UNITMENU не называет ни одного юнита или называет юнит без Builder=1, игнорируется, как и запись, в которой UNITNAME не называет ни одного юнита. MENU и BUTTON хранятся в 8 битах, а меню строителя — его список [CANBUILD] плюс добавленное через download — вмещает не больше 31 юнита.

Это аддитивная точка расширения для модов: она позволяет выпустить один .ufo, не делая собственную копию sidedata.tdf размером 50 КБ. Весь путь от начала до конца описан в руководстве по моддингу.

OTA — метаданные карты#

.ota поставляется вместе с каждым .tnt и содержит всё, что нужно движку, чтобы на карте можно было играть (а не только отрисовать её рельеф):

[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 и рисует пронумерованные метки на каждой стартовой позиции выбранной схемы.

Как игра читает схемы и стартовые позиции (все представления kbot — редактор карт в студии, песочница, обозреватель ресурсов, kbot tnt preview, kbot tnt lint и Quality Checker — читают их одинаково, через игровое представление OTA из kbot-io):

• Схемы ищутся по имени: Schema 0, Schema 1, … до первого пропущенного номера. Имена сравниваются без учёта регистра ([schema 1] тоже подходит), но номер должен быть записан без украшений: [Schema0] или [Schema 01] не находятся никогда, а схема после пропуска (Schema 0, Schema 1, Schema 3) никогда не читается. SCHEMACOUNT игнорируется.
• В схватке и сетевой игре схема выбирается по 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, а заранее расставленный объект ([features]) без XPos или ZPos пропускается, поэтому объекту в столбце или строке 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 уровня, споткнутся на нескольких TDF оружия с вложенностью вида [WEAPON][DAMAGE][category].
• Логические поля — это целые числа (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] в установке.
• Юниты TA: Kingdoms — другой набор полей (buildcost= с единственным ресурсом, damagecategory=, встроенные секции [WEAPONn]). Хорошие отправные точки — ARAKING (Элсин, монарх Арамона) и ARAARCH (лучник).

См. также#

• TNT — ссылается на имена объектов, которые указывают на секции TDF [FEATURE].
• 3DO, COB — на них ссылается Objectname в FBI.
• GAF — на него ссылаются seqname объекта и explosiongaf оружия.
• TDF в gamedata — moveinfo.tdf, sound.tdf, sidedata.tdf, на которые ссылаются поля FBI.
• Звук — как SoundCategory превращается в WAV-файлы.
• Глоссарий — сторона, площадь основания, yardmap, схема.