Усі сторінки форматів ↓
Довідник форматів файлів

Довідник форматів Total Annihilation і TA: Kingdoms

Джерело: coreprime/kbot @ 0ab97bf · Редагувати на GitHub

kbot

Практичний довідник пропрієтарних форматів файлів, що їх Cavedog Entertainment використала в Total Annihilation (1997) і Total Annihilation: Kingdoms (1999), написаний з погляду практика реверс-інжинірингу. Кожна сторінка поєднує структуру байтів на диску з однорядковою командою kbot, тож справжні файли можна досліджувати паралельно з текстом.

Tip

Уперше тут? Прочитайте Швидкий старт — п'ять команд, які за п'ять хвилин покажуть, на що здатен набір інструментів.

Note

Якщо ви ще цього не зробили, спершу встановіть набір інструментів і зареєструйте контекст:

go install github.com/coreprime/kbot/cmd/kbot@latest
kbot ctx add ~/games/totala --alias ta --game totala

Щойно контекст стає поточним, більшість команд (kbot tnt preview …, kbot gaf list …, kbot mount --server) знаходять файл за самим іменем у кожному архіві HPI/UFO/CCX/GP3 інсталяції — абсолютні шляхи більше не потрібно набирати.

Каталог форматів

Контейнери й обгортки

Сторінка Розширення Призначення Повна підтримка?
HPI / UFO / CCX / GP3 .hpi .ufo .ccx .gp3 Зашифрований стиснений архів — обгортка для всього іншого TA ✅   TA:K ✅

Графіка й медіа

