Work in progress. This makes large 3D scenes scale with what the camera sees, rather than with the number of objects. It's measured on the 3d-car-coin-hunt example with a city 10 times larger, and with a new CI benchmark.

Measurements: 3d-car-coin-hunt with a 10x larger city

The city of the example (buildings, roads, trees, parked cars, coins) is repeated in 5x2 tiles, giving 2800 instances. The game is exported with the CLI of the portable build and played headlessly with scripted inputs (driving around) through the gameplay test harness, rendering without a GPU.

Why it was slow: draw calls barely grow with the city, because Three.js already frustum-culls each mesh. But at each render, Three.js goes through every mesh of the scene (about 20,000 nodes at x10) to:

• update its matrices: 24% of the JavaScript time;
• find what to draw for the camera and for the shadow map: 28%, plus 11% of frustum tests.

Changes

• 3D culling (layer-pixi-renderer.ts): before rendering a 3D layer, 3D models and cubes whose box is outside the camera frustum, and outside the frustums of the shadow cameras (directional and spot lights), are hidden (visible = false). Three.js then skips their meshes.
  • Three.js no longer updates their matrices at each render. Their matrices are updated when they are culled and whenever they move, including when an extension calls updateMatrixWorld on them, so raycasts (like the Raycaster3D extension) and extensions reading positions stay correct.
  • The test is a sphere containing the box, whatever the rotation, flipping and center. It's done per GDJS object (2800 tests) rather than per mesh (about 16,000).
  • Never culled: objects that can render outside their box, through isRenderedInsideItsBox(). That covers models with an animation, objects whose root has children added by extensions (like lights), custom objects and extension objects.
  • Disabled for the frame: when a shadow-casting point light exists, or when the last render had a shadow-casting light that the culling didn't check (for example a light nested in an object, detected by watching the shadow map renderer). Also disabled in the in-game editor and for VR.
• Model3D: the animation mixer is no longer updated for models without an animation playing (it ran for all 2800 objects).
• New CI benchmark "Large 3D city (2500 buildings)": 2500 Model3D buildings on a grid, 40 moving cars, a directional light with shadows, and a camera driving through the city. On CI: about 8-9.5ms → 3ms per frame (-63%). The other benchmarks are unchanged.
  • Its draw calls go from 469 to 451, and the benchmark comment flags this counter. The sphere around each box is tighter than the bounding spheres Three.js uses per mesh, so a few meshes that Three.js would send to the GPU without drawing any pixel are skipped. The rendering is the same (below).

Checks

• Renders are pixel-identical between master and this PR: full-resolution screenshots of the x1 and x10 cities, at 3 moments of the drive each.
• The state checksums of the harness are identical.
• New tests (tests/Extensions/3d-culling.js):
  • far objects are hidden, and shown again once they can be seen;
  • objects hidden by the game stay hidden;
  • objects just off screen are kept when a light makes them cast shadows on the screen;
  • culled objects have correct matrices for raycasts: when never moved, after moving, and when an extension updates them;
  • nothing is hidden in the in-game editor.
  • The raycast test fails without the matrix updates, and the shadow test caught a bug on the first frame.
• Full GDJS test suite: 1370 passed.

Known limits

• Shaders displacing vertices (like the FoliageSwaying3D extension) can draw a few pixels outside the box. Three.js's own culling of meshes has the same limit.
• Something rendering the scene from another camera (minimap, mirror) would miss objects culled for the main camera. No extension of the extensions repository does it.

Next steps measured, not in this PR

• Instancing (prototype): draw one InstancedMesh per mesh of each model, filled every frame with the visible instances only, and hide the original meshes (kept for raycasts).
  • Draw calls go from 1457 to 202. Frame time: city x1 10.7-13.4ms → 7.5-8.4ms (render about halved); city x10 21.7ms → 18.6ms (render 12.4ms → 9.0ms). The gain should be bigger on real (mobile) GPUs.
  • It's invisible to the game only under conditions. Materials must be shared, which is true for "StandardWithoutMetalness" and "KeepOriginal", but "Basic" clones them per object. There must be no transparency (no per-instance sorting) and no per-object material change by extensions. Each mesh needs its own batch, keyed by object and material type. Flipped objects need separate batches. Batches must be maintained when objects are created, deleted or reloaded.
  • It's a larger change, best done separately.
• Custom objects: they are never culled. A 3D custom object could be culled as a whole when its children are 3D objects included in its bounds, not rotated around X or Y (its box ignores these rotations), and themselves rendered inside their box.
• Remaining per-object costs at x10 (master, debug runtime): Physics3D for about 2200 mostly static bodies is about 1.4ms per frame (Jolt's step is about 0.4ms of it), and the steps of behaviors doing nothing (each Physics3D behavior after the first, Base3DBehavior) about 1ms. Static bodies could skip the IsActive call after the step and the polling of 9 getters before it; behaviors without steps could be skipped by the scene loop.
• Culling loop: it's still O(objects): about 0.2ms for 2800 objects here. A spatial grid of static objects would only matter for scenes with tens of thousands of objects.

🤖 Generated with Claude Code

https://claude.ai/code/session_01FDUqntVYfmRadSTSqSDDPE