# wrela

> The reference docs of wrela (version 0.1.0, commit 34b6af47a4653b40f4657e167a1fb65869e54db8), an MIT-licensed language, compiler and engine for games that run in the browser. Each page is Markdown. `index.json` lists every public item and every section of the spec, with its page, anchor and source file; `llms-full.txt` is every page in one file. Source: https://github.com/rywible/wrela

## The language

- [wrela: the language](spec/language/index.md): The one prose reference for the language, as it stands.
- [How wrela differs from Rust and TypeScript](spec/language/how-wrela-differs-from-rust-and-typescript.md): No references and no lifetimes: a parameter reads its argument in place, and `mut` marks a change at the call site, `step(mut g)` (§6.2).
- [How to read this](spec/language/how-to-read-this.md): Rules cite the decisions they came from (D-NNN), for history.
- [1. What wrela is](spec/language/1-what-wrela-is.md): One language for CPU and GPU (D-005, D-009).
- [2. Lexical structure and statements](spec/language/2-lexical-structure-and-statements.md): Keywords are listed in `spec/lexical.md` (L11), including the reserved ones, which no feature uses (`dyn`, §18).
- [3. Items](spec/language/3-items.md): Named arguments are optional, Kotlin-style (D-039).
- [4. Types](spec/language/4-types.md): `&T` doesn't exist (D-064).
- [5. Units (T1)](spec/language/5-units-t1.md): Unit suffixes are constants (D-025).
- [6. Memory](spec/language/6-memory.md): Memory-safe without a garbage collector (D-014).
- [7. Generics and traits](spec/language/7-generics-and-traits.md)
- [8. Effects and contexts](spec/language/8-effects-and-contexts.md): Effects (D-072): `alloc`, `io`, `trace`, `nondet`, `recursion`, `host`, `panic`.
- [9. Attributes](spec/language/9-attributes.md): `@` attributes are a closed set defined by the language (D-037, D-081).
- [10. Build-time constants and embedded data (T1)](spec/language/10-build-time-constants-and-embedded-data-t1.md): Constants (§3).
- [11. Numerics](spec/language/11-numerics.md): CPU code always uses strict IEEE floats (D-074).
- [12. GPU code](spec/language/12-gpu-code.md)
- [13. Derived interpretations](spec/language/13-derived-interpretations.md): The compiler derives these from any function that qualifies under the effect table (§8).
- [14. Determinism (T1)](spec/language/14-determinism-t1.md): `@deterministic` is an effect constraint on functions and function types (D-052).
- [15. Errors (T1)](spec/language/15-errors-t1.md): Recoverable failures are `Result<T, E>`, propagated with `?` (D-061).
- [16. Concurrency (T2)](spec/language/16-concurrency-t2.md): Threads: any owned value can move to another worker, and data shared between workers can only be read (§6.12).
- [17. The stdlib boundary](spec/language/17-the-stdlib-boundary.md): The compiler knows three things (D-050): the language, a closed list of stdlib items, and the execution targets.
- [18. What wrela leaves out](spec/language/18-what-wrela-leaves-out.md): References as types, and with them lifetime parameters, variance, `'static` and higher-ranked bounds (D-058, D-064)
- [19. A tier-0 program](spec/language/19-a-tier-0-program.md): This is the subset needed for "hello field" (tier 0, D-088): a field, a derived gradient, one compute kernel and one fragment shader.
- [20. Tiers at a glance](spec/language/20-tiers-at-a-glance.md)
- [21. Settled in milestone 2](spec/language/21-settled-in-milestone-2.md): Packages and dependencies (D-087): §3, *Modules and packages* (`mod.packages`).
- [22. Lifted builds, provenance and the tools (milestone 3)](spec/language/22-lifted-builds-provenance-and-the-tools-milestone-3.md): An agent or a person changes a field by its numbers.
- [wrela lexical structure](spec/lexical.md): Normative (D-104).
- [wrela grammar](spec/grammar.md): The language's syntax, normative, in EBNF over spec/lexical.md's tokens.

## std

