TDF / FBI / OTA — ficheiros de configuração em texto

Os ficheiros TDF ("Text Data File"), FBI ("Feature/Building/Item") e OTA ("Online Total Annihilation") partilham todos o mesmo formato de texto ao estilo INI. São a forma canónica como a Cavedog declarava tudo o que não era binário: atributos das unidades, parâmetros das armas, definições de elementos do mapa, metadados das missões, categorias de som, indicações para a IA.

Estes ficheiros são ASCII simples: pode abri-los em qualquer editor de texto.

# The web UI renders FBI/TDF/OTA as collapsible section trees
kbot mount ~/games/totala --server
# → browse to units/ARMCOM.FBI

import "github.com/coreprime/kbot/formats/tdf"

doc, _ := tdf.ParseFile("units/ARMCOM.FBI")
info := doc.Section("UNITINFO")
fmt.Println(info.String("UnitName"), info.Int("MaxDamage"))

Sintaxe#

Um ficheiro TDF é uma árvore de secções. Cada secção tem um nome entre parênteses retos, seguido de um corpo { ... } com pares chave=valor e/ou secções aninhadas.

[UNITINFO]
{
    UnitName=ARMCOM;
    Designation=Commander;
    Description=Commander, Arm;
    Side=ARM;
    Objectname=armcom;

    BuildCostEnergy=2500;
    BuildCostMetal=2500;
    MaxDamage=3000;

    [SOUNDS]
    {
        canselect=cmdsel1;
        select1=cmdok1;
    }
}

Regras:

• Os nomes das secções ficam entre parênteses retos; tudo o que vem a seguir, até à } correspondente, pertence a essa secção. Uma secção pode ocupar uma só linha ([special0] { specialwhat=StartPos1; XPos=464; ZPos=216; }).
• Um valor vai do = até ao ; seguinte, mesmo atravessando quebras de linha: nada mais o termina, por isso chavetas, parênteses retos e = dentro de um valor são texto simples, e um valor nunca pode conter um ;. Os espaços, as tabulações e as quebras de linha nas extremidades de uma chave ou de um valor são removidos. Uma chave atribuída duas vezes fica com o último valor.
• As chaves não distinguem maiúsculas de minúsculas. UnitName, unitname e UNITNAME referem-se todas ao mesmo campo, e as ferramentas costumam normalizá-las para minúsculas na leitura. Os nomes das secções também são comparados sem distinguir maiúsculas de minúsculas.
• Os valores são cadeias de caracteres por omissão. Os números são lidos à maneira do C, a partir dos dígitos iniciais: 12abc é lido como 12 e 56.8 como 56 quando o jogo quer um número inteiro (campos como killmul e tidalstrength são lidos como frações). As listas são separadas por espaços (por exemplo, Category=NOTSUB COMMANDER NOTAIR ...).
• Os comentários são apagados antes de qualquer outra leitura: // até ao fim da linha, e blocos /* ... */, que podem ocupar várias linhas. Assim, missiondescription=See http://tauniverse.com; perde tudo a partir de //, incluindo o seu ;, e o valor continua pela linha seguinte. O kbot recusa-se a escrever um valor que contenha ;, // ou /*.
• Os espaços em branco e as linhas vazias são ignorados.

As secções aninhadas (como [SOUNDS] dentro de [UNITINFO], acima) são comuns nos FBI e OTA. A especificação do TDF não fixa uma profundidade máxima; na prática, não verá mais de 3 níveis.

FBI — definições de unidades#

Um FBI é a visão completa que o motor tem de uma unidade. Junta num só sítio o modelo 3D da unidade, o script, a lista de armas, o banco de sons, os custos de construção e o comportamento em combate. Um exemplo abreviado do Comandante ARM:

