Runtime API - Akiaaaa20/Bit8_CLI GitHub Wiki

Runtime API

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

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.