TDF / FBI / OTA — テキスト形式の設定ファイル

TDF（「Text Data File」）、FBI（「Feature/Building/Item」）、OTA（「Online Total Annihilation」）の各ファイルは、どれもINIに似た同じテキスト形式を使っています。Cavedogがバイナリではないものをすべて記述するための標準的な手段で、ユニットのステータス、武器のパラメーター、地形物の定義、ミッションのメタデータ、サウンドのカテゴリ、AIへのヒントなどがこの形式で書かれています。

これらのファイルはプレーンなASCIIなので、どのテキストエディターでも開けます。

# 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"))

構文#

TDFファイルはセクションのツリーです。各セクションは角括弧で囲んだ名前の後に{ ... }の本体が続き、本体にはキー=値のペアや入れ子のセクションが入ります。

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

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

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

規則：

• セクション名は角括弧で囲みます。その後に続く、対応する}までのすべてがそのセクションに属します。セクションを1行に収めることもできます（[special0] { specialwhat=StartPos1; XPos=464; ZPos=216; }）。
• 値は=から次の;までで、改行をまたいで続きます。それ以外に値を終わらせるものはないので、値の中の波括弧、角括弧、=はただの文字として扱われ、値に;を含めることはできません。キーや値の両端にあるスペース、タブ、改行は取り除かれます。同じキーに2回代入すると、最後の値が残ります。
• キーは大文字と小文字を区別しません。UnitName、unitname、UNITNAMEはどれも同じフィールドを指します。ツールは読み込み時に小文字にそろえるのが一般的です。セクション名も大文字と小文字を区別せずに比較されます。
• 値は既定では文字列です。数値はC言語と同じく、先頭の数字から読み取られます。ゲームが整数を求める箇所では、12abcは12、56.8は56として読まれます（killmulやtidalstrengthなどのフィールドは小数として読まれます）。リストはスペース区切りです（例：Category=NOTSUB COMMANDER NOTAIR ...）。
• コメントは、ほかの何よりも先に空白に置き換えられます。対象は行末までの//と、複数行にまたがってもよい/* ... */ブロックです。そのためmissiondescription=See http://tauniverse.com;は//以降が;も含めてすべて失われ、値は次の行まで続いてしまいます。kbotは;、//、/*を含む値の書き込みを拒否します。
• 空白文字と空行は無視されます。

入れ子のセクション（上の例の[UNITINFO]の中の[SOUNDS]など）は、FBIやOTAではよく見られます。TDFの仕様は深さの上限を定めていませんが、実際には3段より深いものは見かけません。

FBI — ユニット定義#

FBIはエンジンから見たユニットのすべてです。ユニットの3Dモデル、スクリプト、武器のリスト、サウンドバンク、建設コスト、戦闘時のふるまいを1か所にまとめています。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;
        ...
    }
}

1998年にコミュニティが書いたFBIガイド（このリポジトリの資料に保存されています）は、100を超えるフィールドを解説しています。ほとんどは名前を見ればわかりますが、わかりにくいのは次のようなものです。

TDF — 地形物・武器・サウンドの定義#

features/**/*.tdfファイルには[FEATURE]セクションが入っており、マップに置く静的なオブジェクト1つにつき1セクションです。TNT形式（TNT）はこれらをセクション名で参照します。

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

