Skip to content
auraoneaiPublic

About

AI-native TypeScript 3D SDK for browser 3D apps, prompt-to-code scenes, GLB/glTF product viewers, WebGL/WebGPU, Vite templates, diagnostics, and deploy checks.

Topics

Resources

Contributing

Stars

1 star

Watchers

0 watching

Forks

Latest commit

 

History

7,638 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

Aura3D

npm version npm downloads license: MIT TypeScript

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.

Readiness and top-level await

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.

Built with it

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.

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).
  • Typed scenes and typed assets. npx @aura3d/cli@latest assets resolve "robot" --name robot, then model(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=webgl2 opts out) with dynamic RuntimeQualityGovernor scaling across desktop and mobile GPUs.
  • Worker rendering, opt-in. worker: { createWorker: createWorkerRendererWorker } (from @aura3d/engine/worker) renders off the main thread while game code keeps app.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, validate and render let 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-three turns 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 three writes a port worklist for app code.
  • A deploy gate. check-deploy --dist dist fails the build on missing hashed assets and stray files; --browser also 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.

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, 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).

Documentation

Contributing

Open issues with the prompt, package version, asset source and a screenshot or route-health output. Licensed under MIT.

About

AI-native TypeScript 3D SDK for browser 3D apps, prompt-to-code scenes, GLB/glTF product viewers, WebGL/WebGPU, Vite templates, diagnostics, and deploy checks.

Topics

Resources

Contributing

Stars

1 star

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages