classDocs / Vector3

Vector3

classsharedsource

Object → Vector3

A 3D vector object in Source engine coordinates.

Arithmetic operators work component-wise:

vec3 + vec3, vec3 + number, number + vec3 ( same for - and * )
vec3 / vec3, vec3 / number
-vec3

Constructor

Vector3(x: number?, y: number?, z: number?): Vector3

Fields

Name	Type	Description
`x`	`number`	The X coordinate ( forward ).
`y`	`number`	The Y coordinate ( left ).
`z`	`number`	The Z coordinate ( up ).
`origin`	`Vector3`	The shared zero vector `( 0, 0, 0 )`, must not be modified.

Operators

Operator	Operand	Result
`add`	`Vector3 \| number`	`Vector3`
`sub`	`Vector3 \| number`	`Vector3`
`mul`	`Vector3 \| number`	`Vector3`
`div`	`Vector3 \| number`	`Vector3`
`unm`		`Vector3`

Static functions

`copy`	Creates a new independent copy of the vector.
`dot`	Calculates the dot product of two vectors.
`fromScreen`	Returns the view direction from the screen position.
`getLength`	Calculates the length of the vector.
`getLengthSqr`	Calculates the squared length of the vector.
`getLerped`	Returns a copy of the vector linearly interpolated to another vector or a number.
`getLerpedToNumber`	Returns a copy of the vector linearly interpolated to another vector or a number.
`getLerpedToVector`	Returns a copy of the vector linearly interpolated to another vector or a number.
`lerp`	Linear interpolation between the vector and another vector or a number.
`lerpToNumber`	Linear interpolation between the vector and another vector or a number.
`lerpToVector`	Linear interpolation between the vector and another vector or a number.
`normalize`	Scales the vector to the length of 1.
`order`	Swaps coordinates of the given vectors in place, so every coordinate of mins is less than or equal to the same coordina…
`project`	Projects the vector onto the direction of another vector.
`reflect`	Reflects the vector from the plane with the given normal ( v - 2 * dot( v, n ) * n ).
`rotate`	Rotates the vector by the given angle.
`scale`	Multiplies all coordinates of the vector by the number.
`translateToLocal`	Translates the world position and angle into the local coordinate system.
`translateToWorld`	Translates the local position and angle into the world coordinate system.

#Vector3.copy

sharednodiscardsource

function Vector3.copy(self: Vector3): Vector3

Creates a new independent copy of the vector.

Parameters

Name	Type	Description
`self`	`Vector3`	The vector.

Returns

Type	Name	Description
`Vector3`	`copy`	The new vector.

#Vector3.dot

sharednodiscardsource

function Vector3.dot(self: Vector3, vector: Vector3): number

Calculates the dot product of two vectors.

Parameters

Name	Type	Description
`self`	`Vector3`	The vector.
`vector`	`Vector3`	The other vector.

Returns

Type	Name	Description
`number`	`dot_product`	The dot product of two vectors.

#Vector3.fromScreen

sharednodiscardsource

function Vector3.fromScreen(view_angle: Angle3, view_fov: number, x: number, y: number, screen_width: number, screen_height: number): Vector3

Returns the view direction from the screen position.

Same as util.AimVector and gui.ScreenToVector in Garry's Mod.

Parameters

Name	Type	Description
`view_angle`	`Angle3`	The view angle.
`view_fov`	`number`	The view fov in degrees ( 4:3 based, like `fov_desired` ).
`x`	`number`	The x position on the screen, `0` is the left edge.
`y`	`number`	The y position on the screen, `0` is the top edge.
`screen_width`	`number`	The screen width in pixels.
`screen_height`	`number`	The screen height in pixels.

Returns

Type	Name	Description
`Vector3`	`direction`	The new normalized direction vector.

#Vector3.getLength

sharednodiscardsource

function Vector3.getLength(self: Vector3): number

Calculates the length of the vector.

Parameters

Name	Type	Description
`self`	`Vector3`	The vector.

Returns

Type	Name	Description
`number`	`length`	The length of the vector.

