Three.js Instanced Cube Wave — GPU-Instanced WebGL Grid Animation

The Three.js Instanced Cube Wave snippet animates a 50×50 grid — 2,500 individual cubes — rippling outward from the center like a pond struck by a stone, while every single cube is rendered in one GPU draw call using THREE.InstancedMesh, loaded from Three.js's core CDN build with no extra dependencies.

One geometry, one material, thousands of transforms

Creating 2,500 separate THREE.Mesh objects — each with its own geometry reference, material, and matrix — would issue 2,500 individual draw calls to the GPU every frame, which collapses frame rate almost immediately past a few hundred objects. InstancedMesh inverts this: it holds exactly one shared geometry and one shared material, plus a buffer of per-instance transform matrices. The GPU renders all 2,500 cubes in a single call, reading each instance's own position and scale from that shared buffer — the same core technique that lets modern games render forests, crowds, and particle debris fields with negligible per-object cost.

A reusable dummy Object3D writes each instance's matrix

Three.js has no per-instance .position or .scale property to set directly — instead, the snippet reuses a single, invisible THREE.Object3D (dummy) as scratch space every frame: set its position and scale, call updateMatrix(), then copy that matrix into the mesh via mesh.setMatrixAt(index, dummy.matrix). Reusing one dummy object for all 2,500 writes, rather than creating a fresh Object3D per cube per frame, avoids needless garbage collection pressure in a loop that already runs 60 times a second.

Radial distance drives the ripple, not a flat directional sweep

Every cube's height is computed from Math.sin(distanceFromCenter * frequency - time), where distanceFromCenter is precomputed once per cube at startup and cached. Because the wave's phase depends on radial distance rather than a single X or Z coordinate, the ripple visibly radiates outward in expanding rings from the grid's center — exactly like a real water ripple — rather than sweeping across the grid in one flat, unconvincing direction.

Height and vertical scale move together for a "spike" feel

Each cube's Y position rises with the wave, but its Y-axis *scale* also stretches proportionally at the same time, so rising cubes appear to stretch upward from the ground plane rather than simply floating up as rigid blocks. This two-property coupling — position and scale sharing the same underlying wave value — is a small detail that makes the grid read as flexible, spike-like terrain instead of a field of hovering boxes.

Flagging instanceMatrix.needsUpdate, once per frame

Just like a regular BufferAttribute, the shared instance matrix buffer only re-uploads to the GPU when explicitly flagged. Setting mesh.instanceMatrix.needsUpdate = true once, after all 2,500 individual setMatrixAt calls for that frame, batches the entire update into a single GPU buffer upload rather than 2,500 separate ones.

Where instancing matters beyond cubes

This exact pattern — one shared geometry/material, a scratch Object3D, and a per-instance matrix buffer — is how you'd efficiently render a forest of trees, a crowd of characters, a field of grass, or thousands of UI particles in any WebGL scene. Compare its GPU-instanced efficiency against a particle wave built from raw points, or contrast the rigid grid here with the free-floating motion of a particle network.