Assets and Tilesheets zh TW - Akiaaaa20/Bit8_CLI GitHub Wiki

Asset 與 Tilesheet

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

BIT8_CLI 使用已註冊的 PNG Tilesheet，為遊戲提供圖像素材。

每張 Tilesheet 都會切分成 8×8 像素的 Tile。註冊後的 Tile 會取得穩定的 Asset ID，供腳本、Map、Sprite 和碰撞系統引用。

本指南介紹 BIT8_CLI 0.1.0 的素材系統。

1. Tilesheet

Tilesheet 是一張包含多個 Tile 的 PNG 圖片。

BIT8_CLI 使用固定的 Tile 尺寸：

8 × 8 像素

例如，一張 32×16 的 PNG 包含：

  • 4 欄
  • 2 列
  • 8 個 Tile

Tile 依照由左至右、由上至下的順序編號。

32 × 16 PNG

+------+------+------+------+
|  A1  |  A2  |  A3  |  A4  |
+------+------+------+------+
|  A5  |  A6  |  A7  |  A8  |
+------+------+------+------+

每個 Tile 都佔據 8×8 像素。

2. Asset Registry

BIT8_CLI 使用 Asset Registry 管理已註冊的 Tilesheet。

Registry 儲存在：

bit8.assets.toml

Registry 會將 Tilesheet 與穩定的 Group ID 關聯。

例如，某張 Tilesheet 使用 Group A。

它的 Tile 就可以使用：

A1
A2
A3
A4

作為引用。

Asset Registry 是素材身分的唯一權威來源。

不要假設只要把 PNG 放進專案，就會自動完成註冊。

應透過專案支援的 Asset 註冊流程建立或更新 Registry。

3. Stable Asset IDs

BIT8_CLI 使用以下形式的穩定識別碼：

Group + Tile Number

例如：

A1
A4
B12
C3

Group 代表已註冊的 Tilesheet。

數字代表該 Tilesheet 中的 Tile。

這種設計讓腳本和 Map 不必依賴全域數字排列順序。

例如：

spr(A4, 16, 16)

會在指定座標繪製 A4 Tile。

為什麼需要 Stable IDs？

假設一個專案包含多張 Tilesheet。

如果素材完全依賴全域列表的位置，新增或重新排列 Tilesheet 就可能改變既有引用。

Stable Asset IDs 可以降低這類問題。

BIT8_CLI 也會追蹤已退役的 Group ID，避免意外重複使用。

4. 已註冊 PNG 的命名

已註冊的 Tilesheet 使用以下標準檔名形式：

<名稱> (<GROUP>).png

例如：

terrain (A).png
characters (B).png
items (C).png

Group ID 是已註冊素材身分的一部分。

Asset Registry 仍然是最終依據。

如果直接手動重新命名已註冊的 PNG，卻沒有同步更新註冊資料，可能造成素材引用失效。

5. 繪製 Tile

使用 spr() 繪製已註冊的 Tile。

func draw()
    cls(0)
    spr(A4, 16, 16)
end

這段程式會清除畫面，然後繪製 A4 Tile。

使用前必須確保專案已註冊對應的 Tile。

為了相容舊專案，BIT8_CLI 仍保留傳統數字 Sprite 參照。

新專案建議使用 Stable Asset IDs。

6. 透明度與調色盤

BIT8_CLI 支援已註冊 PNG Tilesheet 中的透明像素。

Tile 繪製時，透明像素會以透明方式處理。

PNG 顏色會轉換成 Runtime 使用的調色盤表示方式。

素材處理流程的設計目標，是讓 Runtime 繪製結果與 Editor 預覽保持一致。

為了得到可預期的結果，建議使用顏色與透明度明確的 Pixel Art 圖片。

7. Solid Tile

Tile 可以標記為 Solid，供碰撞系統使用。

Solid Tile 的設定屬於 Asset Registry。

例如，某張 Tilesheet 可以將第六個 Tile 標記為 Solid：

solid = [6]

這代表該 Tilesheet Group 中的第六個 Tile。

Solid Tile 在碰撞判定中佔據完整的 8×8 像素區域。

Node 可以透過：

self:collide(dx, dy)

以及：

self:move(dx, dy)

使用 Solid Tile 碰撞。

solid 必須放在 bit8.assets.toml 中對應的素材註冊項目內，而不是任意放在最外層。

詳細資訊請閱讀 Collision。

8. Asset 與 Map

Map 使用已註冊的 Asset ID。

Map Cell 可以包含：

A1
A2
A3

等 Tile 參照。

因此，同一張 Map 可以使用不同 Group 的 Tile。

Map Workspace 提供選擇已註冊 Tile，以及將 Tile 繪製到 Map Cell 的工具。

詳細資訊請閱讀 Map。

9. Asset 與 Sprite

Sprite Definition 也會使用已註冊的 Tile。

Sprite 可以引用 Tile 來定義：

  • 靜態預覽
  • Animation Frame
  • 具名 Animation

Sprite Definition 儲存在：

bit8.sprites.toml

例如，名為 Player 的 Sprite 可以使用多個已註冊 Tile 作為動畫影格。

Node Script 就能透過：

self:play("walk")

控制動畫，並使用：

self:spr()

繪製目前的影格。

詳細資訊請閱讀 Sprite 與 Animation。

10. Asset 管理建議

管理素材時：

  1. 使用支援的 Asset 註冊流程加入 PNG Tilesheet。
  2. 維持已註冊 Group ID 的穩定性。
  3. 避免手動重新分配既有 Asset ID。
  4. 修改已註冊素材檔案時，同步更新 Registry。
  5. 移除素材前，先檢查 Map 與 Sprite 的引用。
  6. 利用退役 Group ID 機制，避免素材身分被意外重複使用。

Stable IDs 可以保護引用關係，但不代表任何素材修改都能自動維持相同的視覺意義。

例如，重新排列已註冊 PNG 裡的 Tile，可能讓原本的 Asset ID 指向不同的圖案。

11. 專案結構範例

使用 Tilesheet 的專案可能包含：

my-bit8-game/
├── main.b8
├── bit8.assets.toml
├── bit8.sprites.toml
└── assets/
    ├── terrain (A).png
    └── characters (B).png

這只是示意結構。實際素材路徑必須與 Asset Registry 中的註冊資料一致。

下一步

繼續閱讀：

Map

相關文件：

Stable Asset IDs 讓腳本、Map 和 Sprite 可以穩定引用已註冊的 Tile。

⚠️ **GitHub.com Fallback** ⚠️