classic-guest

Implements the WASM guest runtime and host-import ABI for classic-wgl ROMs.

1|1|Updated Aug 18, 2021
One-click install
npx skills add https://github.com/guilledk/classic-wgl --skill classic-guest-guilledk
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: classic-guest
Source: https://github.com/guilledk/classic-wgl/tree/main/.agents/skills/classic-guest
Command: npx skills add https://github.com/guilledk/classic-wgl --skill classic-guest-guilledk

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Running untrusted game logic inside the classic-wgl engine requires a sandboxed, cross-platform execution layer. This Skill documents how the classic-guest crate runs compiled WASM modules from ROMs against a stable host SDK, with fuel, memory, and watchdog limits enforced per backend. ## Core Features & Use Cases - Four runtime backends: Wasmi and Wasmtime on native, browser-native WebAssembly for trusted guests, and a Worker-isolated runtime with a terminate watchdog for untrusted web guests, all behind one GuestRuntime trait. - Host-import ABI: a single install_host_imports! macro defines the full SDK surface (entities, sprites, UI, input, camera, lights, pathfinding, bulk terrain noise, field kernels) shared across backends. - Sandboxing: fuel metering, memory caps via StoreLimits, and a wall-clock Worker watchdog protect the host from untrusted guest code. - Use Case: When adding a new host import (e.g., a new UI element type), follow the documented steps: add the GuestHost method in sdk.rs, register it in the shared macro plus the web and worker OP tables, and add a WAT test that runs against every backend. ## Quick Start Ask the assistant to add a new host import to the classic-guest runtime following the documented SDK workflow.

Frequently Asked Questions about classic-guest

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I add a new host import to a WASM guest runtime?

Add the method to GuestHost in sdk.rs, register it in the shared install_host_imports! macro plus the web and worker OP tables, marshal strings with the read_str/write_str helpers, and add a WAT test in tests/guest.rs that runs against every backend.

How do I sandbox untrusted WebAssembly code in Rust?

Enable fuel metering with Config::consume_fuel and Store::set_fuel per frame, cap memory with StoreLimitsBuilder and trap_on_grow_failure, and on web run the guest in a Worker with a wall-clock watchdog that terminates on overrun.

Wasmi vs Wasmtime for embedding WASM in a Rust game engine?

Wasmtime runs on native only and is the default native backend, while Wasmi works on both native and wasm targets and serves as the fallback when SharedArrayBuffer is unavailable. Both share the same GuestRuntime trait and import macro here.

Can browser WebAssembly enforce CPU limits on untrusted code?

Browser WebAssembly has no fuel API, so the WorkerWasmRuntime enforces a wall-clock budget per call and terminates the Worker on overrun, surfacing it as a fuel-exhausted error. Trusted guests skip these limits for speed.

Why does my WASM guest trap with OutOfFuel?

The guest exceeded its per-frame fuel budget set before each update call. This only applies to untrusted guests; ROMs marked trusted in the manifest skip fuel metering entirely.