Clunkyard WebAssembly ABI 4

A WebAssembly robot runs inside Wasmtime under build/clunkyard-wasm-host, which links the robot core (sdk/core) natively and speaks protocol 2 for the robot. The robot calls the core through imports from the clunkyard module, one for each API entry, and the core reads each hello and state and writes the ready and each act. There is no WASI context and no other import.

abi4/clunkyard.h is the C SDK. It is generated from protocol/v2/api.json (make api); do not edit it. It declares every import at the name libclunkyard has, without the handle (an instance is one robot), with the plain names (cy_sensors_nearest) aliasing the latest version, and the records and constants the core uses.

#include "clunkyard.h"

static void turn(void) {
  cy_contact target;
  if (cy_sensors_nearest(&target) == CY_OK) {
    cy_gun_aim_heading(target.bearing);
    cy_gun_fire();
  }
}

CY_ROBOT(NULL, turn)

The same surface, generated beside it, for the other languages:

Each declares the imports at their C names in Rust (cy_sensors_nearest) and at their import names elsewhere (sensors_nearest), with the records (a view over the record's bytes in AssemblyScript, field offsets as globals in WAT) and the constants. Only the C header has the DSL words import.

The module

A module exports:

memory
clunkyard_start() -> i32    once, after the hello; 0 to play on
clunkyard_turn() -> i32     once a state; 0 to send the act

CY_ROBOT(start, turn) writes both; start may be NULL. Its imports must all be clunkyard.* functions with exactly the generated signatures. An unknown name, a wrong signature or any other import fails at link, before the hello: that is the version negotiation. A module without clunkyard_start, such as one built for ABI 1 to 3, is refused.

Every import returns a status (CY_OK 0, CY_NONE 1 for absent, CY_SHORT 2 for a short buffer, negative for an error) and writes its result through pointers into guest memory. The host bounds-checks every pointer and length against memory as it is at the call, so a module may grow its memory.

cy_robot_seed(&seed) is the host's own import, not the core's: the seed for the robot's own randomness, from CLUNKYARD_ROBOT_SEED, which the referee derives from the match seed and the robot's id. It defaults to 1.

Metering

Fuel counts the guest's own operators. Each import also takes a nominal fee from the turn's fuel, at once: 32 a call, whatever the core does for it, and 1 a byte for the data it moves (text in, a list's records, text out). The fees are frozen per season in rates/s3.json (reflex.imports); make import-costs checks that they keep the core's real work inside the CPU cap. An import that would overdraw takes the rest of the fuel, is not answered, and the turn forfeits WASM_TURN_FUEL.

Work the core does natively sits outside fuel, so the host also holds a turn to 256 import calls and 200 ms of its thread's CPU; over either, the turn forfeits WASM_CPU. The season's limits are reflex.wasmFuelPerTurn and reflex.wasmFuelPerMatch in rates/s3.json: a floor of the calls a turn makes to act plus the thinking the interpreted DSL allows.

Building

scripts/build-wasm.sh

builds build/clunkyard-wasm-host and the example robot, build/wasm-sentry-c.wasm, from bots/c/sentry.c. It needs cc, Clang with the wasm32 target, the Wasmtime C API (WASMTIME_PREFIX, default /usr/local) and the robot core: the image's /opt/clunkyard/sdk/lib/libclunkyard.a, or cargo to build one from sdk/core. A robot is freestanding C:

clang --target=wasm32 -mbulk-memory -std=c11 -O2 -nostdlib -Isdk/wasm/abi4 robot.c \
  -Wl,--no-entry -Wl,--export-memory -o robot.wasm

With no libc, a struct copy or a zeroed array needs memcpy or memset; -mbulk-memory lowers them to memory.copy and memory.fill, which the host runs. Recent Clang turns it on by default; Clang 18, the image's, does not.

The Rust starter in src/public/starters/rust-wasm uses the Rust surface. The DSL -wasm builds (scripts/build-dsl-wasm.sh) lower Vane, Cadence and Glyph to the same ABI.

Running the host by hand

build/clunkyard-wasm-host robot.wasm \
  --init-fuel 250000 --turn-fuel 5807 --match-fuel 10452600 \
  --memory-bytes 4194304 --table-elements 256 --wasm-stack-bytes 262144 \
  --cpu-ms 200 --import-calls 256 < protocol/v2/fixtures/2d-classic.ndjson

The environment sets the same limits (CLUNKYARD_WASM_INIT_FUEL, CLUNKYARD_WASM_TURN_FUEL, CLUNKYARD_WASM_MATCH_FUEL, CLUNKYARD_WASM_MEMORY_BYTES, CLUNKYARD_WASM_TABLE_ELEMENTS, CLUNKYARD_WASM_STACK_BYTES); the command line takes precedence. Each act carries the turn's fuel (wasmFuel), the match's (wasmFuelTotal), memory and the import calls (wasmImports). A budget exhausted, a trap or memory growth refused ends the robot with a structured failure.

Names

Every entry of the robot API 2.0.0 in WebAssembly (C). names.md has every language side by side.

Download this page as Markdown