#Vector3.getLengthSqr

sharednodiscardsource

function Vector3.getLengthSqr(self: Vector3): number

Calculates the squared length of the vector.

Faster than getLength, use it to compare lengths.

Parameters

Name	Type	Description
`self`	`Vector3`	The vector.

Returns

Type	Name	Description
`number`	`length`	The squared length of the vector.

#Vector3.getLerped

sharednodiscardsource

function Vector3.getLerped(self: Vector3, target: Vector3 | number, frac: number): Vector3

Returns a copy of the vector linearly interpolated to another vector or a number.

Parameters

Name	Type	Description
`self`	`Vector3`	The vector.
`target`	`Vector3 \| number`	The target vector or a number ( used for every coordinate ).
`frac`	`number`	The interpolation factor.

Returns

Type	Name	Description
`Vector3`	`lerped_vec3`	The new vector.

#Vector3.getLerpedToNumber

sharednodiscardsource

function Vector3.getLerpedToNumber(self: Vector3, target: Vector3 | number, frac: number): Vector3

Returns a copy of the vector linearly interpolated to another vector or a number.

Parameters

Name	Type	Description
`self`	`Vector3`	The vector.
`target`	`Vector3 \| number`	The target vector or a number ( used for every coordinate ).
`frac`	`number`	The interpolation factor.

Returns

Type	Name	Description
`Vector3`	`lerped_vec3`	The new vector.

#Vector3.getLerpedToVector

sharednodiscardsource

function Vector3.getLerpedToVector(self: Vector3, target: Vector3 | number, frac: number): Vector3

Returns a copy of the vector linearly interpolated to another vector or a number.

Parameters

Name	Type	Description
`self`	`Vector3`	The vector.
`target`	`Vector3 \| number`	The target vector or a number ( used for every coordinate ).
`frac`	`number`	The interpolation factor.

Returns

Type	Name	Description
`Vector3`	`lerped_vec3`	The new vector.

#Vector3.lerp

sharedsource

function Vector3.lerp(self: Vector3, target: Vector3 | number, frac: number): Vector3

Linear interpolation between the vector and another vector or a number.

frac of 0 keeps the vector, 1 sets it to the target, values outside [0, 1] extrapolate.

Parameters

Name	Type	Description
`self`	`Vector3`	The vector.
`target`	`Vector3 \| number`	The target vector or a number ( used for every coordinate ).
`frac`	`number`	The interpolation factor.

Returns

Type	Name	Description
`Vector3`	`vec3`	The same vector, interpolated.

#Vector3.lerpToNumber

sharedsource

function Vector3.lerpToNumber(self: Vector3, target: Vector3 | number, frac: number): Vector3

Linear interpolation between the vector and another vector or a number.

frac of 0 keeps the vector, 1 sets it to the target, values outside [0, 1] extrapolate.

Parameters

Name	Type	Description
`self`	`Vector3`	The vector.
`target`	`Vector3 \| number`	The target vector or a number ( used for every coordinate ).
`frac`	`number`	The interpolation factor.

Returns

Type	Name	Description
`Vector3`	`vec3`	The same vector, interpolated.

#Vector3.lerpToVector

sharedsource

function Vector3.lerpToVector(self: Vector3, target: Vector3 | number, frac: number): Vector3

Linear interpolation between the vector and another vector or a number.

frac of 0 keeps the vector, 1 sets it to the target, values outside [0, 1] extrapolate.

Parameters

Name	Type	Description
`self`	`Vector3`	The vector.
`target`	`Vector3 \| number`	The target vector or a number ( used for every coordinate ).
`frac`	`number`	The interpolation factor.

Returns

Type	Name	Description
`Vector3`	`vec3`	The same vector, interpolated.

#Vector3.normalize

sharedsource

function Vector3.normalize(self: Vector3): Vector3

Scales the vector to the length of 1.

Zero vector stays unchanged.

Parameters

Name	Type	Description
`self`	`Vector3`	The vector.

Returns

Type	Name	Description
`Vector3`	`vec3`	The same vector, normalized.

#Vector3.order

