Migrating from Aura3D 4.x to 5.0.0

Status: 5.0.0 released 2026-11-03 and superseded by 5.0.1 (2026-11-05); install 5.0.1. This guide covers every breaking and behavior change between Aura3D 4.7.16 and 5.0.0, checked against the packed 5.0.0 packages.

5.0.1 note. 5.0.1 is 5.0.0 plus render fixes; the public API and every row below are unchanged. 5.0.0 blanked the showcase games because contact shadows and eleven other new hard throws rejected the mount. In 5.0.1 those paths degrade with a one-time console.warn code (CONTACT_SHADOW_DEGRADED, DEPTH_ALPHA_HASH_DEGRADED, DEPTH_ALPHA_COVERAGE_DEGRADED, TRANSMISSION_DEGRADED, DIFFUSE_TRANSMISSION_DEGRADED, TEXTURE_FLIPY_DEGRADED); strict mode still throws. Contact shadows are skipped in scenes with an extra contributor pass or a transparent queue. Behaviours quoted below as 5.0.0 behaviour that throw on these paths apply to strict mode only in 5.0.1. See the changelog.

1. Summary

5.0.0 is 4.7.16 plus the native-capability program (roadmap, decision record). Most of the change is additive: new subpaths, a new @aura3d/addons package, an explicit readiness contract, request-policy-aware asset loading, and opt-in WebGPU, worker, depth, color and volumetric paths. Under the deprecation policy, 5.0.0 also removes what 4.x scheduled for removal: nine legacy @aura3d/engine subpaths and 38 deprecated root values (B14, B15). Nothing first deprecated in 5.x is removed.

The breaking changes are narrower than the major number suggests:

• the root createGame now throws a migration error instead of returning a headless stub;
• a few public types gained required members or wider unions, which breaks code that implements those types or switches over them exhaustively;
• renderer.backend is typed and validated, and the experimental-webgpu quality profile now requests WebGPU instead of throwing;
• strict-mount failures reject with a different error object;
• the experimental @aura3d/react adapter changes when onReady fires and how failures and shared resources behave;
• the deprecated 4.x root values and legacy subpaths are removed (B14, B15);
• @aura3d/assets resolves its own browser declarations under the browser condition (B16);
• ConvexHull and its face, edge and vertex classes are the independent hull: structural inputs, frozen HullVector3 results, bounded construction (B17).

Aura3D remains a standalone engine with its own renderer. WebGL2 remains the default backend.

2. Who is affected

3. Upgrade steps

1. Upgrade every @aura3d/* package together. Mixed 4.x/5.x installs are not a supported combination.

   npm install @aura3d/engine@^5.0.0 @aura3d/cli@^5.0.0
   # plus any of: @aura3d/react @aura3d/assets @aura3d/rendering @aura3d/addons ...

2. For a new project, scaffold with npx create-aura3d@latest my-scene --template <template>. It writes the current llms.txt and Aura3D skills. For an existing project, refresh the skills with the CLI version you install.
3. Peer dependencies. @aura3d/engine keeps its optional peers unchanged: @dimforge/rapier3d-compat 0.20.0 and recast-navigation 0.43.1. @aura3d/react declares react ^19.0.0 || ^18.0.0 (unchanged) and @aura3d/engine ^5.0.0 (was ^4.7.16).
4. Fix the compile errors from section 4. Then search your code for createGame imported from "@aura3d/engine", for the removed root values (B14) and for the removed subpaths (B15). For the renderer subpaths, npx @aura3d/cli@latest codemod renderer-imports "src/**/*.ts" --write rewrites @aura3d/engine/advanced-runtime and /production-runtime imports to @aura3d/engine/renderer.
5. Rebuild, then run npx @aura3d/cli@latest check-deploy --dist dist. In this monorepo, run browser checks on the remote runner (tools/remote-acr/run.sh).

4. Breaking changes

@aura3d/react is experimental (support policy), so B7 to B9 fall outside the stable-API window. They are listed here because they change observable behavior.

5. Behavior changes

These need no code change for most apps, but they change what an existing call does.

5.1 Readiness: typed success, failure and cancellation

app.ready() keeps its 4.x contract. It settles when the mount settles, and in non-strict mode it resolves even if the mount failed. Two calls are new:

const outcome = await app.readiness({ stage: "first-frame", signal });
// { state: "ready", stage, backend } | { state: "failed", code, message }
// | { state: "cancelled" | "disposed" } | { state: "superseded" }

