Class ObservableVector3

A Vector3 that tells an observer when it changes

A node's position, scale, rotation and origin use this class, so a change to one updates the node. It has the same methods as Vector3. Each in-place method notifies the observer at most once, and not at all when no component changed. Given an out target, a method writes there and leaves this point and its observer alone.

Example

app.ticker.add((ticker) => {
  player.position.addScaledVector(velocity, ticker.deltaMS / 1000);
});

Implements

PointLike3D

Constructors

constructor

new ObservableVector3(
    observer: Observer<ObservableVector3>,
    x?: number,
    y?: number,
    z?: number,
): ObservableVector3
Creates a new ObservableVector3
Parameters
- observer: Observer<ObservableVector3>
  Observer notified when any component changes
- x: number = 0
  The x component
- y: number = 0
  The y component
- z: number = 0
  The z component
Returns ObservableVector3

Accessors

x

get x(): number
The x component; assigning a different value notifies the observer

Returns number
Example
```
player.position.x += strafeSpeed * dt;
```
Implementation of PointLike3D.x
set x(value: number): void
Sets the x component
Parameters
- value: number
  The new x
Returns void

Implementation of PointLike3D.x

y

get y(): number
The y component; assigning a different value notifies the observer

Returns number
Example
```
if (player.position.y < killPlaneY) respawn(player);
```
Implementation of PointLike3D.y
set y(value: number): void
Sets the y component
Parameters
- value: number
  The new y
Returns void

Implementation of PointLike3D.y

z

get z(): number
The z component; assigning a different value notifies the observer

Returns number
Example
```
crate.position.z = -10;
```
Implementation of PointLike3D.z
set z(value: number): void
Sets the z component
Parameters
- value: number
  The new z
Returns void

Implementation of PointLike3D.z

Methods

add

add(v: PointData3D, out?: PointLike3D): this
Adds v to this point
Parameters
- v: PointData3D
  The point to add
- out: PointLike3D = ...
  The target to write the result into, defaults to this point
Returns this
The point the result was written into
Example
```
rider.position.add(platformMovement);
player.position.add(cameraOffset, cameraTarget);
```

addScaledVector

addScaledVector(v: PointData3D, s: number, out?: PointLike3D): this
Adds v * s to this point, 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 point
Returns this
The point the result was written into
Example
```
player.position.addScaledVector(velocity, dt);
```

angleTo

angleTo(v: PointData3D): number
Computes the angle between this point and v, both seen from the origin

Returns π/2 when either has zero length.
Parameters
- v: PointData3D
  The other point
Returns number
The angle in radians, from 0 to π
Example
```
const distanceOverSurface = player.position.angleTo(base.position) * planetRadius;
```

applyAffineMatrix4

applyAffineMatrix4(m: Matrix4, out?: PointLike3D): this
Transforms this point by m, translation included, without the divide ObservableVector3#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 point
Returns this
The point the result was written into
Example
```
muzzle.position.applyAffineMatrix4(gun.worldTransform, muzzleWorldPosition);
```

applyMatrix3

applyMatrix3(m: Matrix3, out?: PointLike3D): this
Multiplies this point by the 3x3 matrix m
Parameters
- m: Matrix3
  The matrix to apply
- out: PointLike3D = ...
  The target to write the result into, defaults to this point
Returns this
The point the result was written into
Example
```
satellite.position.applyMatrix3(orbitTilt);
```

applyMatrix4

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

Vector3#applyMatrix4 explains when the divide matters.
Parameters
- m: Matrix4
  The matrix to apply
- out: PointLike3D = ...
  The target to write the result into, defaults to this point
Returns this
The point the result was written into
Example
```
enemy.position.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 point around the origin 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 point
Returns this
The point the result was written into
Example
```
chaseCamera.position.copyFrom(followOffset).applyQuaternion(car.quaternion).add(car.position);
```

clamp

clamp(min: PointData3D, max: PointData3D, out?: PointLike3D): this
Clamps each component of this point 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 point
Returns this
The point the result was written into
Example
```
player.position.clamp(arenaMin, arenaMax);
```

clone

clone(observer?: Observer<ObservableVector3>): ObservableVector3
Creates a copy of this point that notifies observer, or this point's own observer when left out

A clone of a node's position that keeps the node as its observer marks the node's transform for an update whenever the clone changes, though the node hasn't moved. For a plain copy, use new Vector3().copyFrom(node.position).
Parameters
- Optionalobserver: Observer<ObservableVector3>
  Optional observer for the clone
Returns ObservableVector3

copyFrom

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

copyTo

copyTo<T extends PointLike3D>(p: T): T
Copies this point'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
```
player.position.copyTo(lastCheckpoint);
```
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 point
- out: PointLike3D = ...
  The target to write the result into, defaults to this point
Returns this
The point the result was written into
Example
```
player.position.cross(planetAxis, travelDirection).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 distanceToExit = player.position.distanceTo(exit.position);
```

distanceToSquared

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

Cheaper than ObservableVector3#distanceTo and enough to compare distances.
Parameters
- v: PointData3D
  The point to measure to
Returns number
Example
```
if (player.position.distanceToSquared(coin.position) < pickupRadius * pickupRadius) collect(coin);
```

divide

divide(v: PointData3D, out?: PointLike3D): this
Divides each component of this point 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 point
Returns this
The point the result was written into
Example
```
player.position.divide(cellSize, cell);
const column = Math.floor(cell.x);
```

divideScalar

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

dot

dot(v: PointData3D): number
Computes the dot product of this point and v
Parameters
- v: PointData3D
  The other point
Returns number
Example
```
const distanceAlongTrack = car.position.dot(trackDirection);
```

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 (!player.position.equals(lastSentPosition)) sendPosition(player.position);
```
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
```
crates.forEach((crate: Container3D, i: number) => crate.position.fromArray(savedPositions, i * 3));
```

