The sg host API that every native 0x game imports, with its calling conventions, every host function grouped by area, the GPU wire protocol, input events and versioning.
A native game imports its host functions from the WebAssembly module sg, and optionally
platform services from sg_platform_v1. sg-guest wraps all of them in safe Rust; this page
is for writing bindings in another language, or for understanding what the wrappers do.
Buffers out are (ptr, cap), and the call returns an i64 length. If the value is larger
than cap, nothing is written and the needed length is returned, so call again with a bigger
buffer (or call with cap 0 first to ask for the size).
Handles are u32 (0 means none or failure). They index per-game tables in the host and
are never reused.
Validation. Every pointer and length is checked against guest memory. A pointer outside it
traps. Out-of-range values in display and audio calls are clamped or rejected with a status
code, not a trap.
Strings are UTF-8.
Exports. The main instance exports sg_init() -> i32 and sg_frame(t: f64, dt: f64);
t and dt are in seconds. Worker instances export sg_worker_init() -> i32 and
sg_worker_tick(t: f64) -> i32.
The guest never holds a GPU object. Requests are postcard-encoded
sg_abi::gpu::Req values passed to gpu_call; the host validates every field and answers with
an encoded Reply. Command encoders, passes and bundles are recorded entirely in the guest and
sent as one request when finished, so a frame costs a handful of host calls. Bulk data (buffer and
texture uploads, mapped ranges) bypasses the serializer through gpu_write_buffer,
gpu_write_texture, gpu_mapped_read and gpu_mapped_write.
The descriptor types embed wgpu-types 30, so their encoding is part of the protocol.
A guest that imports a function the host does not provide fails to instantiate, naming the missing import.
sg-gpu protocol
2 (sg_abi::gpu::VERSION)
Hosts accept guests from version 1 (MIN_VERSION). Version 2 added frame controls; version 1 guests never send them. Bumped on any incompatible change, including a layout-affecting wgpu-types upgrade.
sg_platform_v1
1
Records and events are CBOR maps with text keys: new optional fields and new event types are backward compatible. An incompatible change would be a new module name.
The sg-guest and sg-abi crates are at version 0.1.0.