Class Ray

A half-line that starts at origin and runs along direction, for picking and line-of-sight tests

View3D#screenToRay builds one through a pointer position, in world space. Test a ray against shapes in its own space; Ray#applyMatrix4 moves it into a mesh's local space. Keep direction unit length, and call direction.normalize() after changing it by hand; the distance, closest-point and sphere methods give wrong results otherwise.

Example

const hit = new Vector3();

view3d.on('pointertap', (e) => {
  const ray = view3d.screenToRay(e.global);

  if (ray.intersectPlane(ground, hit)) unit.moveTo(hit);
});

Index

Constructors

constructor

new Ray(origin?: Vector3, direction?: Vector3): Ray
Creates a new Ray

Left out, the ray starts at the origin and points down -Z. Vectors passed in become the ray's own; they are not copied.
Parameters
- Optionalorigin: Vector3
  The origin of the ray
- Optionaldirection: Vector3
  The unit-length direction of the ray
Returns Ray

Properties

`Readonly`direction

direction: Vector3

The unit-length direction the ray runs in

Example

sightLine.direction.copyFrom(target.position).subtract(sightLine.origin).normalize();

`Readonly`origin

origin: Vector3

The point the ray starts from

Example

muzzle.getGlobalPosition(shotRay.origin);

`Readonly`type

type: SHAPE_PRIMITIVE_3D = 'ray'

Names the shape without an instanceof check, like the type on pixi's 2D shapes

Default

'ray'

Methods

applyMatrix4

applyMatrix4(matrix: Matrix4, out?: Ray): this
Transforms this ray by an affine matrix

The direction comes out unit length, so a t measured along the new ray is in the new space's units: under scale, compare hits as points, not as t values.

matrix must be affine (bottom row [0, 0, 0, 1]), as a Container3D#worldTransform always is and a projection matrix isn't.
Parameters
- matrix: Matrix4
  The affine matrix to transform by
- out: Ray = ...
  Target to write the result into instead of mutating this ray
Returns this
The result ray for chaining
Example
```
const worldToLocal = new Matrix4().getInverse(mesh.worldTransform);
const localRay = pointerRay.applyMatrix4(worldToLocal, new Ray());
const overMesh = localRay.intersectsBox(mesh.geometry.bounds3D);
```

at

at(t: number, out?: Vector3): Vector3
Writes the point origin + direction * t into out

With a unit-length direction, t is the distance from origin.
Parameters
- t: number
  The distance along the ray
- Optionalout: Vector3
  Optional vector to write into; a new Vector3 when omitted
Returns Vector3
The point along the ray
Example
```
const reticle = new Vector3();

aimRay.at(20, reticle);
```

clone

clone(): Ray
Creates a new Ray with the same origin and direction

Returns Ray
The new ray
Example
```
const reflected = incoming.clone();
```

closestPointToPoint

closestPointToPoint(point: PointData3D, out?: Vector3): Vector3
Writes the closest point on this ray to point into out

Points behind origin give origin. Requires a unit-length direction.
Parameters
- point: PointData3D
  The point to measure from
- Optionalout: Vector3
  Optional vector to write into; a new Vector3 when omitted
Returns Vector3
The closest point on this ray
Example
```
const nearest = new Vector3();

aimRay.closestPointToPoint(enemy.position, nearest);
```

copyFrom

copyFrom(ray: Ray): this
Copies ray into this ray
Parameters
- ray: Ray
  The ray to copy from
Returns this
This ray for chaining
Example
```
lastPointerRay.copyFrom(pointerRay);
```

copyTo

copyTo<T extends Ray>(target: T): T
Copies this ray into target and returns it
Type Parameters
- T extends Ray
Parameters
- target: T
  The ray to copy into
Returns T
The given target
Example
```
pointerRay.copyTo(lastPointerRay);
```

distanceSqToPoint

distanceSqToPoint(point: PointData3D): number
Returns the squared Euclidean distance from point to the closest point on this ray

Cheaper than Ray#distanceToPoint; compare it against a squared radius. Requires a unit-length direction.
Parameters
- point: PointData3D
  The point to measure from
Returns number
The squared distance to the closest point on this ray
Example
```
const locked = enemies.find((enemy: Container3D) => aimRay.distanceSqToPoint(enemy.position) < 0.25);
```

distanceToPoint

distanceToPoint(point: PointData3D): number
Returns the Euclidean distance from point to the closest point on this ray

Requires a unit-length direction.
Parameters
- point: PointData3D
  The point to measure from
Returns number
The distance to the closest point on this ray
Example
```
const nearMiss = aimRay.distanceToPoint(target.position) < 0.5;
```

equals

equals(ray: Ray): boolean
Returns true when origin and direction match ray exactly (no epsilon tolerance)
Parameters
- ray: Ray
  The ray to compare with
Returns boolean
Whether the origin and direction match
Example
```
if (!pointerRay.equals(lastPointerRay)) updateHover(pointerRay);
```

intersectBox

intersectBox(box: Box, out?: Vector3): Vector3 | null
Intersects this ray with box

Works with a direction of any length.
Parameters
- box: Box
  The box to intersect
- Optionalout: Vector3
  Optional vector to write into; a new Vector3 when omitted
Returns Vector3 | null
The entry point (or the exit point from inside), or null when the ray misses
Example
```
const hit = new Vector3();

if (localRay.intersectBox(mesh.geometry.bounds3D, hit)) decal.position.copyFrom(hit);
```
See
Ray#intersectBoxT For the distance to the same hit, without the point.