sharedsource

function Vector3.order(mins: Vector3, maxs: Vector3): Vector3, Vector3

Swaps coordinates of the given vectors in place, so every coordinate of mins is less than or equal to the same coordinate of maxs.

Same as OrderVectors in Garry's Mod, useful for building bounding boxes from two arbitrary corners.

Parameters

Name	Type	Description
`mins`	`Vector3`	The first corner, becomes the minimum corner.
`maxs`	`Vector3`	The second corner, becomes the maximum corner.

Returns

Type	Name	Description
`Vector3`	`mins`	The same `mins` vector.
`Vector3`	`maxs`	The same `maxs` vector.

#Vector3.project

sharedsource

function Vector3.project(self: Vector3, vector: Vector3): Vector3

Projects the vector onto the direction of another vector.

vector does not have to be normalized, projecting onto a zero vector results in a zero vector.

Parameters

Name	Type	Description
`self`	`Vector3`	The vector.
`vector`	`Vector3`	The direction to project onto.

Returns

Type	Name	Description
`Vector3`	`vec3`	The same vector, projected.

#Vector3.reflect

sharedsource

function Vector3.reflect(self: Vector3, normal: Vector3): Vector3

Reflects the vector from the plane with the given normal ( v - 2 * dot( v, n ) * n ).

Useful for bouncing velocities from surfaces, e.g. with a trace hit normal.

Parameters

Name	Type	Description
`self`	`Vector3`	The vector.
`normal`	`Vector3`	The plane normal, must be normalized.

Returns

Type	Name	Description
`Vector3`	`vec3`	The same vector, reflected.

#Vector3.rotate

sharedsource

function Vector3.rotate(self: Vector3, angle: Angle3): Vector3

Rotates the vector by the given angle.

Same as VectorRotate in Source engine and Vector:Rotate in Garry's Mod.

Parameters

Name	Type	Description
`self`	`Vector3`	The vector to rotate.
`angle`	`Angle3`	The angle to rotate by.

Returns

Type	Name	Description
`Vector3`	`vec3`	The same vector, rotated.

#Vector3.scale

sharedsource

function Vector3.scale(self: Vector3, scale: number): Vector3

Multiplies all coordinates of the vector by the number.

Parameters

Name	Type	Description
`self`	`Vector3`	The vector.
`scale`	`number`	The scale factor.

Returns

Type	Name	Description
`Vector3`	`vec3`	The same vector, scaled.

#Vector3.translateToLocal

sharednodiscardsource

function Vector3.translateToLocal(position: Vector3, angle: Angle3, world_position: Vector3, world_angle: Angle3): Vector3, Angle3

Translates the world position and angle into the local coordinate system.

Same as WorldToLocal in Garry's Mod.

Parameters

Name	Type	Description
`position`	`Vector3`	The world position.
`angle`	`Angle3`	The world angle.
`world_position`	`Vector3`	The origin of the local coordinate system.
`world_angle`	`Angle3`	The angle of the local coordinate system.

Returns

Type	Name	Description
`Vector3`	`vec3`	The new local position vector.
`Angle3`	`ang3`	The new local angle.

#Vector3.translateToWorld

sharednodiscardsource

function Vector3.translateToWorld(local_position: Vector3, local_angle: Angle3, world_position: Vector3, world_angle: Angle3): Vector3, Angle3

Translates the local position and angle into the world coordinate system.

Same as LocalToWorld in Garry's Mod.

Parameters

Name	Type	Description
`local_position`	`Vector3`	The local position.
`local_angle`	`Angle3`	The local angle.
`world_position`	`Vector3`	The origin of the local coordinate system.
`world_angle`	`Angle3`	The angle of the local coordinate system.

Returns

Type	Name	Description
`Vector3`	`vec3`	The new world position vector.
`Angle3`	`ang3`	The new world angle.

Methods