await app.readyStrict(); // rejects on failure (AuraReadinessError), cancellation (AbortError), disposal or supersession

Each non-ready outcome has one cause, and the app's own mount state never changes because a waiter stopped waiting:

app.onRenderTermination(listener) and app.renderTermination() report a mount's terminal state (failed, device-lost, superseded, disposed) with an app-local revision. Subscribe first, then read renderTermination(), because events are not replayed. Source: packages/engine/src/agent-api/nodes/types/runtime.ts (AuraReadyOutcome, AuraRenderTermination, AuraReadinessOptions), stability policy.

5.2 Renderer mount failures and canvas ownership

• A WebGPU or auto app cannot share a canvas or device that another managed renderer already owns. The codes WEBGPU_CANVAS_IN_USE, WEBGPU_DEVICE_IN_USE and WEBGPU_OWNERSHIP_CLEANUP_FAILED reject app.ready() **even without strict**, and they do not paint an error overlay on the peer's canvas (createAuraAppCore.ts, managedCanvasInUse, ownership branch of the mount handler).
• When no WebGL2 or WebGPU renderer is available, the mount records renderer-unavailable in readiness().

5.3 Disposal and cancellation

Remount cleanup now runs every owned disposer (unsubscribe, compute, controller, physics) separately and aggregates their failures, so one failing disposer no longer skips the others. Renderer resource retirement after disposal can be awaited through the renderer controller's whenDisposed(). Cancelled asset decodes are not dispatched, and a decoder result that arrives after cancellation is closed.

A resource whose cleanup fails stays owned and reported rather than being dropped: the failure rejects app.disposeAsync() (or throws from dispose() on the owning handle), and the next call retries only the failed resource, never ones that already retired. This includes a ProgramCache shader program whose disposer threw, also when the program arrived late, after the cache was disposed (ProgramCache.disposalFailures(device) marks entries resolved once a retry succeeds).

Disposing an app cancels every load it owns: texture.load(url, { app }), texture.loadNativeAsset(asset, { app }) and scene model loads reject at once with an AbortError. Their network requests receive an aborted signal even when you passed none. A load that fails after its app closed is not reported to that app's onAssetError, and new loads for a closed app are rejected before any request starts. Call app.dispose() when an app is no longer needed and release resources through their owning handle (stability policy; audit, WP-07 and WP-21 entries).

Typed GLB actors release registered-format (non-glTF adapter) resources asynchronously after actor.dispose(). awaitTypedGLBActorDisposals (new in 5.0.0, exported from @aura3d/engine/renderer next to createTypedGLBActor) waits for that teardown and rejects with an AggregateError ("Native model cleanup failed") if it failed. Call it with no argument to drain actors you created with createTypedGLBActor directly (no runtimeOwner); it never waits on app-owned actors, and each ownerless failure is reported once. awaitTypedGLBActorDisposals(owner) drains only the actors created with that runtimeOwner; app.disposeAsync() already does this for the actors an app mounts.

import { awaitTypedGLBActorDisposals, createTypedGLBActor } from "@aura3d/engine/renderer";

const actor = await createTypedGLBActor({ asset: assets.robot, id: "robot", width, height, formatRegistry });
actor.dispose();
await awaitTypedGLBActorDisposals(); // ownerless actors

5.4 Asset loading: request policy, credentials and cache partitioning

• AssetRequestOptions (@aura3d/assets) adds credentials, headers, cache, priority, mode, redirect, referrerPolicy, allowedOrigins, sourceOrigin, expectedUrl, maxBytes, integrity and securityContext. One policy covers a document and its dependencies, and credentials do not leak to other origins (packages/assets/src/AssetLoader.ts).
• **Without a securityContext, requests that may carry browser credentials are neither shared nor cached.** To keep cache reuse for credentialed loads, set a non-secret generation per app (createAuraApp(canvas, { assets: { securityContext: "session-42" } })). Dispose and recreate the app when credentials change. An empty or non-string value throws (packages/engine/src/contracts/assets.ts, snapshotAuraAssetsOption).
• Default limits: browser raster images in glTF are capped at 64 MiB input and 32 Mi-pixels (packages/assets/src/BrowserImageDimensions.ts). KTX2 input is capped at 64 MiB while it is fetched, not only after it is fully loaded. Larger images that loaded in 4.x are now rejected with a diagnostic.
• Error messages and diagnostics redact URLs and cause details (AssetLoadError, glTF fallback diagnostics).
• glTF now accepts finite, non-negative alphaCutoff values above 1 (a relaxation).

