wasmcart

1. Install

npm install wasmcart

Requires Node.js 22 or newer.

2. Write a cart

The minimal ABI is three exported functions. Set gpu_api = 1 so the cart renders through GL on every host:

#include "wasmcart.h"

static uint32_t framebuffer[320 * 240];
static wc_info_t info;

__attribute__((export_name("wc_get_info")))
wc_info_t* wc_get_info(void) {
  info.version = 3;
  info.width   = 320;
  info.height  = 240;
  info.gpu_api = 1;
  info.fb_ptr  = (uint32_t)(uintptr_t)framebuffer;
  return &info;
}

__attribute__((export_name("wc_init")))
void wc_init(void) {
  // called once at startup
}

__attribute__((export_name("wc_render")))
void wc_render(void) {
  // called every frame — draw here
}

3. Compile to WASM

Emscripten is the reference producer — its GL output already matches the ABI's WebGL2 surface, so a conforming cart falls out with no glue:

emcc -sSTANDALONE_WASM=1 -sALLOW_MEMORY_GROWTH=1 \
  --no-entry -O2 -o cart.wasm cart.c

4. Pack into a cartridge

npx wasmcart pack --wasm cart.wasm --assets ./assets/ \
  --name "My Game" -o game.wasc

5. Run it

npx wasmcart opens a real SDL window with audio and gamepad support. GL carts are auto-detected from the wasm import section — there is no flag to pass:

npx wasmcart game.wasc          # SDL window, audio, gamepad
npx wasmcart my-cart-dir/       # dev mode: straight off disk
npx wasmcart game.wasc --term   # ANSI terminal player

# headless: step N frames, dump a PNG + WAV, exit
npx wasmcart game.wasc --frames 300 --shot out.png --wav out.wav

# deterministic replay — same seed, byte-identical PNG
npx wasmcart game.wasc --seed 7 --frames 60 --shot a.png

Embedding the host in your own app instead:

import { CartHost } from 'wasmcart';        // Node
import { CartHostWeb } from 'wasmcart/web'; // browser

const cart = new CartHost();
await cart.load('game.wasc', {
  // a factory runs only if the cart actually imports GL
  glBackend: () => canvas.getContext('webgl2'),
});

const frame = cart.runFrame(gamepads);
// frame.framebuffer, frame.audio, frame.saveData