유닛 모딩, 처음부터 끝까지

이 안내에서는 아무것도 고치지 않은 Total Annihilation 설치본에서 출발해 Arm Flash 탱크의 새 변형 하나(속도가 두 배인 리스킨)를 추가하는 작은 모드를 만듭니다. 끝나면 게임 폴더에 넣기만 하면 로드되는 배포용 .ufo 아카이브가 생기고, kbot이 지원하는 모든 형식이 어떻게 맞물리는지도 실제로 감을 잡게 됩니다.

전체 과정은 약 20분이 걸리며 HPI, FBI, COB, 3DO, PCX, TDF, sidedata.tdf를 모두 다뤄 봅니다.

---

0. 준비물#

• $TA에 있는 완전한 TA 설치본(GoG, Steam, 또는 원본 CD).
• kbot 설치:

  go install github.com/coreprime/kbot/cmd/kbot@latest
  kbot ctx add "$TA" --alias ta --game totala

• 평탄화한 작업용 사본을 둘 디스크 공간(약 120 MB).

---

1. 설치본 평탄화#

파일을 하나씩 편집하게 되므로, 아카이브를 한 번 평탄화해 두면 일반 도구로 읽을 수 있습니다.

kbot mount "$TA" flatten --target ./ta-flat

결과를 살펴보세요.

ls ta-flat/                # ai/  anims/  features/ ... weapons/
ls ta-flat/units/ | head   # ARMCOM.FBI, ARMFLASH.FBI, ...

폴더 구조는 가상 파일 시스템의 모양과 같습니다 — 실행 중에 아카이브가 어떻게 계층화되는지는 HPI를 참고하세요.

---

2. 모드 작업용 디렉터리 만들기#

TA 모딩은 추가형입니다. 기존 아카이브 옆에 .ufo를 두면 그 안의 파일이 기본 게임보다 우선합니다. 게임과 같은 디렉터리 구조를 본뜬 트리에서 모드를 만드세요.

mkdir -p mymod/{units,scripts,objects3d,unitpics,download}

---

3. 바탕으로 삼을 유닛 고르기#

MYFLASH는 기존 Arm Flash를 바탕으로 만듭니다. 파일 네 개를 복사하세요.

cp ta-flat/units/armflash.fbi      mymod/units/myflash.fbi
cp ta-flat/scripts/ARMFLASH.cob    mymod/scripts/MYFLASH.cob
cp ta-flat/objects3d/armflash.3do  mymod/objects3d/myflash.3do
cp ta-flat/unitpics/armflash.pcx   mymod/unitpics/myflash.pcx

왜 이 네 개일까요? 모든 유닛에는 다음이 필요합니다.

파일 이름은 관례상 FBI의 Objectname을 소문자로 쓴 것이며, .fbi 자체는 가끔 대문자로 씁니다. 엔진은 어디서나 대소문자를 구분하지 않습니다.

---

4. FBI 연결 고치기#

mymod/units/myflash.fbi를 여세요. 반드시 바꿔야 할 필드는 UnitName(조회 키)과 Objectname(파일 이름의 기준)입니다.

[UNITINFO]
{
    UnitName=MYFLASH;             // ← was ARMFLASH
    Objectname=myflash;           // ← was armflash
    Side=ARM;
    Designation=ARM-MV;
    Name=Super Flash;             // ← display name
    Description=Twice-as-fast Flash variant;
    ...
}

그다음 변경이 실제로 적용되는지 확인할 수 있게 능력치 하나를 크게 올려 봅니다. 속도를 두 배로 해 보겠습니다.

    MaxVelocity=4.0;              // was 2.0
    Acceleration=0.30;            // was 0.15

전체 필드 목록은 FBI 부록을 참고하세요. 설정하지 않은 값은 엔진 기본값을 따릅니다.

---

5. 건설 메뉴에 유닛 등록하기#

유닛이 존재하더라도 어떤 건설 유닛의 메뉴에도 없으면 건설할 수 없습니다. 새 유닛의 건설 슬롯을 추가하는 올바른 방법은 모드에 download/<UNITNAME>.tdf 파일을 넣는 것입니다 — Cavedog의 Core Contingency 확장팩도 새 유닛을 이렇게 배포했고, 흔히 볼 수 있는 유닛 하나짜리 .ufo 애드온(AFark.ufo, AFlea.ufo, CorNecro.ufo 등)도 모두 같은 관례를 따릅니다.

mymod/download/MYFLASH.tdf를 만드세요.

[MENUENTRY1]
{
    UNITMENU=ARMVP;       // The builder this unit appears under
    MENU=3;               // Build-menu page number (1-indexed)
    BUTTON=4;             // Slot within that page (0–5 in a 2×3 grid;
                          // 4 = bottom-left)
    UNITNAME=MYFLASH;     // The unit being placed (matches your FBI's UnitName)
}

