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

Question

Resource Lifecycle Management
A-Frame utilizes an Entity-Component System (ECS) to wrap Three.js objects. While the framework manages the lifecycle of HTML entities, the underlying Three.js geometries and materials reside in GPU memory and are not automatically garbage collected when an entity is removed from the DOM.

Integration Constraints
Custom components typically instantiate Three.js objects within the init handler. To prevent memory leaks, developers must manually call .dispose() on these resources. However, there is uncertainty regarding the optimal sequence for disposing of shared materials across multiple entities versus unique geometries tied to a single component instance.

Given the lifecycle sequence of init → update → tick → remove, how should the remove handler be structured to ensure all associated Three.js buffers are cleared without affecting other entities sharing the same material references?

Tasadduq Burney · Answer

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?

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

Resource Lifecycle Management

Integration Constraints

1 answer

1 question comment

Answer the Question First

Why Disposal Matters

Reference Counting for Shared Materials

Final Checklist

Diagnostic Question

Your perspective belongs here.