feat(core): add entity.dispose() for GPU resource cleanup on destroy

Summary:
- Add entity.dispose() method that destroys entity and frees GPU resources (geometry, materials, textures)
  - Existing entity.destroy() behavior unchanged - only removes from scene graph, preserves GPU resources
  - Add disposeObject3DResources() to World that traverses Object3D hierarchy and calls dispose on all resources
  - Use internal _disposeResources flag to signal disposal intent from entity to world
  - Document both methods in docs/concepts/ecs/entity.md with usage examples and warning about shared resources
  - Update docs/concepts/ecs/lifecycle.md to describe both cleanup methods

Reviewed By: zjm-meta

Differential Revision:
D88606732

Privacy Context Container: L1334777

fbshipit-source-id: 4ba5d91673ee76a8b5af72a512f318701b858283

Author: felixtrz

docs/concepts/ecs/entity.md

@@ -52,3 +52,65 @@ e.setValue(Health, 'current', 75);
 const pos = e.getVectorView(Transform, 'position'); // Float32Array
 pos[1] += 1; // move up
 ```
+
+## Destroying Entities
+
+IWSDK provides two ways to destroy entities:
+
+### `entity.destroy()`
+
+Removes the entity from the ECS and detaches its `object3D` from the scene graph:
+
+```ts
+entity.destroy();
+```
+
+This is safe and non-destructive to GPU resources. The geometry, materials, and textures remain in GPU memory and can be reused by other entities.
+
+### `entity.dispose()`
+
+Destroys the entity AND disposes all GPU resources (geometry, materials, textures):
+
+```ts
+entity.dispose();
+```
+
+::: warning
+**Use with caution!** `dispose()` is destructive and will free GPU memory for:
+- All geometries attached to the entity's `object3D` and its children
+- All materials (including shared materials)
+- All textures referenced by those materials
+
+If other entities share the same geometry, material, or texture, they will break after calling `dispose()`.
+:::
+
+### When to use each
+
+| Scenario | Method |
+|----------|--------|
+| Removing an entity that uses shared/reusable assets | `destroy()` |
+| Removing an entity with unique, one-off geometry/materials | `dispose()` |
+| Level unloading with asset reuse | `destroy()` |
+| Full cleanup of procedurally generated content | `dispose()` |
+
+### Example: Safe cleanup pattern
+
+```ts
+// If you created unique resources, dispose them
+const geometry = new BoxGeometry(1, 1, 1);
+const material = new MeshStandardMaterial({ color: 0xff0000 });
+const mesh = new Mesh(geometry, material);
+const entity = world.createTransformEntity(mesh);
+
+// Later: full cleanup since resources aren't shared
+entity.dispose();
+```
+
+```ts
+// If using loaded/shared assets, just destroy
+const gltf = await AssetManager.loadGLTF('model.glb');
+const entity = world.createTransformEntity(gltf.scene.clone());
+
+// Later: don't dispose - other entities may use the same materials
+entity.destroy();
+```

docs/concepts/ecs/lifecycle.md

@@ -62,7 +62,12 @@ this.queries.panels.subscribe('disqualify', (e) => {
 
 - `createEntity()` creates a bare entity (no `object3D`).
 - `createTransformEntity(object?, parentOrOptions?)` creates an entity with an `object3D`, injects a `Transform`, and parents it under the level root or scene based on options.
-- `entity.destroy()` marks the entity inactive, clears its bitmask, resets query membership, and detaches its `object3D` from the scene.
+- `entity.destroy()` marks the entity inactive, clears its bitmask, resets query membership, and detaches its `object3D` from the scene. GPU resources (geometry, materials, textures) are preserved.
+- `entity.dispose()` does everything `destroy()` does, plus disposes all GPU resources. Use with caution when resources may be shared.
+
+::: tip
+Use `destroy()` by default. Only use `dispose()` when you're certain the entity's resources aren't shared with other entities.
+:::
 
 Parenting rules
 

packages/core/src/ecs/entity.ts

@@ -6,14 +6,37 @@
  */
 
 import type { PointerEventsMap } from '@pmndrs/pointer-events';
+import { Entity as ElicsEntity } from 'elics';
 import type { Object3D, Object3DEventMap } from '../runtime/index.js';
 
 declare module 'elics' {
   interface Entity {
     object3D?: Object3D<Object3DEventMap & PointerEventsMap>;
+    /** @internal Flag to indicate GPU resources should be disposed on destroy */
+    _disposeResources?: boolean;
+    /**
+     * Destroy the entity and dispose of its GPU resources (geometry, materials, textures).
+     *
+     * @remarks
+     * Use this instead of `destroy()` when you want to fully clean up GPU memory.
+     * Use with caution when resources may be shared across multiple entities.
+     *
+     * @example
+     * ```ts
+     * // Remove entity and free GPU resources
+     * entity.dispose();
+     * ```
+     */
+    dispose(): void;
   }
 }
 
+// Add dispose method to Entity prototype
+ElicsEntity.prototype.dispose = function (this: ElicsEntity) {
+  (this as any)._disposeResources = true;
+  this.destroy();
+};
+
 export { Entity } from 'elics';
-/** Sentinel value used for “no parent” in Transform.parent. @category ECS */
+/** Sentinel value used for "no parent" in Transform.parent. @category ECS */
 export const NullEntity = -1;

packages/core/src/ecs/world.ts

@@ -20,6 +20,7 @@ import {
 import { LevelTag } from '../level/index.js';
 import type { Object3DEventMap } from '../runtime/index.js';
 import {
+  Material,
   Object3D,
   PerspectiveCamera,
   Scene,
@@ -88,11 +89,57 @@ export class World extends ElicsWorld {
     );
     this.entityManager.releaseEntityInstance = (entity: Entity) => {
       originalReleaseFunc(entity);
-      entity.object3D?.removeFromParent();
-      delete entity.object3D;
+      const obj = entity.object3D;
+      if (obj) {
+        // Check if entity was marked for resource disposal
+        if ((entity as any)._disposeResources) {
+          this.disposeObject3DResources(obj);
+          delete (entity as any)._disposeResources;
+        }
+        obj.removeFromParent();
+        delete entity.object3D;
+      }
     };
   }
 
+  /**
+   * Dispose of an Object3D's GPU resources (geometry, materials, textures).
+   * Traverses all descendants and cleans up disposable resources.
+   *
+   * @remarks
+   * This is called automatically when an entity is destroyed with `disposeResources: true`.
+   * Use with caution when resources may be shared across multiple entities.
+   */
+  private disposeObject3DResources(object: Object3D): void {
+    object.traverse((child: any) => {
+      // Dispose geometry
+      if (child.geometry) {
+        child.geometry.dispose();
+      }
+
+      // Dispose materials (can be single or array)
+      if (child.material) {
+        const materials: Material[] = Array.isArray(child.material)
+          ? child.material
+          : [child.material];
+
+        for (const material of materials) {
+          // Dispose textures attached to the material
+          for (const key of Object.keys(material)) {
+            const value = (material as any)[key];
+            if (value && typeof value.dispose === 'function') {
+              // Check if it's a texture (has isTexture property)
+              if (value.isTexture) {
+                value.dispose();
+              }
+            }
+          }
+          material.dispose();
+        }
+      }
+    });
+  }
+
   createEntity(): Entity {
     return super.createEntity() as Entity;
   }