Class Vector3

A point or direction in 3D, such as a position, a velocity or an offset

Math methods change the vector they're called on and return it, so calls chain. Pass an out vector as the last argument to write the result there instead and leave this one as it is. In code that runs every frame, create out vectors once and reuse them: a new Vector3() per frame is garbage the collector has to clean up.

Where a method takes a point, any PointData3D works, such as a node's position or a plain { x, y, z } object.

Example

const toPlayer = new Vector3();

app.ticker.add((ticker) => {
  player.position.subtract(enemy.position, toPlayer).normalize();
  enemy.position.addScaledVector(toPlayer, enemy.speed * (ticker.deltaMS / 1000));
});

Implements

PointLike3D

Index

Constructors

constructor

new Vector3(x?: number, y?: number, z?: number): Vector3
Creates a new Vector3
Parameters
- x: number = 0
  The x component
- y: number = 0
  The y component
- z: number = 0
  The z component
Returns Vector3

Properties

x

x: number = 0

The x component

Example

const groundSpeed = Math.hypot(velocity.x, velocity.z);

y

y: number = 0

The y component

Example

velocity.y -= gravity * dt;

z

z: number = 0

The z component

Example

velocity.z = runSpeed;

Accessors

`Static`shared

get shared(): Vector3
A static Vector3 reset to (0, 0, 0) on every access, for a result used straight away

Important
This vector is shared and temporary. Do not store references to it.

Returns Vector3
Example
```
const inRange = enemy.getGlobalPosition(Vector3.shared).distanceTo(player.position) < attackRange;
```

Methods

add

add(v: PointData3D, out?: PointLike3D): this
Adds v to this vector
Parameters
- v: PointData3D
  The point to add
- out: PointLike3D = ...
  The target to write the result into, defaults to this vector
Returns this
The point the result was written into
Example
```
waypoint.add({ x: 0, y: 2, z: 0 });
barrelBase.add(muzzleOffset, muzzlePosition);
```

addScaledVector

addScaledVector(v: PointData3D, s: number, out?: PointLike3D): this
Adds v * s to this vector, such as a velocity times the frame time
Parameters
- v: PointData3D
  The point to scale and add
- s: number
  The scalar to multiply v by
- out: PointLike3D = ...
  The target to write the result into, defaults to this vector
Returns this
The point the result was written into
Example
```
velocity.addScaledVector(gravity, dt);
rayOrigin.addScaledVector(rayDirection, hitDistance, hitPoint);
```

angleTo

angleTo(v: PointData3D): number
Computes the angle between this vector and v

Returns π/2 when either vector has zero length.
Parameters
- v: PointData3D
  The other vector
Returns number
The angle in radians, from 0 to π
Example
```
const canSeePlayer = forward.angleTo(toPlayer) < visionHalfAngle;
```

applyAffineMatrix4

applyAffineMatrix4(m: Matrix4, out?: PointLike3D): this
Transforms this point by m, translation included, without the divide Vector3#applyMatrix4 does

Cheaper, and correct for any transform that doesn't project, such as a node's world transform.
Parameters
- m: Matrix4
  The matrix to apply
- out: PointLike3D = ...
  The target to write the result into, defaults to this vector
Returns this
The point the result was written into
Example
```
muzzleOffset.applyAffineMatrix4(gun.worldTransform, muzzleWorldPosition);
```

applyMatrix3

applyMatrix3(m: Matrix3, out?: PointLike3D): this
Multiplies this vector by the 3x3 matrix m, such as a normal matrix
Parameters
- m: Matrix3
  The matrix to apply
- out: PointLike3D = ...
  The target to write the result into, defaults to this vector
Returns this
The point the result was written into
Example
```
const normalMatrix = new Matrix3().getNormalMatrix(mesh.worldTransform);

worldNormal.copyFrom(localNormal).applyMatrix3(normalMatrix).normalize();
```

applyMatrix4

applyMatrix4(m: Matrix4, out?: PointLike3D): this
Transforms this point by m, translation included, then divides by the resulting w

