Моддинг юніта від початку до кінця

Цей посібник проведе вас від стандартної інсталяції 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. Розгорніть інсталяцію#

Ви редагуватимете окремі файли, тож один раз розгорніть (flatten) архіви, щоб читати їх звичайними інструментами.

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 Flash. Скопіюйте чотири файли:

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: саме так постачає свої нові юніти доповнення Core Contingency від самої Cavedog, і саме цієї домовленості дотримується кожне доповнення .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 Fortification Wall, постачається в 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 з Advanced Construction Kbot, Vehicle і Aircraft. Один запис на кожного будівельника.

Як обрати значення MENU і BUTTON#

Стандартна TA резервує перші дві сторінки меню (MENU=1, MENU=2) для юнітів базової гри. За домовленістю спільноти юніти з download розміщують на 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 — це ієрархічна 3D-сітка: вершини, примітиви, посилання на текстури. Редактор від 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 Vehicle Plant, і ваш Super Flash має з'явитися в меню будівництва — удвічі швидший за звичайний Flash.

---

Усунення несправностей#

---

Що далі#

• Додайте нову зброю — скопіюйте .tdf з weapons/, відредагуйте й укажіть його в Weapon1= свого FBI. Див. довідник з weapons.tdf.
• Додайте новий клас руху — допишіть його в moveinfo.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 — формат 3D-сіток.
• Gamedata — довідка з sidedata.tdf, moveinfo.tdf, weapons.tdf.
• Глосарій — довідник термінів.