@needle-tools/engine 4.11.5 → 4.12.0-next.ca2cebd

package/src/engine/xr/NeedleXRSession.ts

@@ -527,7 +527,9 @@ export class NeedleXRSession implements INeedleXRSession {
         else
             console.log("%c" + `Requesting ${mode} session`, "font-weight:bold;");
         for (const script of scripts) {
-            if (script.onBeforeXR) script.onBeforeXR(mode, init);
+            if (script.onBeforeXR && script.activeAndEnabled && !script.destroyed) {
+                script.onBeforeXR(mode, init);
+            }
         }
         for (const listener of this._sessionRequestStartListeners) {
             listener({ mode, init });

package/src/engine-components/AlignmentConstraint.ts

@@ -4,6 +4,14 @@ import { serializable } from "../engine/engine_serialization_decorator.js";
 import * as utils from "./../engine/engine_three_utils.js";
 import { Behaviour, GameObject } from "./Component.js";
 
+/**
+ * Aligns this GameObject between two other GameObjects, scaling it to fit the distance.  
+ * You can use this to create dynamic beams or connectors between objects.
+ *
+ * @summary Aligns and scales the object between two target GameObjects
+ * @category Utility
+ * @group Components 
+ **/
 export class AlignmentConstraint extends Behaviour {
 
     @serializable(GameObject)

package/src/engine-components/Animation.ts

@@ -59,6 +59,8 @@ class Vec2 { x!: number; y!: number }
 
 /**
  * Animation component to play animations on a GameObject.
+ * 
+ * @summary Play animations
  * @category Animation and Sequencing
  * @group Components
  */

package/src/engine-components/Animator.ts

@@ -14,6 +14,7 @@ const debug = getParam("debuganimator");
 /** 
  * Represents an event emitted by an animation mixer
  * @category Animation and Sequencing
+ * @group Components
  */
 export declare class MixerEvent {
     /** The type of event that occurred */
@@ -42,6 +43,7 @@ export declare class PlayOptions {
  * It works with an {@link AnimatorController} to handle state transitions and animation blending.
  * A new AnimatorController can be created from code via `AnimatorController.createFromClips`.  
  * 
+ * @summary Animation controller and playback component
  * @category Animation and Sequencing
  * @group Components
 */

package/src/engine-components/AudioListener.ts

@@ -8,6 +8,8 @@ import { Behaviour, GameObject } from "./Component.js";
  * AudioListener represents a listener that can hear audio sources in the scene.
  * This component creates and manages a Three.js {@link three#AudioListener}, automatically connecting it
  * to the main camera or a Camera in the parent hierarchy.
+ * 
+ * @summary Audio listener for 3D audio capture
  * @category Multimedia
  * @group Components
  */

package/src/engine-components/AudioSource.ts

@@ -52,6 +52,7 @@ export enum AudioRolloffMode {
  * is muted, the volume is set to 0. When unmuted, the volume
  * returns to its previous value.
  * 
+ * @summary 3D audio source with spatial positioning and playback controls
  * @category Multimedia
  * @group Components
  */

package/src/engine-components/AxesHelper.ts

@@ -7,6 +7,8 @@ import { Behaviour } from "./Component.js";
 /**
  * Component that visualizes the axes of an object in the scene.
  * Renders colored lines representing the X (red), Y (green) and Z (blue) axes.
+ * 
+ * @summary Visualizes object axes in the scene
  * @category Helpers
  * @group Components
  */

package/src/engine-components/BasicIKConstraint.ts

@@ -3,6 +3,14 @@ import { Vector3 } from "three";
 import * as utils from "./../engine/engine_three_utils.js";
 import { Behaviour, GameObject } from "./Component.js";
 
+/**
+ * BasicIKConstraint positions the GameObject between two target GameObjects (`from` and `to`) with an optional `hint` GameObject to guide the bending direction.  
+ * This is useful for simple inverse kinematics setups, such as positioning a joint in a limb.
+ * 
+ * @summary Simple Inverse Kinematics Constraint
+ * @category Animation
+ * @group Components
+ */
 export class BasicIKConstraint extends Behaviour {
 
     private from!: GameObject;

package/src/engine-components/BoxHelperComponent.ts

@@ -14,6 +14,7 @@ const debug = getParam("debugboxhelper");
  * Debug mode can be enabled with the URL parameter `?debugboxhelper`, which will visualize intersection tests.
  * Helper visualization can be enabled with the URL parameter `?gizmos`.
  * 
+ * @summary Bounding box helper with intersection tests
  * @category Helpers
  * @group Components
  */

package/src/engine-components/Camera.ts

@@ -36,6 +36,7 @@ const debugscreenpointtoray = getParam("debugscreenpointtoray");
  * Supports both perspective and orthographic cameras with various rendering options.
  * Internally, this component uses {@link PerspectiveCamera} and {@link OrthographicCamera} three.js objects.
  * 
+ * @summary Rendering scenes from a specific viewpoint
  * @category Camera
  * @group Components
  */

package/src/engine-components/CharacterController.ts

@@ -14,7 +14,10 @@ import { Rigidbody } from "./RigidBody.js";
 const debug = getParam("debugcharactercontroller");
 
 /**
- * @category Camera
+ * CharacterController adds a capsule collider and rigidbody to the object, constrains rotation, and provides movement and grounded state.  
+ * It is designed for typical character movement in 3D environments.
+ * @summary Character Movement Controller
+ * @category Character  
  * @group Components
  */
 export class CharacterController extends Behaviour {

package/src/engine-components/Collider.ts

@@ -22,7 +22,7 @@ import { Rigidbody } from "./RigidBody.js";
  * - Example: https://samples.needle.tools/physics-playground
  * - Example: https://samples.needle.tools/physics-&-animation 
  * 
- * 
+ * @summary Physics collider
  * @category Physics  
  * @group Components
  */

package/src/engine-components/Component.ts

@@ -11,6 +11,7 @@ import { syncDestroy, syncInstantiate, SyncInstantiateOptions } from "../engine/
 import { Context, FrameEvent } from "../engine/engine_setup.js";
 import * as threeutils from "../engine/engine_three_utils.js";
 import type { Collision, ComponentInit, Constructor, ConstructorConcrete, GuidsMap, ICollider, IComponent, IGameObject, SourceIdentifier } from "../engine/engine_types.js";
+import { TypeStore } from "../engine/engine_typestore.js";
 import type { INeedleXRSessionEventReceiver, NeedleXRControllerEventArgs, NeedleXREventArgs } from "../engine/engine_xr.js";
 import { type IPointerEventHandler, PointerEventData } from "./ui/PointerEvents.js";
 
@@ -540,7 +541,8 @@ export abstract class GameObject extends Object3D implements Object3D, IGameObje
     }
 }
 
-
+// DO NOT CHANGE THE SYMBOL NAME
+const $componentName = Symbol("component-name");
 
 /** 
  * Needle Engine component's are the main building blocks of the Needle Engine.    
@@ -581,6 +583,12 @@ export abstract class Component implements IComponent, EventTarget,
      */
     get isComponent(): boolean { return true; }
 
+    /**
+     * Get the original component type name before minification (available if the component is registered in the TypeStore)
+     */
+    get [$componentName]() { return TypeStore.getKey(this.constructor as any) || undefined; }
+
+    
     private __context: Context | undefined;
 
     /**

package/src/engine-components/ContactShadows.ts

@@ -53,7 +53,7 @@ type FitParameters = {
  * 
  * ContactShadows can also be enabled on the `<needle-engine>` web component directly by adding the `contactshadows` attribute. The value of the attribute will be used as opacity and darkness of the shadows: `<needle-engine contactshadows="0.7">`.
  * 
- * 
+ * @summary Display contact shadows on the ground
  * @category Rendering
  * @group Components
 */

package/src/engine-components/DeleteBox.ts

@@ -11,6 +11,8 @@ import { UsageMarker } from "./Interactable.js";
 const debug = getParam("debugdeletable");
 /**
  * A box-shaped area that can be used to delete objects that get into it. Useful for sandbox-style builders or physics simulations.
+ * 
+ * @summary Box area that deletes objects entering it
  * @category Interactivity
  * @group Components
  */

package/src/engine-components/DeviceFlag.ts

@@ -11,6 +11,10 @@ export enum DeviceType {
 }
 
 /**
+ * Enables or disables the GameObject based on the device type (mobile or desktop).  
+ * You can use this to show or hide objects depending on whether the user is on a mobile device or a desktop.
+ * 
+ * @summary Show or hide GameObject based on device type
  * @category Utilities
  * @group Components
  */

package/src/engine-components/DragControls.ts

@@ -46,6 +46,7 @@ export enum DragMode {
  * DragControls allows you to drag objects around in the scene. It can be used to move objects in 2D (screen space) or 3D (world space).
  * Debug mode can be enabled with the URL parameter `?debugdrag`, which shows visual helpers and logs drag operations.
  * 
+ * @summary Enables dragging of objects in 2D or 3D space
  * @category Interactivity
  * @group Components
  */

package/src/engine-components/DropListener.ts

@@ -139,6 +139,7 @@ const blobKeyName = "blob";
  * });
  * ```
  * 
+ * @summary Component to handle drag and drop of files into the scene
  * @category Asset Management
  * @group Components
  */

package/src/engine-components/Duplicatable.ts

@@ -14,6 +14,7 @@ import { ObjectRaycaster } from "./ui/Raycaster.js";
 /**
  * The Duplicatable component is used to duplicate a assigned {@link GameObject} when a pointer event occurs on the object.   
  *  
+ * @summary Duplicates a GameObject on pointer events
  * @category Interactivity
  * @group Components
  */

package/src/engine-components/EventTrigger.ts

@@ -14,6 +14,8 @@ class TriggerEvent {
 /**
  * The EventTrigger component is used to trigger events when certain pointer events occur on the GameObject.
  * It implements the {@link IPointerEventHandler} interface and can be used to expose events to the user in the editor without writing code.
+ * 
+ * @summary Triggers events on pointer interactions
  * @category Interactivity
  * @group Components
  */

package/src/engine-components/Gizmos.ts

@@ -8,6 +8,8 @@ import { Behaviour } from "./Component.js";
 
 /**
  * BoxGizmo is a component that displays a box around the object in the scene. It can optionally expand to the object's bounds.
+ *
+ * @summary Display a box around the object
  * @category Helpers
  * @group Components
  */

package/src/engine-components/GridHelper.ts

@@ -6,6 +6,8 @@ import { Behaviour } from "./Component.js";
 
 /**
  * GridHelper is a component that allows to display a grid in the scene.
+ * 
+ * @example Display a grid in the scene
  * @category Helpers
  * @group Components
  */

package/src/engine-components/GroundProjection.ts

@@ -14,6 +14,7 @@ const debug = getParam("debuggroundprojection");
  * 
  * - Example https://engine.needle.tools/samples/ground-projection
  * 
+ * @summary Projects the environment map onto the ground
  * @category Rendering
  * @group Components
  */

package/src/engine-components/Joints.ts

@@ -4,6 +4,12 @@ import { serializable } from "../engine/engine_serialization.js";
 import { Behaviour } from "./Component.js";
 import { Rigidbody } from "./RigidBody.js";
 
+/**
+ * Base class for physics joints connecting two rigid bodies.
+ * @summary Connect two Rigidbodies
+ * @category Physics
+ * @group Components
+ */
 export abstract class Joint extends Behaviour {
     @serializable(Rigidbody)
     connectedBody?: Rigidbody;

package/src/engine-components/LODGroup.ts

@@ -40,6 +40,8 @@ declare class LODSetting {
 
 /**
  * LODGroup allows to create a group of LOD levels for an object.
+ * 
+ * @summary Level of Detail Group for optimizing rendering
  * @category Rendering
  * @group Components
  */

package/src/engine-components/Light.ts

@@ -75,6 +75,7 @@ enum LightShadows {
  * Debug mode can be enabled with the URL parameter `?debuglights`, which shows
  * additional console output and visual helpers for lights.
  * 
+ * @summary Light component for various light types and shadow settings
  * @category Rendering
  * @group Components
  */

package/src/engine-components/LookAtConstraint.ts

@@ -8,6 +8,7 @@ import type { OrbitControls } from "./OrbitControls.js";
  * A LookAtConstraint is used by OrbitControls to make the camera look at a target.  
  * This component is used by {@link OrbitControls} internally.
  * 
+ * @summary Look At Constraint for OrbitControls
  * @category Camera Controls
  * @group Components
  */

package/src/engine-components/NeedleMenu.ts

@@ -10,6 +10,7 @@ import { Behaviour } from './Component.js';
  * Controls display options, button visibility, and menu positioning.
  * From code, you can access the menu via {@link Context.menu}. 
  * 
+ * @summary Configuration component for the Needle Menu
  * @category User Interface
  * @group Components
  **/

package/src/engine-components/NestedGltf.ts

@@ -11,6 +11,7 @@ const debug = getParam("debugnestedgltf");
 /** The nested gltf is a component that is used to load a gltf file when the component becomes active (start)  
  * It will load the gltf file and instantiate it as a child of the parent of the GameObject that has this component
  * 
+ * @summary Loads and instantiates a nested glTF file
  * @category Asset Management
  * @group Components
  */

package/src/engine-components/Networking.ts

@@ -11,6 +11,7 @@ const debug = getParam("debugnet");
  * This component supplies websocket URLs for establishing connections.
  * It implements the {@link INetworkingWebsocketUrlProvider} interface.
  * 
+ * @summary Networking configuration
  * @category Networking
  * @group Components
  */

package/src/engine-components/OffsetConstraint.ts

@@ -4,6 +4,13 @@ import { serializable } from "../engine/engine_serialization_decorator.js";
 import * as utils from "./../engine/engine_three_utils.js";
 import { Behaviour, GameObject } from "./Component.js";
 
+/**
+ * OffsetConstraint component allows an object to maintain a specified positional and rotational offset 
+ * relative to another object, with options for alignment and leveling.
+ * @summary Maintains positional and rotational offset relative to another object
+ * @category Constraints
+ * @group Components
+ */
 export class OffsetConstraint extends Behaviour {
 
     @serializable(GameObject)

package/src/engine-components/OrbitControls.ts

@@ -63,6 +63,7 @@ declare module 'three/examples/jsm/controls/OrbitControls.js' {
 /** The OrbitControls component is used to control a camera using the [OrbitControls from three.js](https://threejs.org/docs/#examples/en/controls/OrbitControls) library.  
  * The three OrbitControls object can be accessed via the `controls` property.  
  * The object being controlled by the OrbitControls (usually the camera) can be accessed via the `controllerObject` property.
+ * @summary Camera controller using three.js OrbitControls
  * @category Camera
  * @group Components
  */

package/src/engine-components/PlayerColor.ts

@@ -9,6 +9,8 @@ import { AvatarMarker } from "./webxr/WebXRAvatar.js";
 /**
  * PlayerColor assigns a unique color for each user in the room to the object it is attached to.  
  * The color is generated based on the user's ID.
+ * 
+ * @summary Assigns a unique color to the player object
  * @category Networking
  * @group Components
  */

package/src/engine-components/ReflectionProbe.ts

@@ -19,6 +19,7 @@ const $originalMaterial = Symbol("original material");
  * 
  * - Sample: http://samples.needle.tools/reflection-probes
  * 
+ * @summary Provides reflection data to materials
  * @category Rendering
  * @group Components
  */

package/src/engine-components/RendererInstancing.ts

@@ -29,8 +29,9 @@ export class InstancingHandler {
      * (The instancing mesh renderer will grow x2 if the max instance count is reached)
      * @default 4
      * @returns The initial instance count
-     * */
-    static getStartInstanceCount = (_obj: Object3D) => {
+     */
+    // @ts-ignore (ignore the unused parameter warning)
+    static getStartInstanceCount = (obj: Object3D) => {
         return 4;
     };
 
@@ -45,20 +46,24 @@ export class InstancingHandler {
         if (res) {
             if (handlesArray === null) handlesArray = [];
             handlesArray.push(res);
-            // load texture lods
-            NEEDLE_progressive.assignTextureLOD(res.renderer.material, 0);
-
-            // Load mesh lods
-            // TODO: technically for multi meshes we do this work multiple times (we search for meshes in children and then use the renderer sharedMeshes... that doesnt make sense)
-            for (let i = 0; i < renderer.sharedMeshes.length; i++) {
-                const mesh = renderer.sharedMeshes[i];
-                const geometry = mesh.geometry;
-                NEEDLE_progressive.assignMeshLOD(mesh, 0).then(lod => {
-                    if (lod && renderer.activeAndEnabled && geometry != lod) {
-                        res.setGeometry(lod);
-                    }
-                });
+
+            // Load LOD for textures
+            const mat = res.object.material;
+            if(Array.isArray(mat)) {
+                mat.forEach(m => NEEDLE_progressive.assignTextureLOD(m, 0));
+            }
+            else {
+                NEEDLE_progressive.assignTextureLOD(mat, 0);
             }
+
+            // Load LOD for geometry
+            const mesh = res.object;
+            const geometry = mesh.geometry;
+            NEEDLE_progressive.assignMeshLOD(mesh, 0).then(lod => {
+                if (lod && geometry != lod) {
+                    res.setGeometry(lod);
+                }
+            });
         }
 
         else if (level <= 0 && obj.type !== "Mesh") {
@@ -349,7 +354,7 @@ class InstancedMeshRenderer {
     private _context: Context;
     private _batchedMesh: BatchedMesh;
     private _handles: (InstanceHandle | null)[] = [];
-    private readonly _geometryIds: Map<BufferGeometry, number> = new Map();
+    private _geometryIds = new WeakMap<BufferGeometry, number>();
     private _maxInstanceCount: number;
 
     private _currentInstanceCount = 0;
@@ -439,6 +444,10 @@ class InstancedMeshRenderer {
     private _needUpdateBounds: boolean = false;
     private _debugMaterial: MeshStandardMaterial | null = null;
 
+    private getBatchedMeshName() {
+        return this.name ? `${this.name} (BatchedMesh)` : "BatchedMesh";
+    }
+
     constructor(name: string, geo: BufferGeometry, material: Material, initialMaxCount: number, context: Context) {
         this.name = name;
         this.geometry = geo;
@@ -452,6 +461,7 @@ class InstancedMeshRenderer {
         this._maxVertexCount = estimate.vertexCount;
         this._maxIndexCount = estimate.indexCount;
         this._batchedMesh = new BatchedMesh(this._maxInstanceCount, this._maxVertexCount, this._maxIndexCount, this._debugMaterial ?? this.material);
+        this._batchedMesh.name = this.getBatchedMeshName();
         // this.inst = new InstancedMesh(geo, material, count);
         this._batchedMesh[$instancingAutoUpdateBounds] = true;
         // this.inst.count = 0;
@@ -475,7 +485,7 @@ class InstancedMeshRenderer {
         context.post_render_callbacks.push(this.onAfterRender);
 
         if (debugInstancing) {
-            console.log(`Instanced renderer created with ${this._maxInstanceCount} instances, ${this._maxVertexCount} max vertices and ${this._maxIndexCount} max indices for \"${name}\"`)
+            console.log(`Instanced renderer (${this.name}) created with ${this._maxInstanceCount} instances, ${this._maxVertexCount} max vertices and ${this._maxIndexCount} max indices for \"${name}\"`)
         }
     }
 
@@ -522,7 +532,8 @@ class InstancedMeshRenderer {
             return false;
         }
 
-        if (this.mustGrow(geo)) {
+        const newInstanceCount = this._currentInstanceCount + 1;
+        if (newInstanceCount > this._maxInstanceCount || this.mustGrow(geo)) {
             if (this.allowResize) {
                 this.grow(geo);
             }
@@ -644,34 +655,42 @@ class InstancedMeshRenderer {
     private mustGrow(geo?: BufferGeometry): boolean {
         if (this.count >= this._maxInstanceCount) return true;
         if (!geo || !geo.attributes) return false;
+
+        const isKnownGeometry = this._geometryIds.has(geo);
+        if (isKnownGeometry) return false;
+
         const meshInfo = getMeshInformation(geo);
         const newVertexCount = meshInfo.vertexCount;
         const newIndexCount = meshInfo.indexCount;
         return this._currentVertexCount + newVertexCount > this._maxVertexCount || this._currentIndexCount + newIndexCount > this._maxIndexCount;
     }
 
+    private _growId = 0;
     private grow(geometry: BufferGeometry) {
+        const id = ++this._growId;
         const growFactor = 2;
         const newSize = Math.ceil(this._maxInstanceCount * growFactor);
 
         // create a new BatchedMesh instance
+        // TODO: we should keep track of how many instances for each geometry we have and consider that when estimating new space
         const estimatedSpace = this.tryEstimateVertexCountSize(newSize, [geometry]);// geometry.attributes.position.count;
         // const indices = geometry.index ? geometry.index.count : 0;
         const newMaxVertexCount = Math.max(this._maxVertexCount, estimatedSpace.vertexCount);
-        const newMaxIndexCount = Math.max(this._maxIndexCount, estimatedSpace.indexCount, Math.ceil(this._maxVertexCount * growFactor));
+        const newMaxIndexCount = Math.max(this._maxIndexCount, estimatedSpace.indexCount);//, Math.ceil(this._maxVertexCount * growFactor));
 
         if (debugInstancing) {
             const geometryInfo = getMeshInformation(geometry);
-            console.warn(`[Instancing] Growing Buffer\nMesh: \"${this.name}${geometry.name?.length ? "/" + geometry.name : ""}\"\n${geometryInfo.vertexCount} vertices, ${geometryInfo.indexCount} indices\nMax count ${this._maxInstanceCount} → ${newSize}\nMax vertex count ${this._maxVertexCount} -> ${newMaxVertexCount}\nMax index count ${this._maxIndexCount} -> ${newMaxIndexCount}`);
+            console.warn(`[Instancing] Growing Buffer\nMesh: \"${this.name}${geometry.name?.length ? "/" + geometry.name : ""}\" (${geometryInfo.vertexCount.toLocaleString()} vertices, ${geometryInfo.indexCount.toLocaleString()} indices)\nMax count ${this._maxInstanceCount.toLocaleString()} → ${newSize.toLocaleString()}\nMax vertex count ${this._maxVertexCount.toLocaleString()} -> ${newMaxVertexCount.toLocaleString()}\nMax index count ${this._maxIndexCount.toLocaleString()} -> ${newMaxIndexCount.toLocaleString()}`);
             this._debugMaterial = createDebugMaterial();
         }
         else if (isDevEnvironment()) {
-            console.debug(`[Instancing] Growing Buffer\nMesh: \"${this.name}${geometry.name?.length ? "/" + geometry.name : ""}\"\nMax count ${this._maxInstanceCount} → ${newSize}\nMax vertex count ${this._maxVertexCount} -> ${newMaxVertexCount}\nMax index count ${this._maxIndexCount} -> ${newMaxIndexCount}`);
+            console.debug(`[Instancing] Growing Buffer\nMesh: \"${this.name}${geometry.name?.length ? "/" + geometry.name : ""}\"\nMax count ${this._maxInstanceCount} → ${newSize}\nMax vertex count ${this._maxVertexCount.toLocaleString()} -> ${newMaxVertexCount.toLocaleString()}\nMax index count ${this._maxIndexCount.toLocaleString()} -> ${newMaxIndexCount.toLocaleString()}`);
         }
 
         this._maxVertexCount = newMaxVertexCount;
         this._maxIndexCount = newMaxIndexCount;
         const newInst = new BatchedMesh(newSize, this._maxVertexCount, this._maxIndexCount, this._debugMaterial ?? this.material);
+        newInst.name = this.getBatchedMeshName();
         newInst.layers = this._batchedMesh.layers;
         newInst.castShadow = this._batchedMesh.castShadow;
         newInst.receiveShadow = this._batchedMesh.receiveShadow;
@@ -686,7 +705,7 @@ class InstancedMeshRenderer {
         // dispose the old batched mesh
         this._batchedMesh.dispose();
         this._batchedMesh.removeFromParent();
-        this._geometryIds.clear();
+        this._geometryIds = new WeakMap<BufferGeometry, number>();
 
         this._batchedMesh = newInst;
         this._maxInstanceCount = newSize;
@@ -698,6 +717,11 @@ class InstancedMeshRenderer {
         const original = [...this._handles];
         this._handles = [];
         for (const handle of original) {
+            if (id !== this._growId) {
+                // another grow happened in the meantime
+                if (debugInstancing) console.warn("[Instancing] Aborting grow since another grow happened in the meantime");
+                return;
+            }
             if (handle && handle.__instanceIndex >= 0) {
                 this.addGeometry(handle);
                 this._handles[handle.__instanceIndex] = handle;
@@ -722,23 +746,31 @@ class InstancedMeshRenderer {
                     entry.count += 1;
                 }
 
+                if (_newGeometries && _newGeometries?.length > 0) {
+                    const index = _newGeometries.indexOf(handle.object.geometry as BufferGeometry);
+                    if (index !== -1) {
+                        _newGeometries.splice(index, 1);
+                    }
+                }
             }
         }
 
         // then calculate the total vertex count
         let totalVertices = 0;
         let totalIndices = 0;
+        let totalGeometries = 0;
         // let maxVertices = 0;
         for (const [_geo, data] of usedGeometries) {
-            totalVertices += data.vertexCount * data.count;
-            totalIndices += data.indexCount * data.count;
+            totalGeometries += 1;
+            totalVertices += data.vertexCount;
+            totalIndices += data.indexCount;
             // maxVertices = Math.max(maxVertices, geo.attributes.position.count * count);
         }
         // we calculate the average to make an educated guess of how many vertices will be needed with the new buffer count
-        const averageVerts = Math.ceil(totalVertices / Math.max(1, this._currentInstanceCount));
-        let maxVertexCount = averageVerts * newMaxInstances;
-        const averageIndices = Math.ceil(totalIndices / Math.max(1, this._currentInstanceCount));
-        let maxIndexCount = averageIndices * newMaxInstances * 2;
+        const averageVerts = Math.ceil(totalVertices / Math.max(1, totalGeometries));
+        let maxVertexCount = averageVerts * totalGeometries;
+        const averageIndices = Math.ceil(totalIndices / Math.max(1, totalGeometries));
+        let maxIndexCount = averageIndices * totalGeometries;
 
         // if new geometries are provided we *know* that they will be added
         // so we make sure to include them in the calculation
@@ -753,6 +785,10 @@ class InstancedMeshRenderer {
             }
         }
 
+        if (debugInstancing) {
+            console.log(`[Instancing] Estimated size for new buffer ${this.name}\nGeometries: ${totalGeometries} (New: ${_newGeometries?.length || 0})\nInstances: ${newMaxInstances}\nEstimated Vertices: ${maxVertexCount.toLocaleString()}\nEstimated Indices: ${maxIndexCount.toLocaleString()}`);
+        }
+
         return { vertexCount: maxVertexCount, indexCount: maxIndexCount };
     }
 
@@ -770,16 +806,16 @@ class InstancedMeshRenderer {
         let geometryId = this._geometryIds.get(geo);
         if (geometryId === undefined || geometryId === null) {
             if (debugInstancing)
-                console.debug(`[Instancing] > ADD NEW GEOMETRY \"${handle.name} (${geo.name}; ${geo.uuid})\"\n${this._currentInstanceCount} instances, ${handle.maxVertexCount} max vertices, ${handle.maxIndexCount} max indices`);
+                console.warn(`[Instancing] > ADD NEW GEOMETRY \"${handle.name} (${geo.name}; ${geo.uuid})\"\nCurrent Instances: ${this._currentInstanceCount}\nMax Vertices: ${handle.maxVertexCount.toLocaleString()}\nMax Indices: ${handle.maxIndexCount.toLocaleString()}\nMax Triangles: ${(handle.maxIndexCount / 3).toLocaleString()}`);
 
             geometryId = this._batchedMesh.addGeometry(geo, handle.maxVertexCount, handle.maxIndexCount);
             this._geometryIds.set(geo, geometryId);
+            this._currentVertexCount += handle.maxVertexCount;
+            this._currentIndexCount += handle.maxIndexCount;
         }
         else {
             if (debugInstancing === "verbose") console.log(`[Instancing] > ADD INSTANCE \"${handle.name}\"\nGEOMETRY_ID=${geometryId}\n${this._currentInstanceCount} instances`);
         }
-        this._currentVertexCount += handle.maxVertexCount;
-        this._currentIndexCount += handle.maxIndexCount;
         const i = this._batchedMesh.addInstance(geometryId);
         handle.__geometryIndex = geometryId;
         handle.__instanceIndex = i;
@@ -787,7 +823,7 @@ class InstancedMeshRenderer {
         handle.__reservedIndexRange = handle.maxIndexCount;
         this._batchedMesh.setMatrixAt(i, handle.object.matrixWorld);
         if (debugInstancing)
-            console.debug(`[Instancing] > ADDED INSTANCE \"${handle.name}\"\nGEOMETRY_ID=${geometryId}\n${this._currentInstanceCount} instances\nIndex: ${handle.__instanceIndex}`);
+            console.debug(`[Instancing] > ADDED INSTANCE \"${handle.name}\"\nGEOMETRY_ID=${geometryId}\n${this._currentInstanceCount} instances\nIndex: ${handle.__instanceIndex}\nVertices: ${this._currentVertexCount.toLocaleString()}/${this._maxVertexCount.toLocaleString()},\nIndices: ${this._currentIndexCount.toLocaleString()}/${this._maxIndexCount.toLocaleString()}`);
 
     }
 
@@ -803,7 +839,7 @@ class InstancedMeshRenderer {
         //     this.inst.deleteGeometry(handle.__instanceIndex);
         // else 
         // this._batchedMesh.setVisibleAt(handle.__instanceIndex, false);
-        if(debugInstancing) {
+        if (debugInstancing) {
             console.debug(`[Instancing] < REMOVE INSTANCE \"${handle.name}\" at [${handle.__instanceIndex}]\nGEOMETRY_ID=${handle.__geometryIndex}\n${this._currentInstanceCount} instances\nIndex: ${handle.__instanceIndex}`);
         }
         this._batchedMesh.deleteInstance(handle.__instanceIndex);

package/src/engine-components/RigidBody.ts

@@ -140,6 +140,7 @@ class TransformWatch {
  * - Example: https://samples.needle.tools/physics-playground
  * - Example: https://samples.needle.tools/physics-&-animation
  * 
+ * @summary Rigidbody for physical interactions
  * @category Physics 
  * @group Components
  */