5.5 Decoder registration and native formats

• glTF/GLB is built in. Other model formats need an adapter registered per app through createAuraApp(..., { formatRegistry }); install only the formats the app uses. AuraModelFormat is open for that reason (B3).
• Basis/KTX2 and Draco initialization now waits for the factory to settle before a decoder is published, and releases abandoned decoder instances before the disposal barrier settles. @aura3d/assets adds a ./vite-client subpath next to ./vite for decoder wiring. Its sideEffects field now lists the KTX2 and Zstd worker modules (previously false), so bundlers keep those files.

5.6 Color pipeline

The default stays a linear working space with sRGB output. output.outputColorSpace may request display-p3. The active space can fall back to sRGB, and diagnostics() reports outputColorSpace as "srgb", "display-p3" or "unknown" (the device-observed value, not a claim about the physical display). output.alphaMode defaults to opaque. Alpha-preserving output also needs an explicit inputAlphaMode warranty (packages/engine/src/contracts/output.ts). @aura3d/rendering adds managed color conversion helpers (convertManagedColor, convertColorPrimaries, transformColorForOutput, and others).

5.7 Camera depth

camera.depth: { mode: "standard" | "reversed" | "logarithmic", allowFallback? } is new. All three modes render natively in the production renderer; the nonstandard modes are experimental (source and mock-device tested, no real-GPU evidence yet). Every mode is authored with a minus-one-to-one camera projection and requires a finite far (packages/engine/src/agent-api/compiler/cameraDepth.ts); the renderer rebuilds a reversed projection in zero-to-one form where the device rasterizes it.

