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

Os arquivos TDF ("Text Data File"), FBI ("Feature/Building/Item") e OTA ("Online Total Annihilation") compartilham o mesmo formato de texto no estilo INI. Eram a forma padrão de a Cavedog declarar tudo o que não fosse binário: atributos de unidades, parâmetros de armas, definições de elementos, metadados de missões, categorias de som, dicas para a IA.

São arquivos em ASCII simples, que podem ser abertos 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 arquivo TDF é uma árvore de seções. Cada seção tem um nome entre colchetes e depois um corpo { ... } com pares chave=valor e/ou seçõ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 de seção ficam entre colchetes; tudo o que vem depois, até o } correspondente, pertence a essa seção. Uma seção pode ocupar uma só linha ([special0] { specialwhat=StartPos1; XPos=464; ZPos=216; }).
• Um valor vai do = até o próximo ;, atravessando quebras de linha: nada mais o encerra, então chaves, colchetes e = dentro de um valor são texto comum, e um valor nunca pode conter ;. Espaços, tabulações e quebras de linha nas pontas 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 diferenciam maiúsculas de minúsculas. UnitName, unitname e UNITNAME se referem ao mesmo campo; as ferramentas costumam normalizar tudo para minúsculas na leitura. Os nomes de seção também são comparados sem diferenciar maiúsculas.
• Os valores são strings por padrã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 espera 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é o fim da linha e blocos /* ... */, que podem ocupar várias linhas. Assim, missiondescription=See http://tauniverse.com; perde tudo a partir de //, inclusive o ;, e o valor continua pela linha seguinte. O kbot se recusa a gravar um valor que contenha ;, // ou /*.
• Espaços em branco e linhas vazias são ignorados.

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

FBI — definições de unidades#

Um FBI é a visão completa que o motor tem de uma unidade. Ele reúne num só lugar o modelo 3D da unidade, o script, a lista de armas, o banco de som, os custos de construção e o comportamento em combate. Um exemplo resumido 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 cem campos. A maioria se explica sozinha; os que não são óbvios costumam ser:

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

