Class Vec3

A 3-dimensional vector. Vec3 is commonly used to represent 3D positions, directions, Euler angles or scales.

Operations follow one convention throughout the math classes: a method that modifies the vector it is called on returns it, so calls can be chained and nothing is allocated, while queries such as distance and dot return a number. Two-operand forms such as add2, sub2 and cross write the result of lhs op rhs into this, and it is safe for this to also be one of the operands. Use clone for an independent copy and copy to overwrite one vector with another.

The static constants such as ZERO, UP and FORWARD are frozen shared instances: read them freely, but writing to one throws. Vectors returned by engine getters such as GraphNode#getPosition are internal storage and should be treated as read-only; clone them if you need to keep or modify the value.

Example

// Move a point 5 units along a direction without allocating
const position = new Vec3(1, 2, 3);
const direction = new Vec3(0, 0, -1);
position.addScaled(direction, 5);   // position is now [1, 2, -2]

Example

// Chain mutating operations; each returns the vector it was called on
const toTarget = new Vec3().sub2(target, origin).normalize();
const distance = target.distance(origin);

Example

// Keep a copy of an entity's position, then modify it safely
const start = entity.getPosition().clone();
start.y += 1;

Index

Constructors

constructor

Properties

x y z BACK DOWN FORWARD HALF LEFT ONE RIGHT UP ZERO

Constructors

constructor

new Vec3(x?: number, y?: number, z?: number): Vec3
Creates a new Vec3 instance.
Parameters
- Optionalx: number
  The x value. Defaults to 0.
- Optionaly: number
  The y value. Defaults to 0.
- Optionalz: number
  The z value. Defaults to 0.
Returns Vec3
Example
```
const v1 = new Vec3(); // defaults to 0, 0, 0
const v2 = new Vec3(1, 2, 3);
```
- Defined in core/math/vec3.js:59
new Vec3(arr: number[]): Vec3
Creates a new Vec3 instance.
Parameters
- arr: number[]
  The array to set the vector values from.
Returns Vec3
Example
```
const v = new Vec3([1, 2, 3]);
```
- Defined in core/math/vec3.js:59

Properties

x

x: number

The first component of the vector.

y

y: number

The second component of the vector.

z

z: number

The third component of the vector.

`Static` `Readonly`BACK

BACK: Vec3 = ...

A constant vector set to [0, 0, 1].

`Static` `Readonly`DOWN

DOWN: Vec3 = ...

A constant vector set to [0, -1, 0].

`Static` `Readonly`FORWARD

FORWARD: Vec3 = ...

A constant vector set to [0, 0, -1].

`Static` `Readonly`HALF

HALF: Vec3 = ...

A constant vector set to [0.5, 0.5, 0.5].

`Static` `Readonly`LEFT

LEFT: Vec3 = ...

A constant vector set to [-1, 0, 0].

`Static` `Readonly`ONE

ONE: Vec3 = ...

A constant vector set to [1, 1, 1].

`Static` `Readonly`RIGHT

RIGHT: Vec3 = ...

A constant vector set to [1, 0, 0].

`Static` `Readonly`UP

UP: Vec3 = ...

A constant vector set to [0, 1, 0].

`Static` `Readonly`ZERO

ZERO: Vec3 = ...

A constant vector set to [0, 0, 0].

Methods

add

add(rhs: Vec3): Vec3
Adds a 3-dimensional vector to another in place.
Parameters
- rhs: Vec3
  The vector to add to the specified vector.
Returns Vec3
Self for chaining.
Example
```
const a = new Vec3(10, 10, 10);
const b = new Vec3(20, 20, 20);

a.add(b);

// Outputs [30, 30, 30]
console.log("The result of the addition is: " + a.toString());
```
- Defined in core/math/vec3.js:107

add2

add2(lhs: Vec3, rhs: Vec3): Vec3
Adds two 3-dimensional vectors together and returns the result.
Parameters
- lhs: Vec3
  The first vector operand for the addition.
- rhs: Vec3
  The second vector operand for the addition.
Returns Vec3
Self for chaining.
Example
```
const a = new Vec3(10, 10, 10);
const b = new Vec3(20, 20, 20);
const r = new Vec3();

r.add2(a, b);
// Outputs [30, 30, 30]

console.log("The result of the addition is: " + r.toString());
```
- Defined in core/math/vec3.js:131

addScalar

addScalar(scalar: number): Vec3
Adds a number to each element of a vector.
Parameters
- scalar: number
  The number to add.
