Crate gasm_host 

Native host for gasm games.

Load a guest .wasm with host::Game::load, drive it with host::Game::frame at the guest’s frame rate, and plug in the pieces you need: assets::Assets (memory, file-backed, folders), gfx::Gfx (wgpu: window, offscreen or null), audio::AudioOut, net::Net (WebSocket, ws:///wss://), storage::Storage (per-game key/value).

Complete runners built from these parts: headless::run (reproducible runs with hashes) and, with the window feature (default), window::run (winit window, cpal audio, gilrs gamepads, keyboard layouts). The gasm-run binary is their command line.

ABI: https://gasm.emdzej.pl/docs/abi (machine-readable: spec/abi.json).

Modules

angle

ANGLE (OpenGL ES 3.0 on Metal, Direct3D 11 or Vulkan): the GL backend of gasm:gl natively. libEGL and libGLESv2 are loaded at run time (scripts/fetch-angle.sh puts them in tools/angle/; release bundles ship them next to gasm-run), so gasm-run runs everything else without them.

assets

Read-only guest assets: in-memory buffers, or files read on demand.

audio

Audio output: guest samples -> linear resampler -> lock-free ring -> device.

consent

Player consent: the window runner asks before a game reaches outside itself, a network host (gasm:net, gasm:fetch) or saving files for the player (gasm:files). Four answers: this time (until the game ends), always (remembered), no (asked again next run) and never (remembered). Remembered answers live in <data dir>/gasm/consent/<game>.txt, one allow <subject> / deny <subject> line each; gasm-run --forget-consent <game|all> removes them.

fetch

gasm:fetch for the native runner: HTTP(S) requests made for the guest (design/fetch.md).

files

gasm:files: files a game hands the player. save queues a copy; the runner writes the queue after the frame (Files::flush) where the player finds it: images in Pictures//, everything else in Downloads//, or --save-dir. Names are reduced to a safe file name and never overwrite a file (“photo (2).png”). The game never learns the path. Headless runs without --save-dir write nothing (each save still completes at the end of its frame, so runs are reproducible).

gfx

gasm:gfx on wgpu, plus the 2D video_present blit.

gl

gasm:gl (OpenGL ES 3.0 with WebGL 2’s rules, design/gasm-gl.md) on the native runner: the shared model and the null GL. Mirrors runners/web/lib/gl.js (its ctx == null paths) line by line: same names, same GL errors, same traps, same hashes. Natively there is no GL backend yet, so gasm:gl guests run headless only.

gles

The GLES 3.0 functions (and the ANGLE extensions gasm uses), loaded at run time. GENERATED by scripts/gen-gl-headers.py from the Khronos registry: do not edit.

headless

Headless runs: N frames with virtual time, scripted input and (optionally) hashes of everything the guest presents. Reproducible: the same module and options give the same hashes on every runner (runners/web/headless.mjs).

host

The gasm ABI v0 host: instantiates a guest and implements the “gasm”, “gasm:gfx”, “gasm:net” and “gasm:storage” imports, plus the WASI subset in crate::wasi.

keymap

Keyboard layouts: the same text format as the web player (gasm-host.js parseKeymap). A line per binding: <pad 1-4> <button> <key code>..., where key codes are W3C KeyboardEvent.code names (winit’s KeyCode uses the same names). Keyboard bindings for pad N >= 2 apply while fewer than N gamepads are connected.

keys

Raw key codes shared by every part of the runner (no windowing dependency).

manifest

The capabilities manifest: what a game (or a mod) says it needs, as JSON. Games embed it as the custom section gasm.manifest (Rust: gasm::manifest!, C: GASM_MANIFEST); a launcher can give it instead (asset gasm.manifest, or gasm-run --manifest <file>: Godot games share one engine module). Mods bring theirs next to the pack (roads.pck + roads.json).

net

gasm:net for the native runner: WebSocket client connections.

present

Showing video_present frames: the letterbox and the upscaling filters (design/presentation.md). Display only: hashes are taken from the guest’s bytes before any of this runs.

prompt

The window runner’s consent question (consent.rs) as an image: drawn instead of the game’s frame while the game waits for the answer (keys 1-4, Esc = not now).

script

Scripted input for headless runs (--input), mirrored by runners/web/headless.mjs.

session

A game ready to start: the module, its assets, parameters, storage and load options. crate::headless::run and window::run (feature window) drive it.

splash

The gasm splash screen: a few frames of Pong in the style of gasm’s icon (the paddles, the dashed net and the square ball on the dark tile), then the court shrinks into the icon, the paddles and the ball move into their places in it, and “gasm” appears under it.

storage

gasm:storage for the native runner: one directory per game, one file per key.

switching

Stack switching for guests that export gasm_run (design/stack-switching.md).

wasi

The WASI preview1 subset gasm runners provide: enough for wasi-libc’s stdio, malloc, clocks and random numbers, and nothing that reaches the host’s files, environment or arguments. runners/web/gasm-host.js wasiImports implements exactly the same functions with the same results (see spec/ABI.md):

window

The windowed runner: winit window, wgpu surface, cpal audio, gilrs gamepads, keyboard layouts, fixed-timestep frames with catch-up, and the hold-Escape quit.