@directivegames/genesys.js 3.1.24

package/src/components/visual/BaseInstancedMeshComponent.ts

@@ -0,0 +1,904 @@
+/**
+ * BaseInstancedMeshComponent provides the foundation for components that manage
+ * multiple THREE.InstancedMesh objects efficiently.
+ *
+ * This component allows rendering multiple instances of different geometry and material
+ * combinations efficiently. Each geometry-material pair creates its own InstancedMesh,
+ * and each instance can have its own transform matrix and optional per-instance colors.
+ * This is ideal for rendering large numbers of similar objects like grass, rocks, trees,
+ * or particles with minimal performance impact.
+ *
+ * The component manages instance matrices and colors internally, providing methods
+ * to update individual instances or all instances at once. It synchronizes shadow
+ * settings and ensures proper cleanup when instances are added or removed.
+ */
+import * as THREE from 'three';
+
+import { ClassRegistry, EngineClass } from '../../systems/ClassRegistry.js';
+import { resourceManager } from '../../utils/ResourceManager.js';
+import { isNode } from '../../utils/Utils.js';
+import { PrimitiveComponent } from '../PrimitiveComponent.js';
+
+import type { GenericMaterialType } from '../../materials.js';
+import type { EditorClassMeta, EditorPropertyChangedResult } from '../../utils/EditorClassMeta.js';
+import type { SceneGraphDebugNode } from '../../utils/SceneGraphUtils.js';
+import type { ComponentDescriptionOptions } from '../Component.js';
+import type { PrimitiveComponentOptions } from '../PrimitiveComponent.js';
+
+export interface GeometryMaterialPair {
+  geometry: THREE.BufferGeometry;
+  material: GenericMaterialType;
+  geometryMatrix?: THREE.Matrix4;
+}
+
+export interface InstanceTransform {
+  position?: THREE.Vector3;
+  rotation?: THREE.Euler;
+  scale?: THREE.Vector3;
+}
+
+export interface BaseInstancedMeshComponentOptions extends PrimitiveComponentOptions {
+  maxInstances?: number;
+  availableInstances?: number;
+  uvScaleTilesPerUnit?: number;
+  excludeFromNavigation?: boolean;
+  instances?: InstanceTransform[];
+  isWorldSpace?: boolean;
+  colors?: THREE.Color[] | THREE.Color | Map<number, THREE.Color>;  // color(s) applied to instances - single color for all, array per instance, or map of index to color
+  updatePhysicsOnInstanceTransform?: boolean;  // if physics should be updated when any instance transform changes
+  instanceScale?: THREE.Vector3;  // base scale applied to all instances
+  instanceRotation?: THREE.Vector3;  // base rotation applied to all instances (in degrees)
+  instanceOffset?: THREE.Vector3;  // base position offset applied to all instances
+  instanceDensity?: number;  // density value for editor placement frequency
+  instanceScaleDelta?: number;  // multiplicative scale variance (0.1 = 10% variance)
+  instanceRotationDelta?: THREE.Vector3;  // additive rotation variance applied randomly (in degrees)
+  instanceOffsetDelta?: THREE.Vector3;  // additive position offset variance applied randomly
+}
+
+@EngineClass('BaseInstancedMeshComponent')
+export class BaseInstancedMeshComponent<TOptions extends BaseInstancedMeshComponentOptions = BaseInstancedMeshComponentOptions> extends PrimitiveComponent<TOptions> {
+  protected _geometryMaterialPairs: GeometryMaterialPair[] = [];
+  protected instancedMeshes: THREE.InstancedMesh[] = [];
+  private shouldRefreshPhysics: boolean = false;
+
+  static override readonly EDITOR_CLASS_META: EditorClassMeta = {
+    ...PrimitiveComponent.EDITOR_CLASS_META,
+    maxInstances: { number: { min: 1, step: 1 } },
+    instances: { hidden: true },
+    availableInstances: { readonly: true },
+    instanceDensity: { number: { min: 0, step: 0.1 } },
+  } as const;
+
+  static override get DEFAULT_OPTIONS(): BaseInstancedMeshComponentOptions {
+    const DEFAULT_MAX_INSTANCES = 1000;
+
+    return {
+      ...PrimitiveComponent.DEFAULT_OPTIONS,
+      maxInstances: DEFAULT_MAX_INSTANCES,
+      excludeFromNavigation: false,
+      uvScaleTilesPerUnit: 1,
+      instances: [{position: new THREE.Vector3(), rotation: new THREE.Euler(), scale: new THREE.Vector3(1, 1, 1)}],
+      isWorldSpace: false,
+      colors: undefined,
+      updatePhysicsOnInstanceTransform: false,
+      availableInstances: DEFAULT_MAX_INSTANCES,
+      instanceScale: new THREE.Vector3(1, 1, 1),
+      instanceRotation: new THREE.Vector3(0, 0, 0),
+      instanceOffset: new THREE.Vector3(0, 0, 0),
+      instanceDensity: 1.0,
+      instanceScaleDelta: 0.0,
+      instanceRotationDelta: new THREE.Vector3(0, 0, 0),
+      instanceOffsetDelta: new THREE.Vector3(0, 0, 0),
+    };
+  }  /**
+   * Creates a new BaseInstancedMeshComponent with the specified options
+   * @param options Configuration options for the base instanced mesh component
+   */
+  constructor(options: TOptions = (BaseInstancedMeshComponent.DEFAULT_OPTIONS as TOptions)) {
+    console.log('BaseInstancedMeshComponent constructor called with options:', options);
+    super(options);
+
+    // make sure we're ready for populating instances
+    this.updateMatrixWorld(true);
+  }
+
+  public override tickPrePhysics(deltaTime: number): void {
+    if (this.shouldRefreshPhysics) {
+      this.refreshPhysics();
+      this.shouldRefreshPhysics = false;
+    }
+    super.tickPrePhysics(deltaTime);
+  }
+
+  protected populateInstances(geometriesAndMaterials: GeometryMaterialPair[]) {
+    const options = this.options;
+    const maxInstances = this.getMaxInstances();
+    const availableInstances = this.availableInstances;
+
+    this._geometryMaterialPairs = geometriesAndMaterials;
+    if (geometriesAndMaterials.length === 0) {
+      console.warn('BaseInstancedMeshComponent.populateInstances called with empty geometry-material pairs');
+    }
+
+    // Initialize instanced meshes from geometry-material pairs
+    // Buffer capacity should be the maxInstances guard
+    this.initializeInstancedMeshes(geometriesAndMaterials, maxInstances);
+
+    // Set initial instances if provided, clamped by maxInstances
+    const instances = options.instances ?? [];
+    if (instances.length > 0) {
+      const isWorldSpace = options.isWorldSpace ?? BaseInstancedMeshComponent.DEFAULT_OPTIONS.isWorldSpace;
+      const effectiveCount = Math.min(instances.length, maxInstances);
+      this.setInstanceTransforms(instances.slice(0, effectiveCount), isWorldSpace);
+    }
+
+    // Apply colors if provided
+    if (options.colors) {
+      this.setInstanceColors(options.colors);
+    }
+
+    console.log(
+      'BaseInstancedMeshComponent populated:',
+      'availableInstances:', availableInstances,
+      'maxInstances:', maxInstances,
+      'actuallyShown:', Math.min(availableInstances, maxInstances),
+      'meshCount:', this.instancedMeshes.length,
+      'isWorldSpace:', this.options.isWorldSpace
+    );
+  }
+
+  protected repopulateInstances() {
+    this.populateInstances(this._geometryMaterialPairs);
+  }
+
+  public requestUpdatePhysics(): void {
+    this.shouldRefreshPhysics = true;
+  }
+
+  protected override shouldSyncToPhysics(): boolean {
+    // if this.shouldRefreshPhysics is true, physics will be re-created in tickPrePhysics,
+    // also the instances won't move if the instanced mesh component itself moves
+    // so no need to update physics by syncToPhysics
+    return false;
+  }
+
+  protected initializeInstancedMeshes(pairs: GeometryMaterialPair[], maxInstances: number): void {
+    // Clear existing meshes
+    this.clearInstancedMeshes();
+
+    for (const pair of pairs) {
+      const instancedMesh = new THREE.InstancedMesh(
+        pair.geometry,
+        undefined,
+        maxInstances
+      );
+      instancedMesh.userData.geometryMatrix = pair.geometryMatrix;
+      instancedMesh.userData.geometryMatrixInv = pair.geometryMatrix ? pair.geometryMatrix.clone().invert() : undefined;
+
+      this.instancedMeshes.push(instancedMesh);
+      this.setupInstancedMesh(instancedMesh);
+
+      // Set material if not in Node.js environment
+      if (!isNode()) {
+        this.setMaterialForMesh(instancedMesh, pair.material);
+      }
+    }
+  }
+
+  private setupInstancedMesh(instancedMesh: THREE.InstancedMesh): void {
+    instancedMesh.setTransient(true);
+    this.bindObject3DProperties(instancedMesh, ['castShadow', 'receiveShadow']);
+    this.add(instancedMesh);
+    instancedMesh.updateMatrixWorld(true);
+
+    // TODO: Fix me
+    // if (this.options.uvScaleTilesPerUnit) {
+    //   MaterialUtils.scaleUVsBySize(instancedMesh, this.options.uvScaleTilesPerUnit);
+    // }
+  }
+
+  private setMaterialForMesh(instancedMesh: THREE.InstancedMesh, material: GenericMaterialType): void {
+    if (typeof material === 'string') {
+      // Otherwise, load it asynchronously
+      resourceManager.loadGenericMaterial(material).then((loadedMaterial) => {
+        if (loadedMaterial) {
+          instancedMesh.material = loadedMaterial;
+        }
+      });
+    } else {
+      // If it's already a THREE.Material, apply it immediately
+      instancedMesh.material = material;
+    }
+  }
+
+  private clearInstancedMeshes(): void {
+    for (const mesh of this.instancedMeshes) {
+      mesh.removeFromParent();
+    }
+    this.instancedMeshes = [];
+  }
+
+  /**
+   * Returns all THREE.InstancedMesh objects associated with this component
+   * @returns Array of THREE.InstancedMesh instances
+   */
+  public getInstancedMeshes(): THREE.InstancedMesh[] {
+    return this.instancedMeshes;
+  }
+
+  /**
+   * Returns a specific THREE.InstancedMesh by index
+   * @param index Index of the mesh to retrieve
+   * @returns The THREE.InstancedMesh instance or undefined if index is invalid
+   */
+  public getInstancedMesh(index: number = 0): THREE.InstancedMesh | undefined {
+    return this.instancedMeshes[index];
+  }
+
+  /**
+   * Returns the materials of all instanced meshes
+   * @returns Array of materials
+   */
+  public getMaterials(): (THREE.Material | THREE.Material[])[] {
+    return this.instancedMeshes.map(mesh => mesh.material);
+  }
+
+  /**
+   * Returns the material of a specific instanced mesh
+   * @param index Index of the mesh
+   * @returns The material of the instanced mesh or undefined if index is invalid
+   */
+  public getMaterial(index: number = 0): THREE.Material | THREE.Material[] | undefined {
+    const mesh = this.instancedMeshes[index];
+    return mesh?.material;
+  }
+
+  /**
+   * Updates the geometry of a specific instanced mesh
+   * @param geometry The new THREE.BufferGeometry to apply
+   * @param index Index of the mesh to update
+   */
+  public setGeometry(geometry: THREE.BufferGeometry, index: number = 0): void {
+    const mesh = this.instancedMeshes[index];
+    if (mesh) {
+      mesh.geometry = geometry;
+    }
+  }
+
+  /**
+   * Updates the material of a specific instanced mesh
+   * @param material The new material to apply
+   * @param index Index of the mesh to update
+   */
+  public setMaterial(material: GenericMaterialType, index: number = 0): void {
+    const mesh = this.instancedMeshes[index];
+    if (mesh) {
+      this.setMaterialForMesh(mesh, material);
+    }
+  }
+
+  /**
+   * Gets the number of available instance transforms
+   * @returns The count of instance positions available
+   */
+  public get availableInstances(): number {
+    return this.options.instances?.length ?? 0;
+  }
+
+  /**
+   * Gets the current number of active instances
+   * @returns The number of instances currently being rendered
+   */
+  public getInstanceCount(): number {
+    if (this.instancedMeshes.length === 0) {
+      return 0;
+    }
+    return this.instancedMeshes[0].count;
+  }
+
+  /**
+   * Gets the maximum number of instances this component can handle
+   * This is the effective limit considering both available instances and the maxInstances guard
+   * @returns The maximum instance count
+   */
+  public getMaxInstances(): number {
+    const optionsMax = this.options.maxInstances ?? BaseInstancedMeshComponent.DEFAULT_OPTIONS.maxInstances!;
+    return optionsMax;
+  }
+
+  /**
+   * Gets the capacity of the instanced mesh buffers
+   * @returns The buffer capacity
+   */
+  private getBufferCapacity(): number {
+    if (this.instancedMeshes.length === 0) {
+      return 0;
+    }
+    return this.instancedMeshes[0].instanceMatrix.count;
+  }
+
+  /**
+   * Private core function that sets a transform for a specific instance on all meshes
+   * @param instanceId The index of the instance to update
+   * @param transform The transformation to apply
+   * @param isWorldSpace Whether the transform is in world space (true) or local space (false)
+   */
+  private setInstanceTransformCore(instanceId: number, transform: InstanceTransform, isWorldSpace: boolean): void {
+    // Validate instance ID against buffer capacity
+    const bufferCapacity = this.getBufferCapacity();
+    if (instanceId < 0 || instanceId >= bufferCapacity) {
+      return;
+    }
+
+    // Create matrix from transform
+    const matrix = new THREE.Matrix4();
+    const euler = transform.rotation ?? new THREE.Euler();
+    matrix.compose(
+      transform.position ?? new THREE.Vector3(),
+      new THREE.Quaternion().setFromEuler(euler),
+      transform.scale ?? new THREE.Vector3(1, 1, 1)
+    );
+
+    // Update all meshes
+    for (const mesh of this.instancedMeshes) {
+      // Create a copy of the matrix for this mesh
+      const meshMatrix = matrix.clone();
+
+      if (mesh.userData.geometryMatrix) {
+        meshMatrix.multiply(mesh.userData.geometryMatrix);
+      }
+
+      // If world space, we need to convert to local space relative to the mesh
+      if (isWorldSpace) {
+        const meshWorldMatrixInverse = new THREE.Matrix4().copy(mesh.matrixWorld).invert();
+        meshMatrix.premultiply(meshWorldMatrixInverse);
+      }
+
+      mesh.setMatrixAt(instanceId, meshMatrix);
+      mesh.instanceMatrix.needsUpdate = true;
+    }
+
+    if (this.options.updatePhysicsOnInstanceTransform) {
+      this.requestUpdatePhysics();
+    }
+  }
+
+  /**
+   * Sets the transform for a specific instance across all meshes
+   * @param instanceId The index of the instance to update
+   * @param transform The transformation to apply
+   * @param isWorldSpace Whether the transform is in world space (default: true) or local space
+   */
+  public setInstanceTransform(instanceId: number, transform: InstanceTransform, isWorldSpace: boolean = false): void {
+    this.setInstanceTransformCore(instanceId, transform, isWorldSpace);
+  }
+
+  /**
+   * Updates all instance transforms at once for all meshes
+   * @param transforms Array of transformations
+   * @param isWorldSpace Whether the transforms are in world space (default: true) or local space
+   */
+  public setInstanceTransforms(transforms: InstanceTransform[], isWorldSpace: boolean = false): void {
+    const bufferCapacity = this.getBufferCapacity();
+    const count = Math.min(transforms.length, bufferCapacity);
+    console.log(`setInstanceTransforms: setting ${count} transforms (bufferCapacity: ${bufferCapacity}, worldSpace: ${isWorldSpace})`);
+
+    // Use the core function for each transform
+    for (let i = 0; i < count; i++) {
+      this.setInstanceTransformCore(i, transforms[i], isWorldSpace);
+    }
+
+    // Update the instance count to match the number of transforms provided
+    for (const mesh of this.instancedMeshes) {
+      mesh.count = count;
+    }
+    console.log(`Instance count after setInstanceTransforms: ${count}`);
+  }
+
+  /**
+   * Gets the transform for a specific instance from the first mesh
+   * @param instanceId The index of the instance to get
+   * @param isWorldSpace Whether to return the transform in world space (default: true) or local space
+   * @returns The transformation of the instance
+   */
+  public getInstanceTransform(instanceId: number, isWorldSpace: boolean = false): InstanceTransform | null {
+    const mesh = this.instancedMeshes[0];
+    if (!mesh || instanceId < 0 || instanceId >= this.getInstanceCount()) {
+      return null;
+    }
+
+    const matrix = new THREE.Matrix4();
+    mesh.getMatrixAt(instanceId, matrix);
+
+    if (mesh.userData.geometryMatrixInv) {
+      matrix.multiply(mesh.userData.geometryMatrixInv);
+    }
+
+    // If world space, convert from local to world space
+    if (isWorldSpace) {
+      // Force update the mesh's world matrix to ensure it's current
+      mesh.updateMatrixWorld(true);
+      matrix.premultiply(mesh.matrixWorld);
+    }
+
+    // Decompose matrix into transform components
+    const position = new THREE.Vector3();
+    const quaternion = new THREE.Quaternion();
+    const scale = new THREE.Vector3();
+    matrix.decompose(position, quaternion, scale);
+
+    const rotation = new THREE.Euler().setFromQuaternion(quaternion);
+
+    return {
+      position,
+      rotation,
+      scale
+    };
+  }
+
+
+  /**
+   * Gets the transforms for all instances from the first mesh
+   * @param isWorldSpace Whether to return the transforms in world space (default: false) or local space
+   * @returns Array of transformations for all instances
+   */
+  public getInstancesTransforms(isWorldSpace: boolean = false): InstanceTransform[] {
+    const instanceCount = this.getInstanceCount();
+    const transforms: InstanceTransform[] = [];
+
+    for (let i = 0; i < instanceCount; i++) {
+      const transform = this.getInstanceTransform(i, isWorldSpace);
+      if (transform) {
+        transforms.push(transform);
+      }
+    }
+
+    return transforms;
+  }
+
+  /**
+   * Adds a single instance at the end of the current instances
+   * @param transform The transformation for the new instance
+   * @param isWorldSpace Whether the transform is in world space (default: true) or local space
+   * @returns The index of the newly added instance, or -1 if max instances reached
+   */
+  public addInstance(transform: InstanceTransform, isWorldSpace: boolean = false): number {
+    const currentCount = this.getInstanceCount();
+    const bufferCapacity = this.getBufferCapacity();
+
+    if (currentCount >= bufferCapacity) {
+      console.warn(`Cannot add instance: buffer capacity (${bufferCapacity}) reached`);
+      return -1;
+    }
+
+    const newInstanceId = currentCount;
+    this.setInstanceTransformCore(newInstanceId, transform, isWorldSpace);
+
+    // Update instance count
+    for (const mesh of this.instancedMeshes) {
+      mesh.count = currentCount + 1;
+    }
+
+    return newInstanceId;
+  }
+
+  /**
+   * Adds multiple instances at the end of the current instances
+   * @param transforms Array of transformations for the new instances
+   * @param isWorldSpace Whether the transforms are in world space (default: true) or local space
+   * @returns Array of indices of the newly added instances
+   */
+  public addInstances(transforms: InstanceTransform[], isWorldSpace: boolean = false): number[] {
+    const currentCount = this.getInstanceCount();
+    const bufferCapacity = this.getBufferCapacity();
+    const availableSlots = bufferCapacity - currentCount;
+    const addCount = Math.min(transforms.length, availableSlots);
+
+    if (addCount < transforms.length) {
+      console.warn(`Cannot add all instances: only ${availableSlots} slots available, requested ${transforms.length}`);
+    }
+
+    const addedIndices: number[] = [];
+    for (let i = 0; i < addCount; i++) {
+      const newInstanceId = currentCount + i;
+      this.setInstanceTransformCore(newInstanceId, transforms[i], isWorldSpace);
+      addedIndices.push(newInstanceId);
+    }
+
+    // Update instance count
+    for (const mesh of this.instancedMeshes) {
+      mesh.count = currentCount + addCount;
+    }
+
+    return addedIndices;
+  }
+
+  /**
+   * Updates the transform of an existing instance
+   * @param instanceId The index of the instance to update
+   * @param transform The new transformation
+   * @param isWorldSpace Whether the transform is in world space (default: true) or local space
+   * @returns True if the instance was updated, false if instanceId is invalid
+   */
+  public updateInstance(instanceId: number, transform: InstanceTransform, isWorldSpace: boolean = false): boolean {
+    if (instanceId < 0 || instanceId >= this.getInstanceCount()) {
+      return false;
+    }
+
+    this.setInstanceTransformCore(instanceId, transform, isWorldSpace);
+    return true;
+  }
+
+  /**
+   * Updates multiple existing instances
+   * @param updates Array of objects containing instanceId and transform
+   * @param isWorldSpace Whether the transforms are in world space (default: true) or local space
+   * @returns Number of instances successfully updated
+   */
+  public updateInstances(updates: Array<{instanceId: number, transform: InstanceTransform}>, isWorldSpace: boolean = false): number {
+    let updatedCount = 0;
+    const currentCount = this.getInstanceCount();
+
+    for (const update of updates) {
+      if (update.instanceId >= 0 && update.instanceId < currentCount) {
+        this.setInstanceTransformCore(update.instanceId, update.transform, isWorldSpace);
+        updatedCount++;
+      }
+    }
+
+    return updatedCount;
+  }
+
+  /**
+   * Removes a single instance by moving the last instance to its position
+   * @param instanceId The index of the instance to remove
+   * @returns True if the instance was removed, false if instanceId is invalid
+   */
+  public removeInstance(instanceId: number): boolean {
+    const currentCount = this.getInstanceCount();
+    if (instanceId < 0 || instanceId >= currentCount) {
+      return false;
+    }
+
+    // If it's not the last instance, move the last instance to this position
+    if (instanceId < currentCount - 1) {
+      const lastInstanceId = currentCount - 1;
+
+      // Copy transform from last instance to the removed instance's position
+      for (const mesh of this.instancedMeshes) {
+        const lastMatrix = new THREE.Matrix4();
+        mesh.getMatrixAt(lastInstanceId, lastMatrix);
+        mesh.setMatrixAt(instanceId, lastMatrix);
+
+        // Copy color if it exists
+        if (mesh.instanceColor) {
+          const lastColor = new THREE.Color();
+          mesh.getColorAt(lastInstanceId, lastColor);
+          mesh.setColorAt(instanceId, lastColor);
+        }
+
+        mesh.instanceMatrix.needsUpdate = true;
+        if (mesh.instanceColor) {
+          mesh.instanceColor.needsUpdate = true;
+        }
+      }
+    }
+
+    // Decrease instance count
+    for (const mesh of this.instancedMeshes) {
+      mesh.count = currentCount - 1;
+    }
+
+    this.requestUpdatePhysics();
+    return true;
+  }
+
+  /**
+   * Removes multiple instances by their indices
+   * @param instanceIds Array of instance indices to remove
+   * @returns Number of instances successfully removed
+   */
+  public removeInstances(instanceIds: number[]): number {
+    // Sort indices in descending order to avoid index shifting issues
+    const sortedIds = [...instanceIds].sort((a, b) => b - a);
+    let removedCount = 0;
+
+    for (const instanceId of sortedIds) {
+      if (this.removeInstance(instanceId)) {
+        removedCount++;
+      }
+    }
+
+    return removedCount;
+  }
+
+  /**
+   * Removes all instance data within a specified radius from a center point (eraser tool)
+   * This modifies the underlying instance data array and rebuilds the visual representation
+   * @param center The center point to check distance from
+   * @param radius The radius within which instances should be removed
+   * @param isWorldSpace Whether the center point is in world space (default: true) or local space
+   * @returns Number of instances successfully removed
+   */
+  public removeInstanceDataInRadius(center: THREE.Vector3, radius: number, isWorldSpace: boolean = true): number {
+    if (!this.options.instances || this.options.instances.length === 0) return 0;
+
+    const radiusSq = radius * radius;
+    const matrix = new THREE.Matrix4();
+    const position = new THREE.Vector3();
+    const scale = new THREE.Vector3();
+    const quaternion = new THREE.Quaternion();
+
+    // Get the component's world transform for local-to-world conversion
+    let componentWorldMatrix: THREE.Matrix4 | null = null;
+    if (isWorldSpace) {
+      this.updateMatrixWorld(true);
+      componentWorldMatrix = this.matrixWorld.clone();
+    }
+
+    // Filter out instances within the radius
+    const initialCount = this.options.instances.length;
+    this.options.instances = this.options.instances.filter((instance) => {
+      // Build matrix from instance transform
+      const euler = instance.rotation ?? new THREE.Euler();
+      quaternion.setFromEuler(euler);
+      matrix.compose(
+        instance.position ?? new THREE.Vector3(),
+        quaternion,
+        instance.scale ?? new THREE.Vector3(1, 1, 1)
+      );
+
+      // Convert to world space if needed
+      if (isWorldSpace && componentWorldMatrix) {
+        matrix.premultiply(componentWorldMatrix);
+      }
+
+      // Extract position and check distance
+      position.setFromMatrixPosition(matrix);
+      const distanceSq = position.distanceToSquared(center);
+
+      // Keep instances that are outside the radius
+      return distanceSq > radiusSq;
+    });
+
+    const removedCount = initialCount - this.options.instances.length;
+
+    // Rebuild visual representation if any were removed
+    if (removedCount > 0) {
+      this.repopulateInstances();
+    }
+
+    return removedCount;
+  }
+
+  /**
+   * Clears all instance data and rebuilds the instanced meshes
+   * This removes all instances from the underlying data array
+   */
+  public clearInstanceData(): void {
+    this.options.instances = [];
+    this.repopulateInstances();
+  }
+
+  /**
+   * Combines the base instance transform properties with a modification transform
+   * @param transform The modification transform to apply on top of base properties
+   * @returns Combined transform
+   */
+  protected combineWithBaseTransform(transform: InstanceTransform): InstanceTransform {
+    const baseScale = this.options.instanceScale ?? BaseInstancedMeshComponent.DEFAULT_OPTIONS.instanceScale!;
+    const baseRotation = this.options.instanceRotation ?? BaseInstancedMeshComponent.DEFAULT_OPTIONS.instanceRotation!;
+    const baseOffset = this.options.instanceOffset ?? BaseInstancedMeshComponent.DEFAULT_OPTIONS.instanceOffset!;
+    const scaleDelta = this.options.instanceScaleDelta ?? BaseInstancedMeshComponent.DEFAULT_OPTIONS.instanceScaleDelta!;
+    const rotationDelta = this.options.instanceRotationDelta ?? BaseInstancedMeshComponent.DEFAULT_OPTIONS.instanceRotationDelta!;
+    const offsetDelta = this.options.instanceOffsetDelta ?? BaseInstancedMeshComponent.DEFAULT_OPTIONS.instanceOffsetDelta!;
+
+    // Combine position: base offset + transform position + random offset delta
+    const position = new THREE.Vector3();
+    if (transform.position) {
+      position.copy(transform.position);
+    }
+    position.add(baseOffset);
+    position.x += (Math.random() * 2 - 1) * offsetDelta.x;
+    position.y += (Math.random() * 2 - 1) * offsetDelta.y;
+    position.z += (Math.random() * 2 - 1) * offsetDelta.z;
+
+    // Combine rotation: use quaternion multiplication for correct rotation composition
+    // Convert from degrees to radians for baseRotation and rotationDelta (user-specified as degrees)
+    // Note: transform.rotation is already a THREE.Euler in radians, so don't convert it
+    const qBase = new THREE.Quaternion().setFromEuler(new THREE.Euler(
+      THREE.MathUtils.degToRad(baseRotation.x),
+      THREE.MathUtils.degToRad(baseRotation.y),
+      THREE.MathUtils.degToRad(baseRotation.z)
+    ));
+    const qTransform = transform.rotation
+      ? new THREE.Quaternion().setFromEuler(transform.rotation)
+      : new THREE.Quaternion();
+    const qDelta = new THREE.Quaternion().setFromEuler(new THREE.Euler(
+      THREE.MathUtils.degToRad((Math.random() * 2 - 1) * rotationDelta.x),
+      THREE.MathUtils.degToRad((Math.random() * 2 - 1) * rotationDelta.y),
+      THREE.MathUtils.degToRad((Math.random() * 2 - 1) * rotationDelta.z)
+    ));
+
+    const qFinal = new THREE.Quaternion();
+    qFinal.multiplyQuaternions(qBase, qTransform);
+    qFinal.multiply(qDelta);
+
+    const rotation = new THREE.Euler().setFromQuaternion(qFinal);
+
+    // Combine scale: base scale * transform scale * (1 + random scale delta)
+    const scale = new THREE.Vector3();
+    scale.copy(baseScale);
+    if (transform.scale) {
+      scale.multiply(transform.scale);
+    }
+    const scaleMultiplier = 1 + (Math.random() * 2 - 1) * scaleDelta;
+    scale.multiplyScalar(scaleMultiplier);
+
+    return { position, rotation, scale };
+  }
+
+  /**
+   * Appends a new instance to the underlying instance data array and rebuilds
+   * @param transform The transformation for the new instance (applied as modification on top of base transform)
+   */
+  public pushInstanceData(transform: InstanceTransform): void {
+    this.options.instances ??= [];
+    const combinedTransform = this.combineWithBaseTransform(transform);
+    this.options.instances.push(combinedTransform);
+    this.repopulateInstances();
+  }
+
+  /**
+   * Gets the color for a specific instance from the first mesh
+   * @param instanceId The index of the instance to get
+   * @param target The color to store the result in (optional)
+   * @returns The color of the instance
+   */
+  public getInstanceColor(instanceId: number, target?: THREE.Color): THREE.Color {
+    const color = target ?? new THREE.Color();
+    const mesh = this.instancedMeshes[0];
+    if (mesh?.instanceColor && instanceId >= 0 && instanceId < this.getBufferCapacity()) {
+      mesh.getColorAt(instanceId, color);
+    }
+    return color;
+  }
+
+  /**
+   * Updates all instance colors at once for all meshes
+   * @param colors Array of colors, a single color to apply to all instances, or a map of index to color
+   */
+  public setInstanceColors(colors: THREE.Color[] | THREE.Color | Map<number, THREE.Color>): void {
+    const bufferCapacity = this.getBufferCapacity();
+    const isMap = colors instanceof Map;
+    const isSingleColor = !Array.isArray(colors) && !isMap;
+
+    for (const mesh of this.instancedMeshes) {
+      if (!mesh.instanceColor) {
+        // Create instance color attribute if it doesn't exist
+        const colorArray = new Float32Array(bufferCapacity * 3);
+        mesh.instanceColor = new THREE.InstancedBufferAttribute(colorArray, 3);
+      }
+
+      if (isSingleColor) {
+        // Apply single color to all instances
+        for (let i = 0; i < bufferCapacity; i++) {
+          mesh.setColorAt(i, colors as THREE.Color);
+        }
+      } else if (isMap) {
+        // Apply colors from map at specific indices
+        for (const [index, color] of colors.entries()) {
+          if (index >= 0 && index < bufferCapacity && color) {
+            mesh.setColorAt(index, color);
+          }
+        }
+      } else {
+        // Apply colors from array
+        const count = Math.min((colors as THREE.Color[]).length, bufferCapacity);
+        for (let i = 0; i < count; i++) {
+          const color = (colors as THREE.Color[])[i];
+          if (!color) continue;
+          mesh.setColorAt(i, color);
+        }
+      }
+      mesh.instanceColor.needsUpdate = true;
+    }
+
+    // Store colors back to options for serialization
+    this.options.colors = colors;
+  }
+
+  /**
+   * Marks the instance matrix buffer as needing an update for all meshes
+   * Call this after manually modifying instance data
+   */
+  public updateInstanceMatrix(): void {
+    for (const mesh of this.instancedMeshes) {
+      mesh.instanceMatrix.needsUpdate = true;
+    }
+  }
+
+  /**
+   * Entirely refreshes the physics representation for this component
+   * This need to be called if instances are updated
+   */
+  public refreshPhysics(): void {
+
+    const actor = this.getActor();
+    if (actor?.isPlaying() && this.isPhysicsEnabled()) {
+      const physicsEngine = this.getPhysicsEngine();
+      if (physicsEngine) {
+        // Remove existing physics representation
+        physicsEngine.removeComponent(this);
+
+        // Create new physics representation based on the loaded model
+        this.motionType = physicsEngine.addComponent(this) ?? null;
+      }
+    }
+    this.shouldRefreshPhysics = false;
+  }
+
+  public override beginPlay(): void {
+    super.beginPlay();
+  }
+
+  public override generateDebugNode(): SceneGraphDebugNode | null {
+    const node = super.generateDebugNode()!;
+    node.data = {
+      ...node.data,
+      meshCount: this.instancedMeshes.length,
+      availableInstances: this.availableInstances,
+      instanceCount: this.getInstanceCount(),
+      maxInstances: this.getMaxInstances(),
+      geometries: this.instancedMeshes.map(mesh => ClassRegistry.getClassOrConstructorName(mesh.geometry)),
+      materials: this.instancedMeshes.map(mesh => ClassRegistry.getClassOrConstructorName(mesh.material)),
+    };
+    return node;
+  }
+
+  public override calcBoundingBox(): void {
+    if (this.instancedMeshes.length === 0) {
+      this._boundingBox.makeEmpty();
+      return;
+    }
+
+    // Start with the first mesh's bounding box
+    const firstMesh = this.instancedMeshes[0];
+    firstMesh.geometry.computeBoundingBox();
+    this._boundingBox.copy(firstMesh.geometry.boundingBox!).applyMatrix4(firstMesh.matrixWorld);
+
+    // Expand to include all other meshes
+    const tempBox = new THREE.Box3();
+    for (let i = 1; i < this.instancedMeshes.length; i++) {
+      const mesh = this.instancedMeshes[i];
+      mesh.geometry.computeBoundingBox();
+      tempBox.copy(mesh.geometry.boundingBox!).applyMatrix4(mesh.matrixWorld);
+      this._boundingBox.union(tempBox);
+    }
+  }
+
+  public override describe(options?: ComponentDescriptionOptions): Record<string, any> {
+    const result = super.describe(options);
+    if (options?.includeDetails) {
+      result.meshCount = this.instancedMeshes.length;
+      result.meshTypes = this.instancedMeshes.map(mesh => mesh.geometry.type);
+      result.availableInstances = this.availableInstances;
+      result.instanceCount = this.getInstanceCount();
+      result.maxInstances = this.getMaxInstances();
+    }
+    return result;
+  }
+
+  //====================================================================================================
+  // Editor Functions
+  //====================================================================================================
+
+  public override onEditorPropertyChanged(path: string, value: any, result: EditorPropertyChangedResult): void {
+    super.onEditorPropertyChanged(path, value, result);
+    this.repopulateInstances();
+  }
+
+  public override getEditorClassIcon(): string | null {
+    return 'Icon_InstancedMesh';
+  }
+}