weapons/*.tdfも同じパターンで、[WEAPON_NAME]セクションを持ちます。FBIのWeapon1=COMMANDER_WEAPONフィールドは、ゲームのIDで索引付けされた武器テーブルを通じて、weapons/内のいずれかのTDFにある[COMMANDER_WEAPON]セクションに解決されます。各セクションには0〜255のID=が必要で、同じIDを持つ後のセクションは前のセクションを置き換え、名前はその名前を持つ最も小さいスロットに解決されます（Gamedata：武器テーブルを参照）。コミュニティの武器ガイドは約60種類のフィールドを解説しています。中心になるのはballistic/lineofsight/dropped（武器の基本タイプ）、weapontimer、weaponvelocity、areaofeffect、edgeeffectiveness、burst/burstrate、そして[DAMAGE]サブセクション（カテゴリごとのダメージ補正）です。

[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] — 建設メニューの拡張#

download/*.tdfのファイルは、sidedata.tdfを変更せずに、1つ以上の建設ユニットの建設メニューにユニットを登録します。CavedogのCore Contingency拡張パックが自分のユニットを追加するのに使っている仕組みで、ユニット1体だけの.ufoアドオンはどれもこの慣例に従っています。

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

ファイル名の慣例。ファイル名は慣例としてdownload/<UNITNAME>.tdf（最初のエントリのUNITNAME=に合わせる）とします。ただしエンジンはdownload/内のすべての*.tdfを読むので、ファイル名はMOD制作者向けの目印にすぎません。1ファイルにユニット1体が普通です。

複数のエントリ。1つのファイルに複数のエントリを入れられます。Cavedogのdownload/Armfort.tdfは3つのエントリを使って、ARMの防壁をACK、ACV、ACAから建設できるようにしています。TA 3.1cは各ファイルの最初の5セクションを、名前に関係なく読みます（慣例は[MENUENTRY1]ですが、[ENTRY0]でも動きます）。6番目のセクションが読まれることはありません。UNITMENUがどのユニットも指していないエントリや、Builder=1のユニットを指していないエントリは無視されます。UNITNAMEがどのユニットも指していないエントリも同様です。MENUとBUTTONは8ビットに収められ、建設ユニットのメニュー（[CANBUILD]のリストとdownloadによる追加分の合計）に入るのは最大31ユニットです。

これは、50 KBのsidedata.tdfをフォークせずに.ufoを1つだけ配布できるようにする、追加型のMOD用フックです。最初から最後までの使い方はMOD制作チュートリアルを参照してください。

OTA — マップのメタデータ#

.otaはすべての.tntに添えて配布され、エンジンがマップを（地形をレンダリングするのではなく）プレイするのに必要なものをすべて持っています。

[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は対応する.otaを読み、選んだスキーマの各開始位置に番号付きのマーカーを描きます。

ゲームはスキーマと開始位置を次のように読みます。kbotのビュー（スタジオのマップエディター、サンドボックス、アセットエクスプローラー、kbot tnt preview、kbot tnt lint、Quality Checker）も、すべてkbot-ioのOTAゲームビューを通じて同じように読みます。

• スキーマは名前で探されます。Schema 0、Schema 1、…と、最初に欠けた番号の手前まで続きます。名前は大文字と小文字を区別せずに比較されます（[schema 1]も数えられます）が、番号はそのまま書かなければなりません。[Schema0]や[Schema 01]は決して見つからず、番号が飛んだ後のスキーマ（Schema 0、Schema 1、Schema 3）は読まれません。SCHEMACOUNTは無視されます。
• スカーミッシュとマルチプレイのゲームは、位置ではなくTypeと開始位置の数でスキーマを選びます。対象になるのは、Network 1〜Network 4のスキーマ（大文字と小文字を区別せずに比較）のうち、開始位置が1つ以上あるものだけです。N人のプレイヤーなら、ゲームは開始位置がちょうどN個ある対象スキーマのうち最後のものを優先し、なければ開始位置が最も多いものを選びます。キャンペーンのミッションは難易度（Easy、Medium、Hard）で選びます。numplayersはロビーに表示されるテキストにすぎません（2, 4、2-8、Anyのどれでも読み込めます）。
• 開始位置は、specialwhatがStartPosで始まる[specials]のエントリです（大文字と小文字は区別しません）。StartPosNはプレイヤースロットN-1で、StartPos0もスロット0です。StartPosの後に番号のないエントリには、それら専用の通し番号が次々に振られます（最初は1）。XPosとZPosはマップ上のピクセル単位で、16ビットに収められます。
• 欠けたキーにはゼロではなく既定値が使われます。missiondescriptionがなければ「No description available」と表示され、maxunits（キャンペーンのみ）がなければ200になります。配置済みの地形物（[features]）でXPosやZPosがないものは飛ばされるので、列0や行0に置くものには明示的に0を書く必要があります。

実例 — 最小限のユニット#

固定式の砲塔を定義する、完全に動作する「仮の」FBIです。

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

これを完全なユニットのアドオンにするには、次のものを配布します。

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

…あとはディレクトリをHPIアーカイブにまとめます。

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

注意点#

• キーは大文字と小文字を区別しませんが、値は区別します。Side=armはARMのユニット分類ロジックには一致しますが、文字列の等値比較に対してif (Side == "ARM")のように陣営をその場で切り替えるMODは動かなくなります。
• リストの値はスペース区切りです（Category=COMMANDER MOBILE WEAPON）。カンマ区切りではありません。エンジンは任意の空白文字で分割します。
• ただし、カンマを使うOTAフィールドもあります。numplayers=2,4,6,8,10がその例です。リストの区切り文字に統一された慣例はなく、しかもゲームはnumplayersをまったく解析せず、テキストを表示するだけです。
• 入れ子のセクションに正式な深さの上限はありませんが、Cavedogが配布したものは3段より深くなっていません。2段までを前提にしたエディターは、[WEAPON][DAMAGE][category]のような入れ子を持ついくつかの武器TDFで失敗します。
• 真偽値のフィールドは整数です（canmove=1、canstop=0）。true/falseではありません。エンジンが受け付けるのは1/0だけです。
• .otaファイルのミッション説明には、UTF-8の文字化けがよくあります（Wordのスマートクォートなど）。エンジンはWindows-1252のコードページで表示するので、その範囲外の文字はすべて豆腐（□）になります。

典型的なサイズ#

付録A — FBIフィールド辞典#

units/*.fbiでよく見られるフィールドをすべて、用途別にまとめます。型列の凡例：str = 識別子・文字列、int = 整数、float = 浮動小数点数、bool = 0/1、list = 空白文字区切りのトークン、enum = 意味が決まっている小さな整数。

ここにないフィールドは、エディター用の作業値（UnitNumber、Copyright）か、文書化されていないものです。エンジンは未知のキーを黙って無視します。

識別と表示#

経済と建設#

戦闘と耐久#

移動#

感知#

建設メニューとフットプリント#

音声#

その他・よくわかっていないもの#

リファレンスカタログの実例#

フィールドの使い方は、実際のFBIから学ぶのがいちばんです。リファレンスのリポジトリには、収録されている全ユニットがカタログ化されています。

• TA — 全FBI：「充実した」例としては、ARMCOM（Commander=1、CloakCost、MaxDamage=3000を持つコマンダー）、ARMSAM（Weapon1/2/3がすべて埋まった砲塔）、ARMBRAWL（CanFly、crusisealt、BankScaleを持つ航空機）、ARMMEX（ExtractsMetalを持つ金属抽出機）がよいでしょう。
• TA — 全武器TDF：burst/burstrate/firestarterなら[FLAMETHROWER]、2段階の誘導ミサイルなら[NUCLEAR_MISSILE]、ビーム兵器なら[LIGHTNING]。
• TA — 地形物と武器の建設ツリー — インストール内のすべての[MENUENTRY]登録。
• TA: Kingdomsのユニット — フィールドの構成が異なります（資源が1つだけのbuildcost=、damagecategory=、インラインの[WEAPONn]）。ARAKING（Aramonの君主Elsin）とARAARCH（Archer）が入り口としてよいでしょう。

関連項目#

• TNT — [FEATURE]のTDFセクションに解決される地形物名を参照します。
• 3DO、COB — FBIのObjectnameから参照されます。
• GAF — 地形物のseqnameと武器のexplosiongafから参照されます。
• GamedataのTDF — FBIのフィールドから参照されるmoveinfo.tdf、sound.tdf、sidedata.tdf。
• サウンド — SoundCategoryがWAVファイルに解決される仕組み。
• 用語集 — side（陣営）、footprint（フットプリント）、yardmap（ヤードマップ）、schema（スキーマ）。