Class Physics

Provides physics utilities including raycasting and overlap detection.
Access via this.context.physics from any component.

For physics engine features (rigidbodies, colliders, forces, etc.), use this.context.physics.engine.
The physics engine is RapierPhysics, which uses the Rapier physics library for realistic simulation.

Performance - Automatic MeshBVH: Needle Engine automatically uses three-mesh-bvh to accelerate raycasting.
MeshBVH structures are generated automatically on web workers in the background, making raycasts significantly faster
without blocking the main thread. This happens transparently - you don't need to do anything to enable it.
While the BVH is being generated, raycasts fall back to standard three.js raycasting (configurable via allowSlowRaycastFallback).

Example: Raycasting from mouse position

const hits = this.context.physics.raycast();
if (hits.length > 0) {
  console.log("Hit:", hits[0].object.name);
}

Example: Raycasting with inline options

const hits = this.context.physics.raycast({
  maxDistance: 100, // Only hit objects within 100 units
  layerMask: 1, // Only layer 0
  ignore: [this.gameObject] // Ignore self
});

Example: Physics engine raycast (against colliders only)

const hit = this.context.physics.engine?.raycast(origin, direction);

See

Constructors

constructor

Accessors

raycasting

Methods

raycast raycastFromRay raycastPhysicsFast raycastPhysicsFastAndGetNormal sphereOverlap sphereOverlapPhysics

Constructors

constructor

Accessors

Staticraycasting

  • get raycasting(): boolean

    Returns true if raycasting is currently in progress

    Returns boolean

Methods

raycast

  • raycast(
        options?: null | IRaycastOptions,
    ): Intersection<Object3D<Object3DEventMap>>[]

    raycast against rendered three objects. This might be very slow depending on your scene complexity. We recommend setting objects to IgnoreRaycast layer (2) when you don't need them to be raycasted. Raycasting SkinnedMeshes is specially expensive. Use raycastPhysics for raycasting against physic colliders only. Depending on your scenario this might be faster.

    Parameters

    • options: null | IRaycastOptions = null

      raycast options. If null, default options will be used.

    Returns Intersection<Object3D<Object3DEventMap>>[]

raycastFromRay

raycastPhysicsFast

  • raycastPhysicsFast(
        origin: Vec3 | Vec2,
        direction?: undefined | Vec3,
        maxDistance?: number,
        solid?: boolean,
    ): null | { collider: ICollider; normal?: Vector3; point: Vector3 }

    Parameters

    • origin: Vec3 | Vec2
    • direction: undefined | Vec3 = undefined
    • maxDistance: number = Infinity
    • solid: boolean = true

    Returns null | { collider: ICollider; normal?: Vector3; point: Vector3 }

    Deprecated

    use this.context.physics.engine.raycast IPhysicsEngine.raycast

raycastPhysicsFastAndGetNormal

  • raycastPhysicsFastAndGetNormal(
        origin: Vec3 | Vec2,
        direction?: undefined | Vec3,
        maxDistance?: number,
        solid?: boolean,
    ): null | { collider: ICollider; normal?: Vector3; point: Vector3 }

    Parameters

    • origin: Vec3 | Vec2
    • direction: undefined | Vec3 = undefined
    • maxDistance: number = Infinity
    • solid: boolean = true

    Returns null | { collider: ICollider; normal?: Vector3; point: Vector3 }

    Deprecated

    use this.context.physics.engine.raycastAndGetNormal IPhysicsEngine.raycastAndGetNormal

sphereOverlap

  • sphereOverlap(
        spherePos: Vector3,
        radius: number,
        traverseChildsAfterHit?: boolean,
        bvh?: boolean,
        shouldRaycast?: null | RaycastTestObjectCallback,
    ): Intersection<Object3D<Object3DEventMap>>[]

    Test overlapping of a sphere with the threejs geometry. This does not use colliders. This does not return an exact intersection point (intersections returned contain the object and the world position of the object that is being hit) For a more accurate test use the physics engine's collider overlap test (see sphereOverlapPhysics)

    Parameters

    • spherePos: Vector3

      the center of the sphere in world space

    • radius: number

      the radius of the sphere

    • traverseChildsAfterHit: boolean = true

      if false it will stop after the first hit. If true it will continue to traverse and add all hits to the result array

    • bvh: boolean = false

      use MeshBVH for raycasting. This is faster than the default threejs raycaster but uses more memory.

    • shouldRaycast: null | RaycastTestObjectCallback = null

      optional callback to filter objects. Return false to ignore the object completely or "continue in children" to skip the object but continue to traverse its children (if you do raycast with recursive enabled)

    Returns Intersection<Object3D<Object3DEventMap>>[]

sphereOverlapPhysics

Settings

Member Visibility

On This Page

Constructors
Accessors
Methods