Runtime API zh TW

Runtime API

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

本頁介紹 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 中。

相關文件

• 語言基礎
• Asset 與 Tilesheet
• Map
• Node
• Sprite 與 Animation
• Collision
• Camera

本頁整理 BIT8_CLI 0.1.0 已確立的 API 功能。完整函式簽名與特殊情況仍應以對應版本的原始碼為準。