magnitude

magnitude(): number
Computes the length of this point, its distance from the origin

Returns number
Example
```
const altitude = player.position.magnitude() - planetRadius;
```

magnitudeSquared

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

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

Returns number
Example
```
if (ball.position.magnitudeSquared() > arenaRadius * arenaRadius) resetBall();
```

max

max(v: PointData3D, out?: PointLike3D): this
Sets each component to the larger of this point's and v's
Parameters
- v: PointData3D
  The point to compare with
- out: PointLike3D = ...
  The target to write the result into, defaults to this point
Returns this
The point the result was written into
Example
```
player.position.max({ x: -Infinity, y: floorHeight, z: -Infinity });
```

min

min(v: PointData3D, out?: PointLike3D): this
Sets each component to the smaller of this point's and v's
Parameters
- v: PointData3D
  The point to compare with
- out: PointLike3D = ...
  The target to write the result into, defaults to this point
Returns this
The point the result was written into
Example
```
player.position.min({ x: Infinity, y: ceilingHeight, z: Infinity });
```

multiply

multiply(v: PointData3D, out?: PointLike3D): this
Multiplies each component of this point 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 point
Returns this
The point the result was written into
Example
```
jelly.scale.multiply({ x: 1.2, y: 0.8, z: 1.2 });
```

multiplyScalar

multiplyScalar(s: number, out?: PointLike3D): this
Multiplies each component of this point by the scalar s
Parameters
- s: number
  The scalar to multiply by
- out: PointLike3D = ...
  The target to write the result into, defaults to this point
Returns this
The point the result was written into
Example
```
balloon.scale.multiplyScalar(1 + inflateRate * dt);
```

negate

negate(out?: PointLike3D): this
Negates each component of this point, mirroring it through the origin
Parameters
- out: PointLike3D = ...
  The target to write the result into, defaults to this point
Returns this
The point the result was written into
Example
```
reflection.position.copyFrom(player.position).negate();
```

normalize

normalize(out?: PointLike3D): this
Scales this point to unit length, keeping its direction from the origin

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

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
```
crate.position.set(0, 1, -5);
crate.scale.set(2);
```
Implementation of PointLike3D.set

setFromCylindrical

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

Vector3#setFromCylindrical describes the angle and height.
Parameters
- c: Cylindrical
  The cylindrical coordinate to convert
Returns this
Example
```
const slot = new Cylindrical(towerRadius, 0, 2);

torches.forEach((torch: Mesh3D, i: number) => {
  slot.theta = (i / torches.length) * Math.PI * 2;
  torch.position.setFromCylindrical(slot);
});
```

setFromMatrixColumn

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

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
```
marker.position.setFromMatrixColumn(target.worldTransform, 3);
```

setFromSpherical

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

Vector3#setFromSpherical describes the angles.
Parameters
- s: Spherical
  The spherical coordinate to convert
Returns this
Example
```
orbit.theta += turnSpeed * dt;
camera.position.setFromSpherical(orbit).add(target.position);
```

setLength

setLength(length: number, out?: PointLike3D): this
Scales this point so its distance from the origin equals length, keeping its direction

A zero point stays zero.
Parameters
- length: number
  The target length
- out: PointLike3D = ...
  The target to write the result into, defaults to this point
Returns this
The point the result was written into
Example
```
satellite.position.setLength(orbitRadius);
```

subtract

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

toArray

toArray<T extends Float32Array<ArrayBufferLike> | number[] = number[]>(
array?: T,
offset?: number,
): T
Writes this point'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
```
crates.forEach((crate: Container3D, i: number) => crate.position.toArray(savedPositions, i * 3));
```

toString

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

Returns string
Example
```
console.log(player.position.toString());
```

transformDirection

transformDirection(m: Matrix4, out?: PointLike3D): this
Turns this point, read as a 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 point
Returns this
The point the result was written into

Class ObservableVector3

Example

Implements

Index

Constructors

Accessors

Methods

Constructors

constructor

Parameters

Returns ObservableVector3

Accessors

x

Returns number

Example

Parameters

Returns void

y

Returns number

Example

Parameters

Returns void

z

Returns number

Example

Parameters

Returns void

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

Parameters

Returns ObservableVector3

copyFrom

Parameters

Returns this

Example

copyTo

Type Parameters

Parameters

Returns T

Example

cross

Parameters

Returns this

Example

distanceTo

Parameters

Returns number

Example