Сторінка Розширення Призначення Повна підтримка?
GAF .gaf .taf Анімації спрайтів з індексованими кольорами (курсори, вибухи, деталі юнітів, об'єкти мапи) TA ✅   TA:K ✅
TAF / TSF .taf .tsf Повнокольорові (16-бітний ARGB) анімації TA: Kingdoms — ефекти заклинань, вибухи, фони меню — а також їхня редагована текстова форма TA:K ✅
PCX .pcx Растр ZSoft Paintbrush — портрети юнітів, панелі інтерфейсу та носії палітр у TA:K TA ✅   TA:K ✅
PAL / ALP / LHT / SHD .pal .alp .lht .shd Палітра на 256 кольорів (1 024 байти) і таблиці пошуку кольорів: .alp 256×256 (65 536 байтів), .shd / .lht 32×256 (8 192 байти) TA ✅   TA:K ✅
FNT .fnt Растровий шрифт змінної ширини, 1 біт на піксель TA ✅
Smacker / ZRB .smk .zrb Відео заставок (RAD Game Tools Smacker, перейменоване на .zrb) TA ✅
Bink .bik Відео заставок TA: Kingdoms (RAD Bink 1) — наступник Smacker TA:K ✅
WAV / Звук .wav Звичайний WAV і трирівнева схема підключення звукових банків TA ✅   TA:K ✅

Мапи й рельєф

Сторінка Розширення Призначення Повна підтримка?
SCT .sct Багаторазові секції мап, із яких зшивають мапи .tnt TA ✅
TNT .tnt Повна мапа для гри (сітка тайлів + карта висот + мінімапа + список об'єктів) TA ✅
Мапи TA:K .tnt .ota .crt .kmp Конвеєр мап TA: Kingdoms — текстурований рельєф + рендер мінімапи, а також супровідний файл сценарію .crt (розставлені юніти, правила, тригери) TA:K 🟡

Юніти, скрипти, конфігурації

Сторінка Розширення Призначення Повна підтримка?
3DO .3do Ієрархічна 3D-сітка юніта чи об'єкта з гранями в індексованих кольорах палітри TA ✅
COB / BOS .cob .bos Стековий байткод анімації та скриптів, що керує кожним юнітом TA ✅   TA:K ✅
TDF / FBI / OTA .tdf .fbi .ota Конфігураційні дерева в стилі INI — характеристики юнітів, зброя, метадані мап. Містить повний словник полів FBI. TA ✅   TA:K ✅
TDF у gamedata gamedata/*.tdf Класи руху, дані сторін, прив'язки звуків, довідка зі зброї TA ✅
Профілі ШІ ai/*.txt Текстові ваги ШІ й ліміти юнітів за рівнем складності (профілі TAK не мають plan; див. примітку про TAK) TA ✅   TA:K ✅

Інтерфейс TA: Kingdoms

Сторінка Розширення Призначення Повна підтримка?
Інтерфейс TA:K .gui Розділене пробілами дерево віджетів для меню TA: Kingdoms TA:K ✅

Посібники й довідка

Сторінка Зміст
Швидкий старт П'ять команд для початку.
Моддинг юніта Наскрізний посібник: видобути → змінити → перепакувати → перевірити (TA).
Підводні камені Шпаргалка на одну сторінку з усіма підводними каменями з документації форматів.
Формати TA і TA:K Таблиця на одну сторінку: що спільне, що схоже, а що є лише в одній грі.
Довідкові каталоги Окремі репозиторії: coreprime/reference-ta — 278 юнітів / 199 видів зброї / 45 будівельників; coreprime/reference-tak — 203 юніти / 198 видів зброї / 32 будівельники.
Глосарій Поширені терміни (piece, axis, sealevel, signal mask, …).
Галерея зображень Усі ілюстрації документації разом із командами, які їх створили.

Позначення: ✅ повна підтримка в kbot · 🟡 задокументовано, але kbot поки що цього не розбирає.

Як формати пов'язані між собою

                                ┌───────────────────────────────┐
                                │   HPI / UFO / CCX / GP3       │
                                │   (encrypted, compressed VFS) │
                                └──────────────┬────────────────┘
                                               │ contains
            ┌──────────────────────┬───────────┼───────────────┬──────────────────┐
            ▼                      ▼           ▼               ▼                  ▼
        ┌───────┐             ┌───────┐   ┌───────┐       ┌────────┐        ┌─────────┐
        │  FBI  │ unit stats  │  COB  │   │  3DO  │ mesh  │  GAF   │ sprites│   TNT   │ map
        └───┬───┘             └───┬───┘   └───┬───┘       └────┬───┘        └────┬────┘
            │ references          │ runs on   │ textured by    │ used by         │ built from
            ▼                     ▼           ▼                ▼                 ▼
        ┌───────┐             ┌───────┐   ┌───────┐       ┌────────┐        ┌─────────┐
        │  TDF  │ weapons     │ piece │   │  PCX  │ skins │  PAL   │ colour │   SCT   │ tiles
        │ /OTA  │ /features   │ tree  │   │  unitpic│      │ /ALP/LHT/SHD   │ + heights
        └───────┘             └───────┘   └───────┘       └────────┘        └─────────┘

Майже кожен сеанс реверс-інжинірингу починається з монтування HPI — навіть розгорнуті інсталяції є лише результатом видобування з HPI. Далі юніти (FBI) вказують на 3D-сітки (3DO), скрипти (COB), портрети юнітів (PCX) та анімовані деталі (GAF). Мапи (TNT) збираються із секцій (SCT) і розставлених об'єктів, які посилаються на визначення об'єктів у TDF.

Note

Монтуйте всю інсталяцію одразу. Замість того щоб досліджувати архіви по одному, передайте kbot mount корінь інсталяції. Команда обходить кожен HPI/UFO/CCX у теці й пошарово об'єднує їхній вміст в одну віртуальну файлову систему, тож units/ARMCOM.fbi можна переглядати, не переймаючись тим, з якого архіву він узявся.

kbot mount ~/games/totala --server   # opens at http://localhost:8090

Порядок байтів, кодування символів і система координат

Ці правила діють для всіх форматів цієї документації, якщо сторінка явно не встановлює інших:

Властивість Домовленість
Порядок байтів Little-endian (від молодшого байта до старшого, Intel x86).
Кодування рядків ASCII / CP-437, із завершальним NUL. TA:K додала часткову підтримку Windows-1252, але UTF-8 так і не з'явився.
Розрядність чисел uint8 (char), uint16 (short), uint32 (long). 64-бітних значень немає.
Початок координат Зображення, сітки тайлів, сітки атрибутів — (0, 0) у лівому верхньому куті. У 3D-сітках 3DO вісь Y вертикальна (вгору).
Масштаб фіксованої коми в 3D Моделі 3DO використовують числа з фіксованою комою з 16-бітною дробовою частиною: value / 65536.0 ≈ одиниці світового простору.
Частота ігрових тіків 30 тіків на секунду. Більшість часових полів у COB і GAF задано в тіках.
Прозорий колір Спільного для всієї палітри прозорого індексу немає. Кадр GAF сам задає свій ключ (часто 9, іноді 0), а пропущені пікселі стисненого кадру прозорі; у рельєфі, мінімапах, фонах і текстурах моделей малюється кожен індекс, зокрема індекс палітри 0 (чорний).

Important

Завжди перевіряйте магічні числа, перш ніж довіряти зміщенню. Кілька форматів (HPI, COB, GAF, TNT, SCT) мають 32-бітну сигнатуру в першому полі. Якщо значення не збігається, файл або пошкоджений, або походить із мода, що використовує власний формат, або — у випадку TA:K — є варіантом .taf/.tsf з іншим словом версії.

Як працювати з цією документацією

Кожна сторінка формату побудована однаково:

  1. Що це таке — призначення формату і де він трапляється в інсталяції TA.
  2. Структура на диску — структура заголовка, далі секції даних із зазначеними зміщеннями в байтах.
  3. Порядок читання — послідовність переміщень (seek) і зчитувань, за якою файл успішно розбирається.
  4. Розібраний приклад — справжній файл Cavedog, розібраний байт за байтом.
  5. Перевірте самі — команди kbot, які можна запустити на власній інсталяції, щоб побачити дані наживо.
  6. Підводні камені — незадокументовані крайові випадки, відмінності між версіями, сміттєві байти, залишені інструментами Cavedog, тощо.

Якщо врізка має такий вигляд:

Tip

Спробуйте самі.

kbot pal swatch palettes/palette.pal --target out.png --cell 24

…то команду можна запускати як є, щойно задано контекст.

Подяки й джерела

Ця документація узагальнює десятиліття роботи спільноти з реверс-інжинірингу. Авторство конкретних знахідок сторінки вказують безпосередньо в тексті, але основу заклали:

  • Joe D. — перший розбір формату HPI (1997).
  • Saruman & Bobban / dFR Engineering — перший докладний опис TNT (1997).
  • Scott «me22» McMurray — уточнення формату TNT (2003) на основі вихідного коду Annihilator від Kinboat.
  • Kinboat — формат SCT, інструменти для GAF, редактор мап Annihilator.
  • Dan Melchione & Dark Rain — формат 3DO (1998, доопрацьовано 2002 року).
  • C_A_P, Switeck, KhalvKalash — реверс-інжиніринг опкодів COB/BOS і сімейство інструментів Scriptor.
  • Dark Rain — формат інтерфейсу TA:K і нотатки про складнощі форматів TA:K.
  • Cavedog Entertainment — за гру, яку варто підтримувати живою й понад 25 років потому.

Якщо ця документація суперечить одному з тих першоджерел, останнє слово за вихідним кодом kbot: описані тут формати перевірено читанням і зворотним записом (round-trip) на тисячах справжніх файлів Cavedog. Якщо ви знайшли розбіжність, відкрийте issue або PR на https://github.com/coreprime/kbot.