@needle-tools/engine
Version:
Needle Engine is a web-based runtime for 3D apps. It runs on your machine for development with great integrations into editors like Unity or Blender - and can be deployed onto any device! It is flexible, extensible and networking and XR are built-in.
272 lines (271 loc) • 9.32 kB
TypeScript
import { Mesh, Object3D, Vector3 } from "three";
import type { PhysicsMaterial } from "../engine/engine_physics.types.js";
import type { IBoxCollider, ICollider, ISphereCollider } from "../engine/engine_types.js";
import { Behaviour } from "./Component.js";
import { Rigidbody } from "./RigidBody.js";
/**
* Collider is the base class for all physics collision shapes.
* Colliders define the physical boundary of objects for collision detection.
*
* 
*
* **Usage with Rigidbody:**
* - Add a collider to define collision shape
* - Add a {@link Rigidbody} to the same or parent object for physics simulation
* - Without Rigidbody, collider acts as static geometry
*
* **Trigger mode:**
* Set `isTrigger = true` for detection without physical collision.
* Triggers fire `onTriggerEnter`, `onTriggerStay`, `onTriggerExit` events.
*
* **Collision filtering:**
* Use `membership` and `filter` arrays to control which objects collide.
*
* @example Add a box collider to an object
* ```ts
* const collider = myObject.addComponent(BoxCollider);
* collider.size = new Vector3(1, 2, 1);
* collider.center = new Vector3(0, 1, 0);
* ```
*
* - Example: https://samples.needle.tools/physics-basic
* - Example: https://samples.needle.tools/physics-playground
*
* @summary Physics collider base class
* @category Physics
* @group Components
* @see {@link BoxCollider} for box-shaped colliders
* @see {@link SphereCollider} for sphere-shaped colliders
* @see {@link CapsuleCollider} for capsule-shaped colliders
* @see {@link MeshCollider} for mesh-based colliders
* @see {@link Rigidbody} for physics simulation
* @link https://engine.needle.tools/samples/?room=needle272&overlay=samples&tag=physics
* @link https://engine.needle.tools/samples-uploads/basic-physics/?showcolliders
*/
export declare abstract class Collider extends Behaviour implements ICollider {
/**
* Identifies this component as a collider.
* @internal
*/
get isCollider(): any;
/**
* The {@link Rigidbody} that this collider is attached to. This handles the physics simulation for this collider.
*/
attachedRigidbody: Rigidbody | 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.
*/
isTrigger: boolean;
/**
* The physics material that defines physical properties of the collider such as friction and bounciness.
*/
sharedMaterial?: PhysicsMaterial;
/**
* The layers that this collider belongs to. Used for filtering collision detection.
* @default [0]
*/
membership: number[];
/**
* The layers that this collider will interact with. Used for filtering collision detection.
*/
filter?: number[];
/** @internal */
awake(): void;
/** @internal */
start(): void;
/** @internal */
onEnable(): void;
/** @internal */
onDisable(): void;
/**
* Returns the underlying physics body from the physics engine.
* Only available if the component is enabled and active in the scene.
*/
get body(): any;
/**
* 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: () => void;
/**
* Updates the physics material in the physics engine.
* Call this after changing the sharedMaterial property.
*/
updatePhysicsMaterial(): void;
}
/**
* SphereCollider represents a sphere-shaped collision volume.
* Efficient and suitable for balls, projectiles, or approximate collision bounds.
*
* 
*
* @example Create a bouncing ball
* ```ts
* const sphere = ball.addComponent(SphereCollider);
* sphere.radius = 0.5;
* const rb = ball.addComponent(Rigidbody);
* rb.mass = 1;
* ```
*
* - Example: https://samples.needle.tools/physics-basic
*
* @summary Sphere-shaped physics collider
* @category Physics
* @group Components
* @see {@link Collider} for base collider functionality
* @see {@link CapsuleCollider} for elongated sphere shapes
*/
export declare class SphereCollider extends Collider implements ISphereCollider {
/**
* The radius of the sphere collider.
*/
radius: number;
/**
* The center position of the sphere collider relative to the transform's position.
*/
center: Vector3;
/**
* Registers the sphere collider with the physics engine and sets up scale change monitoring.
*/
onEnable(): void;
/**
* Removes scale change monitoring when the collider is disabled.
*/
onDisable(): void;
/**
* Updates collider properties when validated in the editor or inspector.
*/
onValidate(): void;
}
/**
* BoxCollider represents a box-shaped (cuboid) collision volume.
* Most common collider type, efficient for walls, floors, crates, and rectangular objects.
*
* 
*
* @example Create a floor collider
* ```ts
* const box = floor.addComponent(BoxCollider);
* box.size = new Vector3(10, 0.1, 10);
* box.center = new Vector3(0, -0.05, 0);
* ```
*
* @example Auto-fit to mesh geometry
* ```ts
* const collider = BoxCollider.add(myMesh, { rigidbody: true });
* // Collider size is automatically set from mesh bounds
* ```
*
* - Example: https://samples.needle.tools/physics-basic
*
* @summary Box-shaped physics collider
* @category Physics
* @group Components
* @see {@link Collider} for base collider functionality
* @see {@link SphereCollider} for sphere shapes
*/
export declare 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;
}): BoxCollider;
/**
* The size of the box collider along each axis.
*/
size: Vector3;
/**
* The center position of the box collider relative to the transform's position.
*/
center: Vector3;
/**
* Registers the box collider with the physics engine and sets up scale change monitoring.
* @internal
*/
onEnable(): void;
/**
* Removes scale change monitoring when the collider is disabled.
* @internal
*/
onDisable(): void;
/**
* Updates collider properties when validated in the editor or inspector.
* @internal
*/
onValidate(): void;
/**
* 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;
}): void;
}
/**
* MeshCollider creates a collision shape from a mesh geometry.
* Allows for complex collision shapes that match the exact geometry of an object.
*
* 
*
* - Example: https://samples.needle.tools/physics-basic
* - Example: https://samples.needle.tools/physics-playground
* - Example: https://samples.needle.tools/physics-&-animation
*
* @category Physics
* @group Components
*/
export declare class MeshCollider extends 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.
*/
sharedMesh?: Mesh;
/**
* 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.
*/
convex: boolean;
/**
* Creates and registers the mesh collider with the physics engine.
* Handles both individual meshes and mesh groups.
*/
onEnable(): void;
}
/**
* CapsuleCollider represents a capsule-shaped collision volume (cylinder with hemispherical ends).
* Ideal for character controllers and objects that need a rounded collision shape.
*
* 
*
* - Example: https://samples.needle.tools/physics-basic
* - Example: https://samples.needle.tools/physics-playground
* - Example: https://samples.needle.tools/physics-&-animation
*
* @category Physics
* @group Components
*/
export declare class CapsuleCollider extends Collider {
/**
* The center position of the capsule collider relative to the transform's position.
*/
center: Vector3;
/**
* The radius of the capsule's cylindrical body and hemispherical ends.
*/
radius: number;
/**
* The total height of the capsule including both hemispherical ends.
*/
height: number;
/**
* Registers the capsule collider with the physics engine.
*/
onEnable(): void;
}