Desperate City Armory — 武器系統模組使用教學

⚠️ !!注意!! 在使用前需要先初始化武器

在遊戲開始時（通常是「初始化」事件），必須先執行 InitGameData 動作，否則所有武器功能都不會正常運作。

事件：初始化
  動作：InitGameData
    ├── 武器資料別名：datas_weaponType（預設）
    ├── 殭屍資料別名：datas_zombieType（預設）
    └── 除錯日誌：false（正式版請關閉）

目錄

1. 模組架構
2. 初始化設定
3. 新增武器到地圖
4. 讓角色裝備武器
5. 自訂武器處理器（Actions）
6. weapon_utils 工具函式
7. datas_gameConfig 武器資料設定
8. 新增武器的完整流程
9. 注意事項與常見問題

模組架構

datas/
  ├── datas_gameConfig.ts           ← 武器資料定義（FarWeaponData）與 WeaponTypeData 管理器
  └── weapon/
        ├── weapon_utils.ts         ← 共用工具函式（registerWeapon、actorCustomGAF 等）
        ├── InitGameData.action.ts  ← 【必須】初始化動作，負責事件監聽與切換偵測
        ├── WeaponActions.action.ts ← WeaponSpawn（生成武器到地上）
        ├── WeaponEquip.action.ts   ← WeaponEquip（讓角色裝備武器）
        └── weapons/
              ├── Demo_actions.ts         ← 新增武器用的模板
              ├── Barret_actions.ts
              ├── AA12_actions.ts
              ├── M249_actions.ts
              ├── P90_actions.ts
              ├── MP5_actions.ts
              ├── SCAR_actions.ts
              ├── M200_actions.ts
              ├── Revolver_actions.ts
              ├── Gating_actions.ts
              ├── GrenadeGun_actions.ts
              ├── Crossbow_actions.ts
              ├── SR16_actions.ts
              ├── ElectricGun_actions.ts
              ├── AUG_actions.ts
              └── CombatShotgun_actions.ts

初始化設定

⚠️ 使用前必須先執行 InitGameData，否則所有武器功能不會正常運作！

InitGameData 會執行以下工作： - 載入所有武器資料（WeaponTypeData） - 建立自訂彈匣（initMagazines） - 註冊所有武器處理器（Handler） - 掛上 ACTOR_PICKUP_STUFF、ACTOR_DROP_STUFF、ACTOR_FIRE 事件監聽 - 啟動輪詢（每 100ms）偵測武器切換與裝填

動作參數說明：

新增武器到地圖

使用 WeaponSpawn 動作將武器放到地圖上。

動作參數說明：

支援的武器種類：

讓角色裝備武器

使用 WeaponEquip 動作讓角色直接持有武器（不需要從地上撿起）。

動作參數說明：

自訂武器處理器

每把有 GAF 動畫或自訂音效的武器，需要一個對應的 _actions.ts 檔案。複製 Demo_actions.ts 作為起點。

const myHandler: WeaponHandler = {
    stuffCode: 'cusfar_myWeapon',  // 對應 WEAPON_DATAS 的 stuff 欄位

    onPickup(actor, game, manager) {
        // 撿起武器：隱藏引擎動畫、設旗標、播 GAF
        setActorDisplayVisible(actor, 'rightHand', false);
        setActorDisplayVisible(actor, 'leftHand', false);
        setWeaponAlpha(actor, 0);
        setGlobal(manager, `${actor.code}_hold_myWeapon`, 1);
        actorCustomGAF({ ..., linkage: 'Idle', stop: true });
    },

    onFire(actor, game, manager) {
        // 開槍：播射擊動畫 + 音效
        actorCustomGAF({ ..., linkage: 'Shoot' });
        mapSoundEffect(game, actor, 'Desperate_City.myWeapon_music', 1.0);
    },

    onReload(actor, game, manager) {
        // 裝填：播裝填動畫
        actorCustomGAF({ ..., linkage: 'Reload' });
    },

    onUnequip(actor, game, manager) {
        // 卸除：移除 GAF、清旗標、恢復引擎動畫
        actorCustomGAF({ actorCode: actor.code, actorCustomGAFCode: gafCode(actor), add: 'remove' });
        setGlobal(manager, `${actor.code}_hold_myWeapon`, 0);
        setActorDisplayVisible(actor, 'rightHand', true);
        setActorDisplayVisible(actor, 'leftHand', true);
        setWeaponAlpha(actor, 100);
    },
};

export function registerMyWeapon(): void {
    registerWeapon(myHandler);
}

新增武器的完整流程

1. 複製 Demo_actions.ts，改名為 MyWeapon_actions.ts
2. 修改三個常數：STUFF_CODE、GAF_ALIAS、HOLD_SUFFIX
3. 調整各 handler 的 linkage、fps、音效等細節
4. InitGameData.action.ts 加上 import 和 registerMyWeapon() 呼叫
5. datas_gameConfig.ts 的 WEAPON_DATAS 加上武器設定

注意事項與常見問題

Q：武器沒有子彈特效？

確認 SpawnedFarWeapon 沒有 override createBulletsData 方法，必須使用引擎原始邏輯。

Q：onPickup 沒有觸發？

確認 stuffCode 能被 _resolveStuffCode 正確對應，系統嘗試順序： 1. 直接查 handler（如 cusfar_barret） 2. 去掉 cusfar_ 前綴（如 SCAR、p90） 3. 去掉 homemade_ 前綴（如 m249）

Q：切換武器時 GAF 沒更新？

系統每 100ms 輪詢 _currentWeapon，偵測切換時觸發 onUnequip（舊）+ onPickup（新）。初次撿起由 ACTOR_PICKUP_STUFF 事件負責。

Q：引擎手持動畫沒有隱藏？

確認 datas_gameConfig 裡該武器設定 hasCustomAnim: true。

Q：clip 設什麼？

• 使用 TwilightWarsLib.actors → 填 lib_rifle、lib_handgun、lib_shotgun 等
• 使用自訂資源 → 填該資源內的 linkage 名稱（如 mp5_clip、barret_clip）

Q：weaponCode 需要手動填？

大多數情況不需要，系統自動從 stuff 推算。以下需手動填： - gating：weaponCode: 'gating_gun' - m249：weaponCode: 'homemade_m249'

Authors

Autumn