Моддинг юнита от начала до конца

Это руководство проведёт вас от стандартной установки Total Annihilation до крошечного мода, который добавляет один новый вариант танка ARM «Вспышка» (Flash) — перекрашенный и вдвое более быстрый. В конце у вас будет готовый к выпуску архив .ufo, который загружается, если положить его в папку игры, и рабочее представление о каждом формате, который поддерживает kbot.

Всё упражнение занимает около 20 минут и затрагивает HPI, FBI, COB, 3DO, PCX, TDF и sidedata.tdf.

---

0. Что понадобится#

• Полная установка TA в $TA (GoG, Steam или оригинальный CD).
• Установленный kbot:

  go install github.com/coreprime/kbot/cmd/kbot@latest
  kbot ctx add "$TA" --alias ta --game totala

• Место на диске для распакованной рабочей копии (~120 МБ).

---

1. Распакуйте установку#

Вы будете править отдельные файлы, поэтому один раз распакуйте архивы, чтобы читать их обычными инструментами.

kbot mount "$TA" flatten --target ./ta-flat

Посмотрите, что получилось:

ls ta-flat/                # ai/  anims/  features/ ... weapons/
ls ta-flat/units/ | head   # ARMCOM.FBI, ARMFLASH.FBI, ...

Структура папок повторяет устройство VFS — как архивы накладываются друг на друга во время игры, описано в HPI.

---

2. Создайте рабочий каталог мода#

Моддинг TA аддитивен: положите .ufo рядом с существующими архивами, и его файлы перекроют основную игру. Собирайте мод в зеркальном дереве:

mkdir -p mymod/{units,scripts,objects3d,unitpics,download}

---

3. Выберите юнит для форка#

Наш MYFLASH мы сделаем на основе существующей «Вспышки» ARM. Скопируйте четыре файла:

cp ta-flat/units/armflash.fbi      mymod/units/myflash.fbi
cp ta-flat/scripts/ARMFLASH.cob    mymod/scripts/MYFLASH.cob
cp ta-flat/objects3d/armflash.3do  mymod/objects3d/myflash.3do
cp ta-flat/unitpics/armflash.pcx   mymod/unitpics/myflash.pcx

Почему именно эти четыре? Каждому юниту нужны:

По соглашению имена файлов — это Objectname из FBI в нижнем регистре, причём сам .fbi иногда пишется в верхнем. Движок везде нечувствителен к регистру.

---

4. Перенастройте FBI#

Откройте mymod/units/myflash.fbi. Два ключевых поля, которые нужно изменить, — UnitName (ключ поиска) и Objectname (основа имён файлов):

[UNITINFO]
{
    UnitName=MYFLASH;             // ← was ARMFLASH
    Objectname=myflash;           // ← was armflash
    Side=ARM;
    Designation=ARM-MV;
    Name=Super Flash;             // ← display name
    Description=Twice-as-fast Flash variant;
    ...
}

Затем подкрутите какую-нибудь характеристику, чтобы убедиться, что изменение работает, — удвойте скорость:

    MaxVelocity=4.0;              // was 2.0
    Acceleration=0.30;            // was 0.15

Полный каталог полей — в приложении о FBI. Всё, что не задано, наследуется из значений движка по умолчанию.

---

5. Зарегистрируйте юнит в меню строительства#

Юнит, который существует, но недоступен ни одному строителю, построить нельзя. Правильный способ добавить слот строительства для нового юнита — положить в мод файл download/<UNITNAME>.tdf: так поставляет свои новые юниты собственное дополнение Cavedog Core Contingency, и этому же соглашению следует любое дополнение .ufo с одним юнитом, какое вам попадётся (AFark.ufo, AFlea.ufo, CorNecro.ufo, …).

Создайте mymod/download/MYFLASH.tdf:

