Nodes zh TW - Akiaaaa20/Bit8_CLI GitHub Wiki
Node 節點系統
Node 是 BIT8_CLI 最重要的核心組件之一。
Node 代表遊戲世界中的物件，可以儲存屬性、執行腳本、進行碰撞判定，以及顯示 Sprite。
在 BIT8_CLI 0.1.0 中，Node 定義於 Map 系統內，並由 Runtime 負責執行。
Main assembles the game. Nodes live the game.
Main 負責組裝遊戲，Node 負責在遊戲世界中運作。
1. 什麼是 Node？
Node 是存在於遊戲世界中的物件。
例如：
- 玩家角色
- 敵人
- NPC
- 可互動物件
- 移動平台
- 具有行為的裝飾物件
每個 Node 都可以擁有自己的位置、屬性和行為。
與單純的 Tile 不同，Node 可以執行腳本，並保留 Runtime 狀態。
2. Node 與 Map
Node 儲存在 Map 資料中。
BIT8_CLI 使用 .b8map 格式儲存 Map。
Map 可以包含：
- Tile 資料
- Node
- Camera
Node 與 Tile Grid 是不同的概念。
因此，Node 可以不受單一 Map Cell 限制，自由移動。
例如，即使 Map 使用 8×8 像素的 Tile，角色仍然可以每次移動 1 像素。
詳細資訊請閱讀 Map。
3. Node 屬性
每個 Node 都會向腳本提供以下屬性。
| 屬性 | 說明 |
|---|---|
self.id |
穩定的 Node 識別碼 |
self.name |
Node 名稱 |
self.x |
世界座標 X |
self.y |
世界座標 Y |
self.enabled |
Node 是否啟用 |
例如：
func update()
self.x = self.x + 1
end
這段程式會在每次更新時增加 Node 的水平位置。
Node 位置使用世界像素座標。
4. Node Script
Node 可以引用使用 BIT8_CLI Lua 腳本語言編寫的 Script。
Script 使用 .b8 副檔名。
例如：
player.b8
Node Script 可以定義生命週期函式：
func init()
end
func update()
end
func draw()
end
這些函式分別負責初始化、更新行為和繪製圖像。
Runtime 會在遊戲生命週期中執行 Node Script。
5. self 物件
在 Node Script 中，self 代表目前的 Node。
透過 self，可以存取 Node 的屬性與支援的方法。
例如：
func init()
self.speed = 1
end
func update()
self.x = self.x + self.speed
end
這個範例建立了一個名為 speed 的 Runtime 屬性。
自訂 Node 狀態存在於 Runtime 執行期間。
不要假設自訂腳本屬性會自動儲存回原始 .b8map 檔案。
6. Node 移動
Node 可以直接修改座標：
self.x = self.x + 1
但直接修改座標與使用碰撞感知移動不同。
BIT8_CLI 提供：
self:move(dx, dy)
這個方法會在遵守支援的碰撞規則下，嘗試移動 Node。
例如：
func update()
self:move(1, 0)
end
這會嘗試讓 Node 向右移動 1 像素。
7. Collision 碰撞判定
BIT8_CLI 提供 Node 碰撞查詢：
self:collide(dx, dy)
這個方法會檢查預定的移動是否與支援的碰撞區域發生衝突。
查詢本身不會移動 Node。
例如：
func update()
if not self:collide(1, 0) then
self:move(1, 0)
end
end
這段程式會先檢查右方是否有障礙，再嘗試移動。
Runtime 支援與 Solid Tile 進行碰撞判定。
Node 也可以定義選用的 Collider。
BIT8_CLI 0.1.0 尚未提供完整的物理引擎。
詳細資訊請閱讀 Collision。
8. 移動判定順序
碰撞感知移動使用像素級判定。
Runtime 會先處理 X 軸，再處理 Y 軸。
移動使用每次 1 像素的步進方式進行判定。
因此，Node 可以在 Tile-based Collision World 中進行像素級移動。
例如：
self:move(2, 1)
會先嘗試水平移動，再嘗試垂直移動。
碰撞可能阻止部分或全部的預定移動。
9. Node 與 Sprite
Node 可以使用 Sprite Definition 顯示圖像。
Sprite Definition 儲存在：
bit8.sprites.toml
Node 可以綁定已定義的 Sprite：
self:sprite("Player")
Sprite 可以包含具名 Animation。
例如：
self:play("walk")
使用以下方法繪製目前的 Sprite Frame：
self:spr()
完整範例：
func init()
self:sprite("Player")
self:play("idle")
end
func draw()
self:spr()
end
這個範例假設專案已經定義名為 Player 的 Sprite，以及名為 idle 的 Animation。
10. 持久化 Sprite 參照
BIT8_CLI 0.1.0 支援在 Map 資料中儲存 Sprite 參照。
Node 可以在 Map 中關聯一個 Sprite 名稱。
例如：
Player
Runtime 會在執行 Node 的初始化函式前，解析已儲存的 Sprite 參照。
因此，Node 可以在開始執行時就擁有指定的 Sprite，不需要每個 Script 都重新手動綁定。
11. 啟用與停用 Node
Node 提供啟用狀態：
self.enabled
這個屬性表示 Node 是否啟用。
例如：
func update()
if self.enabled then
self.x = self.x + 1
end
end
可以利用啟用狀態控制遊戲行為。
停用 Node 的確切 Runtime 處理方式，應以對應版本的實作為準。
12. Main Script 與 Node Script
BIT8_CLI 將遊戲主腳本與 Node 行為分開。
Main Script 可以組織整體遊戲生命週期：
func init()
end
func update()
end
func draw()
cls(0)
map()
end
Node Script 則專注於單一遊戲物件。
例如：
func init()
self.speed = 1
end
func update()
self:move(self.speed, 0)
end
func draw()
self:spr()
end
這種分工鼓勵使用模組化的遊戲結構。
Main 負責組裝遊戲。
Node 負責在遊戲世界中運作。
13. Node 編輯
BIT8_CLI 的 VS Code Map Workspace 提供 Node 編輯工具。
可以透過 Workspace 檢視與修改支援的 Node 屬性。
包括：
- Node 選擇
- 位置
- 名稱
- Script 參照
- 啟用狀態
- 支援的 Sprite 與 Collider 屬性
Map Workspace 負責編輯專案資料。
Runtime 則負責執行 Node 行為。
詳細資訊請閱讀 Map Workspace。
14. 目前限制
BIT8_CLI 0.1.0 提供輕量化 Node 系統。
它並不是完整的 Scene Tree Engine。
以下功能不屬於已確立的 0.1.0 Node 模型：
- 通用階層式 Scene Tree
- 完整的 Rigid Body Physics
- 完整的 Event 或 Signal 系統
- 任意 Runtime 屬性的自動持久化
Node 系統主要專注於輕量遊戲物件、腳本、移動與繪製。
下一步
繼續閱讀：
相關文件：
Main 負責組裝遊戲，Node 負責在遊戲世界中運作。