TDF di gamedata — Tabelle di configurazione del motore

I file in gamedata/ sono file di testo TDF che configurano il motore stesso: classi di movimento, categorie di danno delle armi, dati delle fazioni (disposizione dell'interfaccia, menu di costruzione, unità iniziali), associazioni dei suoni e una manciata di piccole tabelle di ricerca. Le mod che cambiano le regole del gioco (anziché aggiungere unità) stanno quasi sempre qui.

Questa pagina documenta i file di gamedata più utili. Usano tutti la grammatica TDF in stile INI: vedi TDF per i dettagli a livello di parser.

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]

I file in breve#

I tre file più importanti per il modding sono sidedata.tdf (menu di costruzione, fazioni), moveinfo.tdf (classi di movimento) e weapons.tdf (che è documentazione, non dati: le armi vere e proprie stanno in weapons/*.tdf).

moveinfo.tdf — Classi di movimento#

L'FBI di un'unità dichiara la sua MovementClass=KBOTSS2 (o simile); il motore cerca quella classe in moveinfo.tdf per decidere quale terreno l'unità può attraversare.

TA 3.1c legge solo le sezioni da [CLASS0] a [CLASS31] (la prima sezione con ciascuno di quei nomi) e trova una classe tramite il suo Name=, ignorando maiuscole e minuscole, a partire dallo slot più basso. Quando la classe dell'unità si risolve, i valori della classe sostituiscono completamente le chiavi FootprintX/FootprintZ, MaxWaterDepth, MinWaterDepth e di pendenza dell'unità stessa (il MaxSlope=20 del comandante cede il posto al 32 di TANKDS2), e una chiave che la classe omette prende il valore predefinito del gioco indicato più sotto, non il valore dell'FBI. Un'unità senza classe, o che ne nomina una che il gioco non trova, legge le proprie chiavi dell'FBI con gli stessi valori predefiniti. I metadati delle unità, la sandbox e le partite ospitate di KBot Studio risolvono il movimento in questo modo.

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

Campi#

Convenzioni sui nomi#

Il nome della classe ne codifica la forma in una breve sigla, secondo la convenzione di Cavedog:

Segue un suffisso SS / SF / DS / DH / SH (piccolo/profondo/pesante/ ecc.) e una cifra per l'ingombro. I nomi sono solo una convenzione: il motore tratta Name= come una chiave opaca.

sidedata.tdf — Configurazione per fazione#

È il file più lungo di gamedata/ perché riunisce tre aspetti distinti:

1. Dichiarazioni delle fazioni: nome, prefisso, comandante, font, colori.
2. Disposizione dell'HUD: coordinate in pixel di ogni barra di stato, etichetta e pulsante dell'interfaccia di gioco.
3. Menu di costruzione: la sezione [CANBUILD], che elenca ciò che ogni costruttore può costruire.

Blocco della fazione#

[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 legge le fazioni [SIDE0], [SIDE1], … in ordine, fermandosi al primo numero mancante e comunque dopo cinque. Una sezione con qualsiasi altro nome ([SIDE01], un [SIDE3] dopo un [SIDE2] mancante, una sesta fazione) non viene mai letta, e ogni fazione letta ha bisogno di tutti i rettangoli dell'HUD qui sotto (ta.SideRectangles di kbot-io), altrimenti il gioco non carica nessuna fazione. Il selettore di fazione della sandbox dello studio offre le stesse fazioni.

Sottosezioni delle coordinate dell'HUD#

Ogni elemento visibile dell'HUD è un blocco [NAME] con coordinate in pixel x1/y1/x2/y2. Sono relative alla risoluzione di base 640×480; alle modalità più alte le scala il motore.

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

Per riposizionare la barra dell'energia, modifica i quattro numeri. Per cambiarne l'aspetto, sostituisci il GAF che l'HUD usa per disegnare in quella posizione (impostato in unitview.tdf).

Menu di costruzione [CANBUILD]#

La definizione statica del menu di costruzione. Ogni costruttore elenca ciò che può costruire all'inizio della partita:

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

Il numero dello slot è la posizione nella pagina del menu di costruzione. Il menu di costruzione di TA è una griglia di 2 colonne × 3 righe, quindi ogni pagina contiene 6 slot: da canbuild1 a canbuild6 è la pagina 1, da canbuild7 a canbuild12 la pagina 2, e così via.

Come TA 3.1c legge la tabella (CanBuildBuilder.BuildList di kbot-io; kbot document, il visualizzatore di unità e il menu di costruzione della sandbox lo seguono):

• Ottiene una lista solo un'unità il cui FBI imposta Builder=1; una sottosezione per qualsiasi altra unità viene ignorata.
• Il gioco legge la prima sezione [CANBUILD] e, al suo interno, la prima sottosezione che porta il nome del costruttore (ignorando maiuscole e minuscole).
• Legge canbuild1, canbuild2, … e si ferma al primo numero mancante: canbuild1=ARMSOLAR; canbuild3=ARMLAB; dà una sola voce.
• Un nome che non corrisponde a nessuna unità viene saltato, e una lista contiene al massimo 30 unità. Le voci di download (vedi sotto) possono portare il menu di un costruttore a 31. (La documentazione più vecchia sosteneva a volte che ci fossero 12 slot per pagina; la griglia reale nel gioco è di 6.) Vedi il riferimento all'albero di costruzione di TA per la disposizione pagina per pagina di ogni costruttore del gioco base.

weapons.tdf — Riferimento dei TDF delle armi#

Nonostante il nome, gamedata/weapons.tdf è composto per lo più da commenti: è il riferimento pubblicato da Cavedog per la grammatica dei TDF delle armi, e il gioco non lo carica mai. Le definizioni effettive delle armi stanno in weapons/*.tdf, una sezione per arma (vedi TDF). kbot document non elenca come armi le sezioni di gamedata/weapons.tdf.

La tabella delle armi#

TA 3.1c costruisce una tabella di 256 slot per le armi a partire dai file .tdf che si trovano direttamente in weapons/ (non nelle sue sottodirectory), nell'ordine in cui li elenca:

• Una sezione va nello slot indicato dal suo ID=, da 0 a 255. Una sezione senza ID, o con un ID fuori da quell'intervallo, viene saltata.
• Una sezione successiva con lo stesso ID (nello stesso file o in uno successivo) sostituisce quella precedente.
• Weapon1/Weapon2/Weapon3, ExplodeAs e SelfDestructAs di un'unità nominano una sezione; il nome (ignorando maiuscole e minuscole) si risolve nello slot più basso che contiene una sezione con quel nome.
• I valori vengono letti come prefissi numerici: weaponacceleration=13O; vale 13, e un valore non valido non fa mai scartare il resto del file.
• Una struttura rotta fa rifiutare al gioco l'intero file, quindi nessuna delle sue armi viene caricata, comprese le sezioni che precedono l'errore: un'intestazione di sezione senza ] o senza {, testo senza = o un valore senza ; prima della fine del file, il file che termina all'interno di una sezione, oppure un file vuoto. Gli altri file non ne risentono. (Una } isolata fuori da qualsiasi sezione non viene rifiutata: il gioco smette di leggere in quel punto e conserva ciò che c'era prima.)
• Un range mancante vale 32767; un minbarrelangle mancante vale -11.25 gradi; reloadtime si conta in tick interi (30 al secondo, reloadtime*30 troncato: 0.35 ricarica dopo 10 tick, 0,333 s); turnrate è in unità angolari al secondo (65536 = un giro completo).

KBot Studio, i pacchetti e kbot host risolvono tutti le armi tramite questa tabella. I file che il gioco rifiuta e le sezioni che salta o sostituisce vengono segnalati come avvisi (kbot pack li stampa; lo studio li fornisce su /api/studio/weapons/warnings).

Sprite di rendertype=4#

Un'arma con rendertype=4 fa volare uno sprite 2D preso da anims/fx.gaf, e il suo color= sceglie quale: 0 cannonshell, 1 plasmasm, 2 plasmamd, 3 ultrashell, 4 di nuovo plasmasm; qualsiasi altro valore (come il color=255 di EARTHQUAKE) non disegna alcuno sprite. Lo sprite avanza di un frame per tick di gioco dal momento in cui parte il colpo, qualunque siano le durate riportate dai frame del GAF.

I commenti di riferimento documentano:

• Tre archetipi di arma: ballistic, lineofsight, dropped. Ogni TDF di un'arma deve impostarne uno a 1.
• Gittata, velocità, accelerazione: in pixel e pixel/secondo.
• Area d'effetto: raggio in pixel, con edgeeffectiveness come frazione di attenuazione (ad es. 0.5 = metà del danno sul bordo).
• Raffica e dispersione: burst, burstrate, sprayangle.
• Armi a due fasi: twophase, weapontype2, flighttime per i proiettili in stile starburst.
• Tipo di rendering: rendertype=N sceglie tra modello 3D, bitmap con palette, raggio, ecc.

La sottosezione [DAMAGE] è dove si trovano i modificatori del danno per categoria di bersaglio:

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

Le chiavi in [DAMAGE] sono nomi di unità: un'unità elencata subisce quel danno invece di default=, ogni altra unità subisce default=. I valori sono limitati a 16 bit. Le esplosioni alla morte (ExplodeAs, SelfDestructAs) usano la stessa tabella: CORPYRO_BLAST infligge 60 per impostazione predefinita, ma 15 a un Pyro.

category.tdf — Descrizioni delle categorie di unità#

Una lista piatta, puramente estetica, che associa i token delle categorie a un testo leggibile. Il motore li mostra nel pannello informativo dell'unità:

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

I trattini al posto delle descrizioni sono testo di riempimento lasciato involontariamente da Cavedog. La maggior parte delle mod non tocca questo file; alcune sostituiscono le descrizioni con testi descrittivi veri e propri. Modificarlo non influisce sul gameplay.

sound.tdf e allsound.tdf#

Trattati in WAV / Audio. In sintesi:

• sound.tdf: associazioni dei suoni per categoria di unità (le sezioni [ARM_COM], [ARM_KBOT]). Richiamato da SoundCategory= nell'FBI. Il gioco legge 23 eventi, ciascuno come KEY e poi KEY1, KEY2, … fino al primo numero mancante.
• allsound.tdf: associazioni globali dei suoni dell'interfaccia ([BIGBUTTON], [SKIRMISH], [BGM]).

Esempio svolto — aggiungere una classe di movimento#

Per creare una classe "nave che può guadare acque molto basse":

1. Aggiungi in fondo a 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. Nell'FBI della tua unità:

   MovementClass=AMPHIB3;

   L'ingombro e i limiti della classe sostituiscono quelli dell'FBI, quindi le chiavi FootprintX/FootprintZ/MaxWaterDepth dell'unità non contano più.

3. Impacchetta:

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

Ora l'unità attraverserà senza interruzioni sia la terraferma sia l'acqua.

Dimensioni tipiche#

Insidie#

• Gli slot delle classi di movimento sono fissi. Vengono lette solo le sezioni da [CLASS0] a [CLASS31]; i buchi nella numerazione all'interno di quell'intervallo non sono un problema.
• Nella maggior parte dei file i commenti usano //, non /*…*/, ma weapons.tdf li usa entrambi. I parser di test li tollerano entrambi; alcuni strumenti di terze parti no.
• Le coordinate dell'HUD di sidedata.tdf si riferiscono alla base 640×480 e il motore le scala per le risoluzioni più alte. Non scrivere coordinate in risoluzioni moderne.
• La numerazione di [CANBUILD] non deve avere buchi. Il gioco smette di leggere la lista di un costruttore al primo canbuildN mancante, quindi un canbuild11 seguito da canbuild14 perde la quattordicesima voce e tutte quelle successive, senza alcun errore.
• Una MovementClass che il gioco non trova non è un errore. L'unità usa silenziosamente le proprie chiavi dell'FBI, con i valori predefiniti del gioco per quelle mancanti: un'unità senza MaxWaterDepth guada allora fino a una profondità di 10000.

Vedi anche#

• TDF: la grammatica a livello di parser condivisa con FBI e OTA.
• Audio: i collegamenti di sound.tdf e allsound.tdf.
• FBI: le unità richiamano MovementClass, SoundCategory e i nomi dei TDF delle armi.
• Glossario: classe di movimento (movement class), ingombro (footprint), fazione (side).