@aethervtt/shard-project 0.0.1 → 0.2.0

package/dist/docs.js

@@ -7,6 +7,7 @@ import { allComponents } from "@aethervtt/shard-core";
 import { allGenerators } from "@aethervtt/shard-procgen";
 import { saveJsonSchema } from "@aethervtt/shard-save";
 import { prefabJsonSchema, sceneJsonSchema } from "@aethervtt/shard-scene";
+import { capturePlanJsonSchema, perfRecordJsonSchema } from "@aethervtt/shard-verify";
 import { BUILTIN_PLUGINS, manifestJsonSchema } from "./manifest.js";
 const GENERATED_START = "<!-- shard:generated -->";
 const GENERATED_END = "<!-- /shard:generated -->";
@@ -343,9 +344,15 @@ Add \`"sprite"\` to \`plugins\` in \`shard.json\`. 2D uses the same renderer as
    "duration": 0.1 }, ...], "loop": "loop", "events": [{ "frame": 2, "name": "step" }] }\`, then
    \`"sprite/SpriteAnimation": { "clip": { "path": "assets/walk.clip.json" } }\`. Read events with
    \`world.reader(SpriteAnimationEvent)\`.
-4. Tilemaps: \`level.tilemap.json\` layers are base64 u16 tiles (atlas region + 1, 0 empty), and
-   \`"sprite/Tilemap": { "atlas": ..., "data": ..., "tileSize": [1, 1] }\`. Edit at runtime with
-   \`setTile(world, map, x, y, tile)\`; only that chunk re-uploads.
+4. Tilemaps: \`level.tilemap.json\` names tiles by atlas region in a \`palette\`, and stores each layer
+   as \`chunks\` of rows: \`"0,0": ["grass*12 stone*4", "grass stone:fx . water*13"]\` (runs of
+   \`name[:flags][*count]\`, \`.\` empty, flags \`fx\`/\`fy\`/\`r90\` joined by \`+\`), then
+   \`"sprite/Tilemap": { "atlas": ..., "data": ..., "tileSize": [1, 1] }\`. Read and edit cells by
+   name with MCP \`tilemap_read\` / \`tilemap_edit\` (live; \`save: true\` writes the file) or
+   \`shard tiles read|edit\`; \`shard tiles <file> --encoding base64\` compacts a big generated map.
+   In code: \`setTile(world, map, x, y, data.tileId('stone'))\`; only that chunk re-uploads. On a
+   tabletop, add \`"render/GroundLayer": { "band": 10 }\` and lay it flat (\`tilemapOnGround()\`'s
+   rotation): it draws among the ground bands, lit by 3D lights, and picks return the cell.
 5. Pixel art: \`"render/PixelPerfect": { "pixelsPerUnit": 16 }\` on an orthographic camera.
 6. Check: \`shard validate\`, MCP \`preview_asset\` on the atlas (regions outlined and numbered) or
    the clip, and \`render.describe\` \u2192 \`sprites\` (draw calls, sprites per layer, tilemap chunks).
@@ -740,6 +747,9 @@ whose path no longer exists is kept in the file and logged as \`prefab/stale-ove
 `,
   "add-sound.md": `# Add sound
 
+For authored events, mixers, snapshots, acoustics, adaptive music and offline previews, read
+[the audio guide](../audio.md).
+
 Add \`"audio"\` to \`plugins\` in \`shard.json\`. Drop \`.ogg\`, \`.mp3\`, \`.wav\`, or \`.flac\` files under
 \`assets/\` and run \`shard import\`: each is an \`AudioClip\` (MCP \`get_asset\` shows duration, channels,
 sample rate, codec). Files stay compressed. Clips under \`music/\` stream; set \`"mode": "stream"\` in
@@ -758,7 +768,7 @@ the \`.meta\` for other long files, and \`loopStart\`/\`loopEnd\` (seconds) for
 
 - Sources autoplay; set \`playing\` to start or stop one. A clip that doesn't loop clears
   \`playing\` at its end and sends \`audio/AudioFinished\`. Spatial sources follow their transform;
-  the listener is the first \`audio/AudioListener\` (put it on the camera).
+  the fallback listener has the lowest entity ID; setAudioListener selects one explicitly.
 - \`rolloff\`: \`inverse\` (default, natural), \`linear\` (silent at \`maxDistance\`; past it the source
   goes virtual and holds no voice), \`exponential\`. \`panning\`: \`equal-power\` or \`hrtf\`.
 - One-shots from code: \`playSound(world, weapon.sound, { position: muzzle, bus: 'sfx' })\` from
@@ -1158,6 +1168,81 @@ orbit down to 0.4 m vertex spacing on the ground. Put the camera in the planet's
   \`describe_terrain\` shows \`detail.lodBias\` above 1 while it's coarsening.
 - Give it air: \`"render/Atmosphere": {}\` on the planet entity takes the planet's radius, draws
   the sky from the ground to orbit, and hazes distant terrain (tune-an-atmosphere.md).
+- Rocks, trees and grass: give biomes (or the planet) a scatter set (scatter-props-and-foliage.md).
+- A bounded landscape you shape (roads, valleys) rather than a whole planet: make-a-terrain.md.
+`,
+  "make-a-terrain.md": `# Make a heightfield terrain (an open world)
+
+A bounded landscape, 256 m to 64 km a side, shaped on purpose: a \`*.terrain.json\` file stacks
+height layers (noise, heightmap images, splines that flatten, raise or carve) and paint layers, and an
+entity with \`terrain/Terrain\` (it brings \`transform/Grid\`) draws, streams and collides with it. Add
+\`terrain\` to \`shard.json\`'s plugins (with \`render/forward\` and \`physics3d\`). The file's schema is
+\`.shard/schemas/terrain.schema.json\`; coordinates are metres from the terrain's corner.
+
+\`\`\`json
+{ "size": [4096, 4096], "spacing": 1, "heightRange": [-200, 800], "seed": 7,
+  "splines": { "road": { "points": [[120, "ground", 300], [900, "ground", 420]], "width": 8, "falloff": 14 } },
+  "height": [
+    { "noise": { "path": "assets/noise/hills.noise.json" }, "scale": 260 },
+    { "image": { "path": "assets/terrain/valley.height.png" }, "at": [2048, 1800], "size": [1200, 900],
+      "rotation": 20, "range": [0, 140], "blend": "max", "falloff": 80 },
+    { "spline": "road", "mode": "flatten" } ],
+  "layers": [{ "name": "grass" }, { "name": "rock", "triplanar": true }, { "name": "gravel" }],
+  "paint": [{ "layer": "grass" }, { "layer": "rock", "slope": [32, 90], "blend": 6 },
+            { "layer": "gravel", "spline": "road", "blend": 2 }] }
+\`\`\`
+
+- Sizes are whole numbers of roots: 64 \xD7 spacing \xD7 2^k a side, at most 64 roots (2048, 4096 or
+  16384 m at 1 m spacing). \`heightRange\` is what the bake stores in 16 bits: keep it close to the
+  real range (a clipped height is \`terrain/out-of-range\`).
+- Heightmaps are 16-bit grayscale PNGs (name them \`*.height.png\`, or set \`"importer": "heightmap"\`
+  in the \`.meta\`) or \`.r16\`/\`.r32\` raw files with \`width\` and \`height\` in the \`.meta\` settings.
+- \`shard import\` bakes stale terrains into \`.shard/cache/terrain\` (only the blocks an edit touches);
+  \`shard terrain bake\` forces it, \`shard terrain stats\` shows size on disk and time per block.
+  \`shard dev\` rebakes after you save the file.
+- Standing on it: characters, dynamic bodies, \`NavAgent\`s and \`terrain/TerrainAnchor\`s get
+  heightfield colliders within \`colliderRadius\`, exactly the drawn ground. \`terrainHeightAt(world,
+  terrain, x, z)\` is the ground under a point; \`await loadTerrainRegion(world, terrain, rect)\` first
+  makes it exact away from anchors (spawn points). A plain \`nav/NavMesh\` paths on it.
+- Rocks and trees: \`terrain/Terrain.scatter\` takes a \`*.scatter.json\` (scatter-props-and-foliage.md).
+- Check it: MCP \`terrain_map\` (\`{ "mode": "layers" }\`, or \`"bake"\` to see which blocks an edit
+  rebuilt), \`sample_terrain\` (\`{ "points": [[120, 300], [124, 300]] }\`: is the road flat across?),
+  and \`describe_terrain\` (bake, pages, collider tiles). Overlays \`terrain-lod\`, \`terrain-pages\`
+  and \`terrain-colliders\`.
+`,
+  "scatter-props-and-foliage.md": `# Scatter rocks, trees and grass
+
+Add \`scatter\` to \`shard.json\`'s plugins. A \`*.scatter.json\` (a \`scatter/ScatterSet\`) holds rules;
+put it on a biome (\`"scatter": { "path": "assets/scatter/forest.scatter.json" }\` in a \`*.biome.json\`:
+it applies where that biome dominates), on the planet (\`terrain/Planet.scatter\`: everywhere), or on
+a flat level's ground mesh (\`scatter/ScatterSurface\` next to its \`render/Mesh3d\`).
+
+\`\`\`json
+{ "rules": [
+  { "name": "trees", "items": [{ "generator": "shard/Tree", "variants": 6 }],
+    "density": 0.02, "spacing": 4, "masks": { "slope": [0, 25] }, "scale": [0.7, 1.3],
+    "collider": "ball", "range": 400 },
+  { "name": "grass", "kind": "foliage", "items": [{ "generator": "shard/GrassClump", "variants": 4 }],
+    "density": 5, "avoid": ["trees"], "range": 50 } ] }
+\`\`\`
+
+- Two kinds. \`prop\` rules spawn entities (\`scatter/Prop\`, with LODs and an optional collider) in
+  chunks around cameras and \`TerrainAnchor\`s; \`foliage\` rules are GPU instances near cameras only,
+  millions of them, no entities. Grass, flowers and small pebbles are foliage; anything you bump into is a prop.
+- Items are mesh generators (\`shard/Rock\`, \`shard/Tree\`, \`shard/Bush\`, \`shard/GrassClump\`,
+  \`shard/Crystal\`, or a project's) with \`params\` and \`variants\` (4\u20138 shapes read as unique), or
+  prefabs. Without a \`material\`, engine generators get \`scatter/Vegetation\` tinted for their kind.
+- \`density\` is per m\xB2 where the masks pass, \`spacing\` the least distance between items. Too dense
+  for the spacing is \`scatter/density-too-high\` (it says the most that fits). Rule order is priority:
+  \`avoid\` names earlier rules. \`align\` 0 stands items upright, 1 along the slope. \`sink\` buries
+  them by a share of their height.
+- Placement is a global jittered lattice: the same seed puts the same tree in the same place on every
+  visit and machine. A prop the game despawns stays gone (saved in \`scatter/Removed\`).
+- Check it: MCP \`preview_generator\` with \`{ "generator": "assets/scatter/forest.scatter.json" }\`
+  shows the set on a 64 m patch from above and at eye level; \`describe_scatter\` gives per-rule
+  counts; \`sample_scatter\` lists props near a point (\`{ "entity": "landing-pad", "radius": 10 }\`).
+  Overlays \`scatter\` and \`foliage-chunks\` show placements in a screenshot.
+- \`scatter/Budget\` caps props spawned per frame; \`scatter/Wind\` sways foliage and leaves.
 `,
   "tune-an-atmosphere.md": `# Tune an alien sky
 
@@ -1237,6 +1322,47 @@ g.label(position, 'target', [1, 1, 1, 1])
 - \`shard screenshot <scene> --out shot.png --frames 60\` renders headless (no window needed).
 - With the MCP server: \`screenshot\` returns the image; \`step\` advances frames; \`press\`/\`hold\`
   drive input; \`query_entities\` / \`get_entity\` read state; \`recent_errors\` shows what failed.
+`,
+  "check-in-browsers.md": `# Check it in real browsers
+
+Headless screenshots are for regressions. Filtering, color and canvas compositing only show in a
+browser, and so do real frame times.
+
+1. Write a plan (\`.shard/schemas/capture-plan.schema.json\`): the URL (\`shard dev\`'s, or a host
+   page), browsers, DPRs, viewport, and shots with a \`state\` the page's
+   \`installCapturePage(app, { apply })\` understands. \`shard dev\` pages take shots as they are.
+2. \`shard capture plan.json --out captures/latest --json\` takes them, runs \`steps\` and their
+   \`expect\` checks in every client, and records each \`scenario\` (\`records/*.json\`).
+3. \`shard compare captures/latest --approved captures/approved --json\` diffs against approved
+   images (\u0394E2000 and SSIM) and writes \`report.html\`. Changed or new shots fail.
+4. A change you meant: \`shard approve <shot> --reason "why it looks different"\`. A change you
+   didn't: fix it. Approvals without a reason are refused.
+5. \`shard perf-check captures/latest/records --plan plan.json\` fails on a broken threshold and
+   names the metric, the value and the budget.
+
+With the MCP server attached to a running page: \`metrics_reset\`, exercise the scene, then
+\`metrics_record\` returns the same record the scripts write.
+`,
+  "find-what-is-slow.md": `# Find what's slow, or what stutters
+
+The profiler is always on. Systems, schedules, the frame, render-graph encodes (\`render/<node>\`),
+GPU passes (\`gpu:<node>\`), worker jobs and asset loads are spans.
+
+- On average: \`describe_perf\` (or \`shard profile\`'s top spans) lists last, avg, p95 and max ms per
+  span over 120 frames. \`{ "spans": ["render"] }\` keeps the spans a key covers.
+- Against a budget: \`describe_budgets\` names the machine, lists every budget with its latest p95
+  (over budget first), and splits a scenario's frame into slices, each measured share next to
+  its budget share. Where \`describe_perf\` says \`"overlapping": true\` (Apple and other tile GPUs),
+  pass times don't add up: \`ablate_passes\` measures what each pass costs.
+- A stutter: \`capture_perf { "frames": 300 }\`, or a flight recorder that waits for one:
+  \`{ "until": { "frameMs": 30 } }\`. Read \`worst\`: each slow frame lists \`over\`, the spans that ran
+  longest above their median there. The first one is the lead.
+- Your own code: \`const SPAN = defineSpan('<project>/spawn')\` once, then in a system
+  \`const t = profiler.begin(SPAN)\` \u2026 \`profiler.end(t)\` with \`world.resource(ProfilerResource)\`.
+- The line: \`shard profile --cpu-prof\` (or \`"sample": true\`) adds the hottest functions and
+  writes a \`.cpuprofile\`. Traces go to \`.shard/captures/*.trace.json\`: open them in Perfetto.
+- In a browser, \`shard dev\`'s pages are cross-origin isolated, so timings are to 5 \xB5s. Turn on the
+  \`perf\` overlay (\`debug_overlays\`) to watch frame time and the top spans live.
 `
 };
 function agentsBlock(manifest) {
@@ -1252,13 +1378,16 @@ component schemas, game code is ECS (components, systems) in \`scripts/\`.
 shard validate --json     # manifest, assets, scenes: every error with a path
 shard import --json       # import new and changed asset files
 shard mv <from> <to>      # move an asset and rewrite references to it
+shard tiles read <map>    # tilemap cells as rows; tiles edit <map> --cell x,y=name
 shard run --frames 600    # headless run
+shard profile --frames 600  # capture spans: the worst frames and what grew in them
 shard screenshot ${manifest.startScene} --out shot.png
 shard test --json         # gameplay tests in tests/
 shard check --json        # type-check scripts: file, line, column
 shard gen <generator> --seeds 1-9 --out sheet.png   # preview a generator's outputs
 shard dev                 # play it in a browser; saves hot reload in place
-shard docs                # regenerate this block, .agents/, and .shard/schemas/
+shard capture plan.json   # real-browser shots and perf records; then compare, approve, perf-check
+shard docs              # regenerate this block, .agents/, and .shard/schemas/
 shard mcp                 # MCP server for this project (see .mcp.json)
 \`\`\`
 
@@ -1272,6 +1401,9 @@ shard mcp                 # MCP server for this project (see .mcp.json)
 - \`.agents/components.md\`: every component and field; \`.agents/assets.md\`: importers and
   project data types;
   \`.agents/errors.md\`: error codes
+- \`.agents/audio.md\`: authored sound, music, mixing and measured previews
+- \`.agents/effects.md\`: reusable effect timelines, target bindings and owned lifetimes
+- \`.agents/vfx.md\`: trails, beams, projected decals and receiver masks
 - \`.agents/skills/\`: recipes for common tasks
 
 Engine plugins available: ${Object.entries(BUILTIN_PLUGINS).map(([n, d]) => `\`${n}\` (${d})`).join("; ")}.
