A-Frame ECS and Three.js: GPU Memory Disposal in Custom Components

Answer the Question First

The remove handler should explicitly dispose of every Three.js object that the component created, but only dispose of shared resources when no other entity still references them. A minimal pattern looks like this:

AFRAME.registerComponent('dynamic-geometry', {
  schema: { /* your schema */ },

  init: function () {
    // Create geometry and material
    this.geometry = new THREE.BufferGeometry();
    this.material = new THREE.MeshBasicMaterial({ color: this.data.color });
    this.mesh = new THREE.Mesh(this.geometry, this.material);
    this.el.setObject3D('mesh', this.mesh);

    // If you want to share a material, store a reference counter
    if (!this.material.userData.refCount) {
      this.material.userData.refCount = 0;
    }
    this.material.userData.refCount++;
  },

  remove: function () {
    // 1. Dispose geometry – unique to this entity
    if (this.geometry) {
      this.geometry.dispose();
      this.geometry = null;
    }

    // 2. Dispose material only if this was the last user
    if (this.material) {
      this.material.userData.refCount--;
      if (this.material.userData.refCount === 0) {
        this.material.dispose();
      }
      this.material = null;
    }

    // 3. Remove the mesh from the entity
    this.el.removeObject3D('mesh');
  }
});

Why Disposal Matters

• Three.js .dispose() frees GPU buffers, textures, and shader programs. Simply dropping references does not reclaim GPU memory.
• A‑Frame removes the DOM element but does not call .dispose() on custom Three.js objects.
• Leaving orphaned buffers can quickly exhaust WebGL memory on long‑running applications.

Reference Counting for Shared Materials

When a material is shared (e.g., you pass the same material instance to several entities), you must track how many entities use it. The snippet above uses a refCount stored in userData. If you prefer a global registry, create a lightweight map keyed by material UUID.

Final Checklist

• Dispose geometry, material, texture, and any ShaderMaterial programs.
• Only dispose shared objects when the reference count reaches zero.
• Remove the Three.js object from the entity with removeObject3D before disposing.
• Verify cleanup by inspecting renderer.info.memory or the browser’s Performance panel after removal.

Diagnostic Question

Do you create a single material instance that is reused across multiple entities, or does each entity create its own material?