The divide is what a projection matrix needs: with a camera's viewProjection, x and y come out from -1 to 1 across the visible area, and z from -1 at the near plane to 1 at the far plane. A point behind the camera can land inside that x and y range too, so check z as well. Use Vector3#applyAffineMatrix4 for transforms that don't project, and Vector3#transformDirection for directions.
Parameters
- m: Matrix4
  The matrix to apply
- out: PointLike3D = ...
  The target to write the result into, defaults to this vector
Returns this
The point the result was written into
Example
```
point.applyMatrix4(camera.viewProjection, ndc);
const onScreen = Math.abs(ndc.x) <= 1 && Math.abs(ndc.y) <= 1 && Math.abs(ndc.z) <= 1;
```

applyQuaternion

applyQuaternion(q: Quaternion, out?: PointLike3D): this
Rotates this vector by the unit Quaternion q
Parameters
- q: Quaternion
  The unit quaternion to rotate by
- out: PointLike3D = ...
  The target to write the result into, defaults to this vector
Returns this
The point the result was written into
Example
```
forward.set(0, 0, 1).applyQuaternion(ship.quaternion);
```

clamp

clamp(min: PointData3D, max: PointData3D, out?: PointLike3D): this
Clamps each component of this vector between the matching components of min and max

Assumes min <= max componentwise.
Parameters
- min: PointData3D
  The lower bound per component
- max: PointData3D
  The upper bound per component
- out: PointLike3D = ...
  The target to write the result into, defaults to this vector
Returns this
The point the result was written into
Example
```
cameraTarget.clamp(levelMin, levelMax);
```

clone

clone(): Vector3
Creates a copy of this vector

Returns Vector3
Example
```
const startVelocity = velocity.clone();
```

copyFrom

copyFrom(p: PointData3D): this
Copies x, y, z from the given point into this vector
Parameters
- p: PointData3D
  The point to copy from
Returns this
Example
```
respawnPoint.copyFrom(player.position);
```
Implementation of PointLike3D.copyFrom

copyTo

copyTo<T extends PointLike3D>(p: T): T
Copies this vector's x, y, z into the given point
Type Parameters
- T extends PointLike3D
Parameters
- p: T
  The point to copy into
Returns T
The given point with values updated
Example
```
respawnPoint.copyTo(player.position);
```
Implementation of PointLike3D.copyTo

cross

cross(v: PointData3D, out?: PointLike3D): this
Computes the cross product this × v, a vector at right angles to both
Parameters
- v: PointData3D
  The other vector
- out: PointLike3D = ...
  The target to write the result into, defaults to this vector
Returns this
The point the result was written into
Example
```
edgeA.cross(edgeB, faceNormal).normalize();
```

distanceTo

distanceTo(v: PointData3D): number
Computes the distance from this point to v
Parameters
- v: PointData3D
  The point to measure to
Returns number
Example
```
const reached = waypoint.distanceTo(player.position) < 0.5;
```

distanceToSquared

distanceToSquared(v: PointData3D): number
Computes the squared distance from this point to v

Cheaper than Vector3#distanceTo and enough to compare distances.
Parameters
- v: PointData3D
  The point to measure to
Returns number
Example
```
if (bulletPosition.distanceToSquared(target.position) < hitRadius * hitRadius) hit(target);
```

divide

divide(v: PointData3D, out?: PointLike3D): this
Divides each component of this vector by the matching component of v
Parameters
- v: PointData3D
  The point to divide by
- out: PointLike3D = ...
  The target to write the result into, defaults to this vector
Returns this
The point the result was written into
Example
```
worldPosition.divide(cellSize, cell);
const column = Math.floor(cell.x);
```

divideScalar

divideScalar(s: number, out?: PointLike3D): this
Divides each component of this vector by the scalar s
Parameters
- s: number
  The scalar to divide by
- out: PointLike3D = ...
  The target to write the result into, defaults to this vector
Returns this
The point the result was written into
Example
```
const center = new Vector3();

for (const point of points) center.add(point);
center.divideScalar(points.length);
```

dot

dot(v: PointData3D): number
Computes the dot product of this vector and v

