AURA

JSGG

AuraJS
DOCSEXAMPLESGITHUB
Migrating from Three.js
TLDR translation from common Three.js renderer, scene, camera, mesh, loader, and animation concepts into AuraJS lifecycle and 3D APIs.
docs/external/game-dev-api/migrating-from-threejs.md

Migrating from Three.js

Use this page when your current mental model is:

  • Scene
  • Camera
  • Renderer
  • Mesh
  • Loader
  • requestAnimationFrame

AuraJS can cover much of that work, but the canonical authored shape is different.

TL;DR

  • Replace init() plus requestAnimationFrame(...) with aura.setup, aura.update(dt), and aura.draw().
  • Replace renderer.render(scene, camera) with either direct aura.draw3d.drawMesh(...) calls or retained aura.scene3d bindings plus aura.scene3d.submitRenderBindings().
  • Replace THREE.PerspectiveCamera and controls with aura.camera3d.
  • Replace Geometry / BufferGeometry / Material ownership with aura.mesh and aura.material.
  • Replace GLTFLoader and mixer-style scene import flow with aura.scene3d.loadGltfScene(...) plus clip/import helpers.
  • Replace addon physics stacks with aura.physics3d, aura.character3d, and aura.navmesh when the game actually needs them.
  • Treat native 3D as the current canonical AuraJS path. This is not a browser canvas wrapper over Three.js.

Fast API Map

Three.js concept AuraJS canonical API Notes
init() + requestAnimationFrame(animate) aura.setup, aura.update(dt), aura.draw() Aura owns the frame loop.
new THREE.WebGLRenderer() + renderer.render(scene, camera) aura.draw3d.clear3d(...), aura.draw3d.drawMesh(...), aura.scene3d.submitRenderBindings() No separate user-owned renderer object is the normal public path.
new THREE.Scene() / scene.add(...) / Object3D / Group aura.scene3d.createNode(...), aura.scene3d.setParent(...), aura.scene3d.setLocalTransform(...), aura.scene3d.bindRenderNode(...) Use scene3d when you want retained hierarchy.
new THREE.PerspectiveCamera(...) aura.camera3d.perspective(...) Position and aim with setPosition(...), setTarget(...), or lookAt(...).
OrbitControls aura.camera3d.setControlProfile("orbit", ...), aura.camera3d.updateControls(...) Controls live under camera3d, not a separate helper object.
new THREE.Mesh(geometry, material) aura.mesh.createBox(...) / other mesh builders, aura.material.create(...), then aura.draw3d.drawMesh(...) or aura.scene3d.bindRenderNode(...) Aura uses handles, not mutable mesh instances as the main contract.
BoxGeometry, PlaneGeometry, SphereGeometry, CylinderGeometry, TorusGeometry aura.mesh.createBox(...), createPlane(...), createSphere(...), createCylinder(...), createTorus(...) createRing(...), createExtrude(...), and createLathe(...) also exist.
BufferGeometry aura.mesh.createFromVertices(...) Use this for authored raw vertex/index data.
MeshStandardMaterial / MeshBasicMaterial aura.material.create(...) Standard material is the default path; mutate with setColor(...), setTexture(...), setMetallicRoughness(...).
ShaderMaterial aura.material.createCustom(...), aura.material.setUniform(...), aura.material.setCustomTexture(...) Keep custom WGSL narrow; standard materials are still the canonical path.
AmbientLight, DirectionalLight, PointLight, SpotLight aura.light.ambient(...), directional(...), point(...), spot(...) Shadow control also lives on aura.light.
GLTFLoader.load(...) aura.scene3d.loadGltfScene(...), aura.scene3d.getImportedScene(...) Imported scenes can bind nodes/materials automatically.
AnimationMixer, clipAction, crossFadeTo aura.scene3d.createClip(...), playClip(...), crossfadeClips(...), updateClips(...) Imported-scene animation helpers sit under scene3d too.
Raycaster aura.scene3d.queryRaycast(...) or aura.physics3d.queryRaycast(...) Use render-space query vs physics-space query intentionally.
InstancedMesh aura.draw3d.drawMeshInstanced(...) For skinned instance groups, Aura also exposes aura.mesh.createInstanceGroup(...) and related instance helpers.
EffectComposer + passes aura.draw3d.setPostFXPass(...), setPostFXEnabled(...), removePostFXPass(...), getPostFXState() PostFX is part of draw3d today.
scene.environment / PMREM-style environment setup aura.draw3d.setEnvironmentMap(...), aura.draw3d.drawSkybox(...) Environment and skybox stay on draw3d.
SkinnedMesh / Skeleton / character wrapper code aura.skinnedMesh.* or aura.scene3d.createAvatar(...) Use the avatar path for the current character-first native lane.
cannon-es, rapier, or another separate world-sim stack beside Three aura.physics3d.*, aura.character3d.*, aura.navmesh.* Physics/controller/navigation are part of Aura's runtime surface.

The Biggest Mental Shift

  • In AuraJS, aura.setup, aura.update, and aura.draw are the top-level contract. Start there before recreating a Three.js object graph.
  • Aura separates direct draw from retained scene graph. Use aura.draw3d.drawMesh(...) for small explicit draws. Use aura.scene3d when you want node hierarchy, imported scenes, culling, layers, or retained bindings.
  • Most 3D APIs use plain objects and handles, not THREE.Vector3, THREE.Euler, THREE.Object3D, or user-owned renderer instances.
  • Keep gameplay state in your scaffolded project code, not on mesh-like render objects. In practice that means sceneState, appState, config/, and content/, not ad hoc scene-node mutation as your whole game model.

Practical Port Order

  1. Port the frame loop to aura.setup / aura.update / aura.draw.
  2. Port camera and lights with aura.camera3d and aura.light.
  3. Replace procedural geometry/material creation with aura.mesh and aura.material.
  4. Decide whether the game should stay on direct drawMesh(...) calls or move to retained scene3d.
  5. Port imported .glb / .gltf scenes with aura.scene3d.loadGltfScene(...).
  6. Only then port animation, physics, character control, navmesh, or postfx.
DOCUMENT REFERENCE
docs/external/game-dev-api/migrating-from-threejs.md
AURAJS
Cmd/Ctrl+K
aurajsgg