Aura3D 4.1.3

Superseded. This version is deprecated. Upgrade to Aura3D 5.0.1; see the 4.x to 5.0 migration guide.

A patch release: the stock-build fix, a large software-WebGL2 frame-cost cut, library kits extracted from the games, corrected API deprecation annotations, a remote-first look capture, a rewritten documentation set, and the native Aura Slam route polish. No export is removed or renamed.

Fixes

• Fix: root @deprecated annotations corrected (annotation-only, no export removed or renamed). 24 live public-path names are no longer marked deprecated: the scatter and merge planners (scatterAlongPath, scatterInArea, scatterTransforms, splitScatterByDistance, createScatterRandom, mergeStatic, mergeStaticByKey), createAnimationController, the sky, water, weather, character, decals, editor and navigation builders, compilePromptPlan, the evidence helpers (collectAuraSceneEvidence, collectPromptAnimationEvidence, evaluatePromptAnimationPublishReadiness, createCaptionTimingProof), and AuraColor, AuraNodeBuilder, GamePlatformerEvent, validatePlatformerMotion, which shipped templates, games, docs and skills import from the root. 47 annotations remain, and every message now names a replacement that exists (@aura3d/engine/renderer, @aura3d/engine/devtools, @aura3d/animation, @aura3d/assets, @aura3d/workflows, createAuraApp, typed model(assets.x)) or says there is none. Two earlier messages pointed at subpaths that were never in the package exports (@aura3d/engine/animation, @aura3d/engine/assets). Root exports now: 282 value exports, 240 live, 42 deprecated (docs/api/root-exports.md).
• aura3d look capture now defaults to a remote runner, and template npm test no longer starts a local browser. --runner remote (new default) starts no browser on the developer machine: it writes capture-request.json and prints the remote-run steps, runs a configured runner (--remote-cmd or AURA3D_REMOTE_RUNNER), or collects a finished remote run with --from <reports-dir>. --runner local and --runner gh-actions still work and now print a warning (additive; nothing removed). In all 27 templates that ran playwright test, npm test now prints the remote-runner instruction and runs typecheck; the browser specs moved to npm run test:browser for the remote machine. 8 new unit tests; tools/package-clean-install now calls test:browser.
• The game beacon now serializes. window.__AURA3D_GAME__ publishes app, scene and session as non-enumerable properties, so JSON.stringify and remote capture no longer fail on the circular app.post; the handles stay reachable for audit lanes. Cross Hop's local sanitizing setter is deleted; the shared black-frame wrappers import @aura3d/debug instead of relative source paths; the four starter templates' HUDs use the licensed Graphik face (Medium) instead of Inter 600. The leftover audit of all 26 games is in docs/audit/game-leftovers.md.
• Frame cost on software WebGL2: cube 666 -> 50 ms, 18,000-instance forest 38.4 s -> 6.4 s per frame. Three engine causes found by profiling on the remote CPU runner: the legacy LDR postprocess uber-shader (one fullscreen draw ~600 ms, now compiled per feature variant, LdrPostprocessShader.ts); single-object tessellation on every instance of instances.* (a node whose instances x triangles exceed 262,144 now halves its default segments, never below 16x8 for a sphere; up to 64 instances and authored params.*Segments are untouched); and ~15 allocations per instance in the caster/cull bounds (instancedWorldBounds, 243 -> 37 ms JS at 18,000). Software WebGL2 only; open items and method in evidence/perf-frame-cost/README.md.
• A stock vite build / vite dev of an app on the published @aura3d/engine no longer fails with "readFileSync" is not exported by "__vite-browser-external". The root entry statically reached dist/assets/index.js (which re-exports Node-only loaders and asset corpora) through ModelTextureShare; it now imports @aura3d/assets/browser, so no node:* module is reachable from the browser entry. New gate tools/release/consumer-build-smoke.mjs installs the packed tarballs into a temp project outside the repo and runs vite build and vite dev for mini-game, racing-starter, falling-blocks-starter, product-viewer and a config-less createAuraApp hello-world. Verified on packed tarballs with stock vite build and vite dev for the cube app, mini-game, racing-starter, falling-blocks-starter and product-viewer on Vite 7.3.2 and 7.3.7 (evidence/stock-build/); consumer-build-smoke.mjs gained --vite.
• Aura Slam menu and portrait layout fixed on the live route. The menu CSS read type, spacing and column tokens (--text-*, --space-*, --leading-*, --content-*) that nothing defined, so every declaration using one was dropped (menu padding 0, headings 16px, cards touching); they are now defined in examples/aura-slam/ui/styles.css and a unit test fails on any undefined var(--x). The menu masthead brand gets its styles, the controls hint hides while the menu is open, and the quick-switch bar no longer covers the scoreboard or pause button (portrait: one scrollable row whose height is reserved above the scoreboard via --quick-bar-space; desktop: ends left of the pause button). Frames and measured geometry: evidence/live-slam/ui-fix/.