[UNITINFO]
{
    // === Identification ===
    UnitName=ARMCOM;          // Internal lookup key
    Objectname=armcom;        // → objects3d/armcom.3do, scripts/armcom.cob
    Side=ARM;                 // ARM or CORE
    Designation=Commander;    // Mouseover label
    Description=Commander, Arm;

    // === Economy & build ===
    BuildCostMetal=2500;
    BuildCostEnergy=2500;
    BuildTime=89400;          // Build-power × seconds (engine units)
    WorkerTime=300;           // How fast it builds other things

    // === Combat ===
    MaxDamage=3000;           // Hit points
    Weapon1=COMMANDER_WEAPON; // → weapons/commander_weapon.tdf [COMMANDER_WEAPON]
    Weapon2=disintegrator;    // The dreaded D-gun
    candgun=1;                // Allowed to fire weapon2 on demand

    // === Movement ===
    MaxVelocity=1.15;
    Acceleration=0.075;
    BrakeRate=0.0825;
    TurnRate=510;
    MovementClass=COMMANDER_TANK3;  // → gamedata/movinfo.tdf

    // === Senses ===
    SightDistance=520;
    RadarDistance=585;

    // === Tags & categories ===
    Category=COMMANDER SURFACE MOBILE WEAPON ...;
    NoChaseCategory=AIR;

    [SOUNDS] {
        canselect=cmdsel1;
        select1=cmdok1;
        ...
    }
}

O guia de FBI da comunidade, de 1998 (preservado nos materiais de origem deste repositório), documenta mais de uma centena de campos. A maioria explica-se por si; os menos óbvios costumam ser estes:

TDF — definições de elementos, armas e sons#

Os ficheiros features/**/*.tdf contêm secções [FEATURE], uma por cada objeto estático do mapa. O formato TNT (TNT) refere-as pelo nome da secção:

[ArmTree01]
{
    description=Arm Tree;
    category=trees;
    object=arm_tree01;       // → objects3d/arm_tree01.3do
    footprintx=1;
    footprintz=1;
    height=20;
    blocking=1;              // Pathing obstacle
    flamable=1;
    burnmin=10;
    burnmax=20;
    burntime=30;
    feature_reclamate=ArmTree01_Heap; // Recursive: what's left when reclaimed
    damage=15;
    reclaimable=1;
    energy=0;
    metal=2;
    seqname=arm_tree01;      // GAF sequence to draw (for animated features)
}

