Gamedata-TDFs – Konfigurationstabellen der Engine

Die Dateien in gamedata/ sind TDF-Textdateien, die die Engine selbst konfigurieren: Bewegungsklassen, Schadenskategorien der Waffen, Seitendaten (Oberflächen-Layout, Baumenüs, Starteinheiten), Sound-Zuordnungen und eine Handvoll kleiner Nachschlagetabellen. Mods, die die Spielregeln ändern (statt Einheiten hinzuzufügen), sitzen fast immer hier.

Diese Seite dokumentiert die nützlichsten Gamedata-Dateien. Sie alle verwenden die INI-artige TDF-Grammatik – Einzelheiten auf Parser-Ebene stehen unter TDF.

ls $(kbot ctx path)/gamedata/
# The web UI renders these as collapsible section trees
kbot mount $(kbot ctx path) --server
# → browse to gamedata/sidedata.tdf, then sidedata > [CANBUILD]

Die Dateien auf einen Blick#

Die großen drei fürs Modding sind sidedata.tdf (Baumenüs, Seiten), moveinfo.tdf (Bewegungsklassen) und weapons.tdf (das Dokumentation ist, keine Daten – die eigentlichen Waffen stehen in weapons/*.tdf).

moveinfo.tdf – Bewegungsklassen#

Die FBI einer Einheit deklariert ihre MovementClass=KBOTSS2 (oder ähnlich); die Engine sucht diese Klasse in moveinfo.tdf, um zu entscheiden, welches Gelände die Einheit befahren kann.

TA 3.1c liest nur die Abschnitte [CLASS0] bis [CLASS31] (jeweils den ersten Abschnitt mit diesem Namen) und findet eine Klasse über ihr Name=, ohne Rücksicht auf Groß- und Kleinschreibung, beginnend beim niedrigsten Platz. Lässt sich die Klasse der Einheit auflösen, ersetzen die Werte der Klasse die eigenen Schlüssel FootprintX/FootprintZ, MaxWaterDepth, MinWaterDepth und die Steigungsschlüssel der Einheit vollständig – das MaxSlope=20 des Commanders weicht den 32 von TANKDS2 –, und ein Schlüssel, den die Klasse weglässt, bekommt den Standardwert des Spiels (siehe unten), nicht den Wert aus der FBI. Eine Einheit ohne Klasse oder mit einer Klasse, die das Spiel nicht findet, liest ihre eigenen FBI-Schlüssel mit denselben Standardwerten. Die Einheiten-Metadaten, die Sandbox und die gehosteten Partien von KBot Studio lösen die Bewegung auf diese Weise auf.

[CLASS0]
{
    Name=KBOTSS2;        // Class name referenced from FBIs
    FootprintX=2;        // Cells wide (16-px units)
    FootprintZ=2;        // Cells deep
    MaxWaterDepth=12;    // Deepest water it can enter
    MaxSlope=32;         // Steepest land slope it can climb
}

[CLASS3]
{
    Name=TANKDH3;
    FootprintX=3;
    FootprintZ=3;
    MaxWaterDepth=100;   // Heavy tank — can ford deep water
    MaxWaterSlope=30;    // Slope limit *underwater* (separate from MaxSlope)
    MaxSlope=15;
}

Felder#

Namenskonventionen#

Der Klassenname kodiert die Form in einem kurzen Kürzel – nach Cavedogs Konvention:

Danach folgt ein Suffix SS / SF / DS / DH / SH (klein/tief/schwer/usw.) und eine Ziffer für die Grundfläche. Die Benennung ist reine Konvention – die Engine behandelt Name= als undurchsichtigen Schlüssel.

sidedata.tdf – Konfiguration pro Seite#

Das ist die längste Datei in gamedata/, weil sie drei verschiedene Aufgaben bündelt:

1. Seitendeklarationen – Name, Präfix, Commander, Schriften, Farben.
2. HUD-Layout – Pixelkoordinaten für jede Statusleiste, jede Beschriftung und jede Schaltfläche der Oberfläche im Spiel.
3. Baumenüs – der Abschnitt [CANBUILD], der auflistet, was jede Baueinheit bauen kann.

Seitenblock#

[SIDE0]
{
    name=ARM;
    nameprefix=ARM;
    commander=ARMCOM;          // UnitName of the commander unit
    intgaf=ARMINT;             // GAF used for intro screen

    font=console;              // FNT for general text
    fontgui=armbutt;           // FNT for buttons
    energycolor=208;           // Palette index for energy bars
    metalcolor=224;            // Palette index for metal bars

    // …followed by ~60 HUD coordinate sub-sections
    [LOGO]      { x1=132; y1=5;   x2=152; y2=25; }
    [ENERGYBAR] { x1=471; y1=12;  x2=598; y2=14; }
    [METALBAR]  { x1=218; y1=12;  x2=345; y2=14; }
    ...
}

[SIDE1] { name=CORE; ... }

TA 3.1c liest die Seiten [SIDE0], [SIDE1], … der Reihe nach und hört bei der ersten fehlenden Nummer und nach fünf Seiten auf. Ein Abschnitt mit einem anderen Namen ([SIDE01], ein [SIDE3] nach einem fehlenden [SIDE2], eine sechste Seite) wird nie gelesen, und jede gelesene Seite braucht jedes der HUD-Rechtecke unten (ta.SideRectangles in kbot-io), sonst lädt das Spiel überhaupt keine Seiten. Die Seitenauswahl in der Sandbox des Studios bietet dieselben Seiten an.

HUD-Koordinaten in Unterabschnitten#

Jedes sichtbare HUD-Element ist ein [NAME]-Block mit den Pixelkoordinaten x1/y1/x2/y2. Sie beziehen sich auf die Basisauflösung 640×480; in höheren Modi skaliert die Engine.

[ENERGYBAR] { x1=471; y1=12; x2=598; y2=14; }

Um die Energieleiste zu verschieben, bearbeite die vier Zahlen. Um ihr ein neues Aussehen zu geben, tausche das GAF aus, mit dem das HUD an dieser Position zeichnet (festgelegt in unitview.tdf).

Baumenüs mit [CANBUILD]#

Die statische Definition des Baumenüs. Jede Baueinheit listet auf, was sie zu Spielbeginn bauen kann:

[CANBUILD]
{
    [ARMCOM]
    {
        canbuild1=ARMSOLAR;    // Slot 1 on the build menu
        canbuild2=ARMWIN;
        canbuild3=ARMESTOR;
        canbuild4=ARMMSTOR;
        canbuild5=ARMMEX;
        ...
    }
    [ARMLAB]
    {
        canbuild1=ARMCK;
        canbuild2=ARMPW;
        ...
    }
}

Die Platznummer ist die Position auf der Seite des Baumenüs. Das Baumenü von TA ist ein Raster aus 2 Spalten × 3 Zeilen, jede Seite fasst also 6 Plätze: canbuild1–canbuild6 sind Seite 1, canbuild7–canbuild12 sind Seite 2 und so weiter.

Wie TA 3.1c die Tabelle liest (CanBuildBuilder.BuildList in kbot-io; kbot document, der Einheiten-Viewer und das Baumenü der Sandbox folgen dem):

• Nur eine Einheit, deren FBI Builder=1 setzt, bekommt eine Liste; ein Unterabschnitt für jede andere Einheit wird ignoriert.
• Das Spiel liest den ersten [CANBUILD]-Abschnitt und darin den ersten Unterabschnitt, der nach der Baueinheit benannt ist (ohne Rücksicht auf Groß- und Kleinschreibung).
• Es liest canbuild1, canbuild2, … und hört bei der ersten fehlenden Nummer auf: canbuild1=ARMSOLAR; canbuild3=ARMLAB; ergibt einen Eintrag.
• Ein Name, der zu keiner Einheit passt, wird übersprungen, und eine Liste fasst höchstens 30 Einheiten. Einträge aus download (siehe unten) können das Menü einer Baueinheit auf 31 bringen. (Ältere Dokumentation behauptete gelegentlich 12 Plätze pro Seite; das tatsächliche Raster im Spiel hat 6.) Das Layout jeder Baueinheit des Grundspiels pro Seite zeigt die Referenz zum TA-Baubaum.

weapons.tdf – Referenz zu Waffen-TDFs#

Trotz des Namens besteht gamedata/weapons.tdf größtenteils aus Kommentaren – es ist Cavedogs veröffentlichte Referenz zur Grammatik der Waffen-TDFs, und das Spiel lädt die Datei nie. Die eigentlichen Waffendefinitionen stehen in weapons/*.tdf, ein Abschnitt pro Waffe (siehe TDF). kbot document listet die Abschnitte von gamedata/weapons.tdf nicht als Waffen auf.

Die Waffentabelle#

TA 3.1c baut eine Tabelle mit 256 Waffenplätzen aus den .tdf-Dateien, die direkt in weapons/ liegen (nicht in dessen Unterverzeichnissen), in der Reihenfolge, in der es sie auflistet:

• Ein Abschnitt kommt auf den Platz, den sein ID= nennt, 0–255. Ein Abschnitt ohne ID oder mit einer ID außerhalb dieses Bereichs wird übersprungen.
• Ein späterer Abschnitt mit derselben ID – in derselben oder einer späteren Datei – ersetzt den früheren.
• Weapon1/Weapon2/Weapon3, ExplodeAs und SelfDestructAs einer Einheit nennen einen Abschnitt; der Name (ohne Rücksicht auf Groß- und Kleinschreibung) wird zum niedrigsten Platz aufgelöst, der einen Abschnitt dieses Namens enthält.
• Werte werden als Zahlenpräfixe gelesen: weaponacceleration=13O; ist 13, und ein ungültiger Wert lässt nie den Rest der Datei wegfallen.
• Eine kaputte Struktur bringt das Spiel dazu, die ganze Datei abzulehnen, sodass keine ihrer Waffen geladen wird, die Abschnitte vor dem Fehler eingeschlossen: ein Abschnittskopf ohne ] oder ohne {, Text ohne = oder ein Wert ohne ; vor dem Dateiende, eine Datei, die innerhalb eines Abschnitts endet, oder eine leere Datei. Andere Dateien sind nicht betroffen. (Eine verirrte } außerhalb jedes Abschnitts führt nicht zur Ablehnung: Das Spiel hört dort auf zu lesen und behält, was davor kam.)
• Ein fehlendes range ist 32767; ein fehlendes minbarrelangle ist -11.25 Grad; reloadtime zählt in ganzen Ticks (30 pro Sekunde, reloadtime*30 abgeschnitten: 0.35 lädt nach 10 Ticks nach, 0,333 s); turnrate ist in Winkeleinheiten pro Sekunde angegeben (65.536 = ein voller Kreis).

KBot Studio, Packs und kbot host lösen Waffen alle über diese Tabelle auf. Dateien, die das Spiel ablehnt, und Abschnitte, die es überspringt oder ersetzt, werden als Warnungen gemeldet (kbot pack gibt sie aus; das Studio stellt sie unter /api/studio/weapons/warnings bereit).

Sprites mit rendertype=4#

Eine Waffe mit rendertype=4 fliegt als 2D-Sprite aus anims/fx.gaf, und ihr color= wählt, welches: 0 cannonshell, 1 plasmasm, 2 plasmamd, 3 ultrashell, 4 noch einmal plasmasm; jeder andere Wert (etwa color=255 von EARTHQUAKE) zeichnet kein Sprite. Das Sprite rückt ab dem Moment, in dem der Schuss abgefeuert wird, pro Spiel-Tick um einen Frame weiter, unabhängig davon, welche Dauern die GAF-Frames angeben.

Die Referenzkommentare dokumentieren:

• Drei Grundtypen von Waffen: ballistic, lineofsight, dropped. Jede Waffen-TDF muss einen davon auf 1 setzen.
• Reichweite, Geschwindigkeit, Beschleunigung – in Pixeln und Pixeln/Sekunde.
• Wirkungsbereich – Radius in Pixeln, mit edgeeffectiveness als Anteil für den Abfall zum Rand hin (z. B. 0.5 = halber Schaden am Rand).
• Salven und Streuung – burst, burstrate, sprayangle.
• Zweiphasige Waffen – twophase, weapontype2, flighttime für Projektile im Starburst-Stil.
• Darstellungstyp – rendertype=N wählt 3D-Modell, Bitmap mit Palette, Strahl usw.

Im Unterabschnitt [DAMAGE] stehen die Schadensmodifikatoren pro Zielkategorie:

[FLAMETHROWER] {
    ...
    [DAMAGE]
    {
        default=10;     // Damage applied to anything not listed
        corpyro=2;      // Pyros are nearly fire-proof
    }
}

Die Schlüssel in [DAMAGE] sind Einheitennamen: Eine aufgeführte Einheit erleidet diesen Schaden statt default=, jede andere Einheit erleidet default=. Die Werte werden auf 16 Bit beschränkt. Todesexplosionen (ExplodeAs, SelfDestructAs) verwenden dieselbe Tabelle – CORPYRO_BLAST richtet standardmäßig 60 Schaden an, bei einem Pyro aber nur 15.

category.tdf – Beschreibungen der Einheitenkategorien#

Eine kosmetische flache Liste, die Kategorie-Tokens lesbarem Text zuordnet. Die Engine zeigt diese im Infopanel der Einheit an:

[Plant]      { description = Unit Creation plant; }
[KBOT]       { description = Some type of units; }
[Tank]       { description = Some type of units; }
[Metal]      { description = Some type of units; }

Die Striche anstelle von Beschreibungen sind unbeabsichtigter Standardtext von Cavedog. Die meisten Mods lassen diese Datei in Ruhe; manche ersetzen die Beschreibungen durch richtigen atmosphärischen Text. Änderungen daran wirken sich nicht auf das Spielgeschehen aus.

sound.tdf und allsound.tdf#

Behandelt unter WAV / Sound. Zusammengefasst:

• sound.tdf – Sound-Zuordnungen pro Einheitenkategorie (die Abschnitte [ARM_COM], [ARM_KBOT]). Referenziert über SoundCategory= in der FBI. Das Spiel liest 23 Ereignisse, jedes als KEY, dann KEY1, KEY2, … bis zur ersten fehlenden Nummer.
• allsound.tdf – globale Sound-Zuordnungen der Oberfläche ([BIGBUTTON], [SKIRMISH], [BGM]).

Beispiel im Detail – eine Bewegungsklasse hinzufügen#

So erstellst du eine Klasse „Boot, das sehr flaches Wasser durchqueren kann“:

1. An gamedata/moveinfo.tdf anhängen:

   [CLASS20]
   {
       Name=AMPHIB3;
       FootprintX=3;
       FootprintZ=3;
       MaxWaterDepth=100;    // Deep water OK
       MaxSlope=20;          // Reasonable land climbing
       MaxWaterSlope=200;    // Smooth underwater movement
   }

2. In der FBI deiner Einheit:

   MovementClass=AMPHIB3;

   Grundfläche und Grenzen der Klasse ersetzen die eigenen Werte der FBI, die Schlüssel FootprintX/FootprintZ/MaxWaterDepth der Einheit spielen also keine Rolle mehr.

3. Packen:

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

Die Einheit bewegt sich jetzt nahtlos über Land und Wasser.

Typische Größen#

Stolperfallen#

• Die Plätze der Bewegungsklassen sind fest. Nur [CLASS0] bis [CLASS31] werden gelesen; Lücken in der Nummerierung innerhalb dieses Bereichs sind kein Problem.
• Kommentare verwenden in den meisten Dateien //, nicht /*…*/ – aber weapons.tdf verwendet beides. Test-Parser tolerieren beides; manche Werkzeuge von Drittanbietern nicht.
• Die HUD-Koordinaten in sidedata.tdf beziehen sich auf die Basis 640×480 und werden von der Engine für höhere Auflösungen hochskaliert. Schreibe keine Koordinaten in modernen Auflösungen.
• Die Nummerierung in [CANBUILD] darf keine Lücken haben. Das Spiel hört beim ersten fehlenden canbuildN auf, die Liste einer Baueinheit zu lesen, canbuild11 gefolgt von canbuild14 verliert also den 14. Eintrag und jeden danach, ohne Fehlermeldung.
• Eine MovementClass, die das Spiel nicht findet, ist kein Fehler. Die Einheit verwendet stillschweigend ihre eigenen FBI-Schlüssel, mit den Standardwerten des Spiels für fehlende – eine Einheit ohne MaxWaterDepth watet dann bis zu einer Tiefe von 10000.

Siehe auch#

• TDF – die Grammatik auf Parser-Ebene, die FBI/OTA teilen.
• Sound – die Verdrahtung von sound.tdf und allsound.tdf.
• FBI – Einheiten verweisen auf MovementClass, SoundCategory und Namen von Waffen-TDFs.
• Glossar – movement class, footprint, side.