Developer guide
gasm has two sides, and you can work on either one alone:
Writing games →Rust with the
gasm crate (or C): 2D, 3D with WebGPU, audio, input, networking, determinism.Writing runners →Bring every gasm game to a new platform or engine: the ABI, frame loop, GPU, audio, network, conformance.Packages →gasm-sdk (Rust), the C/C++ SDK, @emdzej/gasm-host (npm), gasm-host (crates.io), the relay image.Testing & contributing →Determinism, network and parity suites, benchmarks, repository conventions.Repository layout
spec/ abi.json (source of truth), ABI.md (normative), gasm.h (generated C header)
guests/ Rust workspace, target wasm32-unknown-unknown
gasm/ bindings, game! macro, native stub host
sumo/ 3D two-player game (sim.rs, render.rs, lib.rs)
nes/ NES emulator on tetanes-core
doom/ DOOM: platform layer for doomgeneric (C; engine fetched at build)
scummvm/ ScummVM: gasm backend (C++; engine fetched at build, Asyncify)
triangle/ smallest GPU example
textured/ textures, samplers, explicit layouts, dynamic offsets
inputtest/ raw keyboard, pointer, gamepads
parity/ runs the NES game natively (parity + benchmarks)
test-pattern/ C example (wasi-sdk)
loopdemo/ a game with its own main loop (Rust)
assetcheck/ test guest for asset providers
sdk/c/ C/C++ SDK: CMake toolchain, gasm_loop, gasm_vfile, examples
sdk/sdl3/ SDL 3 for gasm (config + drivers; SDL fetched at build)
runners/native/ crate gasm-host: library + gasm-run (Rust); relay/: gasm-relay
runners/web/ @emdzej/gasm-host (gasm-host.js + lib/), browser player, headless Node runner (JS)
tests/golden/ golden hashes of the determinism suite
scripts/ toolchain/ROM fetchers, test suites, packaging, site build
site/ this website (VitePress)Build from source
sh
git clone https://github.com/emdzej/gasm && cd gasm
make # games + native runner + relay (fetches wasi-sdk on first run)
make test # determinism + network suites
make web # browser runner at http://localhost:8080/runners/web/Requirements: rustup (stable toolchain; the wasm32 target is added automatically), Node ≥ 22, Python 3. On Linux, the native runner also needs libasound2-dev and libudev-dev.
The ABI at a glance
exports: memory, gasm_abi_version() -> 0, gasm_init() -> 0, gasm_frame()
exports (optional): gasm_exit() player is quitting: flush saves
gasm log · has · time_ms · set_frame_rate · param · video_present
video_set_aspect · set_title · audio_config · audio_push · input_pad · text_input · input_mode
key_state · key_events · pointer · gamepad · gamepad_name
asset_size · asset_size64 · asset_read · asset_read_at
asset_read_at64 · asset_count · asset_name
gasm:gfx width · height · create_shader · create_buffer · write_buffer
create_texture · write_texture · create_sampler
create_bind_group_layout · create_pipeline · create_bind_group
begin_frame · set_pipeline · set_bind_group · set_bind_group_offsets
set_viewport · set_scissor_rect · set_vertex_buffer
set_index_buffer · draw · draw_indexed · end_frame · destroy
gasm:net open · state · send · recv · close
gasm:fetch request · state · status · headers · read · close
gasm:storage get · set · delete · count · key
gasm:clipboard set_text · get_text
gasm:files save · stateFull details: ABI v0 specification. What each release added: CHANGELOG.
Design documents
Larger features get a design document with a phased plan before the work starts. In progress:
- Threads: cooperative threads in C, POSIX, SDL 3 (0.7.0) and Rust (0.8.0); real wasm threads later
Implemented (kept as a record of the decisions):
- Presentation: upscaling filters, display aspect, window title (0.6.0)
gasm:gl: OpenGL ES 3.0 with WebGL 2 rules: browser and headless (0.7.0), ANGLE natively and glow for Rust (0.8.0)gasm:fetch: HTTP requests made by the runner, record and replay, Godot'sHTTPRequest(0.9.0)- Stack switching:
gasm_runandyield_frame, games with their own loop without Asyncify (0.7.0)
Everything else that is planned or missing is on the roadmap.