Runtime API

Runtime API

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

This page introduces the runtime scripting API available in BIT8_CLI 0.1.0.

BIT8_CLI uses Lua 5.4 with .b8 scripts and supports func as an alternative to function.

Runtime Overview

Property	Value
Framebuffer	64 × 64 pixels
Simulation	Fixed 30 Hz
Tile size	8 × 8 pixels
Map dimensions	Up to 256 × 256 tiles
Scripting	Lua 5.4
Script extension	.b8

Lifecycle Functions

init()

Called during game initialization.

func init()
    x = 32
    y = 32
end

update()

Handles simulation logic.

func update()
    x = x + 1
end

Simulation updates run at a fixed 30 Hz.

draw()

Draws the current game state.

func draw()
    cls(0)
    pix(x, y, 7)
end

Drawing API

cls(color)

Clears the framebuffer using a palette color.

cls(0)

clear() is also supported as an alias.

pix(x, y, color)

Draws a pixel at the specified screen coordinates.

pix(32, 32, 7)

pixel() is also supported as an alias.

rectfill(...)

Draws a filled rectangle.

rectfill(10, 10, 20, 20, 7)

spr(...)

Draws a tile from the registered assets.

BIT8_CLI supports stable Asset IDs.

spr(A4, 16, 16)

Legacy numeric sprite references remain supported for compatibility.

map(...)

Draws map content using the project's registered tiles.

func draw()
    cls(0)
    map()
end

Map rendering can interact with the active Camera.

For detailed map behavior, see Maps.

Input API

btn(button)

Returns whether a button is currently held.

if btn(LEFT) then
    x = x - 1
end

Available button constants:

UP
DOWN
LEFT
RIGHT
A
B

btnp(button)

Checks whether a button was newly pressed.

if btnp(A) then
    print("A pressed")
end

Unlike btn(), it is intended for press events rather than continuous holding.

Map API

mget(...)

Reads a tile value from the map.

mset(...)

Changes a tile value in the runtime map.

For map coordinates, tile IDs, and editing behavior, see Maps.

Node API

Node scripts access their associated runtime Node through self.

func update()
    self.x = self.x + 1
end

Node Properties

Property	Description
self.id	Stable Node identifier
self.name	Node name
self.x	World X position
self.y	World Y position
self.enabled	Whether the Node is enabled

self:collide(dx, dy)

Checks whether moving the Node by the given offset would collide with supported collision geometry.

if self:collide(1, 0) then
    print("Blocked")
end

This check does not move the Node.

Collision uses enabled Node Box Colliders and solid map tiles.

self:move(dx, dy)

Attempts to move the Node while respecting collision.

self:move(1, 0)

Movement is resolved along the X axis before the Y axis.

BIT8_CLI 0.1.0 provides basic collision-aware movement, not a full physics engine.

Sprite and Animation API

self:sprite(name)

Binds a registered Sprite definition to the Node.

self:sprite("Player")

self:play(animation)

Plays a named animation from the Node's bound Sprite.

self:play("walk")

Repeated requests to play the same animation do not restart it unnecessarily.

self:spr()

Draws the Node's current Sprite animation frame.

func draw()
    self:spr()
end

Sprite definitions are stored in:

bit8.sprites.toml

See Sprites and Animation for configuration details.

Camera

BIT8_CLI supports a Camera Node.

The active Camera controls the world-space view used by supported rendering operations.

Camera coordinates represent the center of the 64 × 64 viewport.

Screen-space drawing operations such as cls(), pix(), and rectfill() are not shifted by the Camera.

See Camera for details.

Example: Node Movement and Animation

The following example is intended for a Node with a registered Sprite and suitable animation definitions.

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

The animation names must exist in the Sprite definition.

Additional References

• Language Basics
• Assets and Tilesheets
• Maps
• Nodes
• Sprites and Animation
• Collision
• Camera

This page documents the established BIT8_CLI 0.1.0 API surface. Detailed signatures and edge cases should be checked against the corresponding release source.