New and promoted library kits

• Library kits: installQaHooks keeps getter extras live, and noise cue layers take attack and loop. Both are additive. A hook object with live getters (ready, frames) now stays live instead of being frozen at install time, and a NoiseLayer can ramp up over attack seconds and loop the shared 0.4 s noise buffer for its whole dur (defaults keep the old full-level, single-pass behaviour). Strange Orbit, Serpentine Sky Run and Where the Wind Wanders now use installQaHooks and createFixedStepLoop, and Serpentine Sky Run's sound effects run on createCueBank: a test replays the original synth and the cue-bank version against the same fake context and finds identical gain, frequency and filter automation for all 11 cues (parameter-level only; not listened to). The other two ports keep their audio because it pans, uses Math.random, runs a compressor or needs speed-driven beds the cue bank does not express.
• Game beacon: installGameBeacon().publishEvidence(evidence). Routes that do not use createGame can publish their per-frame evidence on the frozen library beacon instead of assigning window.__AURA3D_GAME__ by hand. The beacon fields (route, state, frame, ...) merge under the evidence fields (evidence wins), getters stay lazy, evidenceGlobals fills legacy aliases such as __AURA3D_GAME_EVIDENCE__, and the live app/scene handles stay non-enumerable. getState, getFrame and getFirstFrameAt are now optional. Nine index games (links, hoops, fc, diamond, red-zone, heatsink, teleoperator, roadster-rush, slingshot-siege) moved onto it and Dot Dash dropped its sanitizer. Verified on a remote software-WebGL2 spec for Heatsink, Roadster Rush, Aura Hoops and Dot Dash (every evidence key still readable, beacon frozen and JSON-serializable, no errors, guard never reloaded). Slingshot Siege and the other five games are covered by type and unit checks only.
• aura3d evidence judge: the blind A/B model judge is now a CLI command. aura3d evidence judge --a <dir> --b <dir> --trials 48 --seed 20261023 runs a seeded, balanced blind comparison of two folders of matched frames through Kiro Prism, reports accuracy, Wilson 95% interval, exact binomial p-value and pixel metrics, and labels every result "model judge" (not human). Replaces the per-game scripts' shared logic in tools/crayon-capture/; see docs/api/cli-asset-tools.md.
• One mulberry32 for the games: createCountedRng now also exposes draws, and SeededRandom counts draws. Bunker Zero, Dot Dash, Iron Crown, Apex Overdrive, HEATSINK, Drift & Deliver and Splat Rush dropped their inline mulberry32 copies for createCountedRng; a golden test proves every stream is bit-identical to the old code over 2,000 draws per seed (tests/unit/rng-consolidation/). SeededRandom is xorshift32, a different sequence, so it was not swapped in (that would change every replay).
• effects.toon({ bands, outline }) cel pass promoted from Silt & Signal. Luma banding plus a Sobel outline as a post pass (docs/api/toon.md, tests/unit/toon/); options are range-checked and throw instead of being ignored. The Silt & Signal port now uses it instead of its own shader.
• cameras.chase gameplay chase camera rig. A pure, deterministic rig (offset mode with heading smoothing, speed-driven back distance and fov kick, shake; framed mode with exponential smoothing, first-frame snap and a cut flag) extracted from six ports. Drift & Deliver keeps only its constants and matches its original camera within 1e-9 over a scripted drive; Ninja Runner, Roadster Hours, Kid Goku, Last Train and HEATSINK drive their own framing through it. See docs/api/camera-rig.md.
• prefabs.objectiveMarker, compassBearing/updateCompass and drawCanvasMinimap extracted from the ports. The Silt & Signal beacon (ring, rim, halo, light column) and compass and the Drift & Deliver minimap now come from the library instead of per-game code; see docs/api/objective-marker.md.
• attachRootRenderSource, RootRenderSourceBridge and TypedGLBActor are exported from the @aura3d/engine root. Skinned-actor games no longer need the deprecated @aura3d/engine/production-runtime subpath; Saiyan Snake Way, Ninja Runner and parity-animation are migrated (docs/api/skinned-actors.md).

