Skip to content

Developer guide ​

gasm has two sides, and you can work on either one alone:

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 · state

Full 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's HTTPRequest (0.9.0)
  • Stack switching: gasm_run and yield_frame, games with their own loop without Asyncify (0.7.0)

Everything else that is planned or missing is on the roadmap.

MIT licensed. The NES demo core is tetanes-core (MIT/Apache-2.0).