gamedata TDF — 엔진 설정 테이블

gamedata/의 파일들은 엔진 자체를 설정하는 TDF 텍스트 파일입니다: 이동 클래스, 무기 피해 분류, 진영 데이터(UI 레이아웃, 건설 메뉴, 시작 유닛), 사운드 바인딩, 그리고 작은 조회 테이블 몇 개. (유닛을 추가하는 것이 아니라) 게임의 규칙을 바꾸는 모드는 거의 언제나 여기를 고칩니다.

이 페이지는 가장 쓸모 있는 gamedata 파일들을 설명합니다. 모두 INI 모양의 TDF 문법을 쓰며, 파서 수준의 세부 사항은 TDF를 참고하세요.

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]

파일 한눈에 보기#

모딩에서 중요한 세 가지는 sidedata.tdf(건설 메뉴, 진영), moveinfo.tdf(이동 클래스), weapons.tdf(데이터가 아니라 문서입니다 — 실제 무기는 weapons/*.tdf에 있음)입니다.

moveinfo.tdf — 이동 클래스#

유닛의 FBI는 MovementClass=KBOTSS2(또는 비슷한 값)를 선언하고, 엔진은 moveinfo.tdf에서 그 클래스를 찾아 유닛이 어떤 지형을 지나갈 수 있는지 정합니다.

TA 3.1c는 [CLASS0]부터 [CLASS31]까지의 섹션(각 이름마다 첫 번째 섹션)만 읽고, 클래스를 Name=으로 대소문자 구분 없이, 가장 낮은 슬롯부터 찾습니다. 유닛의 클래스가 연결되면 클래스의 값이 유닛 자체의 FootprintX/FootprintZ, MaxWaterDepth, MinWaterDepth, 경사 키를 완전히 대체합니다 — 커맨더의 MaxSlope=20은 TANKDS2의 32에 자리를 내줍니다 — 그리고 클래스에 없는 키는 FBI의 값이 아니라 아래에 있는 게임의 기본값을 받습니다. 클래스가 없거나, 게임이 찾을 수 없는 클래스를 지정한 유닛은 같은 기본값과 함께 자기 FBI 키를 읽습니다. KBot Studio의 유닛 메타, 샌드박스, 호스팅 대전도 이 방식으로 이동을 결정합니다.

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

필드#

이름 붙이기 관례#

클래스 이름은 짧은 태그로 형태를 나타냅니다 — Cavedog의 관례:

그 뒤에 접미사 SS / SF / DS / DH / SH(small/deep/heavy 등)와 풋프린트 숫자가 붙습니다. 이름 붙이기는 관례일 뿐입니다 — 엔진은 Name=을 의미 없는 키로 취급합니다.

sidedata.tdf — 진영별 설정#

gamedata/에서 가장 긴 파일입니다. 서로 다른 세 가지 관심사를 묶고 있기 때문입니다.

1. 진영 선언 — 이름, 접두사, 커맨더, 글꼴, 색상.
2. HUD 레이아웃 — 게임 안 UI의 모든 상태 막대, 레이블, 버튼의 픽셀 좌표.
3. 건설 메뉴 — 각 건설 유닛이 무엇을 건설할 수 있는지 나열하는 [CANBUILD] 섹션.

진영 블록#

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

TA 3.1c는 진영 [SIDE0], [SIDE1], …을 순서대로 읽으며, 처음으로 빠진 번호에서, 그리고 다섯 개를 읽은 뒤 멈춥니다. 그 밖의 이름을 가진 섹션([SIDE01], 빠진 [SIDE2] 뒤의 [SIDE3], 여섯 번째 진영)은 절대 읽지 않으며, 읽는 각 진영에는 아래의 HUD 사각형(kbot-io의 ta.SideRectangles)이 모두 있어야 합니다. 하나라도 빠지면 게임은 진영을 하나도 로드하지 않습니다. 스튜디오의 샌드박스 진영 선택기도 같은 진영들을 제공합니다.

HUD 좌표 하위 섹션#

보이는 HUD 요소는 모두 x1/y1/x2/y2 픽셀 좌표를 가진 [NAME] 블록입니다. 이 좌표는 기준 해상도 640×480에 대한 것이며, 더 높은 해상도에서는 엔진이 배율을 조정합니다.

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

에너지 막대의 위치를 바꾸려면 네 숫자를 고치세요. 모양을 바꾸려면 HUD가 그 위치에 그릴 때 쓰는 GAF(unitview.tdf에서 설정)를 바꾸세요.

[CANBUILD] 건설 메뉴#

정적인 건설 메뉴 정의입니다. 각 건설 유닛이 게임 시작 시 건설할 수 있는 것을 나열합니다.

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

슬롯 번호는 건설 메뉴 페이지에서의 위치입니다. TA의 건설 메뉴는 2열 × 3행 격자이므로 페이지마다 슬롯이 6개입니다: canbuild1–canbuild6이 1페이지, canbuild7–canbuild12가 2페이지, 이런 식입니다.

TA 3.1c가 이 테이블을 읽는 방식(kbot-io의 CanBuildBuilder.BuildList. kbot document, 유닛 뷰어, 샌드박스 건설 메뉴도 이를 따름):

• FBI에 **Builder=1**이 설정된 유닛만 목록을 받습니다. 그 밖의 유닛에 대한 하위 섹션은 무시됩니다.
• 게임은 첫 번째 [CANBUILD] 섹션을 읽고, 그 안에서 건설 유닛의 이름을 딴 첫 번째 하위 섹션을 (대소문자 무시하고) 읽습니다.
• canbuild1, canbuild2, …을 읽다가 처음으로 빠진 번호에서 멈춥니다: canbuild1=ARMSOLAR; canbuild3=ARMLAB;이면 항목은 하나입니다.
• 어떤 유닛과도 맞지 않는 이름은 건너뛰며, 목록에는 최대 30개 유닛이 들어갑니다. download 항목(아래 참고)으로 건설 유닛의 메뉴를 31개까지 늘릴 수 있습니다. (예전 문서에는 페이지당 슬롯이 12개라고 적은 경우가 가끔 있었지만, 실제 게임 안 격자는 6칸입니다.) 기본 게임의 모든 건설 유닛에 대한 페이지별 배치는 TA 건설 트리 레퍼런스를 참고하세요.

weapons.tdf — 무기 TDF 참고 문서#

이름과 달리 gamedata/weapons.tdf는 대부분 주석입니다 — 무기 TDF 문법에 대해 Cavedog이 공개한 참고 문서이며, 게임은 이 파일을 로드하지 않습니다. 실제 무기 정의는 무기 하나당 섹션 하나씩 weapons/*.tdf에 있습니다(TDF 참고). kbot document는 gamedata/weapons.tdf의 섹션을 무기로 나열하지 않습니다.

무기 테이블#

TA 3.1c는 weapons/ 바로 아래(하위 디렉터리는 제외)의 .tdf 파일들을 목록에 나오는 순서대로 읽어 무기 슬롯 256개짜리 테이블을 만듭니다.

• 섹션은 ID=가 지정하는 슬롯(0–255)에 들어갑니다. ID가 없거나 그 범위를 벗어난 섹션은 건너뜁니다.
• 같은 ID를 가진 나중 섹션은 — 같은 파일이든 나중 파일이든 — 앞의 것을 대체합니다.
• 유닛의 Weapon1/Weapon2/Weapon3, ExplodeAs, SelfDestructAs는 섹션 이름을 지정합니다. 그 이름은 (대소문자 무시하고) 그 이름의 섹션을 가진 가장 낮은 슬롯으로 연결됩니다.
• 값은 앞쪽 숫자로 읽습니다: weaponacceleration=13O;의 값은 13이며, 잘못된 값 때문에 파일의 나머지가 버려지는 일은 없습니다.
• 구조가 깨져 있으면 게임은 파일 전체를 거부하므로, 결함 앞의 섹션까지 포함해 그 파일의 무기는 하나도 로드되지 않습니다: 닫는 대괄호(])나 여는 중괄호({)가 없는 섹션 헤더, 파일 끝 전에 등호(=)가 없는 텍스트나 세미콜론(;)이 없는 값, 섹션 안에서 끝나는 파일, 빈 파일. 다른 파일은 영향을 받지 않습니다. (섹션 밖에 홀로 있는 닫는 중괄호(})는 거부되지 않습니다: 게임은 거기서 읽기를 멈추고 그 앞의 내용은 유지합니다.)
• range가 없으면 32767, minbarrelangle이 없으면 -11.25도입니다. reloadtime은 정수 틱 단위로 셉니다(초당 30, reloadtime*30의 소수점 버림: 0.35는 10틱, 즉 0.333초 뒤에 재장전). turnrate는 초당 각도 단위입니다(65536 = 한 바퀴).

KBot Studio, 팩, kbot host는 모두 이 테이블을 통해 무기를 결정합니다. 게임이 거부하는 파일과 건너뛰거나 대체하는 섹션은 경고로 보고됩니다(kbot pack이 출력하고, 스튜디오는 /api/studio/weapons/warnings에서 제공합니다).

rendertype=4 스프라이트#

rendertype=4 무기는 anims/fx.gaf의 2D 스프라이트를 날리며, color=가 어느 스프라이트인지 고릅니다: 0 cannonshell, 1 plasmasm, 2 plasmamd, 3 ultrashell, 4 다시 plasmasm. 그 밖의 값(EARTHQUAKE의 color=255 등)이면 스프라이트를 그리지 않습니다. 스프라이트는 GAF 프레임에 어떤 길이가 적혀 있든 발사 순간부터 게임 틱마다 한 프레임씩 넘어갑니다.

참고 문서의 주석이 설명하는 내용:

• 세 가지 무기 기본 유형: ballistic, lineofsight, dropped. 모든 무기 TDF는 이 중 하나를 1로 설정해야 합니다.
• 사거리, 속도, 가속도 — 픽셀과 픽셀/초 단위.
• 효과 범위 — 픽셀 반경이며, edgeeffectiveness는 감쇠 비율입니다(예: 0.5 = 가장자리에서 피해 절반).
• 연사와 산탄 — burst, burstrate, sprayangle.
• 2단계 무기 — 스타버스트 방식 투사체를 위한 twophase, weapontype2, flighttime.
• 렌더 유형 — rendertype=N이 3D 모델, 팔레트 비트맵, 빔 등을 고릅니다.

대상 분류별 피해 보정치는 [DAMAGE] 하위 섹션에 있습니다.

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

[DAMAGE]의 키는 유닛 이름입니다: 목록에 있는 유닛은 default= 대신 그 피해를 받고, 그 밖의 모든 유닛은 default=를 받습니다. 값은 16비트로 유지됩니다. 사망 폭발(ExplodeAs, SelfDestructAs)도 같은 테이블을 씁니다 — CORPYRO_BLAST는 기본 60의 피해를 주지만 Pyro에게는 15를 줍니다.

category.tdf — 유닛 분류 설명#

분류 토큰을 사람이 읽을 수 있는 텍스트에 대응시키는, 표시용 평면 목록입니다. 엔진은 이를 유닛 정보 패널에 표시합니다.

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

설명 대신 들어간 대시는 의도하지 않은 Cavedog의 상투적인 자리 채움입니다. 대부분의 모드는 이 파일을 그대로 두며, 일부는 설명을 제대로 된 분위기 문구로 바꿉니다. 바꿔도 게임 플레이에는 영향이 없습니다.

sound.tdf와 allsound.tdf#

WAV / 사운드에서 다룹니다. 요약하면:

• sound.tdf — 유닛 분류별 사운드 바인딩([ARM_COM], [ARM_KBOT] 섹션). FBI의 SoundCategory=가 참조합니다. 게임은 이벤트 23개를 읽는데, 각각 KEY, 이어서 KEY1, KEY2, …을 처음으로 빠진 번호 직전까지 읽습니다.
• allsound.tdf — 전역 UI 사운드 바인딩([BIGBUTTON], [SKIRMISH], [BGM]).

실제 예제 — 이동 클래스 추가하기#

"아주 얕은 물을 건널 수 있는 배" 클래스를 만들려면:

1. 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. 유닛의 FBI에:

   MovementClass=AMPHIB3;

   클래스의 풋프린트와 제한이 FBI 자체의 것을 대체하므로, 유닛의 FootprintX/FootprintZ/MaxWaterDepth 키는 더 이상 의미가 없습니다.

3. 패키징합니다.

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

이제 유닛이 땅과 물을 매끄럽게 오갑니다.

일반적인 크기#

주의할 점#

• 이동 클래스 슬롯은 고정되어 있습니다. [CLASS0]부터 [CLASS31]까지만 읽으며, 그 범위 안에서 번호가 비는 것은 괜찮습니다.
• 대부분의 파일에서 주석은 /*…*/가 아니라 //를 씁니다 — 하지만 weapons.tdf는 둘 다 씁니다. 테스트 파서는 둘 다 허용하지만, 일부 서드파티 도구는 그렇지 않습니다.
• sidedata.tdf의 HUD 좌표는 640×480 기준이며, 더 높은 해상도에서는 엔진이 배율을 키웁니다. 현대 해상도 기준으로 좌표를 쓰지 마세요.
• [CANBUILD] 번호에는 빈 곳이 없어야 합니다. 게임은 건설 유닛의 목록을 처음으로 빠진 canbuildN에서 그만 읽으므로, canbuild11 다음에 canbuild14가 오면 14번째 항목과 그 뒤의 모든 항목이 오류 없이 사라집니다.
• 게임이 찾을 수 없는 MovementClass는 오류가 아닙니다. 유닛은 아무 말 없이 자기 FBI 키를 쓰고, 빠진 키에는 게임의 기본값을 씁니다 — 그래서 MaxWaterDepth가 없는 유닛은 수심 10000까지 헤치고 들어갑니다.

함께 보기#

• TDF — FBI/OTA와 공유하는 파서 수준의 문법.
• 사운드 — sound.tdf와 allsound.tdf의 연결 구조.
• FBI — 유닛은 MovementClass, SoundCategory, 무기 TDF 이름을 참조합니다.
• 용어집 — movement class, footprint, side.