intersectBoxT

intersectBoxT(box: Box): number
Intersects this ray with box and returns the distance to the hit rather than the point

Same hit as Ray#intersectBox; Ray#at turns t into the point. With a unit-length direction, t is the distance from origin. A ray that runs along one of the box's faces still gets the right entry or exit distance.
Parameters
- box: Box
  The box to intersect
Returns number
The distance t to the entry point, or to the exit point when the origin is inside the box, or -1 when the ray misses
Example
```
const t = sightLine.intersectBoxT(wallBounds);
const blocked = t !== -1 && t < distanceToTarget;
```

intersectPlane

intersectPlane(plane: Plane, out?: Vector3): Vector3 | null
Intersects this ray with plane

A ray that lies in the plane hits at its origin. Works with a direction of any length.
Parameters
- plane: Plane
  The plane to intersect
- Optionalout: Vector3
  Optional vector to write into; a new Vector3 when omitted
Returns Vector3 | null
The hit point, or null when the ray points away from the plane or runs parallel to it
Example
```
const ground = new Plane(new Vector3(0, 1, 0), 0);
const target = new Vector3();

if (pointerRay.intersectPlane(ground, target)) cursor.position.copyFrom(target);
```

intersectsBox

intersectsBox(box: Box): boolean
Returns true when this ray hits box
Parameters
- box: Box
  The box to test
Returns boolean
Whether the ray hits the box
Example
```
const hovered = pointerRay.intersectsBox(buttonBounds);
```

intersectSphere

intersectSphere(sphere: Sphere, out?: Vector3): Vector3 | null
Intersects this ray with sphere

An empty sphere is never hit. Requires a unit-length direction.
Parameters
- sphere: Sphere
  The sphere to intersect
- Optionalout: Vector3
  Optional vector to write into; a new Vector3 when omitted
Returns Vector3 | null
The entry point (or the exit point from inside), or null when the ray misses
Example
```
const hit = new Vector3();

if (ray.intersectSphere(planet.boundingSphere, hit)) flag.position.copyFrom(hit);
```
See
Ray#intersectSphereT For the distance to the same hit, without the point.

intersectSphereT

intersectSphereT(sphere: Sphere): number
Intersects this ray with sphere and returns the distance to the hit rather than the point

Same hit as Ray#intersectSphere; Ray#at turns the distance into the point. Compare distances to find the nearest of several hits without making a point for each. Requires a unit-length direction.
Parameters
- sphere: Sphere
  The sphere to intersect
Returns number
The distance t to the hit (>= 0), or -1 when the ray misses
Example
```
let nearest: Mesh3D | null = null;
let nearestT = Infinity;

for (const target of targets) {
  const t = ray.intersectSphereT(target.boundingSphere);

  if (t !== -1 && t < nearestT) {
    nearestT = t;
    nearest = target;
  }
}
```

intersectsPlane

intersectsPlane(plane: Plane): boolean
Returns true when this ray hits plane, including when its origin lies on the plane
Parameters
- plane: Plane
  The plane to test
Returns boolean
Whether the ray hits the plane
Example
```
const canLand = dropRay.intersectsPlane(ground);
```

intersectsSphere

intersectsSphere(sphere: Sphere): boolean
Returns true when this ray hits sphere

Requires a unit-length direction. An empty sphere is never hit.
Parameters
- sphere: Sphere
  The sphere to test
Returns boolean
Whether the ray hits the sphere
Example
```
const hovered = enemies.filter((enemy: Mesh3D) => pointerRay.intersectsSphere(enemy.boundingSphere));
```

set

set(origin: PointData3D, direction: PointData3D): this
Sets the origin and direction of this ray, copying their values
Parameters
- origin: PointData3D
  The origin of the ray
- direction: PointData3D
  The unit-length direction of the ray
Returns this
This ray for chaining
Example
```
camera.worldTransform.extractForward(forward);
aimRay.set(camera.getGlobalPosition(eye), forward);
```

toString

toString(): string

Advanced
Returns a string representation of this ray

Returns string
A string in the form [@pixi/3d/math:Ray origin=(0, 0, 0) direction=(0, 0, -1)]

Class Ray

Example

Index

Constructors

Properties

Methods

Constructors

constructor

Parameters

Returns Ray

Properties

Readonlydirection

Example

Readonlyorigin

Example

Readonlytype

Default

Methods

applyMatrix4

Parameters

Returns this

Example

at

Parameters

Returns Vector3

Example

clone

Returns Ray

Example

closestPointToPoint

Parameters

Returns Vector3

Example

copyFrom

Parameters

Returns this

Example

copyTo

Type Parameters

Parameters

Returns T

Example

distanceSqToPoint

Parameters

Returns number

Example

distanceToPoint

Parameters

Returns number

Example

equals

Parameters

Returns boolean

Example

intersectBox

Parameters

Returns Vector3 | null

Example

See

intersectBoxT

Parameters

Returns number

Example

intersectPlane

Parameters

Returns Vector3 | null

Example

intersectsBox

Parameters

Returns boolean

Example

intersectSphere

Parameters

Returns Vector3 | null

Example

See

intersectSphereT

Parameters

Returns number

Example

`Readonly`direction

`Readonly`origin

`Readonly`type