Os arquivos features/**/*.tdf contêm seções [FEATURE], uma para cada objeto estático do mapa. O formato TNT (TNT) se refere a elas pelo nome da seçã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 seções [WEAPON_NAME]. O campo Weapon1=COMMANDER_WEAPON do FBI aponta para a seção [COMMANDER_WEAPON] de algum TDF em weapons/, por meio da tabela de armas indexada por ID do jogo: cada seção precisa de um ID= entre 0 e 255, uma seção posterior com o mesmo ID substitui a anterior, e um nome aponta para a posição mais baixa que o contém (veja Gamedata: a tabela de armas). O guia de armas da comunidade documenta cerca de 60 campos diferentes; os mais importantes são ballistic/lineofsight/dropped (o arquétipo da arma), weapontimer, weaponvelocity, areaofeffect, edgeeffectiveness, burst/burstrate e a subseçã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 arquivos em download/*.tdf registram uma unidade nos menus de construção de um ou mais construtores sem modificar o sidedata.tdf. É o mecanismo que a expansão Core Contingency da Cavedog usa para acrescentar suas unidades, e a convenção que todo add-on .ufo de uma só unidade segue.

[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 de nomes do arquivo. Por convenção, o arquivo se chama download/<UNITNAME>.tdf (igual ao UNITNAME= da primeira entrada), mas o motor lê todos os *.tdf de download/, então o nome do arquivo é só uma indicação para o modder. O normal é uma unidade por arquivo.

Várias entradas. Um único arquivo 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 cinco primeiras seções de cada arquivo, quaisquer que sejam os nomes ([MENUENTRY1] é a convenção, mas [ENTRY0] também funciona); uma sexta seção nunca é lida. Uma entrada cujo UNITMENU não nomeia nenhuma unidade, ou nenhuma unidade com Builder=1, é ignorada, assim como uma cujo UNITNAME não nomeia nenhuma unidade. MENU e BUTTON ficam limitados a 8 bits, e o menu de um construtor — sua lista [CANBUILD] mais os acréscimos de download — comporta no máximo 31 unidades.

É esse o gancho aditivo para mods que permite distribuir um único .ufo sem criar uma versão própria do sidedata.tdf de 50 KB. Veja o tutorial de modding para o uso de ponta a ponta.

OTA — metadados do mapa#

O .ota acompanha todo .tnt e traz tudo o que o motor precisa para jogar o mapa (e não para renderizar 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; }
            ...
        }
    }
}

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 visões do kbot — o editor de mapas do studio, a sandbox, o explorador de recursos, kbot tnt preview, kbot tnt lint e o Quality Checker — os leem da mesma forma, pela visão de jogo do OTA no kbot-io):

• Os esquemas são encontrados pelo nome, Schema 0, Schema 1, … até o primeiro número que faltar. Os nomes são comparados sem diferenciar maiúsculas ([schema 1] conta), mas o número precisa estar escrito de forma simples: [Schema0] ou [Schema 01] nunca é encontrado, 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 posição no arquivo. Só se qualificam os esquemas Network 1 a Network 4 (comparados sem diferenciar maiúsculas) com pelo menos uma posição inicial. Para N jogadores, o jogo prefere o último esquema qualificado com exatamente N posições iniciais; se não houver, o que tiver mais. Uma missão da campanha escolhe pela dificuldade (Easy, Medium, Hard). numplayers é só um 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 com StartPos (sem diferenciar maiú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 próximo número de uma contagem própria (o primeiro é 1). XPos e ZPos são pixels do mapa, limitados a 16 bits.
• Chaves ausentes têm valores padrão, não zeros: sem missiondescription, aparece "No description available"; sem maxunits (só nas campanhas), vale 200; e um elemento pré-posicionado ([features]) sem XPos ou ZPos é ignorado, então um elemento na coluna ou na linha 0 precisa de um 0 explícito.

Exemplo comentado: unidade mínima#

Um FBI "de mentira" 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 transformar isso num add-on completo de unidade, você 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 diferenciam maiúsculas; os valores, sim. Side=arm funciona com a lógica de classificação de unidades do ARM, mas mods que trocam de lado em tempo real com if (Side == "ARM") em comparações exatas de strings vão quebrar.
• Os valores de lista são separados por espaços (Category=COMMANDER MOBILE WEAPON), não por vírgulas. O motor divide em qualquer espaço em branco.
• Alguns campos do OTA usam vírgulas, porém: numplayers=2,4,6,8,10. Não existe uma convenção única de delimitador de listas, e o jogo nunca analisa numplayers: só mostra o texto.
• As seções aninhadas não têm limite formal de profundidade, mas a Cavedog nunca distribuiu nada com mais de 3 níveis. Editores que supõem 2 níveis falham em alguns TDFs de armas com aninhamento no estilo [WEAPON][DAMAGE][category].
• Os campos booleanos são inteiros (canmove=1, canstop=0), não true/false. O motor só aceita 1/0.
• Os arquivos .ota costumam ter mojibake de UTF-8 nas descrições das missões (aspas curvas do Word etc.). O motor os renderiza com a página de código Windows-1252 e mostra como tofu (quadradinhos) tudo o que estiver fora dela.

Tamanhos típicos#

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

Todos os campos encontrados com frequência em units/*.fbi, agrupados por finalidade. Legenda da coluna Tipo: str = identificador/string; int = inteiro; float = ponto flutuante; bool = 0/1; list = tokens separados por espaços em branco; enum = inteiro pequeno com significados documentados.

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

Identidade e exibição#

Economia e construção#

Combate e resistência#

Movimento#

Sentidos#

Menu de construção e área ocupada#

Áudio#

Diversos / pouco compreendidos#

Exemplos reais no catálogo de referência#

O uso dos campos se aprende melhor com FBIs reais. Os repositórios de referência catalogam todas as unidades que vêm com os jogos:

• 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 registros [MENUENTRY] da instalação.
• Unidades do TA: Kingdoms — o conjunto diferente de campos (buildcost= com um só recurso, damagecategory=, [WEAPONn] embutido). ARAKING (o monarca Elsin, de Aramon) e ARAARCH (Archer) são bons pontos de partida.

Veja também#

• TNT — referencia nomes de elementos que apontam para seções [FEATURE] de TDF.
• 3DO, COB — referenciados pelo Objectname do FBI.
• GAF — referenciado pelo seqname dos elementos e pelo explosiongaf das armas.
• TDFs do gamedata — moveinfo.tdf, sound.tdf, sidedata.tdf, referenciados por campos do FBI.
• Som — como SoundCategory aponta para arquivos WAV.
• Glossário — lado, área ocupada, yardmap, esquema.