Modder une unité, de bout en bout

Ce parcours vous mène d'une installation standard de Total Annihilation à un petit mod qui ajoute une nouvelle variante du char Arm Flash : un reskin deux fois plus rapide. À la fin, vous aurez une archive .ufo prête à distribuer, qui se charge dès qu'on la dépose dans le dossier du jeu, et une représentation claire de chaque format que gère kbot.

L'exercice complet prend une vingtaine de minutes et met en jeu HPI, FBI, COB, 3DO, PCX, TDF et sidedata.tdf.

---

0. Prérequis#

• Une installation complète de TA dans $TA (GoG, Steam ou CD d'origine).
• kbot installé :

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

• De l'espace disque pour une copie de travail aplatie (~120 Mo).

---

1. Aplatir l'installation#

Vous allez modifier des fichiers un par un ; aplatissez les archives une fois pour toutes afin de pouvoir lire leur contenu avec des outils ordinaires.

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

Examinez le résultat :

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

L'organisation des dossiers reproduit la forme du système de fichiers virtuel — voir HPI pour la façon dont les archives se superposent à l'exécution.

---

2. Créer un répertoire de travail pour le mod#

Le modding de TA est additif : déposez un .ufo à côté des archives existantes, et ses fichiers remplacent ceux du jeu de base. Construisez votre mod dans une arborescence miroir :

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

---

3. Choisir une unité à dériver#

Notre MYFLASH sera basé sur l'Arm Flash existant. Copiez quatre fichiers :

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

Pourquoi ces quatre-là ? Toute unité a besoin de :

Par convention, les noms de fichiers reprennent l'Objectname du FBI en minuscules, le .fbi lui-même étant parfois en majuscules. Le moteur est insensible à la casse partout.

---

4. Recâbler le FBI#

Ouvrez mymod/units/myflash.fbi. Les deux champs essentiels à modifier sont UnitName (la clé de recherche) et Objectname (la référence au nom de base des fichiers) :

[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;
    ...
}

Gonflez ensuite une caractéristique pour vérifier que la modification fonctionne — doublez la vitesse :

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

Consultez l'annexe FBI pour le catalogue complet des champs. Tout ce qui n'est pas défini prend les valeurs par défaut du moteur.

---

5. Inscrire l'unité au menu de construction#

Une unité qui existe mais ne figure dans le menu d'aucun constructeur ne peut pas être construite. La bonne façon d'ajouter un emplacement de construction pour une nouvelle unité consiste à déposer un fichier download/<UNITNAME>.tdf dans votre mod : l'extension Core Contingency de Cavedog livre ses nouvelles unités de cette façon, et toutes les extensions .ufo à une seule unité que vous trouverez (AFark.ufo, AFlea.ufo, CorNecro.ufo, …) suivent la même convention.

Créez 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)
}

Le menu de construction de TA est une grille de 2 colonnes × 3 lignes par page : BUTTON prend donc les valeurs 0–5, disposées ainsi :

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

Choisissez un emplacement libre dans la disposition existante du constructeur visé — voir la référence de l'arbre de construction de TA pour la disposition complète, page par page, de chaque constructeur du jeu de base.