• Reversed. The projection maps near to depth 1 and far to depth 0; the frame clears depth to 0 and compares greater-equal. Material depthCompare and polygon offsets stay authored in standard terms; the renderer and devices flip them for the frame. On WebGL2 with EXT_clip_control the frame rasterizes a zero-to-one reversed projection into float depth (DEPTH32F_STENCIL8) and renderer.getDepthConvention() / diagnostics().renderer.depth report precision: "full". Without the extension, on WebGPU (its programs remap the minus-one-to-one projection in the vertex stage) or when the frame draws straight into a fixed-point canvas or caller target, ordering is correct and precision is "reduced" with a precisionReason. Render targets accept depthPrecision: "float" (WebGPU: depth32float, or depth32float-stencil8 when the device was created with that feature, else depth24plus-stencil8).
• Logarithmic. The projection is the standard one; generated programs write ln(distance / near) / ln(far / near) as fragment depth, which disables early depth testing for those draws. Requires finite 0 < near < far. Generated WebGL2 and WebGPU programs both write it (WGSL @builtin(frag_depth), same formula, same view and near/far data). Custom or legacy shaders that cannot write logarithmic depth fail with FORWARD_LOG_DEPTH_PROGRAM_UNSUPPORTED.
• What follows the convention. Clears, forward and VFX draw compares, camera depth prepasses (outlines), postprocess depth linearization (AO, DoF, SSR, motion blur, fog, god rays), scene depth copies and CPU depth readback. Shadow maps, probe faces and mirrors keep standard depth for their own projections. Picking and scene queries use app.viewProjection, which is always the standard-depth matrix (x/y is identical in every mode); pass camera.depth.mode to raycast when you supply a reversed matrix yourself.
• Precise failures. Contact shadows, Gaussian splats, scalar volumes, depth preview materials and the native deferred/meshlet/visibility paths require standard depth (or use the forward renderer). Weighted transparency falls back to sorted transparency. The standalone legacy VolumeRenderer (draw({ depth }), default the owning device's active convention) and vegetation impostors (bind impostorDepthUniforms(convention)) write fragment depth in the frame convention.

Before 5.0 the same request threw DEPTH_MODE_UNSUPPORTED, or with allowFallback: true rendered standard depth.

6. New opt-in features (experimental)

Every item here is experimental in 5.0.0. You must opt in, the documented fallback applies, and browser, GPU and device evidence is still pending (claims and boundaries). A source export or mock-device test does not establish rendered or hardware support.

AuraAssetRefIdentity<TType, TId> is a new public type of the root: the kind, id, type and brand fields of an asset ref, so AuraAssetRef is now AuraAssetDefinition & AuraAssetRefIdentity (the same structure as 4.x). A project compiled with declaration: true can now export an inferred value that holds assets.x refs (for example export const bundle = { hero: assets.hero }); in 4.x the emitted type had to name the engine's private brand symbol and failed with TS4023, which forced an explicit type annotation. Refs still come only from defineAuraAssets; the type does not let you construct one.

bindPointerInteractions(app, listener) is a new public export of the root and the staged @aura3d/engine/v5 entry: it routes canvas pointer events to interactions.pointer({ target }) nodes, firing a targeted interaction only when its node is the nearest hit, and returns a disposer.

Hinge joint limits are relative to the creation pose

In 5.0 hinge limits are measured from the pose the joint was created in (both on the Rapier backend and the native solver). In 4.x they were absolute angles. If a hinged body is created already rotated (for example a flipper at rest angle rest that swings to up), change limits: [rest, up] to limits: [0, up - rest]. Bodies created at their zero pose are unaffected.

lookAt on models and primitives is now applied

In 4.x the render path silently ignored lookAt on models and primitives (only Gaussian splats honoured it). In 5.0 the model matrix applies it, composed with any pivot (the pivot point stays fixed and -Z faces the target). If a 4.x scene set lookAt on a model or primitive and relied on it being ignored, remove it. Camera lookAt is unchanged. (No in-repo app or template used model/primitive lookAt.)

7. Removed deprecated items (B14, B15)

These were deprecated in 4.x and removed in 5.0.0 (breaking changes B14 and B15).

Removed @aura3d/engine subpaths (B15):

Removed root values, grouped by replacement (B14):

Under the stability policy, nothing first deprecated in 5.x was removed in 5.0.0.

8. Checklist

• All @aura3d/* packages on the same 5.0.x version; lockfile refreshed.
• No createGame imported from "@aura3d/engine"; game code uses @aura3d/engine/game.
• Mocks and adapters of AuraApp / AuraRuntimeNodeHandle / AuraRuntimeNodeSnapshot implement the new members.
• Exhaustive switches over outputColorSpace, AuraAssetType, AuraModelFormat and material kind have a default branch.
• renderer.backend is webgl2, webgpu or auto; experimental-webgpu profile removed or paired with an explicit fallback choice.
• Strict-mount error handling branches on error.code, or uses readiness() / readyStrict().
• Credentialed asset loads set assets.securityContext if they need cache reuse; images fit the 64 MiB / 32 Mi-pixel limits.
• React: onError or an error boundary around AuraCanvas; custom shared loaders pass a securityContext.
• No imports of the removed root values (B14) or legacy subpaths (B15); see section 7.
• Experimental paths (WebGPU, workers, depth, P3, compute) opted into only with a fallback you have tested.
• npm run build && npx @aura3d/cli@latest check-deploy --dist dist passes.

9. Verify before relying on this guide

These items are uncertain in the current source and must be confirmed against the packed 5.0.0 release:

• Packed declarations. Every manifest reads 5.0.0, but the breaking-change list reflects source, not the packed declarations that the stability policy requires comparing.
• Camera depth. Reversed and logarithmic depth now render natively (section 5.7) without real-GPU evidence. Reversed precision is full on WebGL2 with EXT_clip_control; WebGPU logarithmic depth renders natively. Open: full reversed precision on WebGPU (programs must consume a native zero-to-one projection), infinite far (decision record, item 3).
• WebGPU teardown. A named 5.0 defect. Teardown behavior on disposal (whenDisposed()) may change.
• WebGPU wetness (experimental). atmosphere.setWetness now renders wet surfaces on the native WebGPU forward program and on the deferred, meshlet and visibility paths, with the same response as WebGL2 (darker albedo, smoother puddle roughness, snow cover). It has no real-GPU evidence yet. A puddle-noise texture is not supported on WebGPU.
• Pointer, XR and input types. PointerSnapshot, GamepadSnapshot and the XR types gained exports. Whether any existing interface gained a required member was not audited for this guide.
• Custom geometry attribute types. AuraCustomGeometrySpec.attributes and morphTargets changed type (AuraCustomVertexAttributeSpec, AuraCustomVertexAttributeData). Confirm that 4.x literal inputs still type-check.
• Installed behavior. Every behavior in sections 5 and 6 is source- or mock-tested only. Browser, GPU, device and packed-consumer results are pending acceptance.