`add`	Adds another vector or a number ( to every coordinate ) to the vector.
`cross`	Calculates the cross product of two vectors ( self x vector ).
`div`	Divides the vector by another vector ( component-wise ) or a number.
`getAngle`	Calculates the angle between two vectors in degrees.
`getDistance`	Calculates the distance between two vectors.
`getDistance2D`	Calculates the distance between two vectors in the XY plane ( ignoring Z ).
`getDistance2DSqr`	Calculates the squared distance between two vectors in the XY plane ( ignoring Z ).
`getDistanceSqr`	Calculates the squared distance between two vectors.
`getLength2D`	Calculates the length of the vector in the XY plane ( ignoring Z ).
`getLength2DSqr`	Calculates the squared length of the vector in the XY plane ( ignoring Z ).
`getNormalized`	Returns a copy of the vector with the length of 1.
`getProjected`	Returns a copy of the vector projected onto another vector.
`getReflected`	Returns a copy of the vector reflected from the plane with the given normal.
`getRotated`	Returns a copy of the vector rotated by the given angle.
`getScaled`	Returns a scaled copy of the vector.
`isNear`	Checks if the vector is equal to the given vector with the given tolerance.
`isZero`	Checks if all coordinates of the vector are exactly zero.
`mul`	Multiplies the vector by another vector ( component-wise ) or a number.
`negate`	Negates all coordinates of the vector.
`set`	Copies the coordinates of another vector into this vector.
`setUnpacked`	Sets the x, y, and z coordinates of the vector.
`sub`	Subtracts another vector or a number ( from every coordinate ) from the vector.
`toAngle3`	Returns the angle that points in the direction of the vector.
`toScreen`	Converts the world position to the screen position.
`unpack`	Returns the x, y, and z coordinates of the vector.
`withinAABox`	Checks if the vector is within an axis-aligned box, borders included.
`zero`	Sets all coordinates of the vector to zero.

#Vector3:add

sharedsource

function Vector3:add(value: Vector3 | number): Vector3

Adds another vector or a number ( to every coordinate ) to the vector.

Parameters

Name	Type	Description
`value`	`Vector3 \| number`	The other vector or a number.

Returns

Type	Name	Description
`Vector3`	`vec3`	The same vector, with the sum.

#Vector3:cross

sharednodiscardsource

function Vector3:cross(vector: Vector3): Vector3

Calculates the cross product of two vectors ( self x vector ).

The result is perpendicular to both vectors, e.g. forward x left = up.

Parameters

Name	Type	Description
`vector`	`Vector3`	The other vector.

Returns

Type	Name	Description
`Vector3`	`cross_product`	The new vector.

#Vector3:div

sharedsource

function Vector3:div(value: Vector3 | number): Vector3

Divides the vector by another vector ( component-wise ) or a number.

Modifies the vector in place, division by zero is not checked and results in inf / nan components.

Parameters

Name	Type	Description
`value`	`Vector3 \| number`	The divisor vector or number.

Returns

Type	Name	Description
`Vector3`	`vec3`	The same vector, divided.

#Vector3:getAngle

sharednodiscardsource

function Vector3:getAngle(vector: Vector3): number

Calculates the angle between two vectors in degrees.

Vectors do not have to be normalized, the result is in range [0, 180].

Not to be confused with toAngle3, which returns the direction of the vector as an angle.

Parameters

Name	Type	Description
`vector`	`Vector3`	The other vector.

Returns

Type	Name	Description
`number`	`degrees`	The angle between two vectors.

#Vector3:getDistance

sharednodiscardsource

function Vector3:getDistance(vector: Vector3): number

Calculates the distance between two vectors.

Parameters

Name	Type	Description
`vector`	`Vector3`	The other vector.

Returns

Type	Name	Description
`number`	`distance`	The distance between the two vectors.

#Vector3:getDistance2D

sharednodiscardsource

function Vector3:getDistance2D(vector: Vector3): number

Calculates the distance between two vectors in the XY plane ( ignoring Z ).

Parameters

Name	Type	Description
`vector`	`Vector3`	The other vector.

Returns

Type	Name	Description
`number`	`distance`	The 2D distance between the two vectors.

#Vector3:getDistance2DSqr

sharednodiscardsource

