Skip to main content

Crate wasmcart

Crate wasmcart 

Source
Expand description

§wasmcart

Rust bindings for the wasmcart cart ABI (v3).

A wasmcart cart is a freestanding wasm32-unknown-unknown module that exports memory, wc_get_info, wc_render (and, optionally but conventionally, wc_init). There is no runtime to embed and no JS glue: this crate is a binding, not an engine.

§Quick start

ⓘ
#![no_std]
use wasmcart::*;

wc_cart!(320, 240);

#[no_mangle]
pub extern "C" fn wc_init() {}

#[no_mangle]
pub extern "C" fn wc_render() {
    for px in fb() {
        *px = 0xFF3050C0;
    }
}

wc_cart! declares every buffer the ABI needs plus the live wc_info_t struct, and emits wc_get_info. It also installs a panic handler that reports the panic through wc_log before parking, so a panicking cart says why instead of freezing silently.

§no_std

This crate is #![no_std] and has no dependencies. The optional std feature exists only to let a cart that wants Vec/String link against std; it is NOT enabled by default, and enabling it pulls in machinery that makes the cart substantially larger.

Modules§

gl
OpenGL ES 3.0 / WebGL2 bindings, imported from the wasm module gl.
key
USB HID scancodes, as delivered in the keys_ptr bitmask.
modifier
Keyboard modifier bitmask values.

Macros§

shader_source
A NUL-terminated GLSL source literal, ready for [compile_shader].
wc_cart
Declare a cart: buffers, the live WcInfo, wc_get_info, and a panic handler that logs the panic message through wc_log before trapping.
wc_cart_config
Declare a cart from an explicit CartConfig const expression.

Structs§

CartConfig
Cart configuration, consumed by wc_cart! at compile time.
WcHostInfo
Written by the host before wc_init, read by the cart once at init.
WcInfo
The struct wc_get_info returns a pointer to. All fields are u32; field order is load-bearing and matches the C wc_info_t exactly.
WcPad
Gamepad state, 16 bytes. The host writes this before each wc_render.
WcPointer
Unified mouse/touch pointer, 8 bytes.
WcTime
Frame timing, 20 bytes and 8-byte aligned (two f64 then a u32).

Constants§

WC_ABI_VERSION
ABI version implemented by this crate.
WC_BTN_A
WC_BTN_B
WC_BTN_DOWN
WC_BTN_L
WC_BTN_L3
WC_BTN_LEFT
WC_BTN_R
WC_BTN_R3
WC_BTN_RIGHT
WC_BTN_SELECT
WC_BTN_START
WC_BTN_UP
WC_BTN_X
WC_BTN_Y
WC_FLAG_AUDIO_F32
Audio ring buffer holds f32 samples rather than i16.
WC_FLAG_DEBUG
Cart exports wc_debug_state(). Opt-in, default off.
WC_FLAG_DETERMINISTIC
Cart honors deterministic mode. Opt-in, default off.
WC_FLAG_KEYBOARD
Cart wants raw keyboard input.
WC_FLAG_NET_DC
Cart wants data-channel imports.
WC_FLAG_NET_WS
Cart wants WebSocket imports.
WC_FLAG_POINTER
Cart wants pointer (mouse/touch) input.
WC_GPU_API_NONE
2D framebuffer only.
WC_GPU_API_VULKAN
Reserved.
WC_GPU_API_WEBGL2
WebGL2 / OpenGL ES 3.0.
WC_GPU_API_WEBGPU
Reserved.
WC_HOST_FLAG_DETERMINISTIC
Host-info flag: this run is a deterministic replay.
WC_KEYS_STATE_SIZE
Bytes in the keyboard bitmask at keys_ptr (256 keys).
WC_MAX_PADS
Pads exposed through input_ptr.
WC_MAX_POINTERS
Pointers exposed through pointer_ptr.
WC_RUMBLE_MAX_MS
Longest single rumble effect the host will honor, in milliseconds.

Functions§

key_is_down
Test a keycode against a 32-byte key-state bitmask.
wc_asset_size
Size of an asset packed into the .wasc archive, or None if absent. Bare .wasm carts have no archive and always get None.
wc_debug_mark
Stamp {frame, id} into a debug-capable host’s event trace.
wc_load_asset
Load an archive asset into dest. Returns bytes loaded, or None on error.
wc_log
Write a message to the host’s debug log.
wc_pad_has_rumble
True if the host reports rumble support for this pad. Capability is per-device, so ask rather than assume.
wc_pad_name
Copy the host’s name for pad_id into buf. Returns bytes written.
wc_pad_rumble
Start a rumble effect. low/high are clamped to 0..1 by the host, and duration_ms is capped at WC_RUMBLE_MAX_MS. Re-arm each frame for sustained rumble.
wc_pad_rumble_stop
Stop any rumble effect on this pad.