For unit vectors it's the cosine of the angle between them: 1 when they point the same way, 0 at right angles and -1 when opposite.
Parameters
- v: PointData3D
  The other vector
Returns number
Example
```
const targetIsAhead = forward.dot(toTarget) > 0;
```

equals

equals(p: PointData3D): boolean
Checks whether x, y and z all match p exactly, with no tolerance
Parameters
- p: PointData3D
  The point to compare against
Returns boolean
Example
```
if (!aimPoint.equals(lastAimPoint)) recomputeAim();
```
Implementation of PointLike3D.equals

fromArray

fromArray(
array: Float32Array<ArrayBufferLike> | number[],
offset?: number,
): this
Reads x, y, z from array starting at offset
Parameters
- array: Float32Array<ArrayBufferLike> | number[]
  The array to read from
- offset: number = 0
  The index of the first component
Returns this
Example
```
vertex.fromArray(positions, vertexIndex * 3);
```

magnitude

magnitude(): number
Computes the length of this vector

Returns number
Example
```
const speed = velocity.magnitude();
```

magnitudeSquared

magnitudeSquared(): number
Computes the squared length of this vector

Cheaper than Vector3#magnitude, since it skips the square root, and enough to compare lengths.

Returns number
Example
```
if (velocity.magnitudeSquared() < 0.0001) velocity.set(0);
```

max

max(v: PointData3D, out?: PointLike3D): this
Sets each component to the larger of this vector's and v's
Parameters
- v: PointData3D
  The point to compare with
- out: PointLike3D = ...
  The target to write the result into, defaults to this vector
Returns this
The point the result was written into
Example
```
const boundsMax = new Vector3(-Infinity, -Infinity, -Infinity);

for (const point of points) boundsMax.max(point);
```

min

min(v: PointData3D, out?: PointLike3D): this
Sets each component to the smaller of this vector's and v's
Parameters
- v: PointData3D
  The point to compare with
- out: PointLike3D = ...
  The target to write the result into, defaults to this vector
Returns this
The point the result was written into
Example
```
const boundsMin = new Vector3(Infinity, Infinity, Infinity);

for (const point of points) boundsMin.min(point);
```

multiply

multiply(v: PointData3D, out?: PointLike3D): this
Multiplies each component of this vector by the matching component of v
Parameters
- v: PointData3D
  The point to multiply by
- out: PointLike3D = ...
  The target to write the result into, defaults to this vector
Returns this
The point the result was written into
Example
```
velocity.multiply({ x: 1, y: 0, z: 1 }, groundVelocity);
```

multiplyScalar

multiplyScalar(s: number, out?: PointLike3D): this
Multiplies each component of this vector by the scalar s
Parameters
- s: number
  The scalar to multiply by
- out: PointLike3D = ...
  The target to write the result into, defaults to this vector
Returns this
The point the result was written into
Example
```
velocity.multiplyScalar(friction);
direction.multiplyScalar(speed * dt, step);
```

negate

negate(out?: PointLike3D): this
Negates each component of this vector, reversing its direction
Parameters
- out: PointLike3D = ...
  The target to write the result into, defaults to this vector
Returns this
The point the result was written into
Example
```
toThreat.negate(fleeDirection);
```

normalize

normalize(out?: PointLike3D): this
Scales this vector to unit length, keeping its direction

A zero vector stays zero.
Parameters
- out: PointLike3D = ...
  The target to write the result into, defaults to this vector
Returns this
The point the result was written into
Example
```
input.normalize();
toTarget.normalize(aimDirection);
```

set

set(x?: number, y?: number, z?: number): this
Sets the x, y and z components
Parameters
- x: number = 0
  The x component
- y: number = x
  The y component, defaults to x
- z: number = x
  The z component, defaults to x
Returns this
Example
```
velocity.set(0, jumpSpeed, 0);
size.set(1); // (1, 1, 1)
```
Implementation of PointLike3D.set

setFromCylindrical

setFromCylindrical(c: Cylindrical): this
Sets this point to the position the Cylindrical coordinate c describes

