Crate gasm 

Rust bindings for the gasm game ABI v0 — see spec/ABI.md.

struct MyGame { t: u32 }
impl gasm::Game for MyGame {
    fn init() -> Result<Self, String> { gasm::set_frame_rate(60.0); Ok(MyGame { t: 0 }) }
    fn frame(&mut self) { self.t += 1; /* simulate, draw */ }
}
gasm::game!(MyGame);

Build with --target wasm32-unknown-unknown and crate-type = ["cdylib"]. On native targets the same code links against an in-process stub host (native) for tests and benchmarks.

Re-exports

pub use sys::keys;

Modules

audio

gfx

GPU rendering through gasm:gfx (a WebGPU subset; descriptors are JSON).

input

Raw keyboard, pointer and gamepads (next to the virtual pads).

main_loop

Games that keep their own main loop (loop { update(); draw(); wait_frame(); }) instead of implementing Game. Same mechanism as the C SDK’s gasm_loop.h: main_loop! exports the entry points and runs your function on the first frame; main_loop::wait_frame suspends it until the next frame with Binaryen’s Asyncify, inside the module. Build, then post-process the .wasm:

native

In-process stub host for running a guest natively (non-wasm targets).

net

Message connections through gasm:net (WebSocket semantics, non-blocking).

storage

Persistent per-game key/value store (gasm:storage): saves, settings, scores.

sys

Raw ABI. On wasm32 these are the real imports (see spec/ABI.md). On other targets they are backed by crate::native, an in-process stub host used for native parity tests and benchmarks.

Macros

game

Export the gasm entry points for a Game type.

log

format!-style logging: gasm::log!("x = {x}").

main_loop

Export the gasm entry points for a game with its own main loop (see [main_loop]).

title

The game’s built-in title (custom section gasm.title): runners show it (and launchers list it) before the game runs and while it hasn’t called set_title. Use once, at the top level: gasm::title!("Sumo");

Structs

Buttons

Virtual gamepad buttons (bit positions per spec/ABI.md).

Constants

ABI_VERSION

Traits

Game

A gasm game. init runs once; frame runs at the configured frame rate.

Functions

asset

Read a whole asset (it must fit in memory: under 2 GiB).

asset_names

All asset names, sorted (by UTF-8 bytes). Folder entries keep their on-disk case.

asset_read_at

Read up to buf.len() bytes of an asset starting at offset (for streaming large assets). Returns bytes read (0 at the end), or None if missing.

asset_size

Size of an asset in bytes (any size), or None if it doesn’t exist.

exit

End the game (WASI proc_exit). Runners treat code 0 as a clean exit.

has

Does the runner provide an import? A module ("gasm:gfx") or a function in one ("gasm.asset_size64", "gasm:gfx.destroy"). Calling an import the runner lacks traps, so probe optional features first.

log

pad

Buttons held on virtual pad player (0..=3) this frame.

param

Launch parameter (--param k=v natively, ?k=v in the browser).

present

Present an RGBA8 frame (stride bytes per row; 1-4096 pixels each way).

set_frame_rate

Rate at which the runner calls frame(). Default 60.

set_title

Name the game’s window or browser tab (runners add their own suffix, e.g. “DOOM — gasm”). Control characters are dropped, at most 256 bytes are kept, and "" restores the default (the file name). Does nothing on runners without it.

text_input

Text typed since the previous frame ('\u{8}' = backspace, '\n' = enter), or None if the runner has no keyboard.

time_ms

Monotonic milliseconds (virtual, frame-derived time in headless runs).

video_set_aspect

Show video_present frames at display aspect num:den (e.g. 4:3 for a 320×200 game drawn for a CRT) instead of square pixels; (0, 0) resets. Returns false on runners without it: the game then corrects the aspect itself (or accepts square pixels). Display only: hashes don’t change.