Crate pixel8 

pixel8 — the Pixel8 fantasy console SDK

Write tiny games in Rust, run them on a tiny console.

use pixel8::*;

struct MyGame {
    x: i16,
    y: i16,
}

impl Game for MyGame {
    fn update(&mut self, ctx: &mut Context) {
        if ctx.is_button_down(Button::Right) {
            self.x += 1;
        }
    }

    fn draw(&self, gfx: &mut Graphics) {
        gfx.clear(Color::BLACK);
        gfx.rect_fill(self.x, self.y, 8, 8, Color::WHITE).unwrap();
    }
}

pixel8::game!(MyGame { x: 64, y: 64 });

Carts are built for wasm32-unknown-unknown as a cdylib and run in a strict sandbox: the host functions wrapped by Context and Graphics are the only doors out. The screen is 128x128, the palette has 16 fixed colors, update/draw run at 60 fps (or 30, if the game sets Game::FRAME_RATE). The constraints are the point.

For formatted on-screen text and debug logs, see the printf! and logf! macros.

Modules

ffi

The raw Pixel8 WASM ABI.

memstat

Memory accounting, measured inside the cart.

Macros

game

Declare your game’s entry point.

logf

Log formatted text to the debug console — like Context::log, but with format!-style arguments.

printf

Print formatted text to the screen — like Graphics::print, but with format!-style arguments. Returns the cursor x (as i16) after the last glyph.

Structs

BitFlags

A set of BitFlags of type T.

Body

A moving body that renders a clean pixel staircase instead of a zigzag.

Color

A color in the fixed 16-color palette.

Context

Game state and input, available during update.

Graphics

The screen, available during draw.

Music

A configured-but-not-yet-playing music request.

MusicBusy

The error from Music::play: a song is already playing, so the request was refused. Carries the rejected Music so it can be retried after the current song stops, without rebuilding.

MusicId

A music pattern (0..=63).

OutOfBounds

A point write addressed a coordinate off its surface; nothing was written.

PlayingMusic

A handle to the currently-playing song.

SfxId

A sound effect slot (0..=63).

SpriteId

A sprite on the 16x16 sprite sheet (0..=255).

StorageFull

A storage_set was rejected: the store would exceed its 128 KiB serialized cap (see docs/LIMITS.md). Nothing was written.

UnknownBits

The error from BitFlags::from_bits: the raw value had bits set that do not correspond to any flag.

ZeroSize

A draw call was given a size that was not strictly positive (zero or negative). The call drew nothing.

Enums

Button

The six console buttons.

Channel

One of the four audio channels, shared by sfx and music. Reserve channels for music with Music::reserve_channels.

FrameRate

How many times per second a cart’s update and draw run.

SpriteFlag

One of a sprite’s eight flags. The flags carry no fixed meaning — a cart assigns its own (e.g. “solid”). Used by Context::sprite_flags / Context::set_sprite_flags and the Graphics::map layer filter.

StorageValue

A storage value: a JSON primitive.

Constants

FPS

Default logical frames per second.

MAP_HEIGHT_TILES

MAP_WIDTH_TILES

The map is 128x64 tiles (each tile is one 8x8 sprite cell).

SCREEN_HEIGHT

SCREEN_WIDTH

The screen is 128x128 pixels.

SPRITE_SHEET_HEIGHT

SPRITE_SHEET_WIDTH

The sprite sheet is 128x128 pixels.

Traits

BitFlag

A single bit flag backed by a u8 mask.

Dim

A drawing dimension (width, height, radius, tile count).

Game

Implement this for your game state, then hand it to game!.