Le moteur lit chaque download/*.tdf au démarrage, analyse chaque [MENUENTRY<N>] et fusionne les entrées dans les menus de construction déclarés par sidedata.tdf. Aucune modification de sidedata.tdf n'est nécessaire.

Pourquoi c'est mieux que de modifier sidedata.tdf#

C'est le point d'extension officiellement prévu par Cavedog : il existe précisément pour que les extensions à une seule unité n'aient pas à dériver sidedata.tdf.

Rendre l'unité constructible par plusieurs constructeurs#

Pour rendre l'unité constructible par plusieurs constructeurs, il suffit d'ajouter d'autres sections [MENUENTRY<N>]. Le download/Armfort.tdf de Cavedog (Arm Fortification Wall, livré dans ccdata.ccx) fait exactement cela :

[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; }

Ces trois entrées rendent ARMFORT constructible par l'Advanced Construction Kbot, l'Advanced Construction Vehicle et l'Advanced Construction Aircraft : une entrée par constructeur.

Choisir les valeurs de MENU et BUTTON#

Le TA d'origine réserve les deux premières pages de menu (MENU=1, MENU=2) aux unités du jeu de base. La convention de la communauté est de placer les unités téléchargeables sur MENU=3 (ou plus) pour qu'elles n'entrent en collision avec rien de ce que livre Cavedog. BUTTON est l'emplacement dans cette page.

Dans le doute, copiez les valeurs d'un download/*.tdf existant qui complète le menu du même constructeur. Extrayez Armfort.tdf, Armmark.tdf, Cormort.tdf, etc. de Cavedog pour avoir des références qui fonctionnent :

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

Voir TDF : [MENUENTRY] pour la référence des champs.

---

6. Recompiler le COB (facultatif)#

MYFLASH.cob est une copie de ARMFLASH.cob : il fonctionnera tel quel. Si vous voulez retoucher l'animation, décompilez, modifiez et recompilez :

# 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

L'aller-retour décompilation → compilation est identique à l'octet près pour chaque script d'origine de Cavedog — kbot cob roundtrip le vérifie sur tout le catalogue du jeu.

---

7. (Facultatif) Redessiner le portrait#

unitpics/myflash.pcx est un PCX à palette de 96×96. Modifiez-le dans n'importe quel éditeur d'images qui gère le PCX 8 bits (GIMP, Aseprite, Krita), en conservant la palette de TA. Pour vérifier que la palette a survécu :

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

Si la palette a été abîmée, réimportez la palette de référence de TA (palettes/palette.pal) avant d'enregistrer. Voir PCX pour les pièges liés aux marqueurs 0x0C et au remplissage de BytesPerLine.

---

8. (Facultatif) Retexturer le modèle 3D#

objects3d/myflash.3do est un maillage hiérarchique — sommets, primitives, références de textures. L'éditeur de Cavedog (3DO Builder) reste, malgré son âge, l'éditeur 3DO le plus pratique. kbot ne modifie pas directement les .3do ; l'interface web ne fait que les afficher pour inspection :

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

Voir 3DO pour la structure sur disque si vous écrivez des outils.

---

9. Empaqueter en .ufo#

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

Par défaut, kbot utilise la compression LZ77 par chunks, avec la clé d'en-tête standard de Cavedog et la signature de fin de copyright Cavedog qu'exige le jeu : autrement dit, le moteur l'accepte sans broncher. Vérifiez :

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. Installer et tester#

Pourquoi un .ufo ? TA 3.1c monte rev31.gp3, puis chaque .ccx, chaque .ufo et seulement les dix premiers .hpi, chaque groupe dans l'ordre ASCII des noms en majuscules, et lit chaque fichier dans la première archive qui le contient (voir Ordre de chargement des HPI). Un .ufo est toujours monté et passe avant tous les .hpi ; un mod en .hpi serait en concurrence pour les dix emplacements *.hpi qu'une installation d'origine occupe déjà. Les fichiers que contiennent aussi rev31.gp3 ou un .ccx (par exemple units/ARMCOM.FBI ou gamedata/sidedata.tdf) viennent toujours de ces archives : livrez ces remplacements sous forme de fichiers libres à la racine de l'installation. La boîte de dialogue Export mod… du studio les liste pour un espace de travail avant le téléchargement.

Déposez le .ufo à la racine de l'installation de TA, à côté de totala1.hpi :

cp myflash.ufo "$TA/"

Lancez TA. Démarrez une escarmouche, construisez une Arm Vehicle Plant : votre Super Flash devrait apparaître dans le menu de construction, deux fois plus rapide qu'un Flash normal.

---

Dépannage#

---

Pour aller plus loin#

• Ajouter une nouvelle arme — copiez un .tdf de weapons/, modifiez-le et faites-y référence depuis le Weapon1= de votre FBI. Voir la référence de weapons.tdf.
• Ajouter une nouvelle classe de déplacement — ajoutez-la à la fin de moveinfo.tdf. Voir Gamedata.
• Créer une carte personnalisée — assemblez un .tnt à partir de sections .sct (ou écrivez directement le TNT à la main avec kbot tnt pack). Voir TNT.
• Ajouter de nouveaux sons — déposez des WAV dans sounds/ et câblez-les dans gamedata/sound.tdf. Voir Son.
• Régler l'IA — ajoutez des règles Weight/Limit pour votre nouvelle unité dans ai/default.txt. Voir IA.
• Examiner un mod existant — kbot hpi list et kbot hpi extract fonctionnent aussi sur les .ufo tiers. Étudier comment d'autres ont construit leurs archives est le moyen le plus rapide d'assimiler les conventions du modding.

---

Voir aussi#

• HPI — les détails de l'empaquetage des archives.
• FBI / TDF — le langage de définition des unités, avec le dictionnaire complet des champs.
• COB / BOS — le langage de script.
• 3DO — le format des maillages.
• Gamedata — références de sidedata.tdf, moveinfo.tdf et weapons.tdf.
• Glossaire — référence de la terminologie.