function Vector3:getDistance2DSqr(vector: Vector3): number

Calculates the squared distance between two vectors in the XY plane ( ignoring Z ).

Parameters

Name	Type	Description
`vector`	`Vector3`	The other vector.

Returns

Type	Name	Description
`number`	`distance`	The squared 2D distance between the two vectors.

#Vector3:getDistanceSqr

sharednodiscardsource

function Vector3:getDistanceSqr(vector: Vector3): number

Calculates the squared distance between two vectors.

Faster than getDistance, use it to compare distances.

Parameters

Name	Type	Description
`vector`	`Vector3`	The other vector.

Returns

Type	Name	Description
`number`	`distance`	The squared distance between the two vectors.

#Vector3:getLength2D

sharednodiscardsource

function Vector3:getLength2D(): number

Calculates the length of the vector in the XY plane ( ignoring Z ).

Returns

Type	Name	Description
`number`	`length`	The 2D length of the vector.

#Vector3:getLength2DSqr

sharednodiscardsource

function Vector3:getLength2DSqr(): number

Calculates the squared length of the vector in the XY plane ( ignoring Z ).

Returns

Type	Name	Description
`number`	`length`	The squared 2D length of the vector.

#Vector3:getNormalized

sharednodiscardsource

function Vector3:getNormalized(): Vector3

Returns a copy of the vector with the length of 1.

Zero vector returns a zero copy.

Returns

Type	Name	Description
`Vector3`	`normalized_vec3`	The new vector.

#Vector3:getProjected

sharednodiscardsource

function Vector3:getProjected(vector: Vector3): Vector3

Returns a copy of the vector projected onto another vector.

Parameters

Name	Type	Description
`vector`	`Vector3`	The direction to project onto.

Returns

Type	Name	Description
`Vector3`	`projected_vec3`	The new vector.

#Vector3:getReflected

sharednodiscardsource

function Vector3:getReflected(normal: Vector3): Vector3

Returns a copy of the vector reflected from the plane with the given normal.

Parameters

Name	Type	Description
`normal`	`Vector3`	The plane normal, must be normalized.

Returns

Type	Name	Description
`Vector3`	`reflected_vec3`	The new vector.

#Vector3:getRotated

sharednodiscardsource

function Vector3:getRotated(angle: Angle3): Vector3

Returns a copy of the vector rotated by the given angle.

Parameters

Name	Type	Description
`angle`	`Angle3`	The angle to rotate by.

Returns

Type	Name	Description
`Vector3`	`rotated_vec3`	The new vector.

#Vector3:getScaled

sharednodiscardsource

function Vector3:getScaled(scale: number): Vector3

Returns a scaled copy of the vector.

Parameters

Name	Type	Description
`scale`	`number`	The scale factor.

Returns

Type	Name	Description
`Vector3`	`scaled_vec3`	The scaled copy of the vector.

#Vector3:isNear

sharednodiscardsource

function Vector3:isNear(vector: Vector3, tolerance: number): boolean

Checks if the vector is equal to the given vector with the given tolerance.

Each coordinate is compared separately: |a.x - b.x| <= tolerance and so on.

Parameters

Name	Type	Description
`vector`	`Vector3`	The vector to check.
`tolerance`	`number`	The maximum allowed difference per coordinate.

Returns

Type	Name	Description
`boolean`	`is_near`	`true` if the vectors are equal within the tolerance, otherwise `false`.

#Vector3:isZero

sharednodiscardsource

function Vector3:isZero(): boolean

Checks if all coordinates of the vector are exactly zero.

Returns

Type	Name	Description
`boolean`	`is_zero`	`true` if the vector is zero, `false` otherwise.

#Vector3:mul

sharedsource

function Vector3:mul(value: Vector3 | number): Vector3

Multiplies the vector by another vector ( component-wise ) or a number.

Parameters

Name	Type	Description
`value`	`Vector3 \| number`	The other vector or a number.

Returns

Type	Name	Description
`Vector3`	`vec3`	The same vector, with the product.

#Vector3:negate

sharedsource

function Vector3:negate(): Vector3

