ユニットのMODを最初から最後まで作る

この手順では、標準のTotal Annihilationのインストールから始めて、ARMのフラッシュ戦車の新しい派生型を1つ追加する小さなMODを作ります。速度を2倍にした見た目違いのユニットです。最後には、ゲームフォルダーに置くだけで読み込まれる、配布可能な.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, ...

フォルダーの構成はVFSの構造と同じです。実行時にアーカイブがどう重なるかはHPIを参照してください。

---

2. MODの作業用ディレクトリを作る#

TAのMOD制作は追加方式です。既存のアーカイブの隣に.ufoを置くと、そのファイルがベースゲームのファイルより優先されます。MODは、同じ構成を写したツリーの中で作ります。

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

---

3. 元にするユニットを選ぶ#

MYFLASHは、既存のARMのフラッシュを元にします。4つのファイルをコピーします。

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

なぜこの4つなのでしょうか。どのユニットにも次のファイルが必要だからです。

ファイル名は慣習としてFBIのObjectnameを小文字にしたもので、.fbi自体は大文字になっていることもあります。エンジンはどこでも大文字と小文字を区別しません。

---

4. FBIをつなぎ直す#

mymod/units/myflash.fbiを開きます。必ず変更しなければならないフィールドは、UnitName（参照用のキー）とObjectname（ファイル名の基になる参照）の2つです。

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

次に、変更が効いていることを確かめるために、ステータスを1つ引き上げます。速度を2倍にしましょう。

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

フィールドの一覧はFBIの付録を参照してください。設定していない項目は、エンジンの既定値を受け継ぎます。

---

5. ユニットを建設メニューに登録する#

存在していても、どの建設ユニットからもたどり着けないユニットは建設できません。新しいユニットに建設スロットを追加する正しい方法は、MODに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の建設メニューは1ページが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の防壁。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を、上級建設Kボット、上級建設車両、上級建設航空機から建設できるようになります。建設ユニット1つにつきエントリが1つです。

MENUとBUTTONの値の選び方#

標準のTAは、最初の2つのメニューページ（MENU=1、MENU=2）をベースゲームのユニット用に確保しています。コミュニティの慣習では、Cavedogが同梱するものと衝突しないように、ダウンロードで追加するユニットはMENU=3（またはそれ以降）に置きます。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を直接編集しません。Web 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、そして最初の10個の.hpiだけをマウントします。どのグループもASCIIの大文字に揃えた名前の順で、各ファイルはそれを含む最初のアーカイブから読まれます（HPIの読み込み順を参照）。.ufoは必ずマウントされ、どの.hpiよりも上位になります。.hpiのMODは、製品版のインストールがすでに埋めている10個の*.hpiの枠を奪い合うことになります。rev31.gp3や.ccxにも含まれているファイル（たとえばunits/ARMCOM.FBIやgamedata/sidedata.tdf）は、それでもそれらのアーカイブから読まれます。そうしたファイルを上書きしたい場合は、インストール先のルートに単体のファイルとして置いて配布してください。スタジオの「Export mod…」ダイアログでは、ダウンロードする前に、ワークスペースのそうしたファイルが一覧表示されます。

.ufoを、TAのインストール先のルートのtotala1.hpiと同じ場所に置きます。

cp myflash.ufo "$TA/"

TAを起動します。スカーミッシュを開始してARMの車両工場を建設すると、建設メニューにSuper Flashが表示されるはずです。通常のフラッシュの2倍の速さです。

---

トラブルシューティング#

---

次のステップ#

• 新しい武器を追加する：weapons/から.tdfをコピーして編集し、FBIのWeapon1=から参照します。weapons.tdfのリファレンスを参照してください。
• 新しい移動クラスを追加する：moveinfo.tdfに追記します。Gamedataを参照してください。
• 独自のマップを作る：.sctのセクションから.tntを組み立てます（またはkbot tnt packでTNTを直接手作りします）。TNTを参照してください。
• 新しいサウンドを追加する：WAVをsounds/に置き、gamedata/sound.tdfで結び付けます。サウンドを参照してください。
• AIを調整する：新しいユニットのためのWeight/Limitのルールをai/default.txtに追加します。AIを参照してください。
• 既存のMODを調べる：kbot hpi listとkbot hpi extractは、他人が作った.ufoにも使えます。ほかの人がどのようにアーカイブを作ったかを調べるのが、MOD制作の慣習を身に付ける一番の近道です。

---

関連項目#

• HPI：アーカイブへのまとめ方の詳細。
• FBI / TDF：ユニット定義の言語と、フィールドの完全な辞典。
• COB / BOS：スクリプト言語。
• 3DO：メッシュの形式。
• Gamedata：sidedata.tdf、moveinfo.tdf、weapons.tdfのリファレンス。
• 用語集：用語のリファレンス。