TDFs do gamedata — Tabelas de configuração do motor

Os ficheiros de gamedata/ são ficheiros de texto TDF que configuram o próprio motor: classes de movimento, categorias de dano das armas, dados dos lados (disposição da interface, menus de construção, unidades iniciais), associações de sons e uma mão-cheia de pequenas tabelas de consulta. Os mods que mudam as regras do jogo (em vez de acrescentarem unidades) estão quase sempre aqui.

Esta página documenta os ficheiros de gamedata mais úteis. Todos usam a gramática TDF ao estilo INI; veja TDF para os pormenores ao nível do analisador.

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]

Os ficheiros, em resumo#

Os três grandes, para quem cria mods, são sidedata.tdf (menus de construção, lados), moveinfo.tdf (classes de movimento) e weapons.tdf (que é documentação, não dados; as armas propriamente ditas estão em weapons/*.tdf).

moveinfo.tdf — Classes de movimento#

O FBI de uma unidade declara a sua MovementClass=KBOTSS2 (ou parecida); o motor procura essa classe em moveinfo.tdf para decidir que terreno a unidade consegue atravessar.

O TA 3.1c só lê as secções [CLASS0] a [CLASS31] (a primeira secção com cada um desses nomes) e encontra uma classe pelo seu Name=, sem distinguir maiúsculas de minúsculas, começando pela posição mais baixa. Quando a classe da unidade é resolvida, os valores da classe substituem por completo as chaves FootprintX/FootprintZ, MaxWaterDepth, MinWaterDepth e de declive da própria unidade (o MaxSlope=20 do Comandante dá lugar aos 32 de TANKDS2), e uma chave que a classe omita fica com a predefinição do jogo indicada abaixo, e não com o valor do FBI. Uma unidade sem classe, ou que indique uma que o jogo não encontre, lê as suas próprias chaves do FBI, com as mesmas predefinições. Os metadados de unidades, a sandbox e as partidas alojadas do KBot Studio resolvem o movimento desta forma.

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

Campos#

Convenções de nomes#

O nome da classe codifica a sua forma numa etiqueta curta, segundo a convenção da Cavedog:

Depois vem um sufixo SS / SF / DS / DH / SH (pequeno/profundo/pesado/etc.) e um algarismo com a área ocupada. Os nomes são só uma convenção: o motor trata Name= como uma chave opaca.

sidedata.tdf — Configuração de cada lado#

Este é o ficheiro mais longo de gamedata/, porque junta três assuntos distintos:

1. Declarações dos lados — nome, prefixo, Comandante, tipos de letra, cores.
2. Disposição do HUD — coordenadas em píxeis de cada barra de estado, etiqueta e botão da interface do jogo.
3. Menus de construção — a secção [CANBUILD], que lista o que cada construtor pode construir.

Bloco do lado#

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

O TA 3.1c lê os lados [SIDE0], [SIDE1], … por ordem, e para no primeiro número em falta ou depois do quinto. Uma secção com qualquer outro nome ([SIDE01], um [SIDE3] depois de um [SIDE2] em falta, um sexto lado) nunca é lida, e cada lado lido precisa de todos os retângulos do HUD abaixo (ta.SideRectangles do kbot-io), ou o jogo não carrega lado nenhum. O seletor de lados da sandbox do estúdio oferece os mesmos lados.

Subsecções de coordenadas do HUD#

Cada elemento visível do HUD é um bloco [NAME] com coordenadas em píxeis x1/y1/x2/y2. São relativas à resolução base de 640×480; nos modos superiores, é o motor que faz a escala.

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

Para mudar a barra de energia de sítio, edite os quatro números. Para lhe mudar o aspeto, troque o GAF que o HUD usa para desenhar nessa posição (definido em unitview.tdf).

Menus de construção [CANBUILD]#

A definição estática do menu de construção. Cada construtor lista o que pode construir no início da partida:

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

O número da posição é o lugar na página do menu de construção. O menu de construção do TA é uma grelha de 2 colunas × 3 linhas, por isso cada página tem 6 posições: canbuild1–canbuild6 são a página 1, canbuild7–canbuild12 a página 2, e assim por diante.

Como o TA 3.1c lê a tabela (CanBuildBuilder.BuildList do kbot-io; kbot document, o visualizador de unidades e o menu de construção da sandbox seguem-no):

• Só uma unidade cujo FBI defina Builder=1 recebe uma lista; uma subsecção para qualquer outra unidade é ignorada.
• O jogo lê a primeira secção [CANBUILD] e, dentro dela, a primeira subsecção com o nome do construtor (sem distinguir maiúsculas de minúsculas).
• Lê canbuild1, canbuild2, … e para no primeiro número em falta: canbuild1=ARMSOLAR; canbuild3=ARMLAB; dá uma entrada.
• Um nome que não corresponda a nenhuma unidade é saltado, e uma lista guarda no máximo 30 unidades. As entradas de download (ver abaixo) podem levar o menu de um construtor até 31. (Alguma documentação mais antiga afirmava que havia 12 posições por página; a grelha real do jogo tem 6.) Veja a referência da árvore de construção do TA para a disposição por página de cada construtor do jogo base.

weapons.tdf — Referência dos TDF de armas#

Apesar do nome, gamedata/weapons.tdf é quase só comentários: é a referência publicada pela Cavedog para a gramática dos TDF de armas, e o jogo nunca o carrega. As definições reais das armas estão em weapons/*.tdf, uma secção por arma (veja TDF). kbot document não lista as secções de gamedata/weapons.tdf como armas.

A tabela de armas#

O TA 3.1c constrói uma tabela de 256 posições de armas a partir dos ficheiros .tdf que estão diretamente em weapons/ (não nas subpastas), pela ordem em que os lista:

• Uma secção vai para a posição indicada pelo seu ID=, de 0 a 255. Uma secção sem ID, ou com um fora desse intervalo, é saltada.
• Uma secção posterior com o mesmo ID, no mesmo ficheiro ou num ficheiro posterior, substitui a anterior.
• Weapon1/Weapon2/Weapon3, ExplodeAs e SelfDestructAs de uma unidade indicam uma secção; o nome (sem distinguir maiúsculas de minúsculas) resolve-se na posição mais baixa que tenha uma secção com esse nome.
• Os valores são lidos como prefixos numéricos: weaponacceleration=13O; vale 13, e um valor inválido nunca faz perder o resto do ficheiro.
• Uma estrutura danificada faz o jogo recusar o ficheiro inteiro, pelo que nenhuma das suas armas é carregada, incluindo as secções anteriores ao erro: um cabeçalho de secção sem ] ou sem {, texto sem = ou um valor sem ; antes do fim do ficheiro, o ficheiro a terminar dentro de uma secção, ou um ficheiro vazio. Os outros ficheiros não são afetados. (Uma } solta fora de qualquer secção não leva à recusa: o jogo deixa de ler nesse ponto e fica com o que veio antes.)
• Um range em falta vale 32767; um minbarrelangle em falta vale -11.25 graus; reloadtime conta-se em ticks inteiros (30 por segundo, reloadtime*30 truncado: 0.35 recarrega ao fim de 10 ticks, 0.333 s); turnrate está em unidades de ângulo por segundo (65536 = uma volta completa).

O KBot Studio, os pacotes e kbot host resolvem todos as armas através desta tabela. Os ficheiros que o jogo recusa e as secções que salta ou substitui são assinalados como avisos (kbot pack mostra-os; o estúdio disponibiliza-os em /api/studio/weapons/warnings).

Sprites rendertype=4#

Uma arma rendertype=4 dispara um sprite 2D de anims/fx.gaf, e o seu color= escolhe qual: 0 cannonshell, 1 plasmasm, 2 plasmamd, 3 ultrashell, 4 de novo plasmasm; qualquer outro valor (como o color=255 do EARTHQUAKE) não desenha sprite nenhum. O sprite avança um fotograma por tick do jogo desde o momento do disparo, sejam quais forem as durações dos fotogramas do GAF.

Os comentários de referência documentam:

• Três arquétipos de armas: ballistic, lineofsight, dropped. Todos os TDF de armas têm de pôr um destes a 1.
• Alcance, velocidade, aceleração — em píxeis e píxeis/s.
• Área de efeito — raio em píxeis, com edgeeffectiveness como fração de atenuação (por exemplo, 0.5 = metade do dano na orla).
• Rajada e dispersão — burst, burstrate, sprayangle.
• Armas de duas fases — twophase, weapontype2, flighttime para projéteis ao estilo starburst.
• Tipo de renderização — rendertype=N escolhe modelo 3D, mapa de bits com paleta, feixe, etc.

A subsecção [DAMAGE] é onde ficam os modificadores de dano por categoria de alvo:

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

As chaves de [DAMAGE] são nomes de unidades: uma unidade listada sofre esse dano em vez de default=, e todas as outras sofrem default=. Os valores são guardados em 16 bits. As explosões de morte (ExplodeAs, SelfDestructAs) usam a mesma tabela: CORPYRO_BLAST causa 60 por omissão, mas só 15 a um Pyro.

category.tdf — Descrições das categorias de unidades#

Uma lista simples e cosmética que associa os tokens de categoria a texto legível. O motor mostra-os no painel de informações da unidade:

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

Os traços em vez de descrições são texto-padrão involuntário da Cavedog. A maioria dos mods não mexe neste ficheiro; alguns substituem as descrições por texto de ambientação a sério. Alterá-lo não afeta a jogabilidade.

sound.tdf e allsound.tdf#

Tratados em WAV / Som. Em resumo:

• sound.tdf — associações de sons por categoria de unidade (as secções [ARM_COM], [ARM_KBOT]). Referido no FBI por SoundCategory=. O jogo lê 23 eventos, cada um como KEY e depois KEY1, KEY2, … até ao primeiro número em falta.
• allsound.tdf — associações globais de sons da interface ([BIGBUTTON], [SKIRMISH], [BGM]).

Exemplo comentado — acrescentar uma classe de movimento#

Para criar uma classe de "barco que consegue passar a vau em água muito pouco funda":

1. Acrescente ao fim 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. No FBI da sua unidade:

   MovementClass=AMPHIB3;

   A área ocupada e os limites da classe substituem os do próprio FBI, por isso as chaves FootprintX/FootprintZ/MaxWaterDepth da unidade deixam de contar.

3. Empacote:

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

A unidade passa a atravessar terra e água sem problemas.

Tamanhos típicos#

Armadilhas#

• As posições das classes de movimento são fixas. Só [CLASS0] a [CLASS31] são lidas; os buracos na numeração dentro desse intervalo não fazem mal.
• Os comentários usam //, não /*…*/, na maioria dos ficheiros, mas weapons.tdf usa ambos. Os analisadores de teste toleram ambos; algumas ferramentas de terceiros não.
• As coordenadas do HUD de sidedata.tdf estão na base de 640×480 e o motor aumenta-as nas resoluções mais altas. Não escreva coordenadas em resoluções modernas.
• A numeração de [CANBUILD] não pode ter buracos. O jogo deixa de ler a lista de um construtor no primeiro canbuildN em falta, por isso um canbuild11 seguido de canbuild14 perde a entrada 14 e todas as que vêm depois, sem qualquer erro.
• Uma MovementClass que o jogo não encontra não é um erro. A unidade usa silenciosamente as suas próprias chaves do FBI, com as predefinições do jogo para as que faltam: uma unidade sem MaxWaterDepth passa então a andar pela água até à profundidade 10000.

Ver também#

• TDF — a gramática ao nível do analisador, partilhada com o FBI/OTA.
• Som — a ligação de sound.tdf e allsound.tdf.
• FBI — as unidades referem MovementClass, SoundCategory e nomes de TDF de armas.
• Glossário — classe de movimento, área ocupada, lado.