Negates all coordinates of the vector.

Returns

Type	Name	Description
`Vector3`	`vec3`	The same vector, negated.

#Vector3:set

sharedsource

function Vector3:set(vector: Vector3): Vector3

Copies the coordinates of another vector into this vector.

Parameters

Name	Type	Description
`vector`	`Vector3`	The vector to copy from.

Returns

Type	Name	Description
`Vector3`	`vec3`	The same vector.

#Vector3:setUnpacked

sharedsource

function Vector3:setUnpacked(x: number, y: number, z: number): Vector3

Sets the x, y, and z coordinates of the vector.

Parameters

Name	Type	Description
`x`	`number`	The x coordinate of the vector.
`y`	`number`	The y coordinate of the vector.
`z`	`number`	The z coordinate of the vector.

Returns

Type	Name	Description
`Vector3`	`vec3`	The same vector.

#Vector3:sub

sharedsource

function Vector3:sub(value: Vector3 | number): Vector3

Subtracts another vector or a number ( from every coordinate ) from the vector.

Parameters

Name	Type	Description
`value`	`Vector3 \| number`	The other vector or a number.

Returns

Type	Name	Description
`Vector3`	`vec3`	The same vector, with the difference.

#Vector3:toAngle3

sharednodiscardsource

function Vector3:toAngle3(up?: Vector3): Angle3

Returns the angle that points in the direction of the vector.

Same as VectorAngles in Source engine and Vector:Angle / Vector:AngleEx in Garry's Mod:

without up, pitch and yaw are in range [0, 360) and roll is always 0, e.g. ( 0, 0, 1 ) returns ( 270, 0, 0 ).
with up, roll is calculated from the given up direction and angles are in range [-180, 180].

The vector does not have to be normalized.

Parameters

Name	Type	Description
`up`optional	`Vector3`	The up direction, used to calculate roll.

Returns

Type	Name	Description
`Angle3`	`ang3`	The new angle.

#Vector3:toScreen

sharednodiscardsource

function Vector3:toScreen(view_origin: Vector3, view_angle: Angle3, view_fov: number, screen_width: number, screen_height: number): number, number, boolean

Converts the world position to the screen position.

Like Vector:ToScreen in Garry's Mod, but the view is passed explicitly.

Positions behind the view are still projected ( mirrored ) with visible set to false, a position exactly in the view plane returns the screen center.

Parameters

Name	Type	Description
`view_origin`	`Vector3`	The view origin.
`view_angle`	`Angle3`	The view angle.
`view_fov`	`number`	The view fov in degrees ( 4:3 based, like `fov_desired` ).
`screen_width`	`number`	The screen width in pixels.
`screen_height`	`number`	The screen height in pixels.

Returns

Type	Name	Description
`number`	`x`	The x position on the screen, `0` is the left edge.
`number`	`y`	The y position on the screen, `0` is the top edge.
`boolean`	`visible`	`true` if the position is in front of the view, `false` otherwise.

#Vector3:unpack

sharednodiscardsource

function Vector3:unpack(): number, number, number

Returns the x, y, and z coordinates of the vector.

Returns

Type	Name	Description
`number`	`x`	The x coordinate of the vector.
`number`	`y`	The y coordinate of the vector.
`number`	`z`	The z coordinate of the vector.

#Vector3:withinAABox

sharednodiscardsource

function Vector3:withinAABox(box_start: Vector3, box_end: Vector3): boolean

Checks if the vector is within an axis-aligned box, borders included.

The corners of the box do not have to be ordered.

Same as Vector:WithinAABox in Garry's Mod.

Parameters

Name	Type	Description
`box_start`	`Vector3`	The first corner of the box.
`box_end`	`Vector3`	The second corner of the box.

Returns

Type	Name	Description
`boolean`	`in_box`	`true` if the vector is within the box, `false` otherwise.

#Vector3:zero

sharedsource

function Vector3:zero(): Vector3

Sets all coordinates of the vector to zero.

Returns

Type	Name	Description
`Vector3`	`vec3`	The same vector.