- [std::alloc](std/alloc.md): std's allocator: the heap that `Vec`, `String` and `Box` live in (language.md §6.9).
- [std::arena](std/arena.md): Arenas and handles (language.md §6.8): how long-lived relationships are written.
- [std::audio](std/audio.md): Audio (language.md §6.13, D-004, D-072): a program has one voice, which the audio thread renders a quantum at a time, and rings that carry events to it.
- [Built-in functions](std/builtins.md): The functions every program has without an import.
- [std::cache](std/cache.md): Results cooked from inputs, cooked again when the inputs change (language.md §6.19): where a program kept a flag a cache, and passed a change on to each cache cooked from what changed by hand.
- [std::cmp](std/cmp.md): Comparison (language.md §3): `==` and `!=` for types that declare `Eq`, and `<`, `<=`, `>` and `>=` for types that declare `Ord`.
- [std::collections](std/collections.md): Collections (language.md §6.9, §17): `Vec`, and moving values out of places with `swap` and `replace`.
- [std::derive](std/derive.md): Derived interpretations (language.md §13): the compiler derives them from the body of any function that qualifies.
- [std::field](std/field.md): Fields: functions over space (language.md §17).
- [std::fmt](std/fmt.md): Formatting (language.md §4): `Format`, which `f"…"` calls for each `{value}` or `{value:spec}`.
- [std::gpu](std/gpu.md): GPU resources, entry-point builtins, and the CPU calls that record GPU work (language.md §12, §6.13, D-102).
- [std::handoff](std/handoff.md): Hand-offs (language.md §6.17): the latest value from one thread to another.
- [std::hash](std/hash.md): Hashing (language.md §6.11): `StateHash`, a whole value's checksum, derived field by field.
- [std::host](std/host.md): Asynchronous capabilities supplied by the application host.
- [std::input](std/input.md): Input (language.md §6.15's polled requests' neighbour): the pointer, keyboard and gamepad events the host has queued since the program last read them.
- [std::io](std/io.md): Requests to the host (language.md §6.15): the program's storage ("bytes at a path") and fetching files of its build.
- [std::job](std/job.md): Work over several frames (language.md §6.18): a `@job fn` whose body runs a part a frame, to each `yield`.
- [std::lift](std/lift.md): Lifted literals (language.md §22): in a lifted build (`wrela build --lift <package>`), each `f32` literal of the chosen packages is read from a table, not built into the code, so a tool can change a number while the program runs: a write to the table, never a rebuild.
- [std::math](std/math.md): The transcendental functions for CPU code (language.md §11): compiled to WASM with the program, never taken from the host, so every host computes the same bits (D-015, D-074).
- [std::mem](std/mem.md): Raw memory: what std's unsafe core is built on (language.md §6.14).
- [std::net](std/net.md): Networking's logic (language.md §12): an ordered log for each room.
- [std::pack](std/pack.md): Packing (language.md §6.11): `Pack`, derived field by field, as small as the values allow, for bytes that both ends read with the same build: a network message, a durable log record.
- [std::par](std/par.md): Parallel work (language.md §6.12, §6.17, D-062).
- [std::prelude](std/prelude.md): The prelude: in scope in every module, with the built-in types and functions.
- [std::quat](std/quat.md): Rotations as unit quaternions (language.md §4: `Quat`, tier 1), on the CPU and the GPU alike.
- [std::reload](std/reload.md): One build in place of another, in the same page or process (language.md §22).
- [std::serialize](std/serialize.md): Saving and loading (language.md §6.11): `Serialize`, derived field by field, with each field's name and each variant's name in the bytes.
- [std::stage](std/stage.md): Fields built at runtime (language.md §7, D-029, D-053): a tape of operations, which `interpret` evaluates.
- [std::string](std/string.md): Text (language.md §4): `Text`, the type of string literals, a `Copy` handle to UTF-8 in the build; `String`, UTF-8 on the heap, which can grow; and `str`, a borrowed run of UTF-8, which either passes as.
- [std::tick](std/tick.md): The ticker (language.md §6.17): a fixed-rate step on a thread of its own.
- [std::time](std/time.md): The clock (M6): how long the program's work takes, read while it runs.
- [std::transform](std/transform.md): Transforms as matrices, on the CPU and the GPU alike: what a skeleton, a camera or a shadow map is built from.
- [std::units](std/units.md): Units (language.md §5): constants in SI.

## engine

