# 圖片與動畫素材使用指南（v0.12.0）

遊戲資料夾：`C:\Users\Administrator\Documents\萬能公司團隊\apps\bamboo-odyssey`。

## 開啟與搜尋

1. 雙擊 **shortcuts\工具選單.cmd** 後輸入 **2**，或從遊戲左上角點「圖片與動畫素材庫」。本機網址是 <http://127.0.0.1:8788/editor/media-library.html>。不可直接雙擊 HTML，因為需透過遊戲伺服器讀取、儲存資料。
2. 左側選單可選單張圖片、圖集、影格動畫、人物動作、全部骨架、原始特效參照與缺少來源。搜尋原始檔名、路徑、素材 ID，或原始道具表能配對的名稱。部分道具原名為日文，照原始表保留。
3. 點縮圖，在右側查看來源、尺寸、影格、備註；圖片可用原尺寸、2 倍、4 倍或符合預覽框顯示。下載 PNG 可用 Windows 相片直接開啟。模型動畫下載為通用 GLB；原始 LBI／LSS 仍需對應解析器。
4. 點播放／暫停、拉動進度列逐格查看、調整 FPS、循環及背景。圖集只代表同一檔案含多張圖片，可能是多件道具；不要把所有圖集當成原作動畫。

## 已整理內容與限制

| 類型 | 已整理 | 用途與限制 |
|---|---:|---|
| LBI／LBT、LSI／LST、BMP／TGA 等圖片 | 23,607 份來源、43,667 張 PNG | 保留原尺寸，BGR 及上下方向轉正；洋紅透明色移除，黑色保留。圖集保留原槽位。 |
| IFL 影格清單 | 213 份完整，另 19 份缺圖 | 依原清單順序，重複列保留停留時間。來源未提供 FPS，預設 20，可自行調整。缺圖清單可查詢缺檔名稱，禁止當完整動畫套用。 |
| LSS 骨架 | 586 組、5,559 段 GLB 動作 | 沿用已解出的原骨架；有相同骨架完整模型時一起顯示，否則顯示骨架線。來源原始幀率未知，匯出預覽基準 30 FPS；FPS 改變骨架預覽速度，正式套用則以「完整秒數」為準。 |
| EF 特效控制 | 652 份參照索引 | 查詢原檔及可解析圖片依賴。未還原原引擎的粒子、曲線、網格等控制，不能稱為完整原作特效。 |

原始 `data/`、已備份的模型與既有能力、武器、怪物、商人 CSV 均保留。資料庫中的 Python 程式不會被執行。

## 套用道具圖示

1. 選擇圖片。圖集或影格動畫先暫停並拉到要用的那一格。
2. 在右側「套用到道具圖片」搜尋名稱或 ID，例如 `healing-potion` 是回春露。下拉顯示搜尋結果前 100 件，輸入更完整名稱可找到其他道具。
3. 點「套用目前影格到道具」。出現「已寫入」代表已儲存。
4. 遊戲頁面按 **Ctrl + F5**，重新創角進入，按 **I** 查看背包或 **F** 查看商人商品。兩者使用同一份道具圖示。
5. 想改回來，選取相同道具，再按「恢復原圖」。

此設定替換背包、商店與道具詳情的 2D 圖示。穿在角色身上的 3D 裝備仍由原有裝備模型資料控制。

## 套用遊戲圖片特效

1. 選一份完整 IFL，或確定適合連播的圖集，也可選單張圖。
2. 右側觸發時機選「普通／特殊攻擊」、「E 技能」、「命中怪物」、「生命／能量回復」或「擊殺怪物」。
3. FPS 控制每秒影格數（1～60）；大小是遊戲世界單位（0.1～12）；高度是距地面高度（0～10）。
4. 黑底光效用「發光（去黑底）」；一般圖示與透明圖片用「一般透明」。發光是加色混合，並未刪除原 PNG 中的黑色。
5. 點「套用完整序列到特效」，遊戲 Ctrl + F5 生效。同一觸發位置會換成所選圖片特效，傷害、音效與角色動作邏輯依原設定。

單張圖顯示 0.5 秒，序列播放一次，長度為影格數 ÷ FPS。同一觸發時機的新特效會替換前一個，避免殘影堆疊。過大的圖集會拒絕儲存，請選較小的動畫序列。暫停會凍結播放，重生／重新開始會清除尚未播完的特效。

## 套用人物骨架動作

