Getting Started 3D

The fastest way to get a stable 3D AuraJS project is to start with a tiny authored scene:

one camera
one ambient light
one directional light
one or two meshes
one or two materials

Do not start with imported animation, terrain, physics, and UI all at once.

The golden path

For a first native 3D project:

configure the camera in aura.setup
create a small number of meshes and materials
clear and draw the scene in aura.draw()
add scene graph and imported content after the base render path is stable
add physics, character control, terrain, or navmesh only when the game needs them

Minimal 3D loop

let floorMesh = null;
let crateMesh = null;
let floorMaterial = null;
let crateMaterial = null;
let spin = 0;

aura.setup = function () {
  aura.camera3d.perspective(60, 0.1, 100);
  aura.camera3d.setPosition(0, 3.2, 6.5);
  aura.camera3d.lookAt(0, 0.8, 0);

  aura.light.ambient(aura.rgba(1, 1, 1, 1), 0.3);
  aura.light.directional({ x: -0.5, y: -1, z: -0.35 }, aura.rgba(1, 0.97, 0.92, 1), 1.15);

  floorMesh = aura.mesh.createPlane(10, 10);
  crateMesh = aura.mesh.createBox(1, 1, 1);

  floorMaterial = aura.material.create({
    color: aura.rgba(0.18, 0.2, 0.24, 1),
    roughness: 0.92,
    metallic: 0.04,
  });

  crateMaterial = aura.material.create({
    color: aura.rgba(0.78, 0.55, 0.26, 1),
    roughness: 0.72,
    metallic: 0.08,
  });
};

aura.update = function (dt) {
  spin += dt;
};

aura.draw = function () {
  aura.draw3d.clear3d(aura.rgba(0.04, 0.05, 0.07, 1));

  aura.draw3d.drawMesh(floorMesh, floorMaterial, {
    position: { x: 0, y: 0, z: 0 },
    rotation: { x: 0, y: 0, z: 0 },
    scale: { x: 1, y: 1, z: 1 },
  });

  aura.draw3d.drawMesh(crateMesh, crateMaterial, {
    position: { x: 0, y: 0.5, z: 0 },
    rotation: { x: 0, y: spin, z: 0 },
    scale: { x: 1, y: 1, z: 1 },
  });
};

When to add more systems

Add the next layers in this order:

aura.scene3d for hierarchy and render-node binding
aura.scene3d.loadGltfScene(...) for imported content
clip playback and imported animation
aura.physics3d and aura.character3d
aura.terrain and aura.navmesh

That order keeps debugging simple:

if the scene does not render, the problem is still in the core 3D path
if imported content fails, the problem is in asset/import data
if movement fails, the problem is in the simulation layer

Character-first native path

Once the procedural floor is stable, the canonical next proof is the direct plain-JS avatar path:

aura.scene3d.loadGltfScene(...)
aura.scene3d.getImportedScene(...)
aura.scene3d.createAvatar(...)
avatar.tick(dt)
aura.scene3d.submitRenderBindings()

Current honest boundary:

the committed avatar fixture is the small shipped starter-avatar.gltf asset
it proves imported avatar + animation + controller + camera integration
it is not claiming a production-ready skinned hero export pipeline

Recommended 3D habits

get one procedural scene rendering before you trust imported assets
keep a single known-good light rig for early iteration
prefer one working material first, then add texture complexity
use scene3d when you need hierarchy or imported-scene metadata
use the avatar path when you need the current character-first native path, not just a procedural render floor
treat browser parity as a separate concern; native 3D is the main path today

Common mistakes to avoid

starting with too many engine systems at once
assuming 3D behavior is available in the browser build
loading authored content before you have a known-good camera and light setup
mixing rendering bugs and physics bugs in the same first test scene

AURA

JSGG