Maps zh TW - Akiaaaa20/Bit8_CLI GitHub Wiki
Map 地圖系統
BIT8_CLI 提供以 Tile 為基礎的 Map 系統，用來建立 2D 遊戲世界。
Map 使用已註冊的 Asset ID，支援調整地圖尺寸，也可以包含 Node 與 Camera。
本指南介紹 BIT8_CLI 0.1.0 的 Map 系統。
1. Map 概覽
BIT8_CLI 使用固定的 Tile 尺寸：
8 × 8 像素
預設 Map 尺寸為：
64 × 64 Tiles
Map 的寬度與高度可以設定為：
1 至 256 Tiles
Map Cell 的最大總數為：
65,536
Map 尺寸與遊戲的 64×64 framebuffer 互相獨立。
因此，Map 可以比實際顯示的遊戲畫面大很多。
2. Map 檔案
BIT8_CLI 使用以下副檔名儲存 Map：
.b8map
例如：
world.b8map
Map 檔案包含 Tile 資料，也可以定義 Node 與 Camera。
專案結構可能如下：
my-bit8-game/
├── main.b8
├── bit8.assets.toml
├── world.b8map
└── assets/
└── terrain (A).png
這是示意性的專案結構。
3. Map 座標
Map 使用 Tile 座標。
每個 Map Cell 代表遊戲世界中的 8×8 像素區域。
例如：
Tile (0, 0) → 世界像素 (0, 0)
Tile (1, 0) → 世界像素 (8, 0)
Tile (2, 0) → 世界像素 (16, 0)
Tile (0, 1) → 世界像素 (0, 8)
Tile 座標轉換成像素座標的公式：
pixel_x = tile_x × 8
pixel_y = tile_y × 8
例如，Tile (5, 3) 對應世界像素座標 (40, 24)。
4. Map Cell
每個 Map Cell 都可以引用已註冊的 Tile。
例如：
A1
A2
A3
這些識別碼對應到：
bit8.assets.toml
中已註冊的 Tilesheet。
空白 Map Cell 使用：
--
表示。
簡化的 Map 可能長這樣：
A1 A1 A1 A1 A1
A1 -- -- -- A1
A1 -- A2 -- A1
A1 -- -- -- A1
A1 A1 A1 A1 A1
這只是 Map Cell 的概念示意，不是完整的 .b8map 檔案格式。
5. 繪製 Map
使用 map() 繪製目前的 Map。
func draw()
cls(0)
map()
end
這會清除 framebuffer，並繪製 Map。
實際可見範圍取決於 framebuffer 與目前啟用的 Camera。
完整參數細節應以對應版本的 BIT8_CLI 原始碼為準。
6. 讀取 Map Cell
BIT8_CLI 提供：
mget(...)
這個 API 可以讀取 Runtime Map 中的 Tile 值。
Map 操作使用 Tile 座標，而不是像素座標。
7. 修改 Map Cell
BIT8_CLI 提供：
mset(...)
這個 API 可以修改 Runtime Map 中的 Tile 值。
Runtime Map 修改會影響正在執行的遊戲狀態。
這與透過 Editor 將修改儲存回原始 .b8map 檔案不同。
8. Map Workspace
BIT8_CLI 的 VS Code Extension 內建 Map Workspace。
Map Workspace 提供視覺化的地圖編輯工具。
包含：
- Map 畫布
- Tile 選擇
- Tile 繪製
- Map Cell 檢視
- 縮放控制
- Node 選擇與編輯
- Camera 視覺化
- 屬性檢視
Map Workspace 使用與 Runtime 相同的底層專案資料。
Editor 介面本身不是 Map 行為的最終定義來源。
9. Map 中的 Node
Map 可以包含 Node。
Node 可以定義：
- 穩定的 Node ID
- 名稱
- 位置
- 啟用狀態
- Script 參照
- 選用的 Sprite 參照
- 選用的 Collider
Node 是遊戲世界結構的一部分。
Node Script 可以在 Runtime 執行期間控制其行為。
例如：
func update()
self.x = self.x + 1
end
詳細資訊請閱讀 Node。
10. Map 中的 Camera
Map 可以包含 Camera Node。
Camera 決定遊戲世界中哪個區域會顯示在畫面上。
BIT8_CLI 使用 64×64 Viewport。
Camera 座標代表 Viewport 的中心。
支援世界座標的繪圖操作會依照目前啟用的 Camera 進行轉換。
而螢幕座標繪圖操作，例如：
cls(0)
pix(32, 32, 7)
仍然使用螢幕座標。
詳細資訊請閱讀 Camera。
11. Solid Tile 與 Collision
已註冊的 Tile 可以設定為 Solid。
例如：
solid = [6]
代表對應 Tilesheet 的第六個 Tile 被標記為 Solid。
Solid Tile 在碰撞判定中佔據完整的 8×8 像素區域。
Node 可以透過：
self:collide(dx, dy)
self:move(dx, dy)
與 Solid Tile 進行碰撞判定。
詳細資訊請閱讀 Collision。
12. Map 尺寸與效能
最大支援 Map 尺寸：
256 × 256 Tiles
最大 Cell 數量：
65,536 Cells
Map 不需要限制在 64×64 framebuffer 內。
目前視角只會顯示世界的一部分。
設計大型 Map 時，仍應考慮遊戲的繪製與執行需求。
13. 目前限制
BIT8_CLI 0.1.0 提供以 Tile 為基礎的 Map 系統。
以下功能尚不屬於已確立的 0.1.0 Map 系統：
- 多個獨立 Map Layer
- 直接放置大型背景圖片作為世界物件
- 完整物理引擎
這些功能可以在未來版本中繼續探索。
下一步
繼續閱讀：
相關文件：
Map 定義世界，Node 為世界帶來行為。