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 позначають одне й те саме поле; інструменти зазвичай під час читання зводять їх до нижнього регістру. Імена секцій теж порівнюються без урахування регістру.
• Значення за замовчуванням — рядки. Числа читаються як у C, з початкових цифр: 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 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. Саме цим механізмом розширення Core Contingency від Cavedog додає свої юніти, і саме цієї домовленості дотримується кожне .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 Fortification Wall можна було будувати з ACK, ACV і ACA. TA 3.1c читає перші п'ять секцій кожного файлу, хоч як би вони називалися ([MENUENTRY1] — це домовленість, але [ENTRY0] теж працює); шоста секція ніколи не читається. Запис, чий UNITMENU не відповідає жодному юніту або жодному юніту з Builder=1, ігнорується, так само як і запис, чий UNITNAME не відповідає жодному юніту. MENU і BUTTON обрізаються до 8 бітів, а меню будівельника — його список [CANBUILD] плюс юніти, додані через download, — вміщує щонайбільше 31 юніт.

Це адитивний механізм для модів, який дає змогу постачати один .ufo, не створюючи власної копії 50-кілобайтного sidedata.tdf. Повний приклад використання див. у посібнику з моддингу.

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 (Elsin, монарх Aramon) і ARAARCH (Archer) — зручні для початку.

Див. також#

• TNT — посилається на імена об'єктів, які розв'язуються в секції TDF [FEATURE].
• 3DO, COB — на них посилається Objectname у FBI.
• GAF — на нього посилаються seqname об'єкта й explosiongaf зброї.
• TDF у gamedata — moveinfo.tdf, sound.tdf, sidedata.tdf, на які посилаються поля FBI.
• Звук — як SoundCategory розв'язується у файли WAV.
• Глосарій — side, footprint, yardmap, schema.