Sprites and Animation zh TW - Akiaaaa20/Bit8_CLI GitHub Wiki
Sprite 與 Animation 動畫系統
BIT8_CLI 提供輕量化的 Sprite 與 Animation 系統，用來製作 2D 遊戲角色和動畫。
Sprite 使用 Asset Registry 中已註冊的 Tile，可以定義具名動畫、設定播放速度，並與 Node 關聯。
在 BIT8_CLI 0.1.0 中，每個 Node 都擁有獨立的動畫播放狀態。
因此，多個遊戲物件可以使用相同的 Sprite Definition，同時播放不同的動畫。
1. 什麼是 Sprite？
Sprite 是遊戲物件可以使用的圖像定義。
例如：
- 玩家角色
- 敵人
- NPC
- 可互動物件
- 動態裝飾
Sprite 可以包含靜態圖像，也可以包含多個動畫影格。
BIT8_CLI 將 Sprite Definition 與個別 Node Instance 分開管理。
因此，多個 Node 可以引用相同的 Sprite，而不需要共用動畫播放進度。
2. Sprite Registry
Sprite Definition 儲存在專案中的選用檔案：
bit8.sprites.toml
這個檔案提供 Runtime Sprite 系統所需的定義。
例如：
my-bit8-game/
├── main.b8
├── bit8.assets.toml
├── bit8.sprites.toml
├── world.b8map
└── assets/
└── characters (A).png
Sprite Registry 會與 Asset Registry 搭配使用。
Asset Registry 負責識別已註冊的 Tile。
Sprite Registry 則負責定義這些 Tile 如何組成 Sprite 與 Animation。
實際 TOML 表格結構應以對應版本的實作為準。
3. Sprite Definition
Sprite Definition 描述可以重複使用的圖像資源。
例如，專案可以定義名為：
Player
的 Sprite。
這個 Sprite 可以包含以下動畫：
idle
walk
attack
每個 Animation 都可以引用已註冊的 Tile。
例如：
Player
│
├── idle
│ └── A1
│
├── walk
│ ├── A2
│ ├── A3
│ └── A4
│
└── attack
├── A5
└── A6
這張圖展示 Sprite、Animation 和 Tile 之間的關係。
它不是實際的 TOML 設定格式。
4. Animation Frame
Animation 由多個 Frame 組成。
每個 Frame 都會引用 Asset 系統中已註冊的圖像素材。
例如：
walk
Frame 1 → A2
Frame 2 → A3
Frame 3 → A4
播放動畫時，Runtime 會根據動畫時間選擇對應的 Frame。
Node 就可以繪製目前選取的 Frame。
5. Animation FPS
BIT8_CLI 支援的動畫播放速度為：
1 至 30 FPS
FPS 代表 Frames Per Second，也就是每秒影格數。
例如：
| Animation FPS | 每個 Frame 約持續 |
|---|---|
| 1 FPS | 1 秒 |
| 5 FPS | 0.2 秒 |
| 10 FPS | 0.1 秒 |
| 15 FPS | 0.067 秒 |
| 30 FPS | 0.033 秒 |
BIT8_CLI Runtime 使用固定的：
30 Hz Simulation
動畫播放速度與 Simulation Rate 分開設定。
因此，同一個遊戲可以同時存在快速和緩慢的動畫。
6. 將 Sprite 綁定至 Node
Node 可以使用：
self:sprite("Player")
選擇 Sprite。
這會引用名為 Player 的 Sprite Definition。
例如：
func init()
self:sprite("Player")
end
使用前必須確保 Sprite Registry 中已經定義 Player。
7. 播放 Animation
使用：
self:play("walk")
選擇具名 Animation。
例如：
func init()
self:sprite("Player")
self:play("idle")
end
這會選擇 Player Sprite，並要求播放 idle 動畫。
Animation 名稱必須存在於所選的 Sprite Definition 中。
8. 繪製 Sprite
使用：
self:spr()
繪製 Node 目前的 Sprite Frame。
例如：
func draw()
self:spr()
end
繪製時會使用 Node 的 Sprite 狀態與位置。
目前啟用的 Camera 可能影響最終顯示在畫面上的位置。
詳細資訊請閱讀 Camera。
9. 完整 Node 範例
以下範例假設：
- 已定義名為
Player的 Sprite。 - Sprite 包含
idle和walkAnimation。 - Node 已經關聯這份 Script。
func init()
self:sprite("Player")
self:play("idle")
end
func update()
if btn(LEFT) then
self:move(-1, 0)
self:play("walk")
elseif btn(RIGHT) then
self:move(1, 0)
self:play("walk")
else
self:play("idle")
end
end
func draw()
self:spr()
end
這個範例展示如何結合 Node 移動與動畫選擇。
設計動畫切換時，應確認 Runtime 對重複呼叫 self:play() 的實際處理方式。
10. 獨立 Animation State
BIT8_CLI 的一項重要設計，是讓每個 Node 分別維護動畫播放狀態。
假設有兩個 Node：
Node 1 → Player Sprite → walk
Node 2 → Player Sprite → idle
兩個 Node 都使用相同的 Sprite Definition。
但動畫狀態互相獨立。
例如：
Node 1
Frame: A3
Node 2
Frame: A1
這讓 Sprite Definition 可以有效地重複使用在多個遊戲物件上。
11. 持久化 Sprite 參照
BIT8_CLI 0.1.0 支援在 .b8map 中儲存 Sprite 參照。
Node 可以儲存 Sprite 名稱，例如：
Player
Runtime 會在執行 Node 初始化函式之前，解析已儲存的 Sprite 參照。
因此，Node 可以在遊戲開始時直接使用指定的 Sprite。
Script 仍然可以透過支援的 Runtime API 選擇動畫或更換 Sprite。
12. Sprite 與 Map Workspace
VS Code Map Workspace 支援操作與 Sprite 相關的 Node 屬性。
這讓視覺化編輯與 Runtime 行為可以互相配合。
例如，在編輯 Map 時，可以讓 Node 關聯某個 Sprite Definition。
Runtime 載入遊戲時，就會使用儲存在專案中的資料。
Sprite Registry 仍然負責定義 Sprite 的圖像內容與動畫。
13. Sprite 與 Registered Assets
Sprite 依賴已註冊的圖像素材。
例如：
bit8.assets.toml
│
▼
Registered Tiles
│
▼
bit8.sprites.toml
│
▼
Sprite Definitions
│
▼
Node Animation State
│
▼
Runtime Rendering
這種分離設計帶來幾個優點：
- Tile 可以被多個 Sprite 重複使用。
- Sprite Definition 可以被多個 Node 重複使用。
- 每個 Node 都能擁有獨立的動畫播放狀態。
- Registered Asset ID 提供穩定的圖像資源引用方式。
詳細資訊請閱讀 Asset 與 Tilesheet。
14. 目前限制
BIT8_CLI 0.1.0 提供輕量化的 Sprite 與 Animation 系統。
它不是完整的骨骼動畫或角色 Rigging 系統。
目前已確立的功能主要包含：
- Registered Tile Reference
- 可重複使用的 Sprite Definition
- 具名 Animation
- 可設定的 Animation FPS
- Node 獨立動畫狀態
- Runtime Sprite Rendering
更進階的動畫系統可以在未來版本中繼續探索。
下一步
繼續閱讀：
相關文件：
定義一次 Sprite，讓每個 Node 賦予它生命。