TDF de gamedata — tables de configuration du moteur

Les fichiers de gamedata/ sont des fichiers texte TDF qui configurent le moteur lui-même : classes de déplacement, catégories de dégâts des armes, données des camps (disposition de l'interface, menus de construction, unités de départ), liaisons de sons et une poignée de petites tables de correspondance. Les mods qui changent les règles du jeu (plutôt que d'ajouter des unités) se trouvent presque toujours ici.

Cette page documente les fichiers de gamedata les plus utiles. Ils utilisent tous la grammaire TDF de style INI — voir TDF pour les détails au niveau de l'analyseur.

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]

Les fichiers en un coup d'œil#

Les trois grands fichiers pour le modding sont sidedata.tdf (menus de construction, camps), moveinfo.tdf (classes de déplacement) et weapons.tdf (qui est de la documentation, pas des données — les vraies armes se trouvent dans weapons/*.tdf).

moveinfo.tdf — classes de déplacement#

Le FBI d'une unité déclare sa MovementClass=KBOTSS2 (ou équivalent) ; le moteur cherche cette classe dans moveinfo.tdf pour décider quel terrain elle peut traverser.

TA 3.1c ne lit que les sections [CLASS0] à [CLASS31] (la première section de chacun de ces noms) et trouve une classe par son Name=, sans tenir compte de la casse, en commençant par l'emplacement le plus bas. Quand la classe de l'unité se résout, ses valeurs remplacent entièrement les clés FootprintX/FootprintZ, MaxWaterDepth, MinWaterDepth et de pente propres à l'unité — le MaxSlope=20 du commandant cède la place au 32 de TANKDS2 — et une clé que la classe omet prend la valeur par défaut du jeu ci-dessous, et non la valeur du FBI. Une unité sans classe, ou qui en nomme une que le jeu ne trouve pas, lit ses propres clés du FBI avec les mêmes valeurs par défaut. Les métadonnées d'unité de KBot Studio, le bac à sable et les parties hébergées résolvent le déplacement de cette façon.

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

Champs#

Conventions de nommage#

Le nom de la classe encode sa forme dans une courte étiquette, selon la convention de Cavedog :

Puis un suffixe SS / SF / DS / DH / SH (petit/profond/lourd/etc.) et un chiffre d'emprise. Ce nommage n'est qu'une convention : le moteur traite Name= comme une clé opaque.

sidedata.tdf — configuration par camp#

C'est le plus long fichier de gamedata/, car il regroupe trois préoccupations distinctes :

1. Les déclarations des camps — nom, préfixe, commandant, polices, couleurs.
2. La disposition de l'interface (HUD) — coordonnées en pixels de chaque barre d'état, étiquette et bouton de l'interface en jeu.
3. Les menus de construction — la section [CANBUILD], qui liste ce que chaque constructeur peut construire.

Bloc de camp#

[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 lit les camps [SIDE0], [SIDE1], … dans l'ordre, en s'arrêtant au premier numéro manquant et après cinq. Une section qui porte un autre nom ([SIDE01], un [SIDE3] après un [SIDE2] manquant, un sixième camp) n'est jamais lue, et chaque camp lu a besoin de tous les rectangles d'interface ci-dessous (ta.SideRectangles de kbot-io), faute de quoi le jeu ne charge aucun camp. Le sélecteur de camp du bac à sable du studio propose les mêmes camps.

Sous-sections de coordonnées de l'interface#

Chaque élément visible de l'interface est un bloc [NAME] avec des coordonnées en pixels x1/y1/x2/y2. Elles sont relatives à la résolution de base de 640×480 ; le moteur les met à l'échelle pour les modes supérieurs.

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

Pour déplacer la barre d'énergie, modifiez les quatre nombres. Pour changer son apparence, remplacez le GAF que l'interface utilise pour dessiner à cette position (défini dans unitview.tdf).

Menus de construction [CANBUILD]#

La définition statique des menus de construction. Chaque constructeur liste ce qu'il peut construire en début de partie :

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

Le numéro d'emplacement est la position dans la page du menu de construction. Le menu de construction de TA est une grille de 2 colonnes × 3 lignes : chaque page contient donc 6 emplacements. canbuild1–canbuild6 forment la page 1, canbuild7–canbuild12 la page 2, et ainsi de suite.

Comment TA 3.1c lit la table (CanBuildBuilder.BuildList de kbot-io ; kbot document, la visionneuse d'unités et le menu de construction du bac à sable s'y conforment) :

• Seule une unité dont le FBI fixe Builder=1 reçoit une liste ; une sous-section pour toute autre unité est ignorée.
• Le jeu lit la première section [CANBUILD] et, dans celle-ci, la première sous-section qui porte le nom du constructeur (sans tenir compte de la casse).
• Il lit canbuild1, canbuild2, … et s'arrête au premier numéro manquant : canbuild1=ARMSOLAR; canbuild3=ARMLAB; donne une seule entrée.
• Un nom qui ne correspond à aucune unité est ignoré, et une liste contient au plus 30 unités. Les entrées de download (voir plus bas) peuvent porter le menu d'un constructeur à 31. (D'anciennes documentations affirmaient parfois 12 emplacements par page ; la grille réelle en jeu en compte 6.) Voir la référence de l'arbre de construction de TA pour la disposition page par page de chaque constructeur du jeu de base.

weapons.tdf — référence des TDF d'armes#

Malgré son nom, gamedata/weapons.tdf est surtout fait de commentaires : c'est la référence publiée par Cavedog pour la grammaire des TDF d'armes, et le jeu ne le charge jamais. Les vraies définitions d'armes se trouvent dans weapons/*.tdf, une section par arme (voir TDF). kbot document ne liste pas les sections de gamedata/weapons.tdf comme des armes.

La table des armes#

TA 3.1c construit une table de 256 emplacements d'armes à partir des fichiers .tdf situés directement dans weapons/ (pas dans ses sous-répertoires), dans l'ordre où il les liste :

• Une section va dans l'emplacement que désigne son ID=, de 0 à 255. Une section sans ID, ou avec un ID hors de cette plage, est ignorée.
• Une section ultérieure de même ID — dans le même fichier ou dans un fichier suivant — remplace la précédente.
• Les Weapon1/Weapon2/Weapon3, ExplodeAs et SelfDestructAs d'une unité nomment une section ; le nom (sans tenir compte de la casse) se résout vers l'emplacement le plus bas qui contient une section de ce nom.
• Les valeurs sont lues comme des préfixes numériques : weaponacceleration=13O; vaut 13, et une mauvaise valeur ne fait jamais perdre le reste du fichier.
• Une structure cassée fait refuser le fichier entier par le jeu : aucune de ses armes ne se charge, pas même les sections situées avant l'erreur. Cela vaut pour un en-tête de section sans ] ou sans {, un texte sans = ou une valeur sans ; avant la fin du fichier, un fichier qui se termine à l'intérieur d'une section, ou un fichier vide. Les autres fichiers ne sont pas affectés. (Une } isolée hors de toute section n'est pas refusée : le jeu arrête la lecture à cet endroit et garde ce qui précède.)
• Un range absent vaut 32767 ; un minbarrelangle absent vaut -11.25 degrés ; reloadtime se compte en ticks entiers (30 par seconde, reloadtime*30 tronqué : 0.35 recharge au bout de 10 ticks, soit 0,333 s) ; turnrate est exprimé en unités d'angle par seconde (65 536 = un tour complet).

KBot Studio, les packs et kbot host résolvent tous les armes par cette table. Les fichiers que le jeu refuse et les sections qu'il ignore ou remplace sont signalés par des avertissements (kbot pack les affiche ; le studio les sert sur /api/studio/weapons/warnings).

Sprites de rendertype=4#

Une arme rendertype=4 fait voler un sprite 2D tiré de anims/fx.gaf, et son color= choisit lequel : 0 cannonshell, 1 plasmasm, 2 plasmamd, 3 ultrashell, 4 de nouveau plasmasm ; toute autre valeur (comme le color=255 d'EARTHQUAKE) ne dessine aucun sprite. Le sprite avance d'une frame par tick de jeu à partir du moment où le tir part, quelles que soient les durées que portent les frames du GAF.

Les commentaires de référence documentent :

• Trois archétypes d'armes : ballistic, lineofsight, dropped. Chaque TDF d'arme doit mettre l'un d'eux à 1.
• Portée, vitesse, accélération — en pixels et en pixels par seconde.
• Zone d'effet — rayon en pixels, avec edgeeffectiveness comme fraction d'atténuation (par ex. 0.5 = moitié des dégâts au bord).
• Rafale et dispersion — burst, burstrate, sprayangle.
• Armes en deux phases — twophase, weapontype2, flighttime pour les projectiles de type starburst.
• Type de rendu — rendertype=N choisit modèle 3D, bitmap à palette, rayon, etc.

C'est dans la sous-section [DAMAGE] que se trouvent les modificateurs de dégâts par catégorie de cible :

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

Les clés de [DAMAGE] sont des noms d'unités : une unité listée reçoit ces dégâts au lieu de default=, toutes les autres unités reçoivent default=. Les valeurs sont tronquées à 16 bits. Les explosions de mort (ExplodeAs, SelfDestructAs) utilisent la même table : CORPYRO_BLAST inflige 60 par défaut, mais 15 à un Pyro.

category.tdf — descriptions des catégories d'unités#

Une liste plate et cosmétique qui associe les jetons de catégorie à un texte lisible. Le moteur les affiche dans le panneau d'informations de l'unité :

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

Les tirets à la place des descriptions sont un texte générique laissé par mégarde par Cavedog. La plupart des mods laissent ce fichier tel quel ; certains remplacent les descriptions par un vrai texte d'ambiance. Le modifier n'a aucun effet sur le gameplay.

sound.tdf et allsound.tdf#

Traités dans WAV / Son. En résumé :

• sound.tdf — liaisons de sons par catégorie d'unités (les sections [ARM_COM], [ARM_KBOT]). Référencé par le SoundCategory= du FBI. Le jeu lit 23 événements, chacun sous la forme KEY, puis KEY1, KEY2, … jusqu'au premier numéro manquant.
• allsound.tdf — liaisons de sons globales de l'interface ([BIGBUTTON], [SKIRMISH], [BGM]).

Exemple commenté — ajouter une classe de déplacement#

Pour créer une classe « navire capable de franchir une eau très peu profonde » :

1. Ajoutez à la fin de gamedata/moveinfo.tdf :

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

2. Dans le FBI de votre unité :

   MovementClass=AMPHIB3;

   L'emprise et les limites de la classe remplacent celles du FBI : les clés FootprintX/FootprintZ/MaxWaterDepth de l'unité ne comptent donc plus.

3. Empaquetez :

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

L'unité traverse désormais sans difficulté la terre comme l'eau.

Tailles typiques#

Pièges#

• Les emplacements des classes de déplacement sont fixes. Seules les sections [CLASS0] à [CLASS31] sont lues ; les trous de numérotation dans cette plage ne posent pas de problème.
• Les commentaires utilisent //, pas /*…*/, dans la plupart des fichiers — mais weapons.tdf utilise les deux. Les analyseurs de test tolèrent les deux ; certains outils tiers non.
• Les coordonnées d'interface de sidedata.tdf sont exprimées dans la base 640×480 et mises à l'échelle par le moteur pour les résolutions supérieures. N'écrivez pas de coordonnées dans des résolutions modernes.
• La numérotation de [CANBUILD] ne doit pas avoir de trous. Le jeu arrête de lire la liste d'un constructeur au premier canbuildN manquant : un canbuild11 suivi d'un canbuild14 perd la 14e entrée et toutes les suivantes, sans erreur.
• Une MovementClass introuvable pour le jeu n'est pas une erreur. L'unité utilise silencieusement ses propres clés du FBI, avec les valeurs par défaut du jeu pour celles qui manquent : une unité sans MaxWaterDepth patauge alors jusqu'à une profondeur de 10000.

Voir aussi#

• TDF — la grammaire de l'analyseur, commune aux FBI et aux OTA.
• Son — le câblage de sound.tdf et allsound.tdf.
• FBI — les unités font référence à MovementClass, à SoundCategory et à des noms de TDF d'armes.
• Glossaire — classe de déplacement, emprise, camp.