@needle-tools/engine 4.3.0-alpha → 4.3.0-alpha.3

package/src/engine-components/Collider.ts

@@ -1,59 +1,63 @@
 import { BufferGeometry, Group, Mesh, Object3D, Vector3 } from "three"
 
+import { isDevEnvironment } from "../engine/debug/index.js";
 import { addComponent } from "../engine/engine_components.js";
 import { Gizmos } from "../engine/engine_gizmos.js";
 import type { PhysicsMaterial } from "../engine/engine_physics.types.js";
 import { serializable } from "../engine/engine_serialization_decorator.js";
-import { getBoundingBox, getWorldScale } from "../engine/engine_three_utils.js";
-// import { IColliderProvider, registerColliderProvider } from "../engine/engine_physics.js";
+import { getBoundingBox } from "../engine/engine_three_utils.js";
 import type { IBoxCollider, ICollider, ISphereCollider } from "../engine/engine_types.js";
 import { validate } from "../engine/engine_util_decorator.js";
-import { unwatchWrite, watchWrite } from "../engine/engine_utils.js";
+import { getParam, unwatchWrite, watchWrite } from "../engine/engine_utils.js";
 import { NEEDLE_progressive } from "../engine/extensions/NEEDLE_progressive.js";
 import { Behaviour } from "./Component.js";
 import { Rigidbody } from "./RigidBody.js";
 
 /**
  * Collider is the base class for all colliders. A collider is a physical shape that is used to detect collisions with other objects in the scene.  
- * Colliders are used in combination with a Rigidbody to create physical interactions between objects.  
+ * Colliders are used in combination with a {@link Rigidbody} to create physical interactions between objects.  
  * Colliders are registered with the physics engine when they are enabled and removed when they are disabled.
  * @category Physics  
  * @group Components
  */
 export class Collider extends Behaviour implements ICollider {
 
-    /** @internal */
+    /**
+     * Identifies this component as a collider.
+     * @internal
+     */
     get isCollider(): any {
         return true;
     }
 
     /**
-     * The Rigidbody that this collider is attached to.
+     * The {@link Rigidbody} that this collider is attached to. This handles the physics simulation for this collider.
      */
     @serializable(Rigidbody)
     attachedRigidbody: Rigidbody | null = null;
 
     /**
      * When `true` the collider will not be used for collision detection but will still trigger events.
+     * Trigger colliders can trigger events when other colliders enter their space, without creating a physical response/collision.
      */
     @serializable()
     isTrigger: boolean = false;
 
     /**
-     * The physics material that is used for the collider. This material defines physical properties of the collider such as friction and bounciness.
+     * The physics material that defines physical properties of the collider such as friction and bounciness.
      */
     @serializable()
     sharedMaterial?: PhysicsMaterial;
 
     /**
-     * The layers that the collider is assigned to.
+     * The layers that this collider belongs to. Used for filtering collision detection.
+     * @default [0]
      */
     @serializable()
     membership: number[] = [0];
 
     /**
-     * The layers that the collider will interact with.
-     * @inheritdoc
+     * The layers that this collider will interact with. Used for filtering collision detection.
      */
     @serializable()
     filter?: number[];
@@ -80,62 +84,91 @@ export class Collider extends Behaviour implements ICollider {
         this.context.physics.engine?.removeBody(this);
     }
 
-    /** Returns the underlying physics body from the physics engine (if any) - the component must be enabled and active in the scene */
+    /**
+     * Returns the underlying physics body from the physics engine.
+     * Only available if the component is enabled and active in the scene.
+     */
     get body() {
         return this.context.physics.engine?.getBody(this);
     }
 
     /**
-     * Apply the collider properties to the physics engine.
+     * Updates the collider's properties in the physics engine.
+     * Use this when you've changed collider properties and need to sync with the physics engine.
      */
     updateProperties = () => {
         this.context.physics.engine?.updateProperties(this);
     }
 
-    /** Requests an update of the physics material in the physics engine */
+    /**
+     * Updates the physics material in the physics engine.
+     * Call this after changing the sharedMaterial property.
+     */
     updatePhysicsMaterial() {
         this.context.physics.engine?.updatePhysicsMaterial(this);
-
     }
 }
 
 /**
- * SphereCollider is a collider that represents a sphere shape.
+ * SphereCollider represents a sphere-shaped collision volume.
+ * Useful for objects that are roughly spherical in shape or need a simple collision boundary.
  * @category Physics
  * @group Components
  */
 export class SphereCollider extends Collider implements ISphereCollider {
 
+    /**
+     * The radius of the sphere collider.
+     */
     @validate()
     @serializable()
     radius: number = .5;
 
+    /**
+     * The center position of the sphere collider relative to the transform's position.
+     */
     @serializable(Vector3)
     center: Vector3 = new Vector3(0, 0, 0);
 
+    /**
+     * Registers the sphere collider with the physics engine and sets up scale change monitoring.
+     */
     onEnable() {
         super.onEnable();
         this.context.physics.engine?.addSphereCollider(this);
         watchWrite(this.gameObject.scale, this.updateProperties);
     }
 
+    /**
+     * Removes scale change monitoring when the collider is disabled.
+     */
     onDisable(): void {
         super.onDisable();
         unwatchWrite(this.gameObject.scale, this.updateProperties);
     }
 
+    /**
+     * Updates collider properties when validated in the editor or inspector.
+     */
     onValidate(): void {
         this.updateProperties();
     }
 }
 
 /**
- * BoxCollider is a collider that represents a box shape.
+ * BoxCollider represents a box-shaped collision volume.
+ * Ideal for rectangular objects or objects that need a simple cuboid collision boundary.
  * @category Physics
  * @group Components
  */
 export class BoxCollider extends Collider implements IBoxCollider {
 
+    /**
+     * Creates and adds a BoxCollider to the given object.
+     * @param obj The object to add the collider to
+     * @param opts Configuration options for the collider and optional rigidbody
+     * @returns The newly created BoxCollider
+     */
     static add(obj: Mesh | Object3D, opts?: { rigidbody: boolean, debug?: boolean }) {
         const collider = addComponent(obj, BoxCollider);
         collider.autoFit();
@@ -146,31 +179,51 @@ export class BoxCollider extends Collider implements IBoxCollider {
         return collider;
     }
 
+    /**
+     * The size of the box collider along each axis.
+     */
     @validate()
     @serializable(Vector3)
     size: Vector3 = new Vector3(1, 1, 1);
 
+    /**
+     * The center position of the box collider relative to the transform's position.
+     */
     @serializable(Vector3)
     center: Vector3 = new Vector3(0, 0, 0);
 
-    /** @internal */
+    /**
+     * Registers the box collider with the physics engine and sets up scale change monitoring.
+     * @internal
+     */
     onEnable() {
         super.onEnable();
         this.context.physics.engine?.addBoxCollider(this, this.size);
         watchWrite(this.gameObject.scale, this.updateProperties);
     }
 
-    /** @internal */
+    /**
+     * Removes scale change monitoring when the collider is disabled.
+     * @internal
+     */
     onDisable(): void {
         super.onDisable();
         unwatchWrite(this.gameObject.scale, this.updateProperties);
     }
 
-    /** @internal */
+    /**
+     * Updates collider properties when validated in the editor or inspector.
+     * @internal
+     */
     onValidate(): void {
         this.updateProperties();
     }
 
+    /**
+     * Automatically fits the collider to the geometry of the object.
+     * Sets the size and center based on the object's bounding box.
+     * @param opts Options object with a debug flag to visualize the bounding box
+     */
     autoFit(opts?: { debug?: boolean }) {
         const obj = this.gameObject;
 
@@ -205,24 +258,31 @@ export class BoxCollider extends Collider implements IBoxCollider {
 }
 
 /**
- * MeshCollider is a collider that represents a mesh shape.  
- * The mesh collider can be used to create a collider from a mesh.
+ * MeshCollider creates a collision shape from a mesh geometry.
+ * Allows for complex collision shapes that match the exact geometry of an object.
  * @category Physics
  * @group Components
  */
 export class MeshCollider extends Collider {
 
     /**
-     * The mesh that is used for the collider.
+     * The mesh that is used to create the collision shape.
+     * If not set, the collider will try to use the mesh of the object it's attached to.
      */
     @serializable(Mesh)
     sharedMesh?: Mesh;
 
-    /** When `true` the collider won't have holes or entrances.   
-     * If you wan't this mesh collider to be able to *contain* other objects this should be set to `false` */
+    /**
+     * When `true` the collider is treated as a solid object without holes.
+     * Set to `false` if you want this mesh collider to be able to contain other objects.
+     */
     @serializable()
     convex: boolean = false;
 
+    /**
+     * Creates and registers the mesh collider with the physics engine.
+     * Handles both individual meshes and mesh groups.
+     */
     onEnable() {
         super.onEnable();
         if (!this.context.physics.engine) return;
@@ -272,29 +332,44 @@ export class MeshCollider extends Collider {
                 });
             }
             else {
-                console.warn("A MeshCollider mesh is assigned, but it's neither a Mesh nor a Group. Please report a bug!", this, this.sharedMesh);
+                if (isDevEnvironment() || getParam("showcolliders")) {
+                    console.warn(`[MeshCollider] A MeshCollider mesh is assigned to an unknown object on \"${this.gameObject.name}\", but it's neither a Mesh nor a Group. Please double check that you attached the collider component to the right object and report a bug otherwise!`, this);
+                }
             }
         }
     }
 }
 
 /**
- * CapsuleCollider is a collider that represents a capsule shape.
+ * CapsuleCollider represents a capsule-shaped collision volume (cylinder with hemispherical ends).
+ * Ideal for character controllers and objects that need a rounded collision shape.
  * @category Physics
  * @group Components
  */
 export class CapsuleCollider extends Collider {
+    /**
+     * The center position of the capsule collider relative to the transform's position.
+     */
     @serializable(Vector3)
     center: Vector3 = new Vector3(0, 0, 0);
 
+    /**
+     * The radius of the capsule's cylindrical body and hemispherical ends.
+     */
     @serializable()
     radius: number = .5;
+
+    /**
+     * The total height of the capsule including both hemispherical ends.
+     */
     @serializable()
     height: number = 2;
 
+    /**
+     * Registers the capsule collider with the physics engine.
+     */
     onEnable() {
         super.onEnable();
         this.context.physics.engine?.addCapsuleCollider(this, this.height, this.radius);
     }
-
 }