Eine Einheit modden, von Anfang bis Ende

Dieser Rundgang führt dich von einer Originalinstallation von Total Annihilation zu einem winzigen Mod, der eine neue Variante des Panzers Arm Flash hinzufügt – ein Reskin mit doppelter Geschwindigkeit. Am Ende hast du ein veröffentlichungsfertiges .ufo-Archiv, das geladen wird, sobald du es in den Spielordner legst, und eine brauchbare Vorstellung von jedem Format, das kbot unterstützt.

Die ganze Übung dauert etwa 20 Minuten und nutzt HPI, FBI, COB, 3DO, PCX, TDF und sidedata.tdf.

---

0. Voraussetzungen#

• Eine vollständige TA-Installation unter $TA (GoG, Steam oder Original-CD).
• kbot installiert:

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

• Speicherplatz für eine geflattete Arbeitskopie (ca. 120 MB).

---

1. Die Installation flatten#

Du bearbeitest einzelne Dateien, also werden die Archive einmal geflattet, damit du sie mit normalen Werkzeugen lesen kannst.

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

Sieh dir das Ergebnis an:

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

Der Ordneraufbau entspricht der Struktur des VFS – wie Archive zur Laufzeit übereinandergeschichtet werden, steht unter HPI.

---

2. Ein Arbeitsverzeichnis für den Mod anlegen#

Modding in TA ist additiv: Leg eine .ufo neben die vorhandenen Archive, und ihre Dateien ersetzen die des Grundspiels. Bau deinen Mod in einem Verzeichnisbaum auf, der den des Spiels spiegelt:

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

---

3. Eine Einheit als Vorlage auswählen#

Wir bauen unseren MYFLASH auf dem vorhandenen Arm Flash auf. Kopiere vier Dateien:

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

Warum diese vier? Jede Einheit braucht:

Die Dateinamen entsprechen üblicherweise dem Objectname aus der FBI in Kleinbuchstaben; die .fbi selbst ist manchmal großgeschrieben. Die Engine unterscheidet durchgängig nicht zwischen Groß- und Kleinschreibung.

---

4. Die FBI neu verdrahten#

Öffne mymod/units/myflash.fbi. Die zwei entscheidenden Felder, die du ändern musst, sind UnitName (der Suchschlüssel) und Objectname (der Verweis auf den Basisnamen der Dateien):

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

Dreh dann an einem Wert, um zu zeigen, dass die Änderung wirkt – verdopple die Geschwindigkeit:

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

Den vollständigen Feldkatalog findest du im FBI-Anhang. Alles, was nicht gesetzt ist, erbt die Standardwerte der Engine.

---

5. Die Einheit im Baumenü registrieren#

Eine Einheit, die zwar existiert, aber von keiner Baueinheit aus erreichbar ist, kann nicht gebaut werden. Der richtige Weg, einer neuen Einheit einen Bauplatz zu verschaffen, ist eine Datei download/<UNITNAME>.tdf in deinem Mod – Cavedogs eigene Erweiterung Core Contingency liefert ihre neuen Einheiten auf diese Weise aus, und jedes .ufo-Add-on mit einer einzelnen Einheit, das dir begegnet (AFark.ufo, AFlea.ufo, CorNecro.ufo, …), folgt derselben Konvention.

Lege mymod/download/MYFLASH.tdf an:

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

Das Baumenü von TA ist pro Seite ein Raster aus 2 Spalten × 3 Zeilen; BUTTON nimmt also die Werte 0–5 an, angeordnet wie folgt:

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

Wähle einen freien Platz im vorhandenen Layout der Ziel-Baueinheit – die vollständige Belegung jeder Seite für jede Baueinheit des Grundspiels steht in der Referenz zum Baubaum von TA.

