The live demo starts when it’s in view.Toggle culling to compare submitted plants · drag to pause the camera · Next viewpoint works with reduced motion
Cull spatial batches with one enclosing sphere, test individual instances only at the view edge, and pack visible rows in stable source order.
Unchanged selections skip copies and uploads; empty batches can skip draws entirely. Matrices, colours and other Float32 instance attributes share the same selection.
What it costs a frame
Not measured yet.
What it needs
Renders with
WebGPU or WebGLWebGPU where there is one, WebGL2 where there is not.
Your browser
Runs hereNo WebGPU needed
Depends on
three.js 0.187.0No other packages
With an agent
install("instance-cull")Your coding agent reads its pitfalls and installs it through the library’s MCP server. Set it up
What it’s for
Draw only the visible plants in a resident landscape
Compact several instance attributes without losing row identity
Avoid buffer uploads when the visible set is unchanged
Skip entire off-screen instance batches without compute dispatches
Pitfalls, in brief
CullSet sphere centres/radii and extracted planes are world-space.
Keep immutable source-order arrays separate from all destination attributes.
Call invalidate() after source rows, sphere positions/radii or set.count change.
InstanceCullBatch accepts dedicated non-interleaved Float32 InstancedBufferAttributes with meshPerAttribute = 1.
Disable built-in mesh frustum culling or maintain a conservative bound over every possible source row.
Do not use a main-camera selection for shadows, reflections or a second camera: off-screen instances can affect those views.
viewPlanes updates the camera and its parents; updateProjectionMatrix() remains the host responsibility after FOV, aspect or clipping edits. viewChanged/viewNow compare world poses.
A batch sphere shortcut is useful for spatially coherent groups.
The CPU approach avoids per-group dispatch overhead and empty indirect draws, but still spends time scanning boundary groups, copying changed rows and retaining a source copy.
The demo has 10,000 plants at high, 6,400 at medium and 2,500 at low, all in 25 batches.
11 pitfalls in full, the hook-up guide, the module source and its tests come with the part.
Where it comes from
From HaTac. Adapted from published work, named below.
Hannes Andersson: Source sphere culling, stable batch compaction and the CPU-versus-compute profiling rationale.