Physics, Terrain, Navmesh, Character3D, and Compute

This page covers the simulation-heavy world helpers that sit outside the basic 2D/3D drawing stack.

`aura.physics` (optional module)

2D/world physics surface:

• setGravity(gravity)
• configureStep(options)
• body(options)
• step(dt)
• captureSnapshot()
• rollback(snapshotOrTick)
• replay(fromTick, toTick?)
• restoreSnapshot(snapshot)
• queryPoint(point, options?)
• queryAABB(bounds, options?)
• queryOverlap(shapeOrBody, options?)
• queryRaycast(ray, options?)
• queryPointDetailed(point, options?)
• joint(options)
• removeJoint(jointId)

The body() view also exposes body-local helpers such as:

• applyForce(...)
• setVelocity(...)
• setAngularVelocity(...)
• setFilter(...)
• setFriction(...)
• setRestitution(...)
• setRotationLocked(...)
• setMass(...)
• setDamping(...)
• getMassProperties()
• onCollide(callback)
• setNextPosition(...)

`aura.physics3d`

3D physics surface:

• setGravity(gravity)
• configureStep(options)
• body(options)
• step(dt)
• captureSnapshot()
• rollback(snapshotOrTick)
• replay(fromTick, toTick?)
• restoreSnapshot(snapshot)
• queryPoint(point, options?)
• queryAABB(bounds, options?)
• queryRaycast(ray, options?)
• joint(options)
• removeJoint(jointId)

The body() view similarly exposes per-body force/filter/callback helpers.

Query split guidance:

• use aura.collision3d.* for pure math helpers over authored boxes, spheres, rays, planes, and sweep intervals; this lane does not inspect the live scene graph or a physics world
• use aura.collision3d.raySphereHit(...), rayBoxHit(...), rayPlaneHit(...), sphereBoxContact(...), and boxBoxContact(...) when that pure-math lane needs structured hit/contact data instead of boolean-only probes
• use aura.scene3d.queryRaycast(...) when you need retained scene3d node identity, render-binding identity, or retained-scene filters such as layerMask, visibleOnly, and requireRenderBinding
• use aura.scene3d.pick(...) when that same retained-scene query starts from screen pixels rather than an authored world ray
• use aura.scene3d.raycast(...) when you need submitted draw-mesh hits or optional triangle tests instead of retained node identity
• use aura.physics3d.queryRaycast(...) when you need physics-body queries, collision filters, and physics-world ownership

Practical rule:

• if you only have shapes and vectors, stay on collision3d
• if you need authored node identity from the retained scene graph, use scene3d.queryRaycast
• if you need screen-space picking on that same retained-scene lane, use scene3d.pick
• if you need submitted mesh or triangle-hit truth, use scene3d.raycast
• if you need physics-layer truth, use physics3d.queryRaycast

`aura.terrain`

Terrain surface:

• create(options)
• destroy(terrainHandle)
• setSplatMap(terrainHandle, source)
• setLayerTexture(terrainHandle, layerIndex, source)
• setHeightmap(terrainHandle, sourceOrData)
• sampleHeight(terrainHandle, x, z)
• addVegetation(terrainHandle, options)
• removeVegetation(terrainHandle, vegetationId)
• setVisible(terrainHandle, visible)

Use cases:

• terrain authoring from generated or imported heightmaps
• splat/layer texturing
• vegetation placement

`aura.navmesh`

Current runtime surface:

• bakeFromMesh(meshHandleOrSpec, options?)
• findPath(navmeshHandle, from, to, options?)
• createCrowd(navmeshHandle, options?)
• addAgent(crowdHandle, options)
• removeAgent(crowdHandle, agentId)
• setAgentTarget(crowdHandle, agentId, target)
• updateCrowd(crowdHandle, dt)
• getAgentPosition(crowdHandle, agentId)
• getAgentVelocity(crowdHandle, agentId)

Important note:

• There is no standalone aura.crowd namespace today.
• Crowd simulation is driven through aura.navmesh.createCrowd(...) and the related crowd methods above.

`aura.character3d`

Character controller surface:

• create(options)
• move(handle, movementSpec)
• jump(handle, options?)
• setPosition(handle, position)
• getPosition(handle)
• getState(handle)
• setGravity(handle, gravity)
• destroy(handle)
• update(dt)
• addObstacle(handle, obstacle)
• clearObstacles(handle)

Use cases:

• platformer-style or action-game player controllers
• AI agents that need controller-style movement instead of rigidbody simulation

`aura.compute`

GPU compute surface:

• createPipeline(wgslCode, entryPoint?)
• createBuffer(size, usage?)
• writeBuffer(bufferHandle, data, offset?)
• createBindGroup(pipelineHandle, entries)
• dispatch(pipelineHandle, bindGroupHandle, x, y?, z?)
• readBuffer(bufferHandle, offset?, size?)
• destroyPipeline(handle)
• destroyBuffer(handle)
• destroyBindGroup(handle)
• getError(handle)

Runtime notes:

• usage accepts "storage", "uniform", "storage-read" / "storage_read", and "readback" / "staging".
• readBuffer(...) is queued. Pass a positive size to request readback; the first call returns null, and a later call returns the completed Float32Array / Uint8Array view.

Use cases:

• custom simulation kernels
• GPU-side preprocessing
• agent-generated procedural systems that need raw compute instead of only draw APIs