[MENUENTRY1]
{
    UNITMENU=ARMVP;       // The builder this unit appears under
    MENU=3;               // Build-menu page number (1-indexed)
    BUTTON=4;             // Slot within that page (0–5 in a 2×3 grid;
                          // 4 = bottom-left)
    UNITNAME=MYFLASH;     // The unit being placed (matches your FBI's UnitName)
}

Меню строительства TA — это сетка 2 столбца × 3 строки на каждой странице, поэтому BUTTON принимает значения 0–5 в таком порядке:

┌─────┬─────┐
│  0  │  1  │   page N, top row
├─────┼─────┤
│  2  │  3  │   page N, middle row
├─────┼─────┤
│  4  │  5  │   page N, bottom row
└─────┴─────┘

Выберите пустой слот в существующей раскладке нужного строителя — полная постраничная раскладка каждого строителя основной игры есть в справочнике дерева строительства TA.

При запуске движок читает каждый download/*.tdf, разбирает каждую секцию [MENUENTRY<N>] и сливает записи с меню строительства, объявленными в sidedata.tdf. Править sidedata.tdf не нужно.

Чем это лучше правки sidedata.tdf#

Это одобренная Cavedog точка расширения — она существует именно для того, чтобы дополнениям с одним юнитом не приходилось форкать sidedata.tdf.

Строительство у нескольких строителей#

Чтобы юнит могли строить несколько строителей, просто добавьте ещё секций [MENUENTRY<N>]. Именно так сделан собственный download/Armfort.tdf от Cavedog (оборонительная стена ARM, поставляется в ccdata.ccx):

[MENUENTRY1] { UNITMENU=ARMACK; MENU=3; BUTTON=4; UNITNAME=ARMFORT; }
[MENUENTRY2] { UNITMENU=ARMACV; MENU=3; BUTTON=4; UNITNAME=ARMFORT; }
[MENUENTRY3] { UNITMENU=ARMACA; MENU=3; BUTTON=4; UNITNAME=ARMFORT; }

— и ARMFORT могут строить улучшенный строительный К-бот, улучшенная строительная машина и улучшенный строительный самолёт. По одной записи на строителя.

Как выбрать значения MENU и BUTTON#

Стандартная TA резервирует первые две страницы меню (MENU=1, MENU=2) за юнитами основной игры. В сообществе принято размещать скачиваемые юниты на MENU=3 (или выше), чтобы они не сталкивались ни с чем, что поставляет Cavedog. BUTTON — слот на этой странице.

Если сомневаетесь, скопируйте значения из существующего download/*.tdf, который добавляет юнит тому же строителю. Извлеките Armfort.tdf, Armmark.tdf, Cormort.tdf и т. д. от Cavedog как рабочие образцы:

kbot hpi extract /path/to/ccdata.ccx "*.tdf" -t /tmp/cc-downloads
ls /tmp/cc-downloads/download/

Справка по полям — в TDF: [MENUENTRY].

---

6. Перекомпилируйте COB (необязательно)#

MYFLASH.cob — копия ARMFLASH.cob, и в таком виде он будет работать. Если хотите подправить анимацию, декомпилируйте, отредактируйте и скомпилируйте заново:

# Decompile to readable BOS
kbot cob decompile mymod/scripts/MYFLASH.cob -t mymod/scripts/MYFLASH.bos

# Edit MYFLASH.bos in any text editor
# (See cob.md for the BOS language reference.)

# Compile back to bytecode
kbot cob compile  mymod/scripts/MYFLASH.bos -t mymod/scripts/MYFLASH.cob

# Lint for common issues
kbot cob lint     mymod/scripts/MYFLASH.cob

Round-trip «декомпиляция → компиляция» побайтно идентичен для каждого оригинального скрипта Cavedog — kbot cob roundtrip проверяет это на всём каталоге игры.

---

7. (Необязательно) Перерисуйте портрет#

unitpics/myflash.pcx — PCX 96×96 с палитрой. Редактируйте его в любом графическом редакторе, который умеет работать с 8-битными PCX (GIMP, Aseprite, Krita), сохраняя палитру TA. Чтобы проверить, что палитра уцелела:

kbot pcx describe mymod/unitpics/myflash.pcx
# Expected: BitsPerPixel: 8, embedded palette present

Если палитра испортилась, перед сохранением заново импортируйте каноническую палитру TA (palettes/palette.pal). Подводные камни с маркерами 0x0C и заполнением BytesPerLine описаны в PCX.

---

8. (Необязательно) Перерисуйте 3D-модель#

objects3d/myflash.3do — иерархическая сетка: вершины, примитивы, ссылки на текстуры. Редактор Cavedog (3DO Builder), несмотря на возраст, по-прежнему самый практичный редактор 3DO. kbot не редактирует .3do напрямую; веб-интерфейс отрисовывает их только для просмотра:

kbot mount $(kbot ctx path) --server
# → browse to objects3d/myflash.3do for the piece tree and textures

Если вы пишете инструменты, устройство файла на диске описано в 3DO.

---

9. Упакуйте в .ufo#

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

По умолчанию kbot использует сжатие LZ77 по фрагментам со стандартным ключом заголовка Cavedog и трейлером с копирайтом Cavedog, которого требует игра, — то есть движок принимает такой архив без возражений. Проверьте:

kbot hpi info  myflash.ufo
# Should show ~5–8 files, marker 0x49504148 (HAPI), decrypt key 0xBF,
# and "TA 3.1c would mount: yes". A "no" names the reason (for example
# a missing Cavedog trailer), and the game would silently skip the file.

kbot hpi list  myflash.ufo -v
# units/myflash.fbi, scripts/MYFLASH.cob, objects3d/myflash.3do, ...

---

10. Установите и проверьте#

Почему .ufo? TA 3.1c монтирует rev31.gp3, затем каждый .ccx, каждый .ufo и только первые десять .hpi, каждую группу — в порядке имён в верхнем регистре ASCII, и читает каждый файл из первого архива, где он есть (см. порядок загрузки HPI). .ufo монтируется всегда и стоит выше любого .hpi; мод в .hpi боролся бы за десять слотов *.hpi, которые оригинальная установка уже заняла. Файлы, которые есть и в rev31.gp3 или в .ccx (например, units/ARMCOM.FBI или gamedata/sidedata.tdf), всё равно берутся из этих архивов: такие замены поставляйте как файлы вне архивов в корне установки. Диалог Export mod… в студии перечисляет их для рабочей области ещё до скачивания.

Положите .ufo в корень установки TA, рядом с totala1.hpi:

cp myflash.ufo "$TA/"

Запустите TA. Начните схватку, постройте завод техники ARM — и ваш «Super Flash» должен появиться в меню строительства, вдвое быстрее обычной «Вспышки».

---

Устранение неполадок#

---

Что дальше#

• Добавьте новое оружие — скопируйте .tdf из weapons/, отредактируйте и сошлитесь на него из Weapon1= в своём FBI. См. справку по weapons.tdf.
• Добавьте новый класс передвижения — допишите его в moveinfo.tdf. См. TDF в gamedata.
• Сделайте свою карту — соберите .tnt из секций .sct (или напишите TNT вручную с помощью kbot tnt pack). См. TNT.
• Добавьте новые звуки — положите WAV в sounds/ и подключите их в gamedata/sound.tdf. См. Звук.
• Настройте ИИ — добавьте для нового юнита правила Weight/Limit в ai/default.txt. См. ИИ.
• Изучите существующий мод — kbot hpi list и kbot hpi extract работают и со сторонними .ufo. Разбирать, как другие собирали свои архивы, — самый быстрый способ усвоить соглашения моддинга.

---

См. также#

• HPI — подробности упаковки архивов.
• FBI / TDF — язык описания юнитов с полным словарём полей.
• COB / BOS — язык скриптов.
• 3DO — формат сеток.
• TDF в gamedata — справка по sidedata.tdf, moveinfo.tdf, weapons.tdf.
• Глоссарий — справочник терминов.