Os weapons/*.tdf seguem o mesmo padrão, com secções [WEAPON_NAME]. O campo Weapon1=COMMANDER_WEAPON do FBI resolve-se na secção [COMMANDER_WEAPON] de um dos TDF de weapons/, através da tabela de armas do jogo, indexada por ID: cada secção precisa de um ID= em 0–255, uma secção posterior com o mesmo ID substitui a anterior, e um nome resolve-se na posição mais baixa que o contenha (veja Gamedata: a tabela de armas). O guia de armas da comunidade documenta cerca de 60 campos distintos; os que mais pesam são ballistic/lineofsight/dropped (o arquétipo da arma), weapontimer, weaponvelocity, areaofeffect, edgeeffectiveness, burst/burstrate e a subsecção [DAMAGE] (modificadores de dano por categoria).

[FLAMETHROWER] {
    ID=1;
    name=Flame Thrower;
    rendertype=5;
    ballistic=1;
    turret=1;
    range=160;
    reloadtime=1.2;
    weapontimer=1;
    weaponvelocity=188;
    areaofeffect=32;
    burst=17;
    burstrate=.04;
    [DAMAGE] {
        default=10;
        corpyro=2;          // Pyros are nearly fireproof
    }
}

[MENUENTRY] — extensão do menu de construção#

Os ficheiros download/*.tdf registam uma unidade nos menus de construção de um ou mais construtores sem alterar o sidedata.tdf. É o mecanismo que a expansão Core Contingency da Cavedog usa para acrescentar as suas unidades, e a convenção que todos os complementos .ufo de uma só unidade seguem.

[MENUENTRY1]
{
    UNITMENU=ARMVP;       // Builder's UnitName
    MENU=3;               // Menu page (row)
    BUTTON=4;             // Slot within the page
    UNITNAME=MYFLASH;     // Unit being placed
}

[MENUENTRY2]              // Additional builders for the same unit
{
    UNITMENU=ARMACV;
    MENU=3;
    BUTTON=4;
    UNITNAME=MYFLASH;
}

Convenção para o nome do ficheiro. Por convenção, o ficheiro chama-se download/<UNITNAME>.tdf (igual ao UNITNAME= da primeira entrada), mas o motor lê todos os *.tdf de download/, por isso o nome do ficheiro é apenas uma indicação para o modder. O normal é haver uma unidade por ficheiro.

Várias entradas. Um só ficheiro pode ter várias entradas: o download/Armfort.tdf da Cavedog usa três para que a Muralha de Fortificação ARM possa ser construída pelo ACK, pelo ACV e pelo ACA. O TA 3.1c lê as primeiras cinco secções de cada ficheiro, sejam quais forem os seus nomes ([MENUENTRY1] é a convenção, mas [ENTRY0] também funciona); uma sexta secção nunca é lida. Uma entrada cujo UNITMENU não nomeie nenhuma unidade, ou nenhuma unidade com Builder=1, é ignorada, tal como uma cujo UNITNAME não nomeie nenhuma unidade. MENU e BUTTON ficam limitados a 8 bits, e o menu de um construtor (a sua lista [CANBUILD] mais o que download/ acrescenta) tem no máximo 31 unidades.

É este o ponto de extensão aditivo que permite distribuir um único .ufo sem criar uma cópia divergente do sidedata.tdf de 50 KB. Veja o tutorial de modding para um exemplo de uso do princípio ao fim.

OTA — metadados do mapa#

O .ota acompanha cada .tnt e contém tudo aquilo de que o motor precisa para jogar o mapa (por oposição a renderizar o seu terreno):

[GlobalHeader]
{
    missionname=Metal Heck;
    missiondescription=A small, brutal metal map.;
    planet=metal;
    tidalstrength=0;
    solarstrength=20;
    lavaworld=0;
    killmul=50;
    waterdoesdamage=0;
    minwindspeed=100;
    maxwindspeed=2500;
    gravity=112;
    numplayers=2,4,6,8,10;

    [Schema 0] {
        Type=Network 1;
        aiprofile=DEFAULT;
        SurfaceMetal=10;
        MohoMetal=125;
        HumanMetal=1000;
        ComputerMetal=1000;
        HumanEnergy=1000;
        ComputerEnergy=1000;
        [specials] {
            [special0] { specialwhat=StartPos1; XPos=464; ZPos=216; }
            [special1] { specialwhat=StartPos2; XPos=3408; ZPos=216; }
            ...
        }
    }
}

O kbot tnt preview lê o .ota correspondente e desenha marcadores numerados em cada posição inicial do esquema escolhido.

Como o jogo lê os esquemas e as posições iniciais (todas as vistas do kbot — o editor de mapas do studio, a sandbox, o explorador de recursos, o kbot tnt preview, o kbot tnt lint e o Quality Checker — leem-nos da mesma maneira, através da vista de jogo OTA do kbot-io):

• Os esquemas são encontrados pelo nome, Schema 0, Schema 1, … até ao primeiro número em falta. Os nomes são comparados sem distinguir maiúsculas de minúsculas ([schema 1] conta), mas o número tem de estar escrito de forma simples: [Schema0] ou [Schema 01] nunca são encontrados, e um esquema depois de uma lacuna (Schema 0, Schema 1, Schema 3) nunca é lido. SCHEMACOUNT é ignorado.
• As partidas de escaramuça e multijogador escolhem um esquema pelo Type e pelo número de posições iniciais, não pela ordem. Só contam os esquemas Network 1 a Network 4 (comparados sem distinguir maiúsculas de minúsculas) com pelo menos uma posição inicial. Para N jogadores, o jogo prefere o último desses esquemas com exatamente N posições iniciais e, se não houver, o que tiver mais. Uma missão da campanha escolhe pela dificuldade (Easy, Medium, Hard). numplayers é só texto mostrado no lobby (2, 4, 2-8 e Any carregam todos).
• As posições iniciais são as entradas de [specials] cujo specialwhat começa por StartPos (sem distinguir maiúsculas de minúsculas). StartPosN é o lugar de jogador N-1, StartPos0 também é o lugar 0, e uma entrada sem número depois de StartPos recebe o número seguinte de uma contagem própria (o primeiro é 1). XPos e ZPos são píxeis do mapa, limitados a 16 bits.
• As chaves em falta têm valores predefinidos, não zeros: um missiondescription em falta mostra "No description available", um maxunits em falta (só nas campanhas) significa 200, e um elemento pré-colocado ([features]) sem XPos ou ZPos é ignorado, por isso um que esteja na coluna ou na linha 0 precisa de um 0 explícito.

Exemplo comentado — unidade mínima#

Um FBI "falso", completo e funcional, para uma torre fixa:

[UNITINFO]
{
    UnitName=MYTURRET;
    Objectname=myturret;
    Side=ARM;
    Designation=Test Turret;
    Description=Bare-minimum turret for format testing.

    BuildCostMetal=200;
    BuildCostEnergy=400;
    BuildTime=2400;
    MaxDamage=600;

    Category=NOTSUB SURFACE WEAPON NOTAIR;
    TEDClass=LASER;
    Builder=0;
    canattack=1;
    onoffable=0;
    ActivateWhenBuilt=1;

    Weapon1=LIGHTLASER;

    FootprintX=2;
    FootprintZ=2;
    YardMap=cccc;
    MaxSlope=15;
    MaxWaterDepth=0;
    SightDistance=300;

    Corpse=MyTurret_Dead;

    [SOUNDS] {
        select1=corselect1;
        ok1=corok1;
    }
}

Para fazer disto um complemento de unidade completo, distribuiria:

mymod/
├── units/myturret.fbi
├── objects3d/myturret.3do
├── scripts/MYTURRET.cob
├── features/corpses/myturret.tdf       # contains [MyTurret_Dead]
└── unitpics/MYTURRET.PCX

…e depois empacotaria a pasta em HPI:

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

Armadilhas#

• As chaves não distinguem maiúsculas de minúsculas, os valores sim. Side=arm corresponde à lógica de classificação de unidades do ARM, mas os mods que trocam de lado em tempo real com if (Side == "ARM"), por comparação exata de cadeias, vão falhar.
• Os valores de lista são separados por espaços (Category=COMMANDER MOBILE WEAPON), e não por vírgulas. O motor divide-os em qualquer espaço em branco.
• Alguns campos do OTA usam vírgulas, no entanto: numplayers=2,4,6,8,10. Não há uma convenção única para o delimitador das listas, e o jogo nem sequer analisa numplayers: limita-se a mostrar o texto.
• As secções aninhadas não têm um limite formal de profundidade, mas a Cavedog nunca distribuiu nada com mais de 3 níveis. Os editores que contam com 2 níveis vão falhar em alguns TDF de armas com aninhamentos do tipo [WEAPON][DAMAGE][category].
• Os campos booleanos são inteiros (canmove=1, canstop=0), e não true/false. O motor só aceita 1/0.
• Os ficheiros .ota têm muitas vezes mojibake de UTF-8 nas descrições das missões (aspas curvas do Word, etc.). O motor apresenta-os com a página de código Windows-1252 e mostra como quadrados vazios (tofu) tudo o que estiver fora dela.

Tamanhos típicos#

Apêndice A — dicionário de campos FBI#

Todos os campos que aparecem habitualmente em units/*.fbi, agrupados por finalidade. Legenda da coluna Tipo: str = identificador/cadeia de caracteres; int = inteiro; float = vírgula flutuante; bool = 0/1; list = tokens separados por espaços em branco; enum = inteiro pequeno com significados documentados.

Os campos que não estão aqui ou são rascunho do editor (UnitNumber, Copyright) ou não estão documentados. O motor ignora silenciosamente as chaves desconhecidas.

Identidade e apresentação#

Economia e construção#

Combate e sobrevivência#

Movimento#

Sentidos#

Menu de construção e área ocupada#

Áudio#

Diversos / mal compreendidos#

Exemplos reais no catálogo de referência#

A melhor forma de aprender a usar os campos é com FBI reais. Os repositórios de referência catalogam todas as unidades distribuídas:

• TA — todos os FBI: bons exemplos "ricos" são ARMCOM (comandante com Commander=1, CloakCost, MaxDamage=3000), ARMSAM (torre com Weapon1/2/3 preenchidos), ARMBRAWL (aeronave com CanFly, crusisealt, BankScale) e ARMMEX (extrator de metal com ExtractsMetal).
• TA — todos os TDF de armas: [FLAMETHROWER] para burst/burstrate/firestarter, [NUCLEAR_MISSILE] para mísseis guiados em duas fases, [LIGHTNING] para uma arma de feixe.
• TA — árvore de construção de elementos e armas — todos os registos [MENUENTRY] da instalação.
• Unidades do TA: Kingdoms — o conjunto de campos diferente (buildcost= com um só recurso, damagecategory=, [WEAPONn] em linha). ARAKING (Elsin, o monarca de Aramon) e ARAARCH (Archer) são bons pontos de partida.

Ver também#

• TNT — refere nomes de elementos que se resolvem em secções TDF [FEATURE].
• 3DO, COB — referidos pelo Objectname do FBI.
• GAF — referido pelo seqname dos elementos e pelo explosiongaf das armas.
• TDFs do gamedata — moveinfo.tdf, sound.tdf, sidedata.tdf, referidos por campos do FBI.
• Som — como o SoundCategory se resolve em ficheiros WAV.
• Glossário — side, footprint, yardmap, schema.