Games and ports

• Ports on the QA and fixed-step kits: Silt & Signal, Ninja Runner, Last Train and Roadster Hours. They now install their QA hooks and run their live loops through installQaHooks and createFixedStepLoop; steps per frame match the old accumulators on 20,000 seeded frames each, replay paths are untouched, and their audio stays hand-written (continuous driven voices are not in createCueBank yet).
• Ports on the QA and audio kits: Drift & Deliver, HEATSINK and Kid Goku. installQaHooks (all three; Kid Goku keeps its own ready getter and event-returning stepFrames as extras), createFixedStepLoop (all three) and createCueBank for the oscillator-only cues (Drift chimes and thud, 17 Kid Goku events; the noise-bearing cues stay hand-written). createFixedStepLoop gains resetAccumulator() so a restart does not inherit a partial step. Replay and unit suites are unchanged and green; the audio equivalence is parameter-level only (see docs/audit/game-leftovers.md).

Documentation

• Documentation rewritten for agents and developers. README.md (48 KB to 8 KB), llms.txt (a one-screen fast path; the long guide moved to llms-full.txt), AGENTS.md (a Fast path section after the policy block), one canonical docs/agents/agent-quickstart.md (about 1.8k tokens), docs/agents/build-a-game.md with a compiling sample, docs/agents/asset-workflow.md, docs/migration/from-threejs.md, a rewritten docs/aura3d-vs-threejs.md that uses only the measured, software-GL, one-author figures, and a script-generated docs/api/root-exports.md (checked by tools/docs/check-root-exports.mjs). The core read path for a new agent is about 9.4k tokens, down from 14.9k (bytes/4 estimate). Docs no longer teach nonexistent commands or import paths, dead links are fixed, 28 history-only files moved to docs/archive/, and the skill sources and mirrors are in sync (docs/audit/RESULT.md). The Aura3D vs three.js analysis and execution plan is docs/workflows/aura3d-vs-threejs-analysis-and-plan.md.

Known issues

• The legacy post chain tone-maps and encodes on its own and bypasses OutputPass until PostGraph v2 migrates it, so frames with bloom or vignette on are about 25 to 40% darker and less saturated than with post off. Unchanged from 4.1.2.
• primitives.plane({ params: { widthSegments, heightSegments } }) is accepted by the types but renders a single quad (found by the 4.1.2 benchmark; not fixed in this release).
• The Aura3D bundle is much larger than three.js for a one-cube app (about 3.3 MB raw JS and 963 kB gzip in the stock-build smoke) and the default frame cost on software WebGL2 is still higher than three.js after the 4.1.3 cut (measured: evidence/vs-threejs/RESULTS.md, evidence/perf-frame-cost/). These are software-WebGL2 figures, not real-GPU figures.
• aura3d migrate three emits an annotated worklist, not compiling code (for the benchmark PBR viewer it leaves const scene = scene() and renderer.* and THREE.* references). See docs/migration/from-threejs.md.
• Camera, objective-marker, toon and port-kit migrations were verified by unit and replay tests and remote software-GL specs; frame equivalence was not diffed pixel by pixel for the camera rig on the five non-Drift ports, and HEATSINK and Last Train never finish under software GL, so those two are unchecked in a browser.
• Audio migrations to createCueBank are parameter-level equivalence only (nobody listened); noise-bearing and continuous cues in most ports stay hand-written (docs/audit/game-leftovers.md).
• Real-GPU confirmation is still pending for several ports (Drift & Deliver, Silt & Signal, Last Train's full Enter, E, W path, HEATSINK) and for the native Aura Slam route; all automated checks ran on software WebGL2.
• Aura Slam in portrait shows less court width (the camera uses a fixed 15 degree vertical field of view pinned by the G3 render gate).
• Remaining leftovers in games (hand-rolled QA hooks in a few ports, own fixed-step loops, hand-written audio, an LCG copy in 19 places, system-font fallbacks) are listed in docs/audit/game-leftovers.md. The create-aura3d templates name the Graphik font but do not ship its files, so they fall back to sans-serif.
• The repository has no LICENSE file although package.json declares MIT.