Language Basics

Language Basics

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

BIT8_CLI uses Lua 5.4 for game scripting.

Game scripts normally use the .b8 extension. BIT8_CLI also supports several convenient aliases, including func as an alternative to Lua's function.

This guide introduces the language features needed to create a simple game.

Your First Script

Create a file named main.b8:

func init()
    x = 32
    y = 32
end

func update()
end

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

Run the project:

bit8 run .

The program draws a pixel near the center of the screen.

Functions

Lua functions normally use the function keyword.

BIT8_CLI also accepts func:

func greet()
    print("Hello, BIT8_CLI!")
end

The equivalent Lua syntax is:

function greet()
    print("Hello, BIT8_CLI!")
end

Both forms are valid in BIT8_CLI scripts.

Functions can receive arguments and return values:

func add(a, b)
    return a + b
end

result = add(5, 3)

Variables

Lua variables do not require explicit type declarations.

x = 10
speed = 2
name = "Player"
alive = true

Use local for local variables:

local score = 0

Lua supports numbers, strings, booleans, tables, functions, and other value types.

Conditions

Use if, elseif, and else:

health = 5

if health <= 0 then
    print("Game Over")
elseif health < 3 then
    print("Low Health")
else
    print("Ready")
end

Lua uses then after conditions and end to close blocks.

Loops

A numeric for loop:

for i = 1, 5 do
    print(i)
end

A while loop:

local count = 0

while count < 5 do
    count = count + 1
end

Tables

Lua tables can store multiple values:

player = {
    x = 32,
    y = 32,
    health = 10
}

Access fields with:

player.x = player.x + 1

Tables are commonly used to organize game data.

Game Lifecycle

A basic BIT8_CLI game uses three lifecycle functions:

func init()
end

func update()
end

func draw()
end

init()

Runs when the game initializes.

Use it to set initial values.

update()

Runs during simulation updates.

BIT8_CLI uses a fixed 30 Hz simulation.

Use this function for movement, input, and game logic.

draw()

Draws the current game state.

Rendering commands normally belong here.

Drawing

Clear the screen:

cls(0)

Draw a pixel:

pix(32, 32, 7)

Draw a filled rectangle:

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

BIT8_CLI uses a fixed 64×64 game framebuffer.

Input

Use btn() to check whether a button is held:

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

Available button constants include:

UP
DOWN
LEFT
RIGHT
A
B

btnp() checks for a new button press rather than continuous holding.

A Moving Pixel

The following example combines variables, input, and drawing:

func init()
    x = 32
    y = 32
end

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

    if btn(RIGHT) then
        x = x + 1
    end

    if btn(UP) then
        y = y - 1
    end

    if btn(DOWN) then
        y = y + 1
    end
end

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

Save the file and run:

bit8 run .

Main Scripts and Node Scripts

BIT8_CLI supports both main game scripts and Node scripts.

The main script coordinates the game.

Nodes can have their own scripts and runtime state.

Node scripts can access their associated Node through self.

For example:

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

Node scripts are covered in more detail in Nodes.

Main assembles the game. Nodes live the game.

Next

Continue with:

Runtime API

You can also explore:

• Nodes
• Maps
• Sprites and Animation