Returns Vec3
Self for chaining.
Example
```
const vec = new Vec3(3, 4, 5);

vec.addScalar(2);

// Outputs [5, 6, 7]
console.log("The result of the addition is: " + vec.toString());
```
- Defined in core/math/vec3.js:152

addScaled

addScaled(rhs: Vec3, scalar: number): Vec3
Adds a 3-dimensional vector scaled by scalar value. Does not modify the vector being added.
Parameters
- rhs: Vec3
  The vector to add to the specified vector.
- scalar: number
  The number to multiply the added vector with.
Returns Vec3
Self for chaining.
Example
```
const vec = new Vec3(1, 2, 3);

vec.addScaled(Vec3.UP, 2);

// Outputs [1, 4, 3]
console.log("The result of the addition is: " + vec.toString());
```
- Defined in core/math/vec3.js:174

ceil

ceil(src?: Vec3): Vec3
Each element is rounded up to the next largest integer.
Parameters
- Optionalsrc: Vec3 = ...
  The vector to ceil. If not set, the operation is done in place.
Returns Vec3
Self for chaining.
Example
```
const v = new Vec3(1.2, 3.1, 5.9);
v.ceil();
// v is now [2, 4, 6]
```
- Defined in core/math/vec3.js:583

clone

clone(): Vec3
Returns an identical copy of the specified 3-dimensional vector.

Returns Vec3
A 3-dimensional vector containing the result of the cloning.
Example
```
const v = new Vec3(10, 20, 30);
const vclone = v.clone();
console.log("The result of the cloning is: " + vclone.toString());
```
- Defined in core/math/vec3.js:191

copy

copy(rhs: Vec3): Vec3
Copies the contents of a source 3-dimensional vector to a destination 3-dimensional vector.
Parameters
- rhs: Vec3
  A vector to copy to the specified vector.
Returns Vec3
Self for chaining.
Example
```
const src = new Vec3(10, 20, 30);
const dst = new Vec3();

dst.copy(src);

console.log("The two vectors are " + (dst.equals(src) ? "equal" : "different"));
```
- Defined in core/math/vec3.js:210

cross

cross(lhs: Vec3, rhs: Vec3): Vec3
Returns the result of a cross product operation performed on the two specified 3-dimensional vectors.
Parameters
- lhs: Vec3
  The first 3-dimensional vector operand of the cross product.
- rhs: Vec3
  The second 3-dimensional vector operand of the cross product.
Returns Vec3
Self for chaining.
Example
```
const back = new Vec3().cross(Vec3.RIGHT, Vec3.UP);

// Prints the Z axis (i.e. [0, 0, 1])
console.log("The result of the cross product is: " + back.toString());
```
- Defined in core/math/vec3.js:231

distance

distance(rhs: Vec3): number
Returns the distance between the two specified 3-dimensional vectors.
Parameters
- rhs: Vec3
  The second 3-dimensional vector to test.
Returns number
The distance between the two vectors.
Example
```
const v1 = new Vec3(5, 10, 20);
const v2 = new Vec3(10, 20, 40);
const d = v1.distance(v2);
console.log("The distance between v1 and v2 is: " + d);
```
- Defined in core/math/vec3.js:258

distanceSq

distanceSq(rhs: Vec3): number
Returns the squared distance between the two specified 3-dimensional vectors.
Parameters
- rhs: Vec3
  The second 3-dimensional vector to test.
Returns number
The squared distance between the two vectors.
Example
```
const v1 = new Vec3(5, 10, 20);
const v2 = new Vec3(10, 20, 40);
const d = v1.distanceSq(v2);
console.log("The squared distance between v1 and v2 is: " + d);
```
- Defined in core/math/vec3.js:276

div

div(rhs: Vec3): Vec3
Divides a 3-dimensional vector by another in place.
Parameters
- rhs: Vec3
  The vector to divide the specified vector by.
Returns Vec3
Self for chaining.
Example
```
const a = new Vec3(4, 9, 16);
const b = new Vec3(2, 3, 4);

a.div(b);

// Outputs [2, 3, 4]
console.log("The result of the division is: " + a.toString());
```
- Defined in core/math/vec3.js:297

div2

div2(lhs: Vec3, rhs: Vec3): Vec3
Divides one 3-dimensional vector by another and writes the result to the specified vector.
Parameters
- lhs: Vec3
  The dividend vector (the vector being divided).
- rhs: Vec3
  The divisor vector (the vector dividing the dividend).
