Repository navigation
Sprites and Animation zh TW
BIT8_CLI 提供輕量化的 Sprite 與 Animation 系統，用來製作 2D 遊戲角色和動畫。
Sprite 使用 Asset Registry 中已註冊的 Tile，可以定義具名動畫、設定播放速度，並與 Node 關聯。
在 BIT8_CLI 0.1.0 中，每個 Node 都擁有獨立的動畫播放狀態。
因此，多個遊戲物件可以使用相同的 Sprite Definition，同時播放不同的動畫。
Sprite 是遊戲物件可以使用的圖像定義。
例如：
- 玩家角色
- 敵人
- NPC
- 可互動物件
- 動態裝飾
Sprite 可以包含靜態圖像，也可以包含多個動畫影格。
BIT8_CLI 將 Sprite Definition 與個別 Node Instance 分開管理。
因此，多個 Node 可以引用相同的 Sprite，而不需要共用動畫播放進度。
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 表格結構應以對應版本的實作為準。
Sprite Definition 描述可以重複使用的圖像資源。
例如，專案可以定義名為：
Player
的 Sprite。
這個 Sprite 可以包含以下動畫：
idle
walk
attack
每個 Animation 都可以引用已註冊的 Tile。
例如：
Player
│
├── idle
│ └── A1
│
├── walk
│ ├── A2
│ ├── A3
│ └── A4
│
└── attack
├── A5
└── A6
這張圖展示 Sprite、Animation 和 Tile 之間的關係。
它不是實際的 TOML 設定格式。
Animation 由多個 Frame 組成。
每個 Frame 都會引用 Asset 系統中已註冊的圖像素材。
例如：
walk
Frame 1 → A2
Frame 2 → A3
Frame 3 → A4
播放動畫時，Runtime 會根據動畫時間選擇對應的 Frame。
Node 就可以繪製目前選取的 Frame。
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 分開設定。
因此，同一個遊戲可以同時存在快速和緩慢的動畫。
Node 可以使用：
self:sprite("Player")選擇 Sprite。
這會引用名為 Player 的 Sprite Definition。
例如：
func init()
self:sprite("Player")
end使用前必須確保 Sprite Registry 中已經定義 Player。
使用：
self:play("walk")選擇具名 Animation。
例如：
func init()
self:sprite("Player")
self:play("idle")
end這會選擇 Player Sprite，並要求播放 idle 動畫。
Animation 名稱必須存在於所選的 Sprite Definition 中。
使用：
self:spr()繪製 Node 目前的 Sprite Frame。
例如：
func draw()
self:spr()
end繪製時會使用 Node 的 Sprite 狀態與位置。
目前啟用的 Camera 可能影響最終顯示在畫面上的位置。
詳細資訊請閱讀 Camera。
以下範例假設：
- 已定義名為
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() 的實際處理方式。
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 可以有效地重複使用在多個遊戲物件上。
BIT8_CLI 0.1.0 支援在 .b8map 中儲存 Sprite 參照。
Node 可以儲存 Sprite 名稱，例如：
Player
Runtime 會在執行 Node 初始化函式之前，解析已儲存的 Sprite 參照。
因此，Node 可以在遊戲開始時直接使用指定的 Sprite。
Script 仍然可以透過支援的 Runtime API 選擇動畫或更換 Sprite。
VS Code Map Workspace 支援操作與 Sprite 相關的 Node 屬性。
這讓視覺化編輯與 Runtime 行為可以互相配合。
例如，在編輯 Map 時，可以讓 Node 關聯某個 Sprite Definition。
Runtime 載入遊戲時，就會使用儲存在專案中的資料。
Sprite Registry 仍然負責定義 Sprite 的圖像內容與動畫。
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。
BIT8_CLI 0.1.0 提供輕量化的 Sprite 與 Animation 系統。
它不是完整的骨骼動畫或角色 Rigging 系統。
目前已確立的功能主要包含：
- Registered Tile Reference
- 可重複使用的 Sprite Definition
- 具名 Animation
- 可設定的 Animation FPS
- Node 獨立動畫狀態
- Runtime Sprite Rendering
更進階的動畫系統可以在未來版本中繼續探索。
繼續閱讀：
相關文件：
定義一次 Sprite，讓每個 Node 賦予它生命。
Current Version: 0.1.0