1. 選「人物動作」，點 `pc_man` 或 `pc_woman`。右側「原始動作」選 `pose_000` 等編號，播放、拖進度、向左右旋轉確認姿勢。
2. 右側「武器類型」可選赤手空拳或全部 34 類武器／盾牌。「動作用途」可選待機、跑步、走路、受傷、死亡、各段普通攻擊、E 技能、定時特殊攻擊、擊殺收尾。
3. 「完整秒數」是這一段動作的播放秒數，越小越快；「起點比例／終點比例」選原始動作的使用範圍，0～1。例如 0.2 到 0.8，表示只取原動作 20%～80% 的範圍。必須起點小於終點。
4. 按「套用所選動作」，遊戲 Ctrl + F5 重新進入，裝備該類武器測試。選男或女的預覽後，設定使用相同動作編號套在各自性別骨架；只有兩組人物骨架都存在的編號能儲存。
5. 「恢復原動作」移除該武器、該用途的覆寫，恢復 `src/combat-settings.js` 中的值。

怪物或神甲的不同骨架可播放與下載；不能直接套在目前的人類主角身上，介面會停用此按鈕。既有攻擊設定中的攻速、打斷重播、額外旋轉及音效仍然有效；如果想完整觀看替換的普攻，需在原攻擊設定把該武器 `playback` 改為 `complete` 或降低攻速，再重新編譯。設定影格不會增加傷害判定次數。

## 設定檔、備份與手動修改

正式檔案為 **assets/game-data/素材套用設定.json**。可在 **shortcuts\工具選單.cmd** 輸入 **28** 用記事本開啟。介面修改會立即寫入此檔，並將修改前的內容存為旁邊的 **素材套用設定.json.previous.json**，只保留前一版。兩個頁面同時儲存時，較舊頁面會提示重新載入，避免覆蓋別頁剛存的內容。

| 區域／欄位 | 使用方式 |
|---|---|
| `version` | 固定為 1。 |
| `icons` | 以道具 ID 當索引。每個值含 `assetId` 與 `frame`。`frame` 是素材內從 0 起算的影格順序，**不是原槽位號碼**；介面會自動轉換。 |
| `effects` | 索引為 `attack`、`skill`、`hit`、`heal`、`kill`。每個值含 `assetId`、`fps`、`scale`、`height`、`blend`。`blend` 填 `normal` 或 `additive`。 |
| `animations` | 第一層為 `unarmed` 或武器類型編號字串；第二層為 `idle`、`run`、`walk`、`hurt`、`death`、`attack1`／`attack2`／`attack3`、`skill`、`special`、`finisher`。每個值含 `assetId`、`poseId`、`duration`、`start`、`end`。武器沒有的第 3 段不能新增。 |

最安全的做法是先在介面套用一次，記事本即可看到有實際素材 ID 的完整範例。清空這三個區域 `{}` 即恢復所有原本顯示。JSON 必須使用雙引號，不能加註解或在最後一個欄位後留逗號；欄位說明集中於本文件。介面另有「匯出套用設定」下載副本。

素材設定的優先權高於 `combat-settings.js` 中的對應動作。只修改 JSON 不需要重新編譯，但需重新載入遊戲；直接修改 JS 則要先雙擊「shortcuts\重新編譯遊戲.cmd」。**重新載入會重新開始本次遊戲**，請在方便的時候再操作。

## 檔案對照與重新整理

| 檔案 | 功能 |
|---|---|
| `assets/media-library/images/` | 全部標準 PNG，每張檔名是穩定素材 ID 加原槽位。 |
| `assets/media-library/thumbs/` | 來源檔案第一格縮圖。 |
| `assets/media-library/catalog.json` | 圖片、IFL、骨架、特效參照完整查詢索引；含原始路徑。 |
| `assets/media-library/images.json` | 圖片來源 SHA-256、解碼結果及各槽位 PNG 清單。 |
| `assets/rigged-models/` | 已有的骨架與完整帶皮膚 GLB。 |
| `src/media-library.js`、`src/media-preview.js` | 素材庫查詢、影格播放、3D 預覽、套用介面。 |
| `src/media-bindings.js`、`src/media-effects.js` | 檢查與套用設定、遊戲精靈圖片特效。 |
| `src/main.js`、`src/world.js`、`src/inventory-panel.js` | 遊戲開場載入、觸發特效、道具來源備註。 |
| `server/media-api.mjs` | 本機儲存、欄位驗證、前版備份與版本衝突檢查。 |
| `analysis/export-media.py` | 原始圖片轉 PNG；需 Python、Pillow、NumPy，只在重解素材時使用。 |
| `analysis/index-media.mjs` | 重新建立含 IFL、GLB 動作與原始道具名稱關聯的索引。 |
| `analysis/validate-media.mjs` | 檢查來源與 PNG、縮圖、GLB 路徑，以及正式套用設定。 |

新增原始資源後，在遊戲資料夾依序執行：

```powershell
& "$env:USERPROFILE\.cache\codex-runtimes\codex-primary-runtime\dependencies\python\python.exe" analysis/export-media.py
node analysis/index-media.mjs
node analysis/validate-media.mjs
```

平常不必重新解圖。遊戲使用已匯出的 PNG 與 GLB；素材庫的「下載原始檔」才需要保留原始資料庫。新增整批素材後重啟伺服器，以重新讀取儲存驗證索引。