theta is the angle around Y, starting at +Z and turning toward +X, and y is the height above the XZ plane.
Parameters
- c: Cylindrical
  The cylindrical coordinate to convert
Returns this
Example
```
const slot = new Cylindrical(towerRadius, 0, 2);

for (let i = 0; i < torchCount; i++) {
  slot.theta = (i / torchCount) * Math.PI * 2;
  torchPositions[i].setFromCylindrical(slot);
}
```

setFromMatrixColumn

setFromMatrixColumn(m: Matrix4, index: number): this
Reads the first three values of column index of m into this vector

In a transform, column 3 is the translation and columns 0 to 2 are the X, Y and Z axes, scaled.
Parameters
- m: Matrix4
  The matrix to read from
- index: number
  The column index, 0 to 3
Returns this
Example
```
const worldPosition = new Vector3().setFromMatrixColumn(node.worldTransform, 3);
```

setFromSpherical

setFromSpherical(s: Spherical): this
Sets this point to the position the Spherical coordinate s describes

phi is the angle down from the +Y axis and theta the angle around Y, starting at +Z and turning toward +X.
Parameters
- s: Spherical
  The spherical coordinate to convert
Returns this
Example
```
orbit.theta += turnSpeed * dt;
cameraOffset.setFromSpherical(orbit);
```

setLength

setLength(length: number, out?: PointLike3D): this
Scales this vector so its length equals length, keeping its direction

A zero vector stays zero.
Parameters
- length: number
  The target length
- out: PointLike3D = ...
  The target to write the result into, defaults to this vector
Returns this
The point the result was written into
Example
```
if (velocity.magnitude() > maxSpeed) velocity.setLength(maxSpeed);
```

subtract

subtract(v: PointData3D, out?: PointLike3D): this
Subtracts v from this vector
Parameters
- v: PointData3D
  The point to subtract
- out: PointLike3D = ...
  The target to write the result into, defaults to this vector
Returns this
The point the result was written into
Example
```
const toTarget = new Vector3();

targetPosition.subtract(turretPosition, toTarget);
```

toArray

toArray<T extends Float32Array<ArrayBufferLike> | number[] = number[]>(
array?: T,
offset?: number,
): T
Writes this vector's values into array starting at offset

Allocates a new array when one is not supplied.
Type Parameters
- T extends Float32Array<ArrayBufferLike> | number[] = number[]
Parameters
- array: T = ...
  The array to write into
- offset: number = 0
  The index to write the first component at
Returns T
The array the values were written into
Example
```
velocity.toArray(velocities, particleIndex * 3);
```

toString

toString(): string
Returns a readable string representation of this vector

Returns string
Example
```
console.log(velocity.toString());
```

transformDirection

transformDirection(m: Matrix4, out?: PointLike3D): this
Turns this direction by the rotation and scale in m, ignoring its translation, then normalizes it
Parameters
- m: Matrix4
  The matrix whose rotation to apply
- out: PointLike3D = ...
  The target to write the result into, defaults to this vector
Returns this
The point the result was written into
Example
```
const cameraForward = new Vector3(0, 0, -1).transformDirection(camera.worldTransform);
```

Class Vector3

Example

Implements

Index

Constructors

Properties

Accessors

Methods

Constructors

constructor

Parameters

Returns Vector3

Properties

x

Example

y

Example

z

Example

Accessors

Staticshared

Returns Vector3

Example

Methods

add

Parameters

Returns this

Example

addScaledVector

Parameters

Returns this

Example

angleTo

Parameters

Returns number

Example

applyAffineMatrix4

Parameters

Returns this

Example

applyMatrix3

Parameters

Returns this

Example

applyMatrix4

Parameters

Returns this

Example

applyQuaternion

Parameters

Returns this

Example

clamp

Parameters

Returns this

Example

clone

Returns Vector3

Example

copyFrom

Parameters

Returns this

Example

copyTo

Type Parameters

Parameters

Returns T

Example

cross

Parameters

Returns this

Example

distanceTo

Parameters

Returns number

Example

distanceToSquared

Parameters

Returns number

Example

`Static`shared