Returns Vec3
Self for chaining.
Example
```
const a = new Vec3(4, 9, 16);
const b = new Vec3(2, 3, 4);
const r = new Vec3();

r.div2(a, b);

// Outputs [2, 3, 4]
console.log("The result of the division is: " + r.toString());
```
- Defined in core/math/vec3.js:321

divScalar

divScalar(scalar: number): Vec3
Divides each element of a vector by a number.
Parameters
- scalar: number
  The number to divide by.
Returns Vec3
Self for chaining.
Example
```
const vec = new Vec3(3, 6, 9);

vec.divScalar(3);

// Outputs [1, 2, 3]
console.log("The result of the division is: " + vec.toString());
```
- Defined in core/math/vec3.js:342

dot

dot(rhs: Vec3): number
Returns the result of a dot product operation performed on the two specified 3-dimensional vectors.
Parameters
- rhs: Vec3
  The second 3-dimensional vector operand of the dot product.
Returns number
The result of the dot product operation.
Example
```
const v1 = new Vec3(5, 10, 20);
const v2 = new Vec3(10, 20, 40);
const v1dotv2 = v1.dot(v2);
console.log("The result of the dot product is: " + v1dotv2);
```
- Defined in core/math/vec3.js:362

equals

equals(rhs: Vec3): boolean
Reports whether two vectors are equal.
Parameters
- rhs: Vec3
  The vector to compare to the specified vector.
Returns boolean
True if the vectors are equal and false otherwise.
Example
```
const a = new Vec3(1, 2, 3);
const b = new Vec3(4, 5, 6);
console.log("The two vectors are " + (a.equals(b) ? "equal" : "different"));
```
- Defined in core/math/vec3.js:376

equalsApprox

equalsApprox(rhs: Vec3, epsilon?: number): boolean
Reports whether two vectors are equal using an absolute error tolerance.
Parameters
- rhs: Vec3
  The vector to be compared against.
- Optionalepsilon: number = 1e-6
  The maximum difference between each component of the two vectors. Defaults to 1e-6.
Returns boolean
True if the vectors are equal and false otherwise.
Example
```
const a = new Vec3();
const b = new Vec3();
console.log("The two vectors are approximately " + (a.equalsApprox(b, 1e-9) ? "equal" : "different"));
```
- Defined in core/math/vec3.js:392

floor

floor(src?: Vec3): Vec3
Each element is set to the largest integer less than or equal to its value.
Parameters
- Optionalsrc: Vec3 = ...
  The vector to floor. If not set, the operation is done in place.
Returns Vec3
Self for chaining.
Example
```
const v = new Vec3(1.2, 3.9, 5.5);
v.floor();
// v is now [1, 3, 5]
```
- Defined in core/math/vec3.js:566

fromArray

fromArray(
arr: number[] | ArrayBufferView<ArrayBufferLike>,
offset?: number,
): Vec3
Set the values of the vector from an array.
Parameters
- arr: number[] | ArrayBufferView<ArrayBufferLike>
  The array to set the vector values from.
- Optionaloffset: number = 0
  The zero-based index at which to start copying elements from the array. Default is 0.
Returns Vec3
Self for chaining.
Example
```
const v = new Vec3();
v.fromArray([20, 10, 5]);
// v is set to [20, 10, 5]
```
- Defined in core/math/vec3.js:768

length

length(): number
Returns the magnitude of the specified 3-dimensional vector.

Returns number
The magnitude of the specified 3-dimensional vector.
Example
```
const vec = new Vec3(3, 4, 0);
const len = vec.length();
// Outputs 5
console.log("The length of the vector is: " + len);
```
- Defined in core/math/vec3.js:408

lengthSq

lengthSq(): number
Returns the magnitude squared of the specified 3-dimensional vector.

Returns number
The magnitude squared of the specified 3-dimensional vector.
Example
```
const vec = new Vec3(3, 4, 0);
const len = vec.lengthSq();
// Outputs 25
console.log("The length squared of the vector is: " + len);
```
- Defined in core/math/vec3.js:422

lerp

lerp(lhs: Vec3, rhs: Vec3, alpha: number): Vec3
Returns the result of a linear interpolation between two specified 3-dimensional vectors.
Parameters
- lhs: Vec3
  The 3-dimensional vector to interpolate from.
- rhs: Vec3
  The 3-dimensional vector to interpolate to.
