BufferGeometry dispose() on shared geometry removes active mesh data

Answer to the Core Question

Three.js does not keep an internal reference count for BufferGeometry objects. When multiple Meshs share the same geometry, calling geometry.dispose() will immediately delete the WebGL buffers, making all meshes that reference it empty. The only reliable way to release the GPU resources exactly once after the last mesh is removed is to implement manual reference tracking in your application.

Key Take‑aways

• Three.js provides no built‑in reference counter or event hook for shared geometries.
• Use a Map (or a lightweight wrapper class) to count how many meshes currently reference each geometry.
• Call geometry.dispose() only when the counter reaches zero.
• Alternatively, clone the geometry if you need independent lifecycles.

Manual Reference‑Counting Pattern

1. Initialize a map:

   const geometryRefs = new Map();
   

2. When creating a mesh:

   function addMesh(geometry, material, scene) {
     const mesh = new THREE.Mesh(geometry, material);
     scene.add(mesh);
     const count = geometryRefs.get(geometry) || 0;
     geometryRefs.set(geometry, count + 1);
     return mesh;
   }
   

3. When removing a mesh:

   function removeMesh(mesh, scene) {
     scene.remove(mesh);
     const geometry = mesh.geometry;
     const count = geometryRefs.get(geometry) - 1;
     if (count <= 0) {
       geometryRefs.delete(geometry);
       geometry.dispose(); // safe – no other mesh uses it
     } else {
       geometryRefs.set(geometry, count);
     }
     mesh.geometry = null; // detach reference
     mesh.material = null;
   }
   

4. Optional – store the counter in userData:

   geometry.userData.refCount = (geometry.userData.refCount || 0) + 1;
   

This pattern guarantees that GPU buffers are freed exactly once, regardless of how many independent parts of your code add or remove meshes.

Coordinating Across Independent Lifecycles

If different modules or components manage their own meshes, expose the addMesh and removeMesh helpers (or the wrapper class) as a shared service. Each module should call these helpers instead of manipulating the scene directly. This centralises reference counting and eliminates race conditions where a mesh is removed before the counter is updated.

Cloning for Independent Disposal

When you need a mesh to have its own geometry lifetime (e.g., for animation or dynamic updates), clone the geometry:

const uniqueGeom = originalGeom.clone();
const mesh = new THREE.Mesh(uniqueGeom, material);

Cloning creates a new BufferGeometry instance with its own GPU buffers, so uniqueGeom.dispose() will not affect other meshes.

Does Three.js Expose a Reference Count or Hook?

No. The library deliberately keeps geometry management simple: the JavaScript object is garbage‑collected, but the underlying WebGL buffers are not. The only official way to free those buffers is by calling dispose() yourself. If you need automatic cleanup, you must implement your own reference tracking or use a higher‑level framework that wraps Three.js.

Verification Tips

• Use Chrome DevTools’ Memory tab or Spector.js to confirm that the vertex buffer is removed after the last mesh is disposed.
• Run a quick test: create two meshes sharing a geometry, remove one, then call geometry.dispose(), and observe that both meshes stop rendering.
• Check for WebGL errors in the console after disposal; a missing buffer typically triggers GL_INVALID_OPERATION.