Aura3D
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).
Start in five commands
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 dist
Templates: 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).
If you are an AI agent
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.
What you get
- Typed scene API.
scene, model, looks, lights, camera, effects, interactions, primitives, instances and the game.* 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, installQaHooks and seeded replay, createCueBank audio synth, defineModelAssets, racket-sports and other genre kits.
- Safety net.
installSafetyNet from @aura3d/debug: ?diag=1 panel, quality switches and black-frame self-heal. Custom shader failures are reported, not silent.
- Checks.
aura3d doctor, aura3d check-deploy (add --browser to 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 three is 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.
Built with it
The showcase index has 25 playable games across racing, sports, action, platformers and arcade, including Aura Slam 3D (tennis, with a deterministic replay gate), Apex Overdrive (racing), Glint Courier (maze chase) and Craterline GP (bike racing). Each page states its limits; the games are independent work, not affiliated with any other game or studio. Games are checked on software WebGL2 in remote runs; real-GPU confirmation is partial and tracked in evidence/.
Why Aura3D instead of three.js
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).
- Assets you can trust. Every model is typed, hashed and licensed; in production an unverified model doesn't draw.
- The game stack included. HUD, touch controls, audio cues, a fixed-step loop, seeded replay, a safety net and smooth motion on 120 and 144 Hz displays.
- Built for AI coding agents.
llms.txt, 14 skills and compiled recipes ship with every new project.
- Measured on the published 4.5.0 package. 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. The five benchmark scenes log no console warnings or errors, and the 16 option-coverage tests pass, so an option either takes effect or raises
OPTION_IGNORED. Software WebGL2 on a remote runner, one run, median of 3 cold loads for the first frame; not GPU numbers (results).
Porting an existing three.js project: docs/migration/from-threejs.md.
Packages
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, WebGL2 backend, 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 |
@aura3d/engine/production-runtime, /advanced-runtime, /rendering and /contracts are deprecated subpaths; new code uses the root.
Claims and verification
Every public claim follows docs/agents/claims-and-boundaries.md: label the capability, and claim only what a judged capture or retained evidence shows. Published gates include route health, typed provenance, public-API surface checks, package-size checks and check-deploy. Release notes are in CHANGELOG.md.
Documentation
Contributing
Open issues with the prompt, package version, asset source and a screenshot or route-health output. Inside this monorepo, browsers, Playwright suites and heavy builds run on the remote runner (tools/remote-acr/run.sh), not on a laptop. Licensed under MIT.