- [engine::acoustics](engine/acoustics.md): Acoustics (sketch 01 §7): engine code, not stdlib (D-081).
- [engine::air](engine/air.md): The air (#28 §6): a physically based sky and aerial perspective (Hillaire 2020, "A Scalable and Production Ready Sky and Atmosphere Rendering Technique").
- [engine::anatomy](engine/anatomy.md): An anatomy kit: building blocks at the level a creature artist works in (muscles from origin to insertion, bones that show at the joints, a canid's skull, ears and paws, colour that changes across a part), and a canine built from them from a few proportions.
- [engine::bake](engine/bake.md): A history baked (M6 §3): "bake the decisions, recompute the consequences" (spike 17).
- [engine::character](engine/character.md): Characters drawn (#28 §5.4, §7, §8): a creature's realized mesh with its normals and colours cooked in when it's realized, so no pixel evaluates its field; skinned by its palette; shaded in B's cel treatment (two bands, a narrow terminator, a rim where the sun is behind, a line where the form turns away; `cel`); drawn a second time into the motion target, from this frame's palette and the last, so temporal AA reprojects it by its own motion; and cast into the moving shadow map every frame.
- [engine::construction](engine/construction.md): Construction leaves values which are continuous fields, usable by CPU queries and GPU cooking.
- [engine::creature](engine/creature.md): Creatures (sketch 01 §3, and the authoring surface of M3): a skeleton, and parts, which are fields in their bones' spaces, joined in order across the joints.
- [engine::digits](engine/digits.md): Digits: toes (or fingers, or a hoof's halves) set side by side, each a short sweep from its base through its knuckle to a domed tip, from a few numbers an artist reads off a paw: how far apart the outermost are, how long and thick the middle ones are, how much the toes fan out, how far they curl down at the knuckle, and how much smaller the outer ones are.
- [engine::events](engine/events.md): The events of a history: the map's gales, fires, falls, strikes and the wind's gaps, each in its year (`events`), and what each leaves on the trees and on the land's memory.
- [engine::floor](engine/floor.md): The floor kit: what a floor's program uses to stream its world round the player and keep its caches, with none of a floor's own content (its map, ground, history, kinds, tuning).
- [engine::footing](engine/footing.md): Where a player can stand, and how fast they go (M6 §5): one rule for the sim's collision, the interest check's walkers and the map lens's reachability, so what the check says can be reached can be walked to.
- [engine::gait](engine/gait.md): A creature walking on terrain (#28 §8, D-023): a procedural gait whose speed and turn come from a path; each foot planted where a raycast against the terrain field meets the ground, and held there until it lifts; two-bone IK per leg; the pelvis lowered to the lowest plant; and secondary motion, a damped spring per bone of the head's and the tail's chains.
- [engine::grass](engine/grass.md): Grass (#28 §4): blades of geometry round the eye, placed on the GPU each frame (a kernel into an `Append` buffer, then an indirect draw), so they follow the camera.
- [engine::grow](engine/grow.md): A floor's history (M6 §3), from spikes 16's and 17's: centuries over a map, on the CPU, from the land up.
- [engine::history](engine/history.md): Histories run at build time or at load.
- [engine::impostor](engine/impostor.md): Trees far away (#28 §4): impostors in the mid-distance, density volumes beyond, each cooked at load from a kind's near representation and lit as its cards are, so the levels match where they meet (AC4: the silhouette and the light through it, spike 03).
- [engine::interest](engine/interest.md): The interest check (M6 §4, from spike 17's): from every place a player can stand on a floor, what draws the eye somewhere new, and how a player who follows the draws gets on.
- [engine::landform](engine/landform.md): Landforms: a land's relief as its rock, the uplift under it and its water made it, worked out at build time over a grid.
- [engine::light](engine/light.md): Light that feels real (#28 §5, §6; #44): a low sun through the air (`air`), its sky, and the air between the eye and what it sees (aerial perspective); how the world's surfaces are lit: continuous light (the world's gouache, #28 §7), or two bands and a soft terminator (characters' cel).
- [engine::lit](engine/lit.md): What every surface's shading reads (#28 §5), as one parameter (a group, language.md §12): the frame's camera and light, the sun's shadows, the probes' sky light, the clouds' shadows and the air.
- [engine::lod](engine/lod.md): Levels of detail without popping (the owner's ask, beyond #28's scope for M5): a plant is drawn at a level its size on screen and its distance ask (its cards' levels, then an impostor, then a volume, then nothing), and near a switch it's drawn both ways, each keeping its share of the pixels.
- [engine::loft](engine/loft.md): Lofts: a form around a straight axis, given by its cross-sections.
- [engine::look](engine/look.md): How a creature is drawn (sketch 02 §1): ordinary engine data.
- [engine::noise](engine/noise.md): Cheap value noise for content that's cooked or placed (#28 §3, §4): the same on the CPU and the GPU, bit for bit where their arithmetic is (a lattice's hash is integer arithmetic).
- [engine::paint](engine/paint.md): The look's passes (#28 §7): the owner's pick, gouache and light for the world, cel for characters.
- [engine::perform](engine/perform.md): Performances (spike 14, #48): how a score is played.
- [engine::physique](engine/physique.md): Physical properties from a creature's field (sketch 01 §4): what the simulation reads, so it's computed by `@deterministic` code and comes out the same on every client (D-052).
- [engine::piano](engine/piano.md): A piano (spike 14, #48), synthesized by modes: each string's partials are damped resonators, struck by a hammer and stopped by a damper, as engine::acoustics' strikes are.
- [engine::piano_grand](engine/piano_grand.md): Written by `wrela audio model examples/piano/build/reference2` (spike 14, #48); edit the tool, not this file.
- [engine::place](engine/place.md): A floor's map (M6 §2): what its author decides, as types.
- [engine::plant](engine/plant.md): Plants (#28 §4, §9): trees and shrubs as fields, authored like creatures.
- [engine::player](engine/player.md): The stand-in player and its camera (M6 §5): a body the climber's height that walks at 1.4 m/s and runs at about 5 m/s over a floor's ground, in the sim's tick, where `footing`'s one rule lets it; and the third-person camera that follows it, pulled in when a trunk, a stone or a wall comes between them.
- [engine::present](engine/present.md): Presentation's view of the sim (#43 §6): the snapshots a frame reads from the ticker's hand-off, kept three deep, and where between two of them a frame draws.
- [engine::probes](engine/probes.md): Sky light, occlusion and bounce (#28 §5.2, §5.3; spike 05): a grid of probes baked at load from cooked fields, then a strip of them again each frame, and read by every surface's shading.
- [engine::quadruped](engine/quadruped.md): A four-legged body to start from: a skeleton and named parts for a torso, a neck, a head, four legs and a tail, all from a few proportions, so an author begins with a sound animal and spends their time on what makes it this one.
- [engine::realize](engine/realize.md): 1.
- [engine::render](engine/render.md): Drawing creatures (#43 §8, D-089, D-097): a realized mesh (`realize`), posed on the GPU by its type's `Poser`, skinned by linear blending of four bones, cast into the sun's shadow map, and shaded per pixel by its field: evaluated at the rest position, under the triangle's mask (2 or 3 parts, not 20), with the pixel's footprint, its gradient the normal and its channels what the type's `Look` turns into an albedo and a roughness.
- [engine::rng](engine/rng.md): Seeds and random streams.
- [engine::run](engine/run.md): The driver (#43 §5.1): a world stepped at a fixed rate on the ticker's thread (`std::tick`), through a `Timeline`.
- [engine::score](engine/score.md): Scores (spike 14, #48): what a composer wrote, as values the build makes.
- [engine::senses](engine/senses.md): The senses (vision gap 3: creatures that notice you): what a creature makes of a body near it, by sight and by hearing, and how aware of it that leaves the creature.
- [engine::shadow](engine/shadow.md): Sun shadows (#28 §5.1): two static cascades, one over the near land and one over the far, drawn only when something static changes (spike 15: drawing them every frame cost 11 ms); and a dynamic map over the space round what moves (the creature), drawn every frame.
- [engine::shafts](engine/shafts.md): Sun shafts (#54 §9, Q6: a candidate, kept only if the owner prefers them): the sun's light the air scatters toward the eye where it passes between the crowns.
- [engine::sim](engine/sim.md): The simulation's vocabulary (sketches 01 §6 and 03): sim state is ordinary values, rolled back by cloning and checked by the derived `StateHash` (§6.11).
- [engine::sky](engine/sky.md): The sky's clouds (#28 §6, #31): a field of cloud that drifts with the wind, marched each frame, lit by the air (`air`'s tables), and its shadows on the land.
- [engine::soil](engine/soil.md): The soil: what a place's ground is, how deep, and how well it feeds what grows in it, from the ground's shape, its rock and its water (after the soil production function: Heimsath and others, 1997).
- [engine::sound](engine/sound.md): The mixer (M5.5, #49: "a mixer on the one stereo voice"): every sound a world makes, mixed on the program's one voice (std::audio).
- [engine::spatial](engine/spatial.md): Spatial queries (sketch 03 §3): a grid of positions copied at the start of a tick (D-085), so a system reads them while the entities themselves change.
- [engine::stone](engine/stone.md): Stones (#28 §4): fields, a displaced, faceted oval each (spike 15's boulders), realized to meshes at load by the engine's realization, as creatures are, with their normals and colours cooked in; drawn each frame from the meshes, so no field is evaluated per vertex or per pixel (AC4).
- [engine::sweep](engine/sweep.md): Sweeps: a form along a curved path, given by its sections.
- [engine::temporal](engine/temporal.md): Temporal AA and upscaling (#28 §2): the scene, drawn at a lower resolution and jittered within its pixel each frame (Halton 2, 3), is brought up to the output's resolution by keeping a history at that resolution.
- [engine::terrain](engine/terrain.md): Terrain (#28 §3): one terrain field for a floor, drawn from a clipmap cooked from it on the GPU, and raycast on the CPU by the sim.
- [engine::timeline](engine/timeline.md): The engine's rollback driver (sketch 03 §4), generic over any game's world and inputs.
- [engine::timers](engine/timers.md): Timers (the gameplay paper test §4): work due at a later tick, as data.
- [engine::tower](engine/tower.md): The tower (vision.md, "The lore"): the worlds it ate, each behind a door off an endless stair.
- [engine::vegetation](engine/vegetation.md): Trees and shrubs drawn (#28 §4): each kind of plant cooked once (its leaf cards and its limbs on the GPU); instances of the kinds placed in the world; and each frame, the instances in view sorted by kind and by how they're drawn: near ones as cards at a level by their distance, far ones as impostors, the farthest as volumes (`impostor`).
- [engine::view](engine/view.md): The renderer's camera (#28 §2): what every pass of a frame reads.
- [engine::walk](engine/walk.md): A creature walking on the spot with sketch 01's cycle (`sim::GaitState`), posed by `render::palette`: what the examples and the lens draw, and the record a frame test checks (AC7 of #39: each creature walks for 120 frames).
- [engine::water](engine/water.md): Water (#54 §8): the meres, the streams, the waterfalls and the springs, as one surface.
- [engine::wild](engine/wild.md): The wildwood (#55 AC7, Q9; spike 17's): the forest past the floor's authored square, without end, grown a tile at a time where the player walks, from the place alone.
- [engine::wood](engine/wood.md): A wood that streams (M6 §6, §7): the forest of a floor, its instances loaded a tile at a time into slots and dropped when their tile is, and chosen each frame on the GPU, not the CPU.

## platform

- [platform::host](platform/host.md): Typed application mechanisms over the shared std::host request.
- [platform::net](platform/net.md): Networking (language.md §12): a client's connections to its server's rooms, and a room's journal and connections.
- [platform::presentation](platform/presentation.md): An embedded application's readiness and durable return, independent of game policy.
- [platform::protocol](platform/protocol.md): Shared Wrela session protocol.

## ui

- [ui::draw](ui/draw.md): Drawing: a frame's list of quads (rectangles, rounded or not, ellipses, diamonds, lines and glyphs), each clipped to a rectangle, drawn by one instanced draw in order, later quads over earlier ones.
- [ui::raster](ui/raster.md): Glyphs made from a host's drawing (runtime/browser glyph.ts, `font/glyph`): a character group the baked fonts haven't, drawn by the system's fonts at a few times the fields' size.
- [ui::text](ui/text.md): Text: two fonts as signed distance fields (Inter for the UI, JetBrains Mono for source), baked from ui/fonts when the program is built (ttf.wrela), and laid out a line at a time.
- [ui::ttf](ui/ttf.md): TrueType fonts baked into distance fields when the program is built (§10): each Latin-1 glyph's outline as a signed distance field, its metrics, and the font's kerning, from the font's file (`embed`).
- [ui::widgets](ui/widgets.md): An immediate-mode toolkit: widgets are calls a program makes each frame, which draw themselves and say what the person did to them.