0xDocs 0x.limo

Docs / Native runtime

The sg ABI

Coming

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.

#Conventions

  • Buffers in are (ptr, len) pairs in guest memory.
  • 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.

#Host functions (module sg)

The import list as sg-guest declares it (sg_guest::sys):

#Core

FunctionReturns
log(p: *const u8, l: usize)—
set_title(p: *const u8, l: usize)—
surface_size()u64
now_ms()f64
wall_ms()f64
random_fill(p: *mut u8, l: usize)—
args(p: *mut u8, cap: usize)i64
is_worker()u32
quit()—

#GPU (the sg-gpu protocol)

FunctionReturns
gpu_call(p: *const u8, l: usize, out: *mut u8, cap: usize)i64
gpu_reply(out: *mut u8, cap: usize)i64
gpu_write_buffer(buf: u32, off: u64, p: *const u8, l: usize)—
gpu_write_texture(dp: *const u8, dl: usize, p: *const u8, l: usize)—
gpu_mapped_read(buf: u32, off: u64, p: *mut u8, l: usize)—
gpu_mapped_write(buf: u32, off: u64, p: *const u8, l: usize)—

#Input

FunctionReturns
input_poll(p: *mut u8, max: u32)u32
pointer_lock(on: u32)—
pointer_locked()u32
window_focused()u32

#TCP (manifest tcp)

FunctionReturns
tcp_connect(p: *const u8, l: usize, port: u32)u32
tcp_status(s: u32, ep: *mut u8, ecap: usize)i32
tcp_recv(s: u32, p: *mut u8, cap: usize)u32
tcp_send(s: u32, p: *const u8, l: usize)u32
tcp_close(s: u32)—

#HTTP fetch (manifest fetch)

FunctionReturns
fetch_start(p: *const u8, l: usize)u32
fetch_status(f: u32)i32
fetch_body_len(f: u32)i64
fetch_meta(f: u32, p: *mut u8, cap: usize)i64
fetch_read(f: u32, off: u64, p: *mut u8, cap: usize)u32
fetch_free(f: u32)—

#Key/value storage (manifest storage_mb)

FunctionReturns
kv_size(kp: *const u8, kl: usize)i64
kv_read(kp: *const u8, kl: usize, off: u64, p: *mut u8, cap: usize)i64
kv_write(kp: *const u8, kl: usize, p: *const u8, l: usize)u32
kv_delete(kp: *const u8, kl: usize)—
kv_list(kp: *const u8, kl: usize, p: *mut u8, cap: usize)i64

#Audio (manifest audio)

FunctionReturns
sound_create(p: *const u8, l: usize, format: u32, channels: u32, rate: u32)u32
sound_free(s: u32)—
voice_play(s: u32, vol: f32, pan: f32, pitch: f32, looping: u32)u32
voice_set(v: u32, vol: f32, pan: f32, pitch: f32)u32
voice_stop(v: u32)u32
voice_fx(v: u32, lowpass_hz: f32, send: f32)u32
reverb_set(rt60: f32, damp_hz: f32, predelay_ms: f32, early: f32)—
voice_active(v: u32)u32
audio_master(v: f32)—

#Workers and messages (manifest workers)

FunctionReturns
worker_spawn(p: *const u8, l: usize)u32
worker_terminate(id: u32)—
msg_post(to: u32, p: *const u8, l: usize)u32
msg_peek()i64
msg_recv(p: *mut u8, cap: usize)i64

#WebRTC data channels (manifest rtc)

FunctionReturns
rtc_available()u32
rtc_ice(p: *const u8, l: usize)u32
rtc_offer()u32
rtc_accept_offer(p: *const u8, l: usize)u32
rtc_accept_answer(peer: u64, p: *const u8, l: usize)u32
rtc_send(peer: u64, p: *const u8, l: usize)u32
rtc_close(peer: u64)—
rtc_poll(p: *mut u8, cap: usize)i64

#Display (main instance only)

FunctionReturns
display_info(p: *mut u8, cap: usize)i64
frame_stats(p: *mut u8, cap: usize)i64
present_config(mode: u32, latency: u32)i32
frame_cap(fps: f64)i32
fullscreen(mode: u32)i32
hdr_metadata(p: *const u8, l: usize)i32

#Manifest assets

FunctionReturns
asset_size(p: *const u8, l: usize)i64
asset_read(p: *const u8, l: usize, off: u64, dst: *mut u8, cap: usize)i64

#The GPU protocol

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.

#Input events

input_poll fills 24-byte records (sg_abi::input::RawEvent): a kind, a code, x and y, modifier bits and flags.

KindValueMeaning
KEY_DOWN, KEY_UP1, 2code indexes KEY_NAMES (1-based, 0 unknown), which are DOM KeyboardEvent.code names, so web input code ports unchanged. FLAG_REPEAT marks auto-repeat.
TEXT3code is a Unicode scalar the user typed.
MOUSE_MOVE4Raw relative motion, locked or not.
CURSOR5Cursor position in physical pixels.
BUTTON_DOWN, BUTTON_UP6, 7DOM button numbering: 0 left, 1 middle, 2 right, 3 back, 4 forward.
WHEEL8Scroll in lines; positive y is away from the user.
FOCUS9Window focus changed.
RESIZE10New surface size in pixels.
POINTER_LOCK11Pointer lock changed.

Modifiers: MOD_SHIFT 1, MOD_CTRL 2, MOD_ALT 4, MOD_META 8.

#Display status codes

present_config, frame_cap, fullscreen and hdr_metadata return OK 0, NOT_APPLIED 1 (stored, but no HDR swapchain), INVALID -1, UNSUPPORTED -2, DENIED -3, RATE_LIMITED -4 or LOCKED -5 (the player's launch settings win).

#Versioning

InterfaceVersionCompatibility
Module sgno version in the nameA guest that imports a function the host does not provide fails to instantiate, naming the missing import.
sg-gpu protocol2 (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_v11Records 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.