Справочник форматов Total Annihilation и TA: Kingdoms

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

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

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

Контейнеры и обёртки#

Графика и медиа#

Карты и рельеф#

Юниты, скрипты, конфигурации#

Интерфейс TA: Kingdoms#

Руководства и справка#

Условные обозначения: ✅ полноценная поддержка в 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) ссылаются на сетки (3DO), скрипты (COB), портреты юнитов (PCX) и анимированные детали (GAF). Карты (TNT) собираются из секций (SCT) и расстановки объектов, которая разрешается в определения объектов в TDF.

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

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

Эти соглашения действуют для всех форматов в этом справочнике, если страница явно не оговаривает иное:

Как пользоваться этой документацией#

Все страницы о форматах устроены одинаково:

1. Что это такое — назначение и где файл встречается в установке TA.
2. Устройство на диске — структура заголовка, затем секции данных с указанием смещений в байтах.
3. Порядок чтения — последовательность переходов и чтений, которая успешно разбирает файл.
4. Разбор примера — настоящий файл Cavedog, разобранный байт за байтом.
5. Проверьте сами — команды kbot, которые можно запустить на своей установке и увидеть данные вживую.
6. Подводные камни — недокументированные пограничные случаи, различия версий, мусорные байты, оставленные инструментами Cavedog, и т. п.

Если врезка выглядит так:

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.