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

규칙:

• 섹션 이름은 대괄호 안에 씁니다. 그 뒤부터 짝이 맞는 }까지가 모두 그 섹션에 속합니다. 섹션은 한 줄에 쓸 수도 있습니다([special0] { specialwhat=StartPos1; XPos=464; ZPos=216; }).
• 값은 =에서 다음 ;까지 이어지며, 줄바꿈이 있어도 계속됩니다. 다른 어떤 것도 값을 끝내지 않으므로 값 안의 중괄호, 대괄호, 등호(=)는 평범한 텍스트이고, 값에는 ;을 절대 넣을 수 없습니다. 키나 값 양 끝의 공백, 탭, 줄바꿈은 잘려 나갑니다. 같은 키에 값을 두 번 지정하면 마지막 값이 남습니다.
• 키는 대소문자를 구분하지 않습니다. 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 모델, 스크립트, 무기 목록, 사운드 뱅크, 건설 비용, 전투 동작을 한곳에 모읍니다. 줄여 놓은 Arm Commander 예:

[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 가이드(이 저장소의 원자료에 보존되어 있음)는 백 개가 넘는 필드를 문서화하고 있습니다. 대부분은 이름만 봐도 알 수 있고, 그렇지 않은 것은 대개 다음과 같습니다.

TDF — 지형지물, 무기, 사운드 정의#

features/**/*.tdf 파일에는 정적인 맵 소품 하나당 하나씩 [FEATURE] 섹션이 들어 있습니다. 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를 고치지 않고도 건설 유닛 하나 이상의 건설 메뉴에 유닛을 등록합니다. Cavedog의 Core Contingency 확장팩이 자체 유닛을 추가할 때 쓴 방식이며, 유닛 하나짜리 .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를 읽으므로 파일 이름은 순전히 모더를 위한 힌트입니다. 파일 하나에 유닛 하나를 두는 것이 일반적입니다.

여러 항목. 파일 하나에 항목을 여러 개 담을 수 있습니다. Cavedog의 download/Armfort.tdf는 항목 세 개로 Arm Fortification Wall을 ACK, ACV, ACA에서 건설할 수 있게 합니다. TA 3.1c는 각 파일의 처음 다섯 섹션을 이름에 상관없이 읽습니다([MENUENTRY1]이 관례지만 [ENTRY0]도 됩니다). 여섯 번째 섹션은 절대 읽지 않습니다. UNITMENU가 어떤 유닛도 가리키지 않거나 Builder=1인 유닛을 가리키지 않는 항목은 무시되며, UNITNAME이 어떤 유닛도 가리키지 않는 항목도 마찬가지입니다. MENU와 BUTTON은 8비트로 제한되며, 건설 유닛의 메뉴([CANBUILD] 목록과 download 추가분을 합친 것)에는 최대 31개 유닛이 들어갑니다.

이것이 50 KB짜리 sidedata.tdf를 통째로 복사해 고치지 않고도 .ufo 하나만 배포할 수 있게 해 주는, 덧붙이는 방식의 모드 연결 지점입니다. 처음부터 끝까지의 사용법은 모딩 튜토리얼을 참고하세요.

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까지의 스키마(대소문자 무시 비교)만 해당됩니다. 플레이어가 N명이면 게임은 시작 위치가 정확히 N개인 해당 스키마 중 마지막 것을 우선하고, 없으면 시작 위치가 가장 많은 것을 고릅니다. 캠페인 미션은 난이도(Easy, Medium, Hard)로 고릅니다. numplayers는 로비에 표시되는 텍스트일 뿐입니다(2, 4, 2-8, Any 모두 문제없이 로드됩니다).
• 시작 위치는 specialwhat이 StartPos로 시작하는(대소문자 무시) [specials] 항목입니다. StartPosN은 플레이어 슬롯 N-1이고, StartPos0도 슬롯 0이며, StartPos 뒤에 번호가 없는 항목은 그런 항목끼리 따로 매기는 순번에서 다음 번호를 받습니다(첫 번째는 1). XPos와 ZPos는 맵 픽셀 단위이며 16비트로 제한됩니다.
• 빠진 키는 0이 아니라 기본값으로 처리됩니다. missiondescription이 없으면 "No description available"이 표시되고, maxunits(캠페인 전용)가 없으면 200으로 간주되며, XPos나 ZPos가 없는 미리 배치된 지형지물([features])은 건너뛰므로 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")처럼 문자열 일치로 비교해 실행 중에 진영을 바꾸는 모드는 제대로 동작하지 않습니다.
• 목록 값은 쉼표가 아니라 공백으로 구분합니다 (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 글자 깨짐(mojibake)이 흔합니다(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 유닛 — 다른 필드 집합(단일 자원의 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.