TDF в gamedata — таблицы настройки движка

Файлы в gamedata/ — это текстовые файлы TDF, которые настраивают сам движок: классы передвижения, категории урона оружия, данные сторон (раскладка интерфейса, меню строительства, стартовые юниты), привязки звуков и несколько небольших таблиц поиска. Моды, которые меняют правила игры (а не добавляют юниты), почти всегда работают именно здесь.

На этой странице описаны самые полезные файлы gamedata. Все они используют грамматику TDF в стиле INI — подробности на уровне парсера см. в TDF.

ls $(kbot ctx path)/gamedata/
# The web UI renders these as collapsible section trees
kbot mount $(kbot ctx path) --server
# → browse to gamedata/sidedata.tdf, then sidedata > [CANBUILD]

Кратко о файлах#

Для моддинга главные три файла — sidedata.tdf (меню строительства, стороны), moveinfo.tdf (классы передвижения) и weapons.tdf (это документация, а не данные: настоящее оружие лежит в weapons/*.tdf).

moveinfo.tdf — классы передвижения#

В FBI юнита объявлен его MovementClass=KBOTSS2 (или похожий); движок ищет этот класс в moveinfo.tdf и по нему решает, по какому рельефу юнит может перемещаться.

TA 3.1c читает только секции с [CLASS0] по [CLASS31] (первую секцию с каждым из этих имён) и находит класс по его Name= без учёта регистра, начиная с меньшего номера слота. Если класс юнита найден, значения класса полностью заменяют собственные FootprintX/FootprintZ, MaxWaterDepth, MinWaterDepth и ключи уклона юнита — MaxSlope=20 Командира уступает 32 из TANKDS2, — а ключ, которого нет в классе, получает значение игры по умолчанию (см. ниже), а не значение из FBI. Юнит без класса или с классом, которого игра не находит, читает собственные ключи FBI с теми же значениями по умолчанию. Метаданные юнитов, песочница и размещённые матчи KBot Studio определяют передвижение именно так.

[CLASS0]
{
    Name=KBOTSS2;        // Class name referenced from FBIs
    FootprintX=2;        // Cells wide (16-px units)
    FootprintZ=2;        // Cells deep
    MaxWaterDepth=12;    // Deepest water it can enter
    MaxSlope=32;         // Steepest land slope it can climb
}

[CLASS3]
{
    Name=TANKDH3;
    FootprintX=3;
    FootprintZ=3;
    MaxWaterDepth=100;   // Heavy tank — can ford deep water
    MaxWaterSlope=30;    // Slope limit *underwater* (separate from MaxSlope)
    MaxSlope=15;
}

Поля#

Соглашения об именах#

Имя класса кодирует его форму коротким тегом — таково соглашение Cavedog:

Затем идёт суффикс SS / SF / DS / DH / SH (малый, глубоководный, тяжёлый и т. п.) и цифра площади основания. Именование — лишь соглашение: движок воспринимает Name= как непрозрачный ключ.

sidedata.tdf — настройки сторон#

Это самый длинный файл в gamedata/, потому что в нём собраны три разные задачи:

1. Объявления сторон — имя, префикс, Командир, шрифты, цвета.
2. Раскладка HUD — пиксельные координаты каждой полосы состояния, надписи и кнопки игрового интерфейса.
3. Меню строительства — секция [CANBUILD] со списком того, что может строить каждый строитель.

Блок стороны#

[SIDE0]
{
    name=ARM;
    nameprefix=ARM;
    commander=ARMCOM;          // UnitName of the commander unit
    intgaf=ARMINT;             // GAF used for intro screen

    font=console;              // FNT for general text
    fontgui=armbutt;           // FNT for buttons
    energycolor=208;           // Palette index for energy bars
    metalcolor=224;            // Palette index for metal bars

    // …followed by ~60 HUD coordinate sub-sections
    [LOGO]      { x1=132; y1=5;   x2=152; y2=25; }
    [ENERGYBAR] { x1=471; y1=12;  x2=598; y2=14; }
    [METALBAR]  { x1=218; y1=12;  x2=345; y2=14; }
    ...
}

[SIDE1] { name=CORE; ... }

TA 3.1c читает стороны [SIDE0], [SIDE1], … по порядку и останавливается на первом пропущенном номере, а также после пятой. Секция с любым другим именем ([SIDE01], [SIDE3] после пропущенной [SIDE2], шестая сторона) никогда не читается, а каждой прочитанной стороне нужны все прямоугольники HUD, перечисленные ниже (ta.SideRectangles в kbot-io), иначе игра не загрузит ни одной стороны. Выбор стороны в песочнице студии предлагает те же стороны.

Подсекции координат HUD#

Каждый видимый элемент HUD — это блок [NAME] с пиксельными координатами x1/y1/x2/y2. Они заданы относительно базового разрешения 640×480; в более высоких режимах движок их масштабирует.

[ENERGYBAR] { x1=471; y1=12; x2=598; y2=14; }

Чтобы переместить полосу энергии, измените четыре числа. Чтобы сменить её оформление, замените GAF, которым HUD рисует в этой позиции (задаётся в unitview.tdf).

Меню строительства [CANBUILD]#

Статическое определение меню строительства. Для каждого строителя перечислено, что он может строить с начала игры:

[CANBUILD]
{
    [ARMCOM]
    {
        canbuild1=ARMSOLAR;    // Slot 1 on the build menu
        canbuild2=ARMWIN;
        canbuild3=ARMESTOR;
        canbuild4=ARMMSTOR;
        canbuild5=ARMMEX;
        ...
    }
    [ARMLAB]
    {
        canbuild1=ARMCK;
        canbuild2=ARMPW;
        ...
    }
}

Номер слота — это позиция на странице меню строительства. Меню строительства TA — сетка из 2 столбцов × 3 строк, поэтому на каждой странице 6 слотов: canbuild1–canbuild6 — страница 1, canbuild7–canbuild12 — страница 2 и так далее.

Как TA 3.1c читает таблицу (CanBuildBuilder.BuildList в kbot-io; ей следуют kbot document, просмотрщик юнитов и меню строительства в песочнице):

• Список получает только юнит, в FBI которого задано Builder=1; подсекция для любого другого юнита игнорируется.
• Игра читает первую секцию [CANBUILD], а в ней — первую подсекцию с именем строителя (без учёта регистра).
• Она читает canbuild1, canbuild2, … и останавливается на первом пропущенном номере: canbuild1=ARMSOLAR; canbuild3=ARMLAB; даёт одну запись.
• Имя, которому не соответствует ни один юнит, пропускается, а список вмещает не более 30 юнитов. Записи из download (см. ниже) могут довести меню строителя до 31. (В старой документации иногда утверждалось, что на странице 12 слотов; на самом деле сетка в игре — 6.) Раскладку по страницам для каждого строителя основной игры см. в справочнике по дереву строительства TA.

weapons.tdf — справка по TDF оружия#

Несмотря на название, gamedata/weapons.tdf состоит в основном из комментариев — это опубликованный Cavedog справочник по грамматике TDF оружия, и игра его никогда не загружает. Настоящие определения оружия лежат в weapons/*.tdf, по секции на каждое оружие (см. TDF). kbot document не выводит секции gamedata/weapons.tdf как оружие.

Таблица оружия#

TA 3.1c строит таблицу из 256 слотов оружия по файлам .tdf, лежащим непосредственно в weapons/ (не в подкаталогах), в том порядке, в котором их перечисляет:

• Секция попадает в слот, номер которого задан её ID=, от 0 до 255. Секция без ID или с ID вне этого диапазона пропускается.
• Более поздняя секция с тем же ID — в том же файле или в следующем — заменяет предыдущую.
• Weapon1/Weapon2/Weapon3, ExplodeAs и SelfDestructAs юнита указывают имя секции; имя (без учёта регистра) разрешается в слот с наименьшим номером, где лежит секция с таким именем.
• Значения читаются как числовые префиксы: weaponacceleration=13O; — это 13, и неверное значение никогда не отбрасывает остаток файла.
• При нарушенной структуре игра отвергает весь файл, так что ни одно оружие из него не загружается, включая секции до ошибки: заголовок секции без ] или без {, текст без = или значение без ; до конца файла, конец файла внутри секции, пустой файл. Другие файлы это не затрагивает. (Лишняя } вне секций не приводит к отказу: игра прекращает чтение в этом месте и сохраняет всё, что было до неё.)
• Отсутствующий range равен 32767, отсутствующий minbarrelangle — -11.25 градуса; reloadtime считается в целых тиках (30 в секунду, reloadtime*30 с отбрасыванием дробной части: 0.35 перезаряжается за 10 тиков, 0,333 с); turnrate задаётся в единицах угла в секунду (65536 = полный оборот).

KBot Studio, пакеты и kbot host определяют оружие через эту таблицу. Файлы, которые игра отвергает, и секции, которые она пропускает или заменяет, выводятся как предупреждения (kbot pack их печатает, студия отдаёт их по адресу /api/studio/weapons/warnings).

Спрайты rendertype=4#

Оружие с rendertype=4 выпускает 2D-спрайт из anims/fx.gaf, а его color= выбирает, какой именно: 0 — cannonshell, 1 — plasmasm, 2 — plasmamd, 3 — ultrashell, 4 — снова plasmasm; при любом другом значении (например, color=255 у EARTHQUAKE) спрайт не рисуется. Спрайт переходит на один кадр за игровой тик с момента выстрела, какие бы длительности ни были записаны в кадрах GAF.

Справочные комментарии описывают:

• Три архетипа оружия: ballistic, lineofsight, dropped. В каждом TDF оружия один из них должен быть равен 1.
• Дальность, скорость, ускорение — в пикселях и пикселях в секунду.
• Площадь поражения — радиус в пикселях, edgeeffectiveness задаёт долю урона на краю (например, 0.5 = половина урона на краю).
• Очереди и разброс — burst, burstrate, sprayangle.
• Двухфазное оружие — twophase, weapontype2, flighttime для снарядов в стиле starburst.
• Тип отрисовки — rendertype=N выбирает 3D-модель, растр с палитрой, луч и т. д.

В подсекции [DAMAGE] находятся модификаторы урона для категорий целей:

[FLAMETHROWER] {
    ...
    [DAMAGE]
    {
        default=10;     // Damage applied to anything not listed
        corpyro=2;      // Pyros are nearly fire-proof
    }
}

Ключи в [DAMAGE] — это имена юнитов: указанный юнит получает заданный урон вместо default=, все остальные получают default=. Значения хранятся в 16 битах. Взрывы при гибели (ExplodeAs, SelfDestructAs) используют ту же таблицу: CORPYRO_BLAST по умолчанию наносит 60, но Поджигателю — только 15.

category.tdf — описания категорий юнитов#

Косметический плоский список, который сопоставляет токенам категорий читаемый текст. Движок показывает его в панели информации о юните:

[Plant]      { description = Unit Creation plant; }
[KBOT]       { description = Some type of units; }
[Tank]       { description = Some type of units; }
[Metal]      { description = Some type of units; }

Прочерки вместо описаний — ненамеренная заготовка Cavedog. Большинство модов этот файл не трогают, некоторые заменяют описания нормальным художественным текстом. На игровой процесс его изменение не влияет.

sound.tdf и allsound.tdf#

Описаны на странице WAV / Звук. Вкратце:

• sound.tdf — привязки звуков к категориям юнитов (секции [ARM_COM], [ARM_KBOT]). На них ссылается SoundCategory= в FBI. Игра читает 23 события, каждое как KEY, затем KEY1, KEY2, … до первого пропущенного номера.
• allsound.tdf — глобальные привязки звуков интерфейса ([BIGBUTTON], [SKIRMISH], [BGM]).

Разбор примера — добавление класса передвижения#

Создадим класс «корабль, способный пересекать вброд очень мелкую воду»:

1. Допишите в конец gamedata/moveinfo.tdf:

   [CLASS20]
   {
       Name=AMPHIB3;
       FootprintX=3;
       FootprintZ=3;
       MaxWaterDepth=100;    // Deep water OK
       MaxSlope=20;          // Reasonable land climbing
       MaxWaterSlope=200;    // Smooth underwater movement
   }

2. В FBI вашего юнита:

   MovementClass=AMPHIB3;

   Площадь основания и ограничения класса заменяют те, что заданы в FBI, так что ключи FootprintX/FootprintZ/MaxWaterDepth юнита больше ничего не значат.

3. Упакуйте:

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

Теперь юнит будет без затруднений перемещаться и по суше, и по воде.

Типичные размеры#

Подводные камни#

• Слоты классов передвижения фиксированы. Читаются только [CLASS0] – [CLASS31]; пропуски в нумерации внутри этого диапазона допустимы.
• Комментарии в большинстве файлов — //, а не /*…*/, но в weapons.tdf встречаются оба вида. Тестовые парсеры понимают оба, некоторые сторонние инструменты — нет.
• Координаты HUD в sidedata.tdf заданы для базового 640×480, а для более высоких разрешений движок их масштабирует. Не записывайте координаты в современных разрешениях.
• В нумерации [CANBUILD] не должно быть пропусков. Игра прекращает читать список строителя на первом отсутствующем canbuildN, поэтому если за canbuild11 следует canbuild14, 14-я запись и все следующие теряются без всякой ошибки.
• MovementClass, которого игра не находит, — не ошибка. Юнит молча использует собственные ключи FBI со значениями игры по умолчанию для отсутствующих — так юнит без MaxWaterDepth пойдёт вброд на глубину до 10000.

См. также#

• TDF — грамматика на уровне парсера, общая с FBI/OTA.
• Звук — подключение sound.tdf и allsound.tdf.
• FBI — юниты ссылаются на MovementClass, SoundCategory и имена TDF оружия.
• Глоссарий — movement class, footprint, side.