Die Engine liest beim Start jede download/*.tdf, parst jedes [MENUENTRY<N>] und führt die Einträge mit den Baumenüs zusammen, die sidedata.tdf deklariert hat. sidedata.tdf muss dafür nicht bearbeitet werden.

Warum das besser ist, als sidedata.tdf zu bearbeiten#

Das ist der von Cavedog offiziell vorgesehene Erweiterungs-Hook – es gibt ihn genau dafür, dass Add-ons mit einzelnen Einheiten keine eigene Fassung von sidedata.tdf pflegen müssen.

Von mehreren Baueinheiten aus bauen#

Damit die Einheit von mehreren Baueinheiten aus gebaut werden kann, füge einfach weitere [MENUENTRY<N>]-Abschnitte hinzu. Cavedogs eigene download/Armfort.tdf (Arm Fortification Wall, ausgeliefert in ccdata.ccx) macht genau das:

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

– damit ist ARMFORT vom Advanced Construction Kbot, Vehicle und Aircraft aus baubar. Ein Eintrag pro Baueinheit.

Werte für MENU und BUTTON wählen#

Das Original-TA reserviert die ersten beiden Menüseiten (MENU=1, MENU=2) für die Einheiten des Grundspiels. Nach Konvention der Community kommen herunterladbare Einheiten auf MENU=3 (oder höher), damit sie mit nichts kollidieren, was Cavedog ausliefert. BUTTON ist der Platz innerhalb dieser Seite.

Im Zweifel übernimm die Werte aus einer vorhandenen download/*.tdf, die dieselbe Baueinheit ergänzt. Entpacke Cavedogs Armfort.tdf, Armmark.tdf, Cormort.tdf usw. als funktionierende Vorlagen:

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

Die Feldreferenz steht unter TDF: [MENUENTRY].

---

6. Die COB neu kompilieren (optional)#

MYFLASH.cob ist eine Kopie von ARMFLASH.cob – sie funktioniert so, wie sie ist. Wenn du die Animation anpassen willst, dekompiliere, bearbeite und kompiliere neu:

# 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

Der Round-Trip Dekompilieren→Kompilieren ist für jedes Cavedog-Skript der Verkaufsversion byte-identisch – kbot cob roundtrip prüft das über den gesamten Spielkatalog.

---

7. (Optional) Das Porträt neu gestalten#

unitpics/myflash.pcx ist ein 96×96-PCX mit Palette. Bearbeite es in einem beliebigen Bildeditor, der mit 8-Bit-PCX umgehen kann (GIMP, Aseprite, Krita), und behalte dabei die Palette von TA bei. So prüfst du, ob die Palette heil geblieben ist:

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

Ist die Palette verstümmelt, importiere vor dem Speichern die kanonische Palette von TA (palettes/palette.pal) neu. Die Stolperfallen rund um den Marker 0x0C und die Auffüllung von BytesPerLine stehen unter PCX.

---

8. (Optional) Das 3D-Modell neu gestalten#

objects3d/myflash.3do ist ein hierarchisches Mesh – Vertices, Primitive, Texturverweise. Der Cavedog-Editor (3DO Builder) ist trotz seines Alters immer noch der praktischste 3DO-Editor. kbot bearbeitet .3do nicht direkt; die Web-Oberfläche rendert sie nur zur Ansicht:

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

Wenn du Werkzeuge baust, findest du den Aufbau auf der Platte unter 3DO.

---

9. In eine .ufo packen#

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

Standardmäßig verwendet kbot chunkweise LZ77-Kompression mit Cavedogs üblichem Header-Schlüssel und dem Cavedog-Copyright-Trailer, den das Spiel verlangt – die Engine akzeptiert die Datei also anstandslos. Zur Bestätigung:

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. Installieren und testen#

Warum eine .ufo? TA 3.1c hängt rev31.gp3 ein, dann jede .ccx, jede .ufo und nur die ersten zehn .hpi – jede Gruppe nach dem großgeschriebenen ASCII-Namen sortiert – und liest jede Datei aus dem ersten Archiv, das sie enthält (siehe Ladereihenfolge von HPI). Eine .ufo wird immer eingehängt und rangiert über jeder .hpi; ein Mod als .hpi müsste um die zehn *.hpi-Plätze konkurrieren, die eine Installation der Verkaufsversion bereits belegt hat. Dateien, die auch rev31.gp3 oder eine .ccx enthält (zum Beispiel units/ARMCOM.FBI oder gamedata/sidedata.tdf), kommen trotzdem aus diesen Archiven: Liefere solche Überschreibungen als lose Dateien im Wurzelverzeichnis der Installation aus. Der Dialog Export mod… des Studios listet sie für einen Workspace auf, bevor du herunterlädst.

Leg die .ufo in das Wurzelverzeichnis der TA-Installation, neben totala1.hpi:

cp myflash.ufo "$TA/"

Starte TA. Beginne ein Skirmish-Spiel, bau eine Arm Vehicle Plant, und dein Super Flash sollte im Baumenü erscheinen – doppelt so schnell wie ein gewöhnlicher Flash.

---

Fehlersuche#

---

Wie es weitergeht#

• Eine neue Waffe hinzufügen – kopiere eine .tdf aus weapons/, bearbeite sie und verweise im Weapon1= deiner FBI darauf. Siehe die Referenz zu weapons.tdf.
• Eine neue Bewegungsklasse hinzufügen – ergänze moveinfo.tdf. Siehe Gamedata.
• Eine eigene Karte erstellen – setze eine .tnt aus .sct-Sektionen zusammen (oder schreib die TNT mit kbot tnt pack direkt von Hand). Siehe TNT.
• Neue Sounds hinzufügen – leg WAVs in sounds/ und verdrahte sie in gamedata/sound.tdf. Siehe Sound.
• Die KI abstimmen – füge in ai/default.txt Regeln mit Weight/Limit für deine neue Einheit hinzu. Siehe KI.
• Einen vorhandenen Mod untersuchen – kbot hpi list und kbot hpi extract funktionieren auch mit .ufo-Dateien von Dritten. Am schnellsten verinnerlichst du die Konventionen des Moddings, wenn du dir ansiehst, wie andere ihre Archive gebaut haben.

---

Siehe auch#

• HPI – Details zum Packen von Archiven.
• FBI / TDF – Sprache für Einheitendefinitionen mit vollständigem Feldverzeichnis.
• COB / BOS – Skriptsprache.
• 3DO – Mesh-Format.
• Gamedata – Referenzen zu sidedata.tdf, moveinfo.tdf und weapons.tdf.
• Glossar – Nachschlagewerk zur Terminologie.