The TypeScript 3D engine that ships the whole stack. Aura3D is a browser 3D engine with its own renderer, plus the toolchain around it: typed and licensed assets, lighting looks, a game kit and deploy checks. It is built for agent-written browser 3D, and people who write it by hand use the same API. The current version is in CHANGELOG.md.
A lit, shadowed, framed product with orbit controls, in 10 lines:
import { camera, createAuraApp, interactions, looks, model, scene } from "@aura3d/engine";
import { assets } from "./aura-assets";
createAuraApp("#app", {
scene: scene()
.add(looks.preset("product-studio"))
.add(model(assets.product, { name: "product", targetHeight: 1.6, castShadow: true }))
.add(interactions.orbit({ target: "product" }))
.camera(camera.frameAsset(assets.product, { targetHeight: 1.6 })),
...looks.appOptions("product-studio")
});A looks.preset supplies image-based light, a shadow-casting key, fog, background and a post grade as one unit. model(assets.product) is a typed asset generated by the CLI, never a raw URL. The same scene in three.js is 38 lines before orbit controls (tagline check; line counts include imports and skip blank and comment lines).
npx create-aura3d@latest my-scene --template mini-game # also writes llms.txt and the Aura3D agent skills
cd my-scene && npm install
npm run dev # Vite on 127.0.0.1
npx @aura3d/cli@latest assets resolve "robot" --name robot # assets add also works for local GLBs; then model(assets.robot)
npm run build && npx @aura3d/cli@latest check-deploy --dist distTemplates: product-viewer (default), cinematic-scene, mini-game, racing-starter, falling-blocks-starter, fighting-game, character-controller, arena-shooter and more (npx create-aura3d@latest --help).
Read llms.txt (one screen, the fast path), then docs/agents/agent-quickstart.md and docs/agents/claims-and-boundaries.md. The index of every agent doc is docs/agents/README.md; skills live in packages/aura3d-cli/skills/. npx create-aura3d@latest and npx @aura3d/cli@latest init --agent all write the instruction files into your project.
- Typed scene API.
scene,model,looks,lights,camera,effects,interactions,primitives,instancesand thegame.*genre kits through one entry,@aura3d/engine. - Typed, provenance-checked assets.
assets search,assets resolve,assets add,assets import-meshy,assets optimize,assets validate. In production a model needs a same-origin URL, a sha256 and provenance, otherwise it draws nothing. Meshy generation goes through the CLI with admission records. - Game kit.
@aura3d/engine/game(createGame: lifecycle, pause, results, DOM HUD, touch, juice, sound),createFixedStepLoop,installQaHooksand seeded replay,createCueBankaudio synth,defineModelAssets, racket-sports and other genre kits. - Safety net.
installSafetyNetfrom@aura3d/debug:?diag=1panel, quality switches and black-frame self-heal. Custom shader failures are reported, not silent. - Checks.
aura3d doctor,aura3d check-deploy(add--browserto load every route in headless Chromium and fail on failed requests and console errors), route-health and screenshot evidence, the look-dev loop (aura3d look capture,aura3d look lint). - Migration.
aura3d migrate threeis a codemod that records each approximation. It is not a drop-in claim.
Kit documentation: docs/api/game-kit.md, qa-kit.md, safety-net.md, audio-synth.md, model-loader.md, glsl-chunks.md, scatter-merge.md, cli-asset-tools.md, toon.md.
app.ready() resolves once the renderer mount settles, so a frame can be drawn. It also resolves, rather than rejects, if the mount fails (the failure is in app.diagnostics().errors; use readyStrict() to get a rejection). Wait for it inside a function or chain on it; never await it at module top level:
import { createAuraApp, scene } from "@aura3d/engine";
const app = createAuraApp("#app", { scene: scene(), autoStart: false });
void app.ready().then(() => {
app.step(1 / 60);
});Or inside an async function:
import { createAuraApp, scene } from "@aura3d/engine";
async function main(): Promise<void> {
const app = createAuraApp("#app", { scene: scene(), autoStart: false });
await app.ready();
app.step(1 / 60);
}
void main();A module-level await app.ready() (or readyStrict(), readiness(), precompile(), game.ready(), warmPrograms(app)) deadlocks a default Vite production build. Vite puts the engine modules the app imports into the entry chunk, and the lazily loaded engine chunks (renderer, environment, decoders) import that entry back. An entry suspended on the await never finishes evaluating, so those chunks never run, the mount never settles and the page stays black with no console error. vite dev serves separate modules and hides it. aura3d validate reports it as LINT_TOP_LEVEL_AWAIT_READY; details in evidence/n4-frame/integration/README.md.
The showcase index features 30 playable games across racing, sports, action, platformers and arcade, including Aura Slam 3D (tennis, with deterministic replay), Apex Overdrive (racing), Glint Courier (maze chase) and Craterline GP (bike racing). All 30 games are independent work and run on WebGPU by default with automatic WebGL2 fallback and OffscreenCanvas worker rendering.
three.js gives you a renderer. Aura3D is a complete TypeScript 3D engine and toolchain with its own renderer, so the parts three.js leaves to you come built in:
- A lit, shadowed, framed product in 10 lines. The same scene in three.js is 38 lines before orbit controls (tagline check). In our five-scene benchmark, a PBR viewer with HDR lighting, shadow, bloom and orbit controls is 24 lines instead of 49, with 1 import instead of 8 (results).
- Typed scenes and typed assets.
npx @aura3d/cli@latest assets resolve "robot" --name robot, thenmodel(assets.robot): a misspelt asset is a compile error, and every model is hashed and licensed. In production an unverified model doesn't draw. - WebGPU with a WebGL2 fallback.
renderer: { backend: "auto" }asks for WebGPU and falls back to WebGL2 on the same canvas, with the same scene code. All 30 showcase games run on WebGPU by default (?backend=webgl2opts out) with dynamicRuntimeQualityGovernorscaling across desktop and mobile GPUs. - Worker rendering, opt-in.
worker: { createWorker: createWorkerRendererWorker }(from@aura3d/engine/worker) renders off the main thread while game code keepsapp.nodes, frame callbacks and picking. All 30 showcase games run with?worker=1. - A good frame with no setup. A bare scene keeps its authored colours, reflects a built-in studio room, gets a key-light shadow and is framed by
camera.auto({ subject }). - The game stack included. HUD, responsive multi-touch controls, audio cues, a fixed-step loop, seeded replay, a safety net and smooth motion on 60, 120 and 144 Hz displays.
- Built for AI coding agents.
llms.txt, 14 skills and compiled recipes ship with every new project.aura3d info,examples,validateandrenderlet an agent look up the installed API, start from working code, lint and screenshot its scene. three.js names models guess (material.standard,handle.setColor,"aces-filmic") resolve; others throw an error naming the Aura3D call (agent tools, guessable API). - Bring your three.js work.
aura3d import-threeturns a three.js scene factory into a typed asset plus an editable Aura3D scene, with a report of what was carried (three.js bridge);aura3d migrate threewrites a port worklist for app code. - A deploy gate.
check-deploy --dist distfails the build on missing hashed assets and stray files;--browseralso loads every route in headless Chromium. - 30 playable games as proof in the showcase.
- Low draw-call overhead out of the box. A one-cube scene reaches its first frame in about 420 ms and draws in 1 call; a PBR viewer scene with a shadow and bloom draws in 25, with zero console warnings or errors and strict option-coverage checks (results).
Agent-authoring benchmark (Aura3D 5.5.1, three.js 0.185.1). The same AI model built the same eight scenes three times with each engine. The Aura3D apps came out 17% shorter (median 270 lines against 326; shorter on 6 of 8 tasks), passed the same functional checks (every check passed in 88% of runs in both, every follow-up edit in 100%), and a blind visual judge picked the Aura3D frame in 13 of 24 pairs. One model (claude-sonnet-5.5), 72 runs, frames on a real GPU (results, full report).
Full comparison with sources: docs/aura3d-vs-threejs.md. Porting an existing three.js project: docs/migration/from-threejs.md.
Public packages (all at the same version; @aura3d/engine is the root of this repository):
| Package | Purpose |
|---|---|
@aura3d/engine |
Public runtime: createAuraApp, scene nodes, looks, effects, game kits, subpaths such as /game and /audio |
@aura3d/cli |
Typed asset workflow, asset search across open public sources, Meshy admission, look-dev, check-deploy, init, migrate three |
create-aura3d |
Vite project scaffolder with agent skills and llms.txt |
@aura3d/core, @aura3d/math, @aura3d/scene |
Lifecycle and deterministic stepping, math, scene graph |
@aura3d/rendering |
Render device, WebGPU and WebGL2 backends, RuntimeQualityGovernor, materials, passes |
@aura3d/assets, @aura3d/asset-index |
Asset loading and caching; asset search across public sources |
@aura3d/animation, @aura3d/audio, @aura3d/input, @aura3d/controls |
Clips and state machines, audio buses, input, camera controls |
@aura3d/physics, @aura3d/physics-rapier, @aura3d/navigation-recast |
Physics, with optional Rapier and navigation adapters |
@aura3d/ecs, @aura3d/scripting |
ECS and behaviour graphs |
@aura3d/debug |
Diagnostics and the runtime safety net |
@aura3d/product-studio, @aura3d/apps, @aura3d/workflows, @aura3d/react, @aura3d/editor-runtime |
Product viewers, app presets, workflows, React host, editor runtime |
The 4.x legacy subpaths (@aura3d/engine/production-runtime, /advanced-runtime, /rendering, /contracts and six more) were removed in 5.0.0; use the root, @aura3d/engine/renderer, /assets or /workflows (migration guide).
docs/index.md: hub for humans and agentsdocs/agents/README.md: agent docs indexdocs/api/public-api.md: public APIdocs/aura3d-vs-threejs.mdanddocs/migration/from-threejs.md: why Aura3D over three.js, and how to portdocs/workflows/game-conversion-playbook.md: turning a browser game into an Aura3D game- Site: https://aura3d.auraone.ai
Open issues with the prompt, package version, asset source and a screenshot or route-health output. Licensed under MIT.