Your First Project

Your First Project

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

This guide creates a minimal BIT8_CLI project and runs your first .b8 program.

Before continuing, make sure BIT8_CLI is installed:

bit8 --version

See Installation if you have not installed it yet.

Create a Project

Create a new directory:

mkdir my-bit8-game
cd my-bit8-game

Create a file named:

main.b8

Your project now looks like:

my-bit8-game/
└── main.b8

Your First Program

Open main.b8 and add:

func init()
end

func update()
end

func draw()
    cls(0)
    pix(32, 32, 7)
end

BIT8_CLI accepts func as a convenient form of Lua's function.

This program clears the screen and draws one pixel near the center of the 64×64 framebuffer.

Run the Project

From outside or inside the project directory, run BIT8_CLI with the project path.

For example:

bit8 run .

BIT8_CLI loads the project and opens the game window.

You should see your first tiny pixel.

Congratulations. Your project is alive. 👾

The Game Lifecycle

A basic BIT8_CLI program can define three lifecycle functions:

func init()
end

func update()
end

func draw()
end

init()

Called when the game starts.

Use it to initialize game state.

update()

Called during the fixed simulation.

BIT8_CLI runs simulation updates at 30 Hz.

Use it for movement, input, game logic, timers, and state changes.

draw()

Used to draw the current game state.

Drawing functions such as cls() and pix() normally belong here.

Add Movement

Let's make the pixel move.

Replace main.b8 with:

x = 32
y = 32

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

Run the project again:

bit8 run .

The directional controls now move the pixel around the framebuffer.

The 64×64 Screen

BIT8_CLI uses a fixed:

64 × 64

game framebuffer.

Game coordinates use this logical resolution even when the window is displayed at a larger size.

For example:

pix(0, 0, 7)

draws at the top-left corner.

pix(32, 32, 7)

draws near the center.

Where to Go Next

You now have a working BIT8_CLI project.

Continue with:

Language Basics

After that, explore:

• Assets and Tilesheets
• Maps
• Nodes
• Sprites and Animation

The single pixel has officially begun its career. 👾