Module cart 

The PNG cartridge format.

A Pixel8 cart is a real PNG image — the picture is the cartridge, complete with label art — with the game embedded in a private ancillary chunk. Any image viewer shows the cart; Pixel8 plays it.

Chunk layout (see docs/CART_FORMAT.md for the full story):

PNG signature
IHDR, IDAT*, ...      # ordinary PNG image: the cart label art
pxRt                  # Pixel8 payload chunk:
  "PIXEL8"             #   magic
  u16 LE version      #   cartridge format version (currently 1)
  deflate( json( Cart ) )
IEND

Cart always carries the compiled game.wasm and the full asset bundle; carts exported as editable also carry the Rust source.

Structs

Cart

Everything inside a cartridge.

Constants

CART_VERSION

Current cartridge format version. Bump (and reject older carts with a clear message) once carts are published; until then format changes are free.

LABEL_H

LABEL_W

Cart image dimensions.

MAX_WASM_SIZE

Hard cap on a cart’s compiled wasm module: 128 K, shared with the memory and fuel limits. Keeps carts small and shareable and rations dependency bloat. Enforced on both save and load.

MEMORY_CAP

Hard cap on a cart’s initial linear memory: 128 K, enforced at load (see vm.rs). Numerically equals MAX_WASM_SIZE but is a distinct limit.

WASM_PAGE_SIZE

One wasm linear-memory page: 64 KiB.

Functions

decode

Decode and validate a cart from PNG bytes.

default_label

The built-in default label used when no screenshot was captured.

encode

Encode a cart into PNG bytes.

encode_screen_png

Encode the virtual screen as a standalone PNG (for screenshots and docs). scale is an integer zoom factor.

initial_memory_bytes

The initial linear memory a cart commits at instantiation, in bytes, read from the wasm’s exported memory minimum. None when the wasm cannot be parsed or declares no exported memory.

is_cart

Cheap check: is this PNG a Pixel8 cart? Scans chunk headers for pxRt without decompressing anything — used by cart pickers to filter directories quickly.

load_png

Load and validate a cart from a PNG file.

save_png

Save a cart as a PNG file with label art.