Guides
Each guide covers one subsystem's Rust API and where it differs from SHAG. The behaviour itself, such as which cvars exist, what a shader keyword does or what a snapshot holds, is in SHAG's manual, linked at the top of each guide.
| Guide | Covers | SHAG's page |
|---|---|---|
| Cvars and console | core::cvar, console, debug::debug_console | Cvar system, Console system |
| Input | input | none yet |
| Packages and maps | loader::{pk3, bsp, shader, texture} | PK3 filesystem, BSP system, Shader system, Skybox system |
| Models and animation | loader::model, animation, world | Model loading, Pickup system |
| Rendering | rendering, lighting, effects, babylon | Render variables, Lighting system |
| Audio | audio | none yet |
| Networking and lobby | shagger_shared::net, network, lobby | Networking, Lobby server |
| Collision and physics | shagger_shared::collision, physics, movement | Physics system, Movement system |
| Viewport and weapons | camera, viewport, weapon | Camera system, Viewport effects, Weapon system |
| UI | ui | none yet |
| Demos and highlight reels | shagger_shared::demo | none yet |
| JavaScript parity | shagger_shared::{js, fdlibm, json, math_random} | none: this is the port's own |
| Native runtime | core::{crash_report, console_log, atomic_file, join}, TLS | none: this is the port's own |
Conventions across the API
- Names follow the TypeScript. A Rust item keeps its TypeScript name in snake case, and its doc comment quotes the TypeScript name in backticks (
`Cvar.init()`), so a search for either finds it. - The game owns I/O and the clock. Where SHAG relies on the browser's event loop, the Rust port is a state machine the game drives: it passes in the time (
wallmilliseconds forDate.now(),monomilliseconds forperformance.now()) and polls for what happened. Threads that block (sockets, downloads, sound) report through channels, and nothing a frame calls blocks. - The game's parts come in through traits and closures. The engine does not know Washoi's events, files or settings. It asks for them: an
EventCodecfor snapshot events, afetchclosure for files out of the packages, a context typeCfor console commands. - Axes are Babylon's in public, Q3's inside. As in SHAG, collision and map code takes and returns y-up vectors and works in Quake's z-up space internally.
f64where JavaScript computes. JavaScript numbers are doubles. Simulation and protocol code keepsf64wherever the TypeScript does arithmetic, and narrows to the wire type only where the TypeScript writes bytes. File data stays in the type it is stored as (f32in a BSP) and widens where the TypeScript computes with it.