@@ -1293,8 +1425,143 @@ Project-specific notes for agents go here; \`shard docs\` keeps them.
 ${existing}`;
   return `${existing.slice(0, start)}${block}${existing.slice(end + GENERATED_END.length)}`;
 }
+const AUDIO_GUIDE = `# Authoring audio
+
+Enable \`audio/events\` for layered events and parameters, \`audio/mixer\` for effects and snapshots,
+\`audio/acoustics\` for zones/obstruction, and \`audio/music\` for adaptive music. Their dependencies
+are enabled automatically. Base \`audio\` keeps AudioSource/playSound for simple clips.
+
+Assets are ordinary JSON: \`.audio-event.json\`, \`.audio-parameters.json\`, \`.audio-collection.json\`,
+\`.audio-mixer.json\`, \`.audio-snapshot.json\` and \`.audio-music.json\`. Use their generated schemas
+under \`.shard/schemas\`. Import edits with \`shard import\`; references can use paths or stable GUIDs.
+Authored gains use dB and pitches use semitones. Legacy volume/gain use linear multipliers.
+
+Prepare a collection with \`await prepareAudio(world, ref)\`, play its events with \`playAudioEvent\`,
+and release the returned lease when its scope ends. Active instances retain their own pins.
+Use local \`parameters\` for surface labels, RPM or intensity; shared parameter assets connect
+weather/environment values to events, music and mixer curves. Built-in distance/speed are readonly.
+Sequence/no-repeat selectors retain bounded session history. Layers have independent RNG streams.
+
+Simulation event decisions follow timeScale and pause. Their samples normally follow audio time;
+\`pitchLinked\` opts into scaled playback. Realtime UI/ambience can continue without visual frames.
+Transient blocked events expire after 250 ms by default. \`wait\` preserves their phase; \`restart\`
+starts their timeline again after unlock. Choose an explicit AudioListener with setAudioListener;
+the fallback is the lowest live listener entity ID. There is one audio session per app/protocol target.
+
+Mixer domain buses (music/sfx/ui/voice) are direct children of master. Put submixes below them.
+Each event layer can declare up to eight \`sends\` with \`target\`, \`gainDb\`, and an optional
+parameter/points curve. Declare those routes in its mixer bus first. Per-instance sends tap after
+spatialization and preserve the originating category's user gate. Event \`tags\` can drive ducking;
+only physically rendering voices trigger it by default. Duck rules also include descendant buses.
+
+Parent inserts process the summed children once. Pre/post sends feed named returns, and user
+category mute gates that category's dry and wet output. Apply imported mixer edits with
+\`await configureAudioMixer(world, ref)\`: scalar edits preserve effect history; topology/IR
+changes crossfade within the overlap budget. Delay and convolution tails are finite;
+decoded PCM and generated DSP kernels have separate bounded memory budgets. Snapshots compose
+by priority and stable identity; they do not overwrite user volume settings.
+Player controls apply to master and ordinary direct-child categories; nested/return controls reject.
+Use \`setAudioUserBus(world, 'music', { volume: 0.5, muted: false })\` for player settings;
+\`setBus\` remains the independent gameplay fader. Effect target fields
+are \`effectId/parameter\` (for example \`water/frequency\`), and send fields are \`send/returnBus\`.
+Zones use spheres or world-axis boxes and at most four smoothly handed-off returns. Obstruction
+comes from an injected bounded query provider; headless tests can supply deterministic queries.
+Optional \`gainCurve\` and \`lowpassCurve\` map transmission to dB and Hz.
+
+Music programs use decoded stems, fixed tempo/meter, source sample markers and a 960-PPQ grid.
+Rate conform is explicit and pitch changing, bounded by authored cents. Prepare then start a
+program, request beat/bar/marker transitions, and set intensity parameters. Current, incoming and
+crossfading sections own PCM; retired sections are released. Entire stem groups reserve voices.
+Pause/seek cancel future sources, and resume creates fresh scheduled sources at the saved phase.
+Cancelling an already audible destination pauses it and releases both sides of its crossfade.
+Replacing a stinger reserves overlap capacity first; failure preserves the existing stinger.
+Persist only intentional sustained events/music; save restoration diagnoses changed revisions.
+
+Use \`audio.describe\` and \`audio.log\` (cursor plus truncation metadata), \`audio.events.inspect\`,
+\`audio.mix.inspect\`, \`audio.music.inspect\`, and \`audio.meters\`. Headless gains are modeled; meters
+must say unavailable there. Gameplay tests expose \`game.audio.describe/events/music/mix/log\`.
+CLI: \`shard audio call audio.parameter.set --attach --params '{"instance":1,"name":"rpm","value":0.8}'\`.
+Without --attach, the CLI uses a temporary headless target. MCP exposes matching audio_* tools.
+
+\`shard audio preview plans/showcase.json --out captures/mix.wav --json\` runs Chromium's offline
+renderer through the same event/music/mixer implementations. The preview schema accepts clips,
+authored events/music, seed, controls, movement, duration, rate and tails. Controls evaluate at
+60 Hz aligned upward to 128-sample render quanta; the trace includes requested/actual times.
+Music timestamps are scheduled natively. Output includes WAV, decisions, peak/RMS/clipping,
+backend and capabilities. Limits: 60 seconds including tails and 64 MiB each for input/PCM/output.
+No audio device, microphone or GPU is needed. Install Playwright Chromium in the CLI package.
+See \`examples/audio-lab\` for a complete authored showcase and original synthetic assets.
+`;
+const VFX_GUIDE = `# Trails, beams and projected decals
+
+"render/forward" includes ribbonsPlugin and decalsPlugin. SDK hosts can use forwardCorePlugin
+plus just the optional plugins they need. Components are schema-authored; use render.describe
+for ribbons/decals records, points/triangles, age, allocation sizes and structured error codes.
+
+Trail follows its Transform (including parent/bone attachments) and local offset. Old points
+stay in world space. capacity bounds the history, lifetime expires points, minDistance rejects
+duplicates, and breakDistance clears history after teleporting. playing=false drains the trail;
+paused=true freezes its clock. Beam uses local start/end, or end relative to its target entity;
+local points override endpoints. segments/noise/seed control deterministic endpoint-beam shape.
+Both accept width, ordered widthCurve [{at,value}], color/endColor, opacity, repeat, scroll,
+blend alpha/additive, layers and a Texture handle. Width curves use trail age or beam distance.
+Colors are display-referred unlit overlays, not PBR lighting inputs. Alpha compositing uses
+stable creation order; intersecting transparent ribbons are not sorted per segment.
+
+Decal projects along local -Z, with local X/Y as UVs and size as the clipping box. Mark eligible
+rigid Mesh3d entities with DecalReceiver; its mask must overlap receiverMask. The projector clips
+real triangles and caches them until geometry/transforms/masks change. maxAngle rejects grazing
+and back-facing surfaces; offset avoids z fighting. lifetime=0 persists; fadeOut fades the end
+of a finite lifetime. paused freezes age, playing=false hides it. maxVertices and a 32768 input
+triangle budget bound projection; overflow gives a diagnostic and no partial mark. Skinned,
+morph/compute-deformed and transparent receivers are unsupported. No PBR normal/roughness decals.
+
+All texture handles resolve through the host AssetServer catalog (GUIDs work). No file picker,
+URL loading or database dependency is introduced. Prefabs carry reusable VFX component settings;
+0081 visual tracks own activation and cleanup. A beam visual track's endpoint binds another
+named sequence target. Use property tracks for opacity/width changes. Effects are presentation;
+the host remains responsible for damage, collision and persistent game state.
+
+Preview: playground/vfx.html. Toggle each feature to isolate its pixels; replay a seed, pause,
+clear, and switch perspective/orthographic cameras. The host registers the original textures.
+`;
+const EFFECTS_GUIDE = `# Coordinate reusable effect sequences
+
+Enable "effects" in shard.json and the plugins used by your tracks: "animation", "particles",
+"audio/events" and "render/forward" for visual tracks. The scene plugin handles owned prefab targets. Author *.effect-sequence.json
+against .shard/schemas/effect-sequence.schema.json. Hosts may supply the same JSON directly;
+all dependencies resolve through the host's AssetServer catalog, including GUID-only assets.
+
+A sequence has duration, parameters, named targets and tracks. Targets with a prefab handle
+are spawned/owned; other targets are borrowed entity bindings. Property tracks interpolate
+float/vector/color component fields (from/to arrays, linear or smoothstep, optional parameter
+multiplier). Animation and particle tracks require owned targets. Audio tracks use authored
+AudioEvent assets. Visual tracks require owned targets and name render/Trail, render/Beam or
+render/Decal in component. They activate playing, pause their clocks, and stop at track end;
+trails drain their remaining history. Beam tracks may bind an endpoint by target name.
+Marker tracks record presentation milestones; gameplay applies damage itself.
+
+Use prepareEffect(world, source), then playEffect(world, preparation, { bindings, parameters,
+seed, parent, ownerEntity }). The optional parent anchors owned targets in a local frame, so
+one prepared spell can play at different positions/orientations. Removing the parent cancels
+the effect unless another ownerEntity was supplied. Release the preparation when no more plays are needed: active instances
+retain it. cancelEffect restores borrowed fields, stops audio and removes owned prefab trees.
+pauseEffect pauses only that instance. Keep claimed fields free of other writers while playing.
+No runtime file picker, URL fetcher or persistence backend is assumed.
+
+Protocol/MCP: effects.prepare, effects.play, effects.pause, effects.cancel, effects.release,
+effects.inspect (trace cursor, active instances and preparation references). The inspect trace
+reports late windows skipped after a large frame step. A missing target fails and cleans up the
+whole instance. Calls return structured effects/* errors. Dispose the app to release all plans.
+
+Preview at playground/effects.html; its spell asset and host catalog adapter demonstrate the
+complete flow. Replay by cancelling and playing again; backward scrubbing is not implemented.
+`;
 function generateDocs(manifest, errors) {
   const files = {
+    ".agents/audio.md": AUDIO_GUIDE,
+    ".agents/effects.md": EFFECTS_GUIDE,
+    ".agents/vfx.md": VFX_GUIDE,
     ".agents/components.md": renderComponentCatalog(),
     ".agents/errors.md": renderErrorCatalog(errors),
     ".agents/generators.md": renderGeneratorCatalog(),
@@ -1309,6 +1576,11 @@ function generateDocs(manifest, errors) {
     ".shard/schemas/prefab.schema.json": `${JSON.stringify(prefabJsonSchema(), null, 2)}
 `,
     ".shard/schemas/save.schema.json": `${JSON.stringify(saveJsonSchema(), null, 2)}
+`,
+    // Browser verification (0062): other renderers' pages validate their records against it.
+    ".shard/schemas/perf-record.schema.json": `${JSON.stringify(perfRecordJsonSchema(), null, 2)}
+`,
+    ".shard/schemas/capture-plan.schema.json": `${JSON.stringify(capturePlanJsonSchema(), null, 2)}
 `
   };
   for (const [name, content] of Object.entries(SKILLS))

package/dist/host.d.ts

@@ -1,4 +1,4 @@
-import type { GpuContext } from '@aethervtt/shard-gpu';
+import type { BakedTranslations, GpuContext } from '@aethervtt/shard-gpu';
 import type { AudioBackend, InputSource, Platform } from '@aethervtt/shard-platform';
 import { type RenderTarget } from '@aethervtt/shard-render';
 import { App, type Plugin } from '@aethervtt/shard-runtime';
@@ -12,6 +12,11 @@ export interface BuildAppOptions {
     canvas?: HTMLCanvasElement | OffscreenCanvas;
     /** Headless stand-in for the window (CLI screenshots). */
     target?: RenderTarget;
+    /**
+     * The project's baked WebGL2 translations (`shard shaders bake`), or their URL: on WebGL2, the
+     * shaders they cover load without naga (0064). WebGPU never reads them.
+     */
+    webgl2Shaders?: string | URL | BakedTranslations;
     inputSource?: InputSource;
     /** Where sound goes (`platform.audio`). Without one, audio records voices (headless). */
     audio?: AudioBackend;

package/dist/host.js

@@ -1,7 +1,16 @@
 import { animationPlugin } from "@aethervtt/shard-animation";
-import { audioPlugin } from "@aethervtt/shard-audio";
+import {
+  audioAcousticsPlugin,
+  audioEventsPlugin,
+  audioMixerPlugin,
+  audioMusicPlugin,
+  audioPlugin
+} from "@aethervtt/shard-audio";
+import { controlsPlugin } from "@aethervtt/shard-controls";
+import { dicePlugin } from "@aethervtt/shard-dice";
+import { effectsPlugin } from "@aethervtt/shard-effects";
 import { gltfPlugin } from "@aethervtt/shard-gltf";
-import { inputPlugin } from "@aethervtt/shard-input";
+import { gesturesPlugin, inputPlugin } from "@aethervtt/shard-input";
 import { loadNavCache, Nav, navGridPlugin, navPlugin } from "@aethervtt/shard-nav";
 import { noisePlugin } from "@aethervtt/shard-noise";
 import { particlesPlugin } from "@aethervtt/shard-particles";
@@ -11,6 +20,7 @@ import { forwardPlugin, renderPlugin, Shaders } from "@aethervtt/shard-render";
 import { materialNoisePlugin } from "@aethervtt/shard-render/noise";
 import { App, LogResource } from "@aethervtt/shard-runtime";
 import { savePlugin } from "@aethervtt/shard-save";
+import { scatterPlugin } from "@aethervtt/shard-scatter";
 import { loadScene, ScenePlugin } from "@aethervtt/shard-scene";
 import { spritePlugin } from "@aethervtt/shard-sprite";
 import { terrainPlugin } from "@aethervtt/shard-terrain";
@@ -20,20 +30,33 @@ import { uiPlugin } from "@aethervtt/shard-ui";
 function buildApp(options) {
   const { manifest } = options;
   const names = new Set(manifest.plugins);
-  if (names.has("sprite") || names.has("text") || names.has("particles") || names.has("animation"))
+  if (names.has("sprite") || names.has("text") || names.has("particles") || names.has("animation") || names.has("dice"))
     names.add("render/forward");
+  if (names.has("controls")) {
+    names.add("gestures");
+    names.add("render/forward");
+  }
+  if (names.has("audio/acoustics")) names.add("audio/mixer");
+  if (names.has("audio/music") || names.has("audio/mixer")) names.add("audio/events");
+  if (names.has("audio/events")) names.add("audio");
+  if (names.has("gestures")) names.add("input");
   if (names.has("render/forward")) {
     names.add("render");
     names.add("core/transform");
   }
-  if (names.has("physics3d") || names.has("physics2d") || names.has("audio") || names.has("ui") || names.has("nav") || names.has("nav/grid") || names.has("terrain"))
+  if (names.has("physics3d") || names.has("physics2d") || names.has("audio") || names.has("ui") || names.has("nav") || names.has("nav/grid") || names.has("terrain") || names.has("scatter"))
     names.add("core/transform");
   const app = new App({ seed: manifest.seed });
   app.addPlugin(gltfPlugin);
   if (names.has("core/transform")) app.addPlugin(TransformPlugin);
   if (names.has("render")) {
     app.addPlugin(
-      renderPlugin({ gpu: options.gpu, canvas: options.canvas, target: options.target })
+      renderPlugin({
+        gpu: options.gpu,
+        canvas: options.canvas,
+        target: options.target,
+        webgl2: options.webgl2Shaders ? { shaders: options.webgl2Shaders } : void 0
+      })
     );
   }
   if (names.has("render/forward")) {
@@ -44,16 +67,26 @@ function buildApp(options) {
   if (names.has("text")) app.addPlugin(textPlugin);
   if (names.has("particles")) app.addPlugin(particlesPlugin);
   if (names.has("animation")) app.addPlugin(animationPlugin);
-  if (names.has("physics3d")) app.addPlugin(physics3dPlugin);
-  if (names.has("physics2d")) app.addPlugin(physics2dPlugin);
+  if (names.has("dice")) app.addPlugin(dicePlugin());
+  if (names.has("physics3d")) app.addPlugin(physics3dPlugin());
+  if (names.has("physics2d")) app.addPlugin(physics2dPlugin());
   if (names.has("input")) app.addPlugin(inputPlugin({ source: options.inputSource }));
+  if (names.has("gestures")) app.addPlugin(gesturesPlugin);
+  if (names.has("controls")) app.addPlugin(controlsPlugin);
   if (names.has("audio")) app.addPlugin(audioPlugin({ backend: options.audio }));
+  if (names.has("audio/events")) app.addPlugin(audioEventsPlugin());
+  if (names.has("audio/mixer")) app.addPlugin(audioMixerPlugin());
+  if (names.has("audio/acoustics")) app.addPlugin(audioAcousticsPlugin());
+  if (names.has("audio/music")) app.addPlugin(audioMusicPlugin());
   if (names.has("ui")) app.addPlugin(uiPlugin);
   if (names.has("nav")) app.addPlugin(navPlugin);
   else if (names.has("nav/grid")) app.addPlugin(navGridPlugin);
-  if (names.has("terrain")) app.addPlugin(terrainPlugin({ workers: options.platform?.workers }));
+  if (names.has("terrain"))
+    app.addPlugin(terrainPlugin({ workers: options.platform?.workers, fs: options.platform?.fs }));
+  if (names.has("scatter")) app.addPlugin(scatterPlugin({ workers: options.platform?.workers }));
   app.addPlugin(noisePlugin);
   app.addPlugin(ScenePlugin);
+  if (names.has("effects")) app.addPlugin(effectsPlugin);
   app.addPlugin(
     procgenPlugin({
       fs: options.platform?.fs,

package/dist/manifest.d.ts

@@ -18,6 +18,9 @@ export declare const Manifest: import("@aethervtt/shard-core").ComponentDef<{
     readonly procgen: import("@aethervtt/shard-core").FieldType<import("@aethervtt/shard-core").InferFields<{
         cacheSize: import("@aethervtt/shard-core").FieldType<number, "u32">;
     }>, "object">;
+    readonly graphics: import("@aethervtt/shard-core").FieldType<import("@aethervtt/shard-core").InferFields<{
+        baseline: import("@aethervtt/shard-core").FieldType<"optional" | "required", "u8">;
+    }>, "object">;
     readonly plugins: import("@aethervtt/shard-core").FieldType<string[], "object">;
 }>;
 export type ManifestValue = Infer<typeof Manifest>;
@@ -25,6 +28,7 @@ export type ManifestValue = Infer<typeof Manifest>;
 export declare function validateManifest(json: unknown): ShardError[];
 /** Built-in engine plugins a manifest can name, with what they bring. */
 export declare const BUILTIN_PLUGINS: {
+    readonly effects: 'Prepared effect sequences: coordinated properties, animation, particles, audio and markers; add the feature plugins used by tracks';
     readonly render: 'GPU device, render graph, views, shaders';
     readonly 'render/forward': 'cameras, meshes, standard material, lights (includes render and core/transform)';
     readonly sprite: 'sprites, atlases, frame animation, tilemaps (includes render/forward)';
@@ -34,11 +38,19 @@ export declare const BUILTIN_PLUGINS: {
     readonly physics3d: 'Rapier 3D rigid bodies, colliders, joints, raycasts (includes core/transform)';
     readonly physics2d: 'Rapier 2D physics in the XY plane (includes core/transform)';
     readonly input: 'keyboard, mouse, gamepad, touch, action maps';
+    readonly gestures: 'taps, long presses, drags, pinches, twists and the wheel as Gesture events, with claims and Escape to cancel (includes input)';
+    readonly controls: 'OrbitControls and MapControls on cameras, syncViews, PlaneDrag to drag entities along a plane, controls.describe (includes gestures, render/forward)';
     readonly audio: 'AudioSource, AudioListener, playSound, buses and ducking, spatial audio, voice limits (includes core/transform)';
+    readonly 'audio/events': 'Authored layered events, parameters, collections and prepared voice lifetimes (includes audio)';
+    readonly 'audio/mixer': 'Hierarchical effects, sends and composable snapshots (includes audio/events)';
+    readonly 'audio/acoustics': 'Listener reverb zones and bounded injected obstruction queries (includes audio/mixer)';
+    readonly 'audio/music': 'Prepared stems, beat/bar/marker transitions and stingers (includes audio/events)';
     readonly ui: 'UiNode trees under a UiRoot: flexbox layout, text, images, buttons, sliders, text fields, world-anchored markers, themes (includes core/transform)';
     readonly nav: 'navigation: NavGrid A* (2D), NavMesh baked by Recast from NavSource geometry, OffMeshLink, path queries, NavAgent steering (includes core/transform)';
     readonly 'nav/grid': 'navigation on NavGrids only, without loading the Recast WASM (includes core/transform)';
     readonly terrain: 'planets: Planet cube-sphere terrain from noise graphs with LOD, geomorphing, oceans, biomes, collider chunks around characters, navmeshes on the surface; terrain.* methods (includes core/transform; add render/forward to draw it, physics3d for colliders)';
+    readonly scatter: 'props and foliage from ScatterSet rules (*.scatter.json) on planets (Planet.scatter, Biome.scatter) and ScatterSurface meshes: props as entities around cameras and anchors, GPU foliage near cameras; scatter.* methods; the engine generators shard/Rock, Tree, Bush, GrassClump and Crystal make their meshes (includes core/transform; add terrain for planets, render/forward to draw)';
+    readonly dice: 'the dice table (0054): dice skins, face layouts and effect recipes as data, dice.play and dice.describe, dice/RollRequest in scenes; tracks record on the calling thread (includes render/forward)';
     readonly 'core/transform': 'Transform and hierarchy propagation';
 };
 export declare function manifestJsonSchema(): JsonSchema;

package/dist/manifest.js

@@ -39,9 +39,18 @@ const Manifest = defineSchema(
       },
       { description: "Generators (0042): output cache limits." }
     ),
+    graphics: t.struct(
+      {
+        baseline: t.enum(["optional", "required"], {
+          default: "optional",
+          description: "required: the project must run at the baseline tier (WebGPU compatibility mode, WebGL2), and shard validate checks it. optional: what the tier can't run is reported when it runs."
+        })
+      },
+      { description: "Graphics tiers (0064)." }
+    ),
     plugins: t.list(t.string, {
       default: ["render/forward", "input"],
-      description: "Engine plugins to enable, by name: render, render/forward, sprite, text, particles, animation, physics3d, physics2d, input, audio, ui, nav, nav/grid, core/transform."
+      description: "Engine plugins to enable, by name: render, render/forward, sprite, text, particles, animation, physics3d, physics2d, input, gestures, controls, audio, ui, nav, nav/grid, terrain, scatter, dice, core/transform."
     })
   },
   { description: "shard.json: the project manifest." }
@@ -80,6 +89,7 @@ function validateManifest(json) {
   return errors;
 }
 const BUILTIN_PLUGINS = {
+  effects: "Prepared effect sequences: coordinated properties, animation, particles, audio and markers; add the feature plugins used by tracks",
   render: "GPU device, render graph, views, shaders",
   "render/forward": "cameras, meshes, standard material, lights (includes render and core/transform)",
   sprite: "sprites, atlases, frame animation, tilemaps (includes render/forward)",
@@ -89,11 +99,19 @@ const BUILTIN_PLUGINS = {
   physics3d: "Rapier 3D rigid bodies, colliders, joints, raycasts (includes core/transform)",
   physics2d: "Rapier 2D physics in the XY plane (includes core/transform)",
   input: "keyboard, mouse, gamepad, touch, action maps",
+  gestures: "taps, long presses, drags, pinches, twists and the wheel as Gesture events, with claims and Escape to cancel (includes input)",
+  controls: "OrbitControls and MapControls on cameras, syncViews, PlaneDrag to drag entities along a plane, controls.describe (includes gestures, render/forward)",
   audio: "AudioSource, AudioListener, playSound, buses and ducking, spatial audio, voice limits (includes core/transform)",
+  "audio/events": "Authored layered events, parameters, collections and prepared voice lifetimes (includes audio)",
+  "audio/mixer": "Hierarchical effects, sends and composable snapshots (includes audio/events)",
+  "audio/acoustics": "Listener reverb zones and bounded injected obstruction queries (includes audio/mixer)",
+  "audio/music": "Prepared stems, beat/bar/marker transitions and stingers (includes audio/events)",
   ui: "UiNode trees under a UiRoot: flexbox layout, text, images, buttons, sliders, text fields, world-anchored markers, themes (includes core/transform)",
   nav: "navigation: NavGrid A* (2D), NavMesh baked by Recast from NavSource geometry, OffMeshLink, path queries, NavAgent steering (includes core/transform)",
   "nav/grid": "navigation on NavGrids only, without loading the Recast WASM (includes core/transform)",
   terrain: "planets: Planet cube-sphere terrain from noise graphs with LOD, geomorphing, oceans, biomes, collider chunks around characters, navmeshes on the surface; terrain.* methods (includes core/transform; add render/forward to draw it, physics3d for colliders)",
+  scatter: "props and foliage from ScatterSet rules (*.scatter.json) on planets (Planet.scatter, Biome.scatter) and ScatterSurface meshes: props as entities around cameras and anchors, GPU foliage near cameras; scatter.* methods; the engine generators shard/Rock, Tree, Bush, GrassClump and Crystal make their meshes (includes core/transform; add terrain for planets, render/forward to draw)",
+  dice: "the dice table (0054): dice skins, face layouts and effect recipes as data, dice.play and dice.describe, dice/RollRequest in scenes; tracks record on the calling thread (includes render/forward)",
   "core/transform": "Transform and hierarchy propagation"
 };
 function manifestJsonSchema() {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aethervtt/shard-project",
-  "version": "0.0.1",
+  "version": "0.2.0",
   "license": "MIT",
   "type": "module",
   "sideEffects": false,
@@ -8,6 +8,10 @@
     ".": {
       "types": "./dist/index.d.ts",
       "default": "./dist/index.js"
+    },
+    "./manifest": {
+      "types": "./dist/manifest.d.ts",
+      "default": "./dist/manifest.js"
     }
   },
   "files": [
@@ -16,29 +20,35 @@
     "README.md"
   ],
   "dependencies": {
-    "@aethervtt/shard-animation": "0.0.1",
-    "@aethervtt/shard-assets": "0.0.1",
-    "@aethervtt/shard-audio": "0.0.1",
-    "@aethervtt/shard-core": "0.0.1",
-    "@aethervtt/shard-gltf": "0.0.1",
-    "@aethervtt/shard-gpu": "0.0.1",
-    "@aethervtt/shard-input": "0.0.1",
-    "@aethervtt/shard-nav": "0.0.1",
-    "@aethervtt/shard-noise": "0.0.1",
-    "@aethervtt/shard-particles": "0.0.1",
-    "@aethervtt/shard-physics": "0.0.1",
-    "@aethervtt/shard-platform": "0.0.1",
-    "@aethervtt/shard-procgen": "0.0.1",
-    "@aethervtt/shard-protocol": "0.0.1",
-    "@aethervtt/shard-render": "0.0.1",
-    "@aethervtt/shard-runtime": "0.0.1",
-    "@aethervtt/shard-save": "0.0.1",
-    "@aethervtt/shard-scene": "0.0.1",
-    "@aethervtt/shard-sprite": "0.0.1",
-    "@aethervtt/shard-terrain": "0.0.1",
-    "@aethervtt/shard-text": "0.0.1",
-    "@aethervtt/shard-transform": "0.0.1",
-    "@aethervtt/shard-ui": "0.0.1"
+    "@aethervtt/shard-animation": "0.2.0",
+    "@aethervtt/shard-assets": "0.2.0",
+    "@aethervtt/shard-audio": "0.2.0",
+    "@aethervtt/shard-controls": "0.2.0",
+    "@aethervtt/shard-core": "0.2.0",
+    "@aethervtt/shard-dice": "0.2.0",
+    "@aethervtt/shard-fog": "0.2.0",
+    "@aethervtt/shard-gltf": "0.2.0",
+    "@aethervtt/shard-gpu": "0.2.0",
+    "@aethervtt/shard-input": "0.2.0",
+    "@aethervtt/shard-nav": "0.2.0",
+    "@aethervtt/shard-noise": "0.2.0",
+    "@aethervtt/shard-particles": "0.2.0",
+    "@aethervtt/shard-physics": "0.2.0",
+    "@aethervtt/shard-platform": "0.2.0",
+    "@aethervtt/shard-procgen": "0.2.0",
+    "@aethervtt/shard-protocol": "0.2.0",
+    "@aethervtt/shard-render": "0.2.0",
+    "@aethervtt/shard-runtime": "0.2.0",
+    "@aethervtt/shard-save": "0.2.0",
+    "@aethervtt/shard-scatter": "0.2.0",
+    "@aethervtt/shard-scene": "0.2.0",
+    "@aethervtt/shard-sprite": "0.2.0",
+    "@aethervtt/shard-terrain": "0.2.0",
+    "@aethervtt/shard-text": "0.2.0",
+    "@aethervtt/shard-transform": "0.2.0",
+    "@aethervtt/shard-ui": "0.2.0",
+    "@aethervtt/shard-verify": "0.2.0",
+    "@aethervtt/shard-effects": "0.2.0"
   },
   "repository": {
     "type": "git",
@@ -50,6 +60,6 @@
     "provenance": true
   },
   "shard": {
-    "buildSha": "d6c5c6aef4675575c878b02cf2c8f738b4190229"
+    "buildSha": "32c22a3944ed23f5d1baa90bf7cc9fae724f5fd8"
   }
 }