Backend Runtime Structure

Folder Layout

runtime/
  api-3d.js
  gpu-threejs.js
  gpu-babylon.js
  api-3d/
  backends/
    threejs/
    babylon/
  shared/

Ownership

• runtime/ Public entrypoints, stable cart-facing wrappers, and compatibility re-exports.
• runtime/backends/threejs/ Three.js-specific implementation modules used by runtime/api-3d.js and the public runtime/gpu-threejs.js wrapper.
• runtime/backends/babylon/ Babylon-specific implementation modules composed by the public runtime/gpu-babylon.js wrapper.
• runtime/shared/ Cross-backend contracts and helpers that should not belong to only one renderer.

Public Compatibility Rules

• Keep flat globals stable: createCube, setCameraPosition, createPointLight, and similar functions must not change names.
• Keep nova64.* namespaces stable.
• Keep runtime/api-3d/* import paths working through re-export wrappers while backend internals live in runtime/backends/threejs/*.
• Keep runtime/gpu-threejs.js as the public Three.js entrypoint, even though the implementation now lives in runtime/backends/threejs/gpu-threejs.js.
• Keep runtime/gpu-babylon.js as the public Babylon entrypoint, even though the implementation now lives in runtime/backends/babylon/gpu-babylon.js.

Backend Surface Contract

runtime/shared/backend-surface.js defines the shared backend surface used to keep Three.js and Babylon aligned.

It currently separates:

• Required surface keys Functions that both backends must expose for cart/runtime parity.
• Capability-gated keys Functions that may be backend-specific or intentionally unsupported.

This contract is used to:

• expose Babylon cart-facing APIs without a handwritten export list
• keep required camera/light/mesh/scene accessors synchronized
• make parity regressions visible in Playwright

Capability Flags

Each backend exposes explicit capability flags:

• runtime/backends/threejs/capabilities.js
• runtime/backends/babylon/capabilities.js

Use capability checks for behavior that is intentionally unsupported instead of silent no-ops. Current examples include Babylon particles, post-processing, and dithering behavior.

Cart Reset Lifecycle

Nova64 now has a shared cart-reset pipeline so cart loads do not depend on scattered one-off cleanup calls.

Primary pieces:

• runtime/cart-reset.js Internal registry for named cart reset hooks.
• runtime/console.js Calls the shared reset pipeline at the start of Nova64.loadCart(...).
• src/main.js Registers the default runtime reset hooks used by the browser console bootstrap.

The default browser/runtime reset sequence now covers:

• input state
• UI buttons and panels
• screen manager registrations
• novaStore
• voxel world/config/material state
• scene and skybox cleanup
• camera reset
• fog reset
• manifest/env/i18n/data/assets reset

Why this exists:

• dashboard cart switching should behave like a fresh cart start
• subsystems should not leak hidden state between carts
• new stateful runtime modules need one clear place to integrate cleanup

Rule for future runtime work:

• if a module owns mutable global or long-lived cart state, register a cart reset hook for it instead of relying on ad hoc cleanup from carts or page reloads

Tests That Guard This Split

• tests/playwright/api-compatibility.spec.js Required backend surface, camera access, point-light mutation, instancing, and unsupported-capability behavior.
• tests/playwright/wad-vox-regression.spec.js Focused WAD, VOX, and Wizardry Babylon smoke coverage.
• tests/playwright/backend-parity.spec.js Broader cross-backend cart parity coverage.
• tests/playwright/visual-regression.spec.js Visual guardrails for skybox and PBR scenes where Babylon should stay close to Three.js without claiming pixel-perfect parity.

Public Backend Entry Points

• runtime/gpu-threejs.js Thin public wrapper over runtime/backends/threejs/gpu-threejs.js.
• runtime/gpu-babylon.js Thin public wrapper over runtime/backends/babylon/gpu-babylon.js.

Babylon Notes

The Babylon backend implementation is grouped into focused modules. The main implementation areas are:

• bootstrap.js
• compat.js
• scene.js
• camera.js
• lights.js
• primitives.js
• transforms.js
• models.js
• instancing.js
• surface.js

Current Babylon design rules:

• engine must mean the Nova64 engine adapter, not the raw Babylon renderer.
• getRenderer() returns the raw Babylon engine when direct renderer access is needed.
• Unsupported features should fail safely and advertise capability flags.
• Babylon WebXR support is routed through Babylon's native WebXR default experience in runtime/xr.js; do not use Three.js renderer.xr objects in Babylon mode.
• When WebXR VR is unavailable, Babylon mode should offer the Cardboard stereoscopic fallback instead of ending on an unavailable state.

Babylon Compatibility Layer

runtime/backends/babylon/compat.js is the normalization layer for Babylon objects that need to satisfy long-standing Three-style cart expectations.

It currently provides parity shims for:

• scene traversal and root inspection: scene.traverse, scene.children
• scene graph object checks: isObject3D, isMesh, isLight, type
• Babylon mesh visibility bridging: mesh.visible
• material aliases: material.color, material.map, material.transparent, material.opacity
• Babylon material render shims: needAlphaBlendingForMesh, needAlphaTesting, needAlphaTestingForMesh, isReady, isReadyForSubMesh
• imported material light budget normalization: GLB/PBR materials opt into at least eight simultaneous lights so shader compilation stays stable in carts with combat or prop point lights
• color helpers: color.set(...), color.setHex(...), color.getHex(), color.getHexString()
• texture helpers: texture.repeat, texture.offset, texture.wrapS, texture.wrapT, texture.needsUpdate
• dirty/version tracking used by parity tests and cart utilities

Design rules for this layer:

• Put backend-normalization logic here instead of scattering one-off Babylon checks through carts.
• Keep the shim focused on Nova64 cart/runtime expectations, not a full Three.js reimplementation.
• Wire compatibility at creation and assignment points so loaded models, generated meshes, lights, textures, and materials all opt in automatically.
• Back new compatibility assumptions with Playwright coverage before depending on them broadly.

Recent Babylon Rendering Work

Recent parity work focused on the places where carts were still clearly broken under Babylon:

• @babylonjs/core is now pinned to the current latest 9.x line used by the backend parity work.
• Babylon enableAR() now creates a native Babylon WebXR AR entry point, while enableVR() creates a Babylon WebXR entry point when the browser supports it.
• Babylon VR now exposes a working Cardboard fallback when native WebXR is not available, using Babylon stereoscopic camera rig mode and device-orientation updates.
• MediaPipe camera-background helpers now avoid assigning Three.js VideoTexture objects into Babylon scenes; Babylon uses a DOM video layer and transparent scene clear color for AR-style passthrough.
• ar-hand-demo now initializes its 3D scene even when webcam or MediaPipe hand tracking cannot start, so Babylon/headless smoke coverage does not fail on camera availability.
• WAD wall, floor, and sprite materials now use a safer Babylon texture/material path, including alpha and color-space handling for runtime-created textures.
• Babylon WAD rendering now leans on the compat layer for shared mesh/material/texture behavior instead of cart-local backend branching for every parity gap.
• Textured WAD walls use Babylon planes with per-mesh UV updates, while the Babylon wall/floor material tuning now avoids the earlier over-bright emissive look.
• Babylon engine-level material assignment now resolves mesh proxies as well as numeric mesh IDs, which keeps WAD wall/floor/sprite textures attached when carts call engine.setMeshMaterial(meshProxy, material).
• Babylon vignette/post-processing setup now capability-checks pipeline properties and falls back when image-processing internals are unavailable, preventing WAD cart boot from aborting during environment load.
• Babylon native camera controls stay detached from the canvas so cart-owned camera movement remains deterministic across demos and tests.
• Three-style runtime calls like material.color.set(0x336699) and texture.repeat.set(...) now behave consistently on Babylon too.
• wizardry-3d no longer depends on the old store polyfill behavior; plain-object game store initializers now work with real Zustand too.
• Procedural Babylon sky spheres now use the correct material path and ignore fog, which fixes the blown-out hello-skybox rendering.
• Image skyboxes now rebuild asynchronously in carts that clear the scene, and Babylon now splits environment-map usage from visible skybox usage instead of treating both as the same texture path.
• Babylon planes are created double-sided so rotated floor planes in carts like pbr-showcase and wad-demo render reliably.
• Babylon voxel carts now use a backend-native voxel path in runtime/backends/babylon/voxel.js for atlas textures, chunk meshes, and simple voxel entity boxes instead of trying to add raw Three.js meshes into a Babylon scene.
• runtime/api-voxel.js now builds backend-neutral voxel mesh payloads and delegates chunk/entity creation to the active renderer, which fixes the Babylon gpu.scene.add is not a function crash path in carts like minecraft-demo and voxel-creatures.
• The default voxel world seed is now derived deterministically from the cart/demo identity instead of Math.random(), so Babylon and Three load the same terrain unless a cart explicitly requests a custom seed.
• Babylon voxel chunk materials now use a safer two-sided shader path, which fixes the large terrain-void/culling mismatch that was still visible in minecraft-demo.
• Babylon now also has guarded NOA probe and adapter seams in runtime/backends/babylon/noa-prototype.js and runtime/backends/babylon/noa-adapter.js; use them to investigate noa-engine incrementally without letting a Babylon-only engine bypass Nova64's shared voxel API. See docs/BABYLON_NOA_PROTOTYPE.md and docs/BABYLON_NOA_INTEGRATION.md for the current guardrails.
• The first tsl-showcase Galaxy scene now uses deterministic star placement, which makes Babylon-vs-Three visual comparisons measure renderer parity instead of per-load randomness.
• Babylon high-strength bloom requests now map to a wider/brighter Babylon post-processing setup so glowing TSL scenes stay closer to the Three.js UnrealBloom path while low-strength bloom scenes keep the conservative mapping.
• createCube(...) now accepts rectangular width/height/depth/color signatures as well as the classic cube size/color signature in both backends, keeping scene prop dimensions stable in demos such as particles-demo.
• createSphere(...) now accepts material options as the fourth argument as well as the explicit segments/options form, matching cart usage in glow-heavy demos such as the galaxy particle scene.
• createCylinder(...) now accepts the cart-facing radius/height/color signatures and the older tapered radiusTop/radiusBottom/height signature in both backends, preventing Babylon from interpreting colors as giant cylinder heights.
• createPlane(...) forwards material options through both backends, including opacity and transparency, so shared translucent scene props do not become opaque rectangles on Three.js.
• Babylon thin instances keep their source mesh render-visible, refresh matrix/color buffers during finalizeInstances(...), and refresh bounds so the same instanced cart content remains visible under Babylon.
• Babylon particles now opt into mesh-level vertex colors/alpha, correct Babylon alpha modes, and HDR bloom so emissive particle carts such as particles-demo stay much closer to Three.js.
• 3D particle emitters now accept directionX, directionY, and directionZ in both backends; the default remains upward, but carts such as the waterfall scene can emit downward water without relying on inverted gravity.
• Godot shim now exposes engine.createDataTexture(pixels, w, h) as a material-proxy entry point routing through texture.createFromImage in the bridge; cart code that calls engine.createDataTexture and then passes the handle to engine.createMaterial({ map: tex }) works the same way as the Three.js and Babylon adapters.
• Godot material.create bridge command now accepts uvOffset (Vector3) alongside uvScale, enabling setWallUVs to pass WAD texture X/Y offsets through to StandardMaterial3D::set_uv1_offset so DOOM wall textures align precisely instead of being clamped to origin.
• Godot shim's WADTextureManager._uploadDataTexture now delegates to engine.createDataTexture internally, removing duplicated bridge-transport code.
• Godot shim now exposes getCamera() in nova64.camera returning { position: { x, y, z } }, so billboard sprite code like const cam = getCamera(); Math.atan2(cam.position.x - e.x, ...) works without throwing on the Godot host.
• Godot createPlane already creates double-sided planes by default (matches the Babylon plane double-sided fix), so WAD floor/ceiling and sprite billboards render correctly from all viewing angles.
• Point lights now include a shared setLightVisible(id, visible) backend API, allowing carts to temporarily hide scene-local lights during alternate scene states such as Indie Odyssey combat without destroying and recreating them.
• Babylon imported GLB materials now receive the compat-layer render-method shims and a minimum simultaneous-light budget, preventing PBR shader compile failures when carts mix default lights with several controlled point lights.
• Babylon bloom now accepts the same object-form options as the Three.js effects API and pairs low-strength bloom with a restrained GlowLayer, so emissive cart geometry such as Indie Odyssey's neon grid reads as glow instead of flat colour.
• Babylon material creation now honors emissiveIntensity for PBR and Standard materials; carts can tune backend parity without replacing materials or branching into raw Babylon APIs.

Current visual status:

• hello-skybox is back in close visual range with Three.js and covered by Playwright visual regression.
• pbr-showcase is much closer than the earlier broken Babylon output, but it still does not match Three.js perfectly because Babylon does not yet have full PMREM and post-processing parity in Nova64.
• tsl-showcase scene 1, Galaxy Spiral, has a focused visual regression check and currently stays below the intentionally loose shader/parity threshold after the deterministic star-field and Babylon bloom tuning work.
• wad-demo now has focused Babylon visual guardrails and is back down in the low-single-digit diff range in the gameplay-frame regression check on a clean server.
• Babylon voxel carts now boot and render chunk/entity content without Three-only scene errors, but voxel visual parity still needs follow-up work around custom material parity, chunk shading, and screenshot-level similarity against Three.js.
• minecraft-demo now has deterministic terrain and a focused voxel visual regression guardrail, with the Babylon gameplay-frame diff back down into the low-to-mid teens instead of the earlier broken ~35%+ range caused by seed drift and chunk-face culling.
• The visual regression threshold for pbr-showcase is intentionally looser than simple skybox scenes so it can still catch major regressions without pretending the two backends are identical today.
• particles-demo now has a focused visual regression pass again after the cylinder signature fix and Babylon particle bloom/material tuning; the demo is still not pixel-identical, but the fire scene should no longer show the old center-pillar artifact.
• particles-demo also has a waterfall-specific visual regression check, and instancing-demo now uses deterministic scene layouts plus its own visual parity guardrail.

Focused Validation

These are the most useful narrow checks for the current Babylon parity surface:

• pnpm test:babylon:api
• pnpm exec playwright test tests/playwright/api-compatibility.spec.js --reporter=line
• pnpm exec playwright test tests/playwright/wad-vox-regression.spec.js --grep "wad-demo" --reporter=line
• pnpm exec playwright test tests/playwright/wad-vox-regression.spec.js --grep "Voxel Regression" --reporter=line
• pnpm exec playwright test tests/playwright/backend-parity.spec.js --grep 'Minecraft Demo|Voxel Terrain|Voxel Creative|Voxel Creatures' --reporter=line
• pnpm exec playwright test tests/playwright/visual-regression.spec.js --grep "minecraft-demo should stay reasonably similar" --reporter=line
• pnpm exec playwright test tests/playwright/visual-regression.spec.js --grep "wad-demo gameplay frame" --reporter=line
• pnpm exec playwright test tests/playwright/visual-regression.spec.js --grep "tsl-showcase galaxy" --reporter=line
• pnpm exec playwright test tests/playwright/visual-regression.spec.js --grep "particles-demo" --reporter=line
• pnpm exec playwright test tests/playwright/xr-ar-babylon.spec.js --reporter=line

Use the WAD-specific visual and regression slices first when touching Babylon WAD rendering, UVs, materials, lights, or compatibility shims. Use the voxel-focused regression and backend-parity slices first when touching runtime/api-voxel.js or runtime/backends/babylon/voxel.js. Use the XR/AR slice first when touching runtime/xr.js, runtime/mediapipe.js, or demos that call WebXR/MediaPipe APIs. Use the TSL Galaxy slice first when touching Babylon post-processing, procedural shader materials, particle glow, or the tsl-showcase cart.

Remaining Babylon Work

Remaining Babylon parity work is tracked in ../BACKLOG.md. Keep this document focused on backend architecture, runtime contracts, and validation guidance rather than a second backlog.

Extending The Runtime

When adding a new cart-facing 3D API:

1. Add the function to the appropriate backend module(s).
2. Update runtime/shared/backend-surface.js if it is required or capability-gated.
3. Expose it through the public wrapper layer.
4. Add or update parity coverage in Playwright.

When behavior is backend-specific:

1. Add an explicit capability flag.
2. Fail safely instead of throwing in normal cart usage.
3. Cover the limitation with a focused regression or compatibility test.