Maps zh TW

Map 地圖系統

English | 繁體中文 | 日本語 | 한국어

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
• 直接放置大型背景圖片作為世界物件
• 完整物理引擎

這些功能可以在未來版本中繼續探索。

下一步

繼續閱讀：

Node

相關文件：

• Asset 與 Tilesheet
• Collision
• Camera
• Map Workspace
• Runtime API

Map 定義世界，Node 為世界帶來行為。