TA의 건설 메뉴는 페이지마다 2열 × 3행 격자이므로, BUTTON 값 0–5는 다음과 같이 배치됩니다.

┌─────┬─────┐
│  0  │  1  │   page N, top row
├─────┼─────┤
│  2  │  3  │   page N, middle row
├─────┼─────┤
│  4  │  5  │   page N, bottom row
└─────┴─────┘

대상 건설 유닛의 기존 배치에서 빈 슬롯을 고르세요 — 기본 게임의 모든 건설 유닛에 대한 페이지별 전체 배치는 TA 건설 트리 레퍼런스를 참고하세요.

엔진은 시작할 때 모든 download/*.tdf를 읽고 각 [MENUENTRY<N>]을 파싱한 뒤, 그 항목들을 sidedata.tdf가 선언한 건설 메뉴에 합칩니다. sidedata.tdf를 고칠 필요가 없습니다.

sidedata.tdf를 고치는 것보다 나은 이유#

이것은 Cavedog이 공식으로 마련해 둔 확장 지점입니다. 유닛 하나짜리 애드온이 sidedata.tdf를 복사해 고치지 않아도 되도록 바로 그 목적으로 만들어졌습니다.

여러 건설 유닛에서 건설하기#

여러 건설 유닛에서 유닛을 건설할 수 있게 하려면 [MENUENTRY<N>] 섹션을 더 추가하기만 하면 됩니다. Cavedog의 download/Armfort.tdf(Arm Fortification Wall, ccdata.ccx에 들어 있음)가 바로 그렇게 합니다.

[MENUENTRY1] { UNITMENU=ARMACK; MENU=3; BUTTON=4; UNITNAME=ARMFORT; }
[MENUENTRY2] { UNITMENU=ARMACV; MENU=3; BUTTON=4; UNITNAME=ARMFORT; }
[MENUENTRY3] { UNITMENU=ARMACA; MENU=3; BUTTON=4; UNITNAME=ARMFORT; }

— 이렇게 하면 ARMFORT를 Advanced Construction Kbot, Vehicle, Aircraft에서 모두 건설할 수 있습니다. 건설 유닛마다 항목 하나입니다.

MENU와 BUTTON 값 고르기#

원래 TA는 처음 두 메뉴 페이지(MENU=1, MENU=2)를 기본 게임 유닛용으로 예약합니다. 커뮤니티 관례는 다운로드 유닛을 MENU=3(또는 그 이상)에 두어 Cavedog이 배포하는 어떤 것과도 겹치지 않게 하는 것입니다. BUTTON은 그 페이지 안의 슬롯입니다.

확신이 서지 않으면 같은 건설 유닛에 추가하는 기존 download/*.tdf의 값을 복사하세요. 동작하는 참고 자료로 Cavedog의 Armfort.tdf, Armmark.tdf, Cormort.tdf 등을 추출해 보세요.

kbot hpi extract /path/to/ccdata.ccx "*.tdf" -t /tmp/cc-downloads
ls /tmp/cc-downloads/download/

필드 레퍼런스는 TDF: [MENUENTRY]를 참고하세요.

---

6. COB 다시 컴파일하기(선택)#

MYFLASH.cob는 ARMFLASH.cob의 사본이므로 그대로도 동작합니다. 애니메이션을 조정하고 싶다면 디컴파일하고, 편집한 다음, 다시 컴파일하세요.

# Decompile to readable BOS
kbot cob decompile mymod/scripts/MYFLASH.cob -t mymod/scripts/MYFLASH.bos

# Edit MYFLASH.bos in any text editor
# (See cob.md for the BOS language reference.)

# Compile back to bytecode
kbot cob compile  mymod/scripts/MYFLASH.bos -t mymod/scripts/MYFLASH.cob

# Lint for common issues
kbot cob lint     mymod/scripts/MYFLASH.cob

디컴파일→컴파일 왕복 변환은 Cavedog의 모든 정식판 스크립트에서 바이트 단위로 동일합니다 — kbot cob roundtrip이 게임 전체 목록에 대해 이를 검증합니다.

---

7. (선택) 초상화 다시 그리기#

unitpics/myflash.pcx는 96×96 팔레트 PCX입니다. 8비트 PCX를 다룰 수 있는 아무 이미지 편집기(GIMP, Aseprite, Krita)에서나 TA 팔레트를 유지한 채 편집하세요. 팔레트가 그대로 남아 있는지는 다음과 같이 확인합니다.

kbot pcx describe mymod/unitpics/myflash.pcx
# Expected: BitsPerPixel: 8, embedded palette present

팔레트가 망가졌다면 저장하기 전에 표준 TA 팔레트(palettes/palette.pal)를 다시 가져오세요. 0x0C 표식과 BytesPerLine 패딩에 관한 주의할 점은 PCX를 참고하세요.

---

8. (선택) 3D 모델 외형 바꾸기#

objects3d/myflash.3do는 정점, 프리미티브, 텍스처 참조로 이루어진 계층형 메시입니다. 오래되긴 했지만 Cavedog의 에디터(3DO Builder)가 여전히 가장 실용적인 3DO 에디터입니다. kbot은 .3do를 직접 편집하지 않으며, 웹 UI는 살펴보기용으로만 렌더링합니다.

kbot mount $(kbot ctx path) --server
# → browse to objects3d/myflash.3do for the piece tree and textures

도구를 만들고 있다면 디스크상 구조는 3DO를 참고하세요.

---

9. .ufo로 패킹하기#

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

kbot은 기본적으로 LZ77 청크 압축을 쓰며, 표준 Cavedog 헤더 키와 게임이 요구하는 Cavedog 저작권 트레일러를 붙입니다 — 즉 엔진이 아무 불평 없이 받아들입니다. 확인해 보세요.

kbot hpi info  myflash.ufo
# Should show ~5–8 files, marker 0x49504148 (HAPI), decrypt key 0xBF,
# and "TA 3.1c would mount: yes". A "no" names the reason (for example
# a missing Cavedog trailer), and the game would silently skip the file.

kbot hpi list  myflash.ufo -v
# units/myflash.fbi, scripts/MYFLASH.cob, objects3d/myflash.3do, ...

---

10. 설치하고 테스트하기#

왜 .ufo일까요? TA 3.1c는 rev31.gp3, 그다음 모든 .ccx와 모든 .ufo, 그리고 처음 열 개의 .hpi만 마운트하며, 각 묶음 안에서는 이름을 ASCII 대문자로 바꾼 순서를 따릅니다. 각 파일은 그 파일이 들어 있는 첫 아카이브에서 읽습니다(HPI 로드 순서 참고). .ufo는 항상 마운트되며 모든 .hpi보다 순위가 높습니다. .hpi 모드는 정식판 설치본이 이미 채운 열 개의 *.hpi 자리를 놓고 경쟁해야 합니다. rev31.gp3나 .ccx에도 들어 있는 파일(예: units/ARMCOM.FBI나 gamedata/sidedata.tdf)은 여전히 그 아카이브에서 읽히므로, 그런 재정의 파일은 설치 폴더 루트에 낱개 파일로 배포하세요. 스튜디오의 Export mod… 대화 상자는 다운로드하기 전에 워크스페이스에 있는 그런 파일을 목록으로 보여 줍니다.

.ufo를 TA 설치 폴더 루트의 totala1.hpi 옆에 넣으세요.

cp myflash.ufo "$TA/"

TA를 실행하세요. 스커미시를 시작해 Arm Vehicle Plant를 지으면, 건설 메뉴에 Super Flash가 나타날 것입니다 — 일반 Flash보다 두 배 빠릅니다.

---

문제 해결#

---

다음 단계#

• 새 무기 추가 — weapons/에서 .tdf를 복사해 편집하고, FBI의 Weapon1=에서 참조하세요. weapons.tdf 레퍼런스를 참고하세요.
• 새 이동 클래스 추가 — moveinfo.tdf에 덧붙이세요. Gamedata를 참고하세요.
• 커스텀 맵 만들기 — .sct 섹션을 이어 붙여 .tnt를 만드세요(또는 kbot tnt pack으로 TNT를 직접 손으로 만드세요). TNT를 참고하세요.
• 새 사운드 추가 — sounds/에 WAV를 넣고 gamedata/sound.tdf에서 연결하세요. 사운드를 참고하세요.
• AI 조정 — 새 유닛을 위해 ai/default.txt에 Weight/Limit 규칙을 추가하세요. AI를 참고하세요.
• 기존 모드 살펴보기 — kbot hpi list와 kbot hpi extract는 서드파티 .ufo에도 동작합니다. 다른 사람들이 아카이브를 어떻게 만들었는지 살펴보는 것이 모딩 관례를 몸에 익히는 가장 빠른 방법입니다.

---

함께 보기#

• HPI — 아카이브 패킹의 세부 사항.
• FBI / TDF — 전체 필드 사전이 있는 유닛 정의 언어.
• COB / BOS — 스크립트 언어.
• 3DO — 메시 형식.
• Gamedata — sidedata.tdf, moveinfo.tdf, weapons.tdf 레퍼런스.
• 용어집 — 용어 레퍼런스.