- alpha: number
  The value controlling the point of interpolation. Between 0 and 1, the linear interpolant will occur on a straight line between lhs and rhs. Outside of this range, the linear interpolant will occur on a ray extrapolated from this line.
Returns Vec3
Self for chaining.
Example
```
const a = new Vec3(0, 0, 0);
const b = new Vec3(10, 10, 10);
const r = new Vec3();

r.lerp(a, b, 0);   // r is equal to a
r.lerp(a, b, 0.5); // r is 5, 5, 5
r.lerp(a, b, 1);   // r is equal to b
```
- Defined in core/math/vec3.js:444

max

max(rhs: Vec3): Vec3
Each element is assigned a value from rhs parameter if it is larger.
Parameters
- rhs: Vec3
  The 3-dimensional vector used as the source of elements to compare to.
Returns Vec3
Self for chaining.
Example
```
const a = new Vec3(5, 1, 7);
const b = new Vec3(2, 8, 3);
a.max(b);
// a is now [5, 8, 7]
```
- Defined in core/math/vec3.js:636

min

min(rhs: Vec3): Vec3
Each element is assigned a value from rhs parameter if it is smaller.
Parameters
- rhs: Vec3
  The 3-dimensional vector used as the source of elements to compare to.
Returns Vec3
Self for chaining.
Example
```
const a = new Vec3(5, 1, 7);
const b = new Vec3(2, 8, 3);
a.min(b);
// a is now [2, 1, 3]
```
- Defined in core/math/vec3.js:618

mul

mul(rhs: Vec3): Vec3
Multiplies a 3-dimensional vector to another in place.
Parameters
- rhs: Vec3
  The 3-dimensional vector used as the second multiplicand of the operation.
Returns Vec3
Self for chaining.
Example
```
const a = new Vec3(2, 3, 4);
const b = new Vec3(4, 5, 6);

a.mul(b);

// Outputs [8, 15, 24]
console.log("The result of the multiplication is: " + a.toString());
```
- Defined in core/math/vec3.js:466

mul2

mul2(lhs: Vec3, rhs: Vec3): Vec3
Returns the result of multiplying the specified 3-dimensional vectors together.
Parameters
- lhs: Vec3
  The 3-dimensional vector used as the first multiplicand of the operation.
- rhs: Vec3
  The 3-dimensional vector used as the second multiplicand of the operation.
Returns Vec3
Self for chaining.
Example
```
const a = new Vec3(2, 3, 4);
const b = new Vec3(4, 5, 6);
const r = new Vec3();

r.mul2(a, b);

// Outputs [8, 15, 24]
console.log("The result of the multiplication is: " + r.toString());
```
- Defined in core/math/vec3.js:490

mulScalar

mulScalar(scalar: number): Vec3
Multiplies each element of a vector by a number.
Parameters
- scalar: number
  The number to multiply by.
Returns Vec3
Self for chaining.
Example
```
const vec = new Vec3(3, 6, 9);

vec.mulScalar(3);

// Outputs [9, 18, 27]
console.log("The result of the multiplication is: " + vec.toString());
```
- Defined in core/math/vec3.js:511

normalize

normalize(src?: Vec3): Vec3
Returns this 3-dimensional vector converted to a unit vector in place. If the vector has a length of zero, the vector's elements will be set to zero.
Parameters
- Optionalsrc: Vec3 = ...
  The vector to normalize. If not set, the operation is done in place.
Returns Vec3
Self for chaining.
Example
```
const v = new Vec3(25, 0, 0);

v.normalize();

// Outputs [1, 0, 0]
console.log("The result of the vector normalization is: " + v.toString());
```
- Defined in core/math/vec3.js:544

project

project(rhs: Vec3): Vec3
Projects this 3-dimensional vector onto the specified vector.
Parameters
- rhs: Vec3
  The vector onto which the original vector will be projected on.
Returns Vec3
Self for chaining.
Example
```
const v = new Vec3(5, 5, 5);
const normal = new Vec3(1, 0, 0);

v.project(normal);

// Outputs [5, 0, 0]
console.log("The result of the vector projection is: " + v.toString());
```
- Defined in core/math/vec3.js:657

round

round(src?: Vec3): Vec3
Each element is rounded up or down to the nearest integer.
Parameters
- Optionalsrc: Vec3 = ...
  The vector to round. If not set, the operation is done in place.
Returns Vec3
Self for chaining.
Example
```
const v = new Vec3(1.4, 3.6, 5.5);
v.round();
// v is now [1, 4, 6]
```
- Defined in core/math/vec3.js:600

set

