Runtime API zh TW - Akiaaaa20/Bit8_CLI GitHub Wiki
Runtime API
本頁介紹 BIT8_CLI 0.1.0 提供的 Runtime 腳本 API。
BIT8_CLI 使用 Lua 5.4，腳本副檔名為 .b8，並支援使用 func 代替 function。
Runtime 概覽
| 項目 | 規格 |
|---|---|
| Framebuffer | 64 × 64 像素 |
| 模擬更新 | 固定 30 Hz |
| Tile 大小 | 8 × 8 像素 |
| Map 尺寸 | 最大 256 × 256 Tiles |
| 腳本語言 | Lua 5.4 |
| 腳本副檔名 | .b8 |
生命週期函式
init()
遊戲初始化時呼叫。
func init()
x = 32
y = 32
end
update()
負責處理遊戲模擬邏輯。
func update()
x = x + 1
end
模擬更新頻率固定為 30 Hz。
draw()
負責繪製目前的遊戲狀態。
func draw()
cls(0)
pix(x, y, 7)
end
繪圖 API
cls(color)
使用指定的調色盤顏色清除 framebuffer。
cls(0)
也支援別名 clear()。
pix(x, y, color)
在指定的螢幕座標繪製像素。
pix(32, 32, 7)
也支援別名 pixel()。
rectfill(...)
繪製填滿的矩形。
rectfill(10, 10, 20, 20, 7)
spr(...)
使用已註冊的 Asset 繪製 Tile。
BIT8_CLI 支援穩定的 Asset ID。
spr(A4, 16, 16)
為了相容舊專案，仍然支援傳統數字 Sprite 參照。
map(...)
使用專案中註冊的 Tile 繪製 Map。
func draw()
cls(0)
map()
end
Map 繪製可以受到目前啟用的 Camera 影響。
詳細資訊請閱讀 Map。
輸入 API
btn(button)
檢查按鈕目前是否持續按住。
if btn(LEFT) then
x = x - 1
end
支援的按鈕常數：
UP
DOWN
LEFT
RIGHT
A
B
btnp(button)
檢查按鈕是否剛被按下。
if btnp(A) then
print("A pressed")
end
與 btn() 不同，btnp() 適合處理單次按下事件。
Map API
mget(...)
讀取 Map 中的 Tile 值。
mset(...)
修改 Runtime Map 中的 Tile 值。
關於 Map 座標、Tile ID 和編輯行為，請閱讀 Map。
Node API
Node Script 可以透過 self 存取對應的 Runtime Node。
func update()
self.x = self.x + 1
end
Node 屬性
| 屬性 | 說明 |
|---|---|
self.id |
穩定的 Node ID |
self.name |
Node 名稱 |
self.x |
世界座標 X |
self.y |
世界座標 Y |
self.enabled |
Node 是否啟用 |
self:collide(dx, dy)
檢查 Node 如果移動指定距離，是否會與支援的碰撞物件發生碰撞。
if self:collide(1, 0) then
print("Blocked")
end
這個函式只負責檢查，不會實際移動 Node。
碰撞判定使用啟用的 Node Box Collider 與 Solid Tile。
self:move(dx, dy)
嘗試移動 Node，並考慮碰撞阻擋。
self:move(1, 0)
移動會先處理 X 軸，再處理 Y 軸。
BIT8_CLI 0.1.0 提供的是基本碰撞移動，不是完整物理引擎。
Sprite 與 Animation API
self:sprite(name)
將已註冊的 Sprite Definition 綁定到 Node。
self:sprite("Player")
self:play(animation)
播放目前 Sprite 中指定名稱的 Animation。
self:play("walk")
重複要求播放同一個 Animation，不會不必要地重新開始。
self:spr()
繪製 Node 目前的 Sprite Animation Frame。
func draw()
self:spr()
end
Sprite 定義儲存在：
bit8.sprites.toml
詳細設定請閱讀 Sprite 與 Animation。
Camera
BIT8_CLI 支援 Camera Node。
目前啟用的 Camera 會影響支援世界座標的繪圖操作。
Camera 座標代表 64 × 64 Viewport 的中心。
cls()、pix()、rectfill() 等螢幕座標繪圖操作不會受到 Camera 位移影響。
詳細資訊請閱讀 Camera。
範例：Node 移動與動畫
以下範例適用於已綁定 Sprite，且已定義對應 Animation 的 Node。
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
Animation 名稱必須存在於 Sprite Definition 中。
相關文件
本頁整理 BIT8_CLI 0.1.0 已確立的 API 功能。完整函式簽名與特殊情況仍應以對應版本的原始碼為準。