set(x: number, y: number, z: number): Vec3
Sets the specified 3-dimensional vector to the supplied numerical values.
Parameters
- x: number
  The value to set on the first component of the vector.
- y: number
  The value to set on the second component of the vector.
- z: number
  The value to set on the third component of the vector.
Returns Vec3
Self for chaining.
Example
```
const v = new Vec3();
v.set(5, 10, 20);

// Outputs [5, 10, 20]
console.log("The result of the vector set is: " + v.toString());
```
- Defined in core/math/vec3.js:681

sub

sub(rhs: Vec3): Vec3
Subtracts a 3-dimensional vector from another in place.
Parameters
- rhs: Vec3
  The vector to subtract from the specified vector.
Returns Vec3
Self for chaining.
Example
```
const a = new Vec3(10, 10, 10);
const b = new Vec3(20, 20, 20);

a.sub(b);

// Outputs [-10, -10, -10]
console.log("The result of the subtraction is: " + a.toString());
```
- Defined in core/math/vec3.js:703

sub2

sub2(lhs: Vec3, rhs: Vec3): Vec3
Subtracts two 3-dimensional vectors from one another and returns the result.
Parameters
- lhs: Vec3
  The first vector operand for the subtraction.
- rhs: Vec3
  The second vector operand for the subtraction.
Returns Vec3
Self for chaining.
Example
```
const a = new Vec3(10, 10, 10);
const b = new Vec3(20, 20, 20);
const r = new Vec3();

r.sub2(a, b);

// Outputs [-10, -10, -10]
console.log("The result of the subtraction is: " + r.toString());
```
- Defined in core/math/vec3.js:727

subScalar

subScalar(scalar: number): Vec3
Subtracts a number from each element of a vector.
Parameters
- scalar: number
  The number to subtract.
Returns Vec3
Self for chaining.
Example
```
const vec = new Vec3(3, 4, 5);

vec.subScalar(2);

// Outputs [1, 2, 3]
console.log("The result of the subtraction is: " + vec.toString());
```
- Defined in core/math/vec3.js:748

toArray

toArray(arr?: number[], offset?: number): number[]
Parameters
- Optionalarr: number[]
  The array to populate with the vector's number components. If not specified, a new array is created.
- Optionaloffset: number
  The zero-based index at which to start copying elements to the array. Default is 0.
Returns number[]
The vector as an array.
- Defined in core/math/vec3.js:790
toArray(arr: ArrayBufferView, offset?: number): ArrayBufferView
Parameters
- arr: ArrayBufferView
  The array to populate with the vector's number components. If not specified, a new array is created.
- Optionaloffset: number
  The zero-based index at which to start copying elements to the array. Default is 0.
Returns ArrayBufferView
The vector as an array.
- Defined in core/math/vec3.js:798

toString

toString(): string
Converts the vector to string form.

Returns string
The vector in string form.
Example
```
const v = new Vec3(20, 10, 5);
// Outputs [20, 10, 5]
console.log(v.toString());
```
- Defined in core/math/vec3.js:785

Class Vec3

Example

Example

Example

Index

Constructors

Properties

Methods

Constructors

constructor

Parameters

Returns Vec3

Example

Parameters

Returns Vec3

Example

Properties

x

y

z

Static ReadonlyBACK

Static ReadonlyDOWN

Static ReadonlyFORWARD

Static ReadonlyHALF

Static ReadonlyLEFT

Static ReadonlyONE

Static ReadonlyRIGHT

Static ReadonlyUP

Static ReadonlyZERO

Methods

add

Parameters

Returns Vec3

Example

add2

Parameters

Returns Vec3

Example

addScalar

Parameters

Returns Vec3

Example

addScaled

Parameters

Returns Vec3

Example

ceil

Parameters

Returns Vec3

Example

clone

Returns Vec3

Example

copy

Parameters

Returns Vec3

Example

cross

Parameters

Returns Vec3

Example

distance

Parameters

Returns number

Example

distanceSq

Parameters

Returns number

Example

div

Parameters

Returns Vec3

Example

div2

Parameters

Returns Vec3

Example

divScalar

Parameters

Returns Vec3

`Static` `Readonly`BACK

`Static` `Readonly`DOWN

`Static` `Readonly`FORWARD

`Static` `Readonly`HALF

`Static` `Readonly`LEFT

`Static` `Readonly`ONE

`Static` `Readonly`RIGHT

`Static` `Readonly`UP

`Static` `Readonly`ZERO