Scripting Math

Classes

FLOAT3D

Class for holding a position or a rotation in 3D space and performing operations on it.

Metamethods

FLOAT3D(x = 0, y = 0, z = 0)

Constructs a vector value instance with the specified values for each axis. Unspecified axis values are defaulted to 0.

Arguments:

• x (optional) - First value to set. Either position on the X axis or heading (H) rotation around the Y axis.
• y (optional) - Second value to set. Either position on the Y axis or pitch (P) rotation around the X axis.
• z (optional) - Third value to set. Either position on the Z axis or banking (B) rotation around the Z axis.

---

+ operator

Adds two vectors together.

Right-side operand: FLOAT3D

Return value: FLOAT3D

---

- operator

Subtracts another vector from the first one.

Right-side operand: FLOAT3D

Return value: FLOAT3D

---

- operator(unary)

Inverts the value of each axis.

Return value: FLOAT3D

---

* operator(1)

Calculates cross product between two vectors.

Right-side operand: FLOAT3D

Return value: FLOAT3D

---

* operator(2)

Multiplies each axis value by the specified number.

Right-side operand: float

Return value: FLOAT3D

---

* operator(3)

Rotates the vector using a rotation matrix.

Right-side operand: FLOATmatrix3D

Return value: FLOAT3D

---

/ operator

Divides each axis value by the specified number.

Right-side operand: float

Return value: FLOAT3D

---

% operator

Calculates dot product between two vectors.

Right-side operand: FLOAT3D

Return value: FLOAT3D

---

clone()

Creates a copy of the vector instance.

Return value: FLOAT3D

---

tostring()

Returns vector values formatted as [%g, %g, %g].

Return value: string

Methods

Equal(other)

Compares this vector with another vector. A helper method for the lack of the == operator overloading.

Arguments:

• other - Another FLOAT3D to compare this one with.

Return value: bool

---

Length()

Returns length of the vector in meters. Equivalent to the engine's FLOAT3D::Length().

Return value: float

---

ManhattanNorm()

Returns manhattan norm of the vector in meters. Equivalent to the engine's FLOAT3D::ManhattanNorm().

Return value: float

---

MaxNorm()

Returns maximum norm of the vector in meters. Equivalent to the engine's FLOAT3D::MaxNorm().

Return value: float

---

Normalize()

Normalizes the vector in some direction by dividing it by its length, resulting in 1m length. Equivalent to the engine's FLOAT3D::Normalize().

Return value: FLOAT3D (itself)

---

SafeNormalize()

Same as Normalize but resets it to a forward vector (FLOAT3D(0, 0, -1)) if its current length is close to zero. Equivalent to the engine's FLOAT3D::SafeNormalize().

Return value: FLOAT3D (itself)

---

Flip()

Inverts the value of each axis. Equivalent to the engine's FLOAT3D::Flip().

Return value: FLOAT3D (itself)

Variables

x / h / [1]

First axis value. "X" signifies the physical position on the East-West axis; "H" signifies the "heading" rotation angle.

Type	Readable	Writeable
float	Yes	Yes

---

y / p / [2]

Second axis value. "Y" signifies the physical position on the Up-Down axis; "P" signifies the "pitch" rotation angle.

Type	Readable	Writeable
float	Yes	Yes

---

z / b / [3]

Third axis value. "Z" signifies the physical position on the North-South axis; "B" signifies the "banking" rotation angle.

Type	Readable	Writeable
float	Yes	Yes

FLOATplane3D

Class for representing planes in 3D space with an optional distance offset along its normal. Extends FLOAT3D class.

Metamethods

FLOATplane3D()

Constructs a default plane with a [0, 1, 0] vector (facing upwards) with a distance of 0.

---

FLOATplane3D(normal, distance)

Constructs a plane with the specified normal and distance.

Arguments:

• normal - FLOAT3D with the plane normal pointing towards some direction.
• distance - Plane distance in meters.

---

FLOATplane3D(point0, point1)

Constructs a plane with the specified normal at a specific point on it (by offsetting the distance using a dot product between the normal and the point).

Arguments:

• point0 - FLOAT3D with the first point at the plane itself.
• point1 - FLOAT3D with the second point some distance away from the plane.

---

FLOATplane3D(point0, point1, point2)

Constructs a plane from 3 different points in space in the counter-clockwise order with a distance of 0.

Arguments:

• point0 - FLOAT3D with the first point of a triangle plane.
• point1 - FLOAT3D with the second point of a triangle plane.
• point2 - FLOAT3D with the third point of a triangle plane.

---

+ operator

Offsets the plane by a dot product between the normal and the specified point forward.

Right-side operand: FLOAT3D

Return value: FLOATplane3D

---

- operator

Offsets the plane by a dot product between the normal and the specified point backward.

Right-side operand: FLOAT3D

Return value: FLOATplane3D

---

- operator(unary)

Inverts the normal vector and the distance value.

Return value: FLOATplane3D

---

* operator

Rotates the plane normal using a rotation matrix.

Right-side operand: FLOATmatrix3D

Return value: FLOATplane3D

---

clone()

Creates a copy of the plane instance.

Return value: FLOATplane3D

---

tostring()

Returns plane values formatted as [%g, %g, %g; %g].

Return value: string

Methods

Offset(distance)

Offsets the plane by its normal using the specified distance in meters. Equivalent to the engine's FLOATplane3D::Offset().

Arguments:

• distance - Distance to offset the plane by. May be positive or negative.

Return value: null

---

GetMaxNormal()

Returns index of the greatest coordinate of the plane normal. Equivalent to the engine's FLOATplane3D::GetMaxNormal().

Return value: integer

---

ReferencePoint(origin = N/A)

If origin point is left unspecified, it simply returns the reference point on the plane itself. Equivalent to the engine's FLOATplane3D::ReferencePoint().

Arguments:

• origin (optional) - FLOAT3D with the origin point to get a reference point on the plane from.

Return value: FLOAT3D

---

PointDistance(point)

Equivalent to the engine's FLOATplane3D::PointDistance().

Arguments:

• point - FLOAT3D with a point to calculate the distance from this plane to.

Return value: float

---

PlaneDistance(plane)

Equivalent to the engine's FLOATplane3D::PlaneDistance().

Arguments:

• plane - FLOATplane3D with another plane to calculate the distance from this plane to.

Return value: float

---

GetCoordinate(axis)

Equivalent to the engine's FLOATplane3D::GetCoordinate().

Arguments:

• axis - Index of an axis to get the missing coordinate of (1 for X, 2 for Y, 3 for Z).

Return value: FLOAT3D

---

ProjectPoint(point)

Equivalent to the engine's FLOATplane3D::ProjectPoint().

Arguments:

• point - FLOAT3D with the point to project onto this plane.

Return value: FLOAT3D

---

ProjectDirection(direction)

Equivalent to the engine's FLOATplane3D::ProjectDirection().

Arguments:

• direction - FLOAT3D with the direction vector to project onto this plane.

Return value: FLOAT3D

---

DeprojectPoint(plane, point)

Equivalent to the engine's FLOATplane3D::DeprojectPoint().

Arguments:

• plane - FLOATplane3D with the other plane to deproject the point from.
• point - FLOAT3D with the point to deproject from another plane.

Return value: FLOAT3D

---

DeprojectDirection(plane, direction)

Equivalent to the engine's FLOATplane3D::DeprojectDirection().

Arguments:

• plane - FLOATplane3D with the other plane to deproject the direction vector from.
• direction - FLOAT3D with the direction vector to deproject from another plane.

Return value: FLOAT3D

Variables

vec

Underlying vector value that acts as a plane normal.

Type	Readable	Writeable
FLOAT3D	Yes	Yes

---

dist

Plane distance offset along the normal.

Type	Readable	Writeable
float	Yes	Yes

FLOATmatrix3D

Class for holding a 3D rotation matrix and performing operations on it.

Metamethods

FLOATmatrix3D(value = 0)

Constructs a matrix value instance with the specified value in every row and column. Unspecified value is defaulted to 0.

Arguments:

• value (optional) - Value to set to each matrix cell.

---

+ operator

Adds two matrices together.

Right-side operand: FLOATmatrix3D

Return value: FLOATmatrix3D

---

- operator

Subtracts another matrix from the first one.

Right-side operand: FLOATmatrix3D

Return value: FLOATmatrix3D

---

- operator(unary)

Transposes the matrix.

Return value: FLOATmatrix3D

---

* operator(1)

Multiplies two matrices together.

Right-side operand: FLOATmatrix3D

Return value: FLOATmatrix3D

---

* operator(2)

Multiplies each matrix value by the specified number.

Right-side operand: float

Return value: FLOATmatrix3D

---

/ operator

Divides each matrix value by the specified number.

Right-side operand: float

Return value: FLOATmatrix3D

---

clone()

Creates a copy of the matrix instance.

Return value: FLOATmatrix3D

---

tostring()

Returns matrix values formatted as [%g, %g, %g; %g, %g, %g; %g, %g, %g].

Return value: string

Methods

Diagonal(value)

Resets the entire matrix to 0 and diagonally sets the specified number in the matrix. Equivalent to the engine's FLOATmatrix3D::Diagonal().

Arguments:

• value - Float value to set to the matrix diagonally.

Return value: null

---

Diagonal(values)

Resets the entire matrix to 0 and diagonally sets the numbers from the specified vector in the matrix. Equivalent to the engine's FLOATmatrix3D::Diagonal().

Arguments:

• values - FLOAT3D value to take the values from and set to the matrix diagonally.

Return value: null

---

GetRow(row)

Returns matrix values from the specified row as a vector. Equivalent to the engine's FLOATmatrix3D::GetRow().

Arguments:

• row - Index of the matrix row to get the values from (1 - 3).

Return value: FLOAT3D

---

GetColumn(column)

Returns matrix values from the specified column as a vector. Equivalent to the engine's FLOATmatrix3D::GetColumn().

Arguments:

• column - Index of the matrix column to get the values from (1 - 3).

Return value: FLOAT3D

Variables

m11

First value of the first row in the matrix (top-left).

Type	Readable	Writeable
float	Yes	Yes

m12

Second value of the first row in the matrix (top-center).

Type	Readable	Writeable
float	Yes	Yes

m13

Third value of the first row in the matrix (top-right).

Type	Readable	Writeable
float	Yes	Yes

m21

First value of the second row in the matrix (middle-left).

Type	Readable	Writeable
float	Yes	Yes

m22

Second value of the second row in the matrix (middle-center).

Type	Readable	Writeable
float	Yes	Yes

m23

Third value of the second row in the matrix (middle-right).

Type	Readable	Writeable
float	Yes	Yes

m31

First value of the third row in the matrix (bottom-left).

Type	Readable	Writeable
float	Yes	Yes

m32

Second value of the third row in the matrix (bottom-center).

Type	Readable	Writeable
float	Yes	Yes

m33

Third value of the third row in the matrix (bottom-right).

Type	Readable	Writeable
float	Yes	Yes

FLOATaabbox3D

Class for holding an axis-aligned bounding box defined by two points in 3D space.

Metamethods

FLOATaabbox3D()

Constructs an empty/invalid box.

---

FLOATaabbox3D(point)

Constructs a box out of a single point. Min and max points are equal to each other (i.e. an infinitely small box).

Arguments:

• point - FLOAT3D with the center point of the box.

---

FLOATaabbox3D(min, max)

Constructs a box out of min and max points that define a area that the box covers.
After creation, the "minimum" point of the box contains the smallest coordinates of the two specified points, whereas the "maximum" point contains the largest coordinates.

Arguments:

• min - FLOAT3D with the "minimum" point of the box.
• max - FLOAT3D with the "maximum" point of the box.

---

FLOATaabbox3D(center, radius)

Constructs a box out of a center point and a radius to expand each side to.

Arguments:

• center - FLOAT3D with the center point of the box.
• radius - Size of the box in each direction from the center point.

---

+ operator

Offsets the box in space by the specified vector forward.

Right-side operand: FLOAT3D

Return value: FLOATaabbox3D

---

- operator

Offsets the box in space by the specified vector backward.

Right-side operand: FLOAT3D

Return value: FLOATaabbox3D

---

* operator

Creates a box that fits both boxes inside of it (union). Equivalent to the engine's FLOATaabbox3D::operator|=().

Right-side operand: FLOATaabbox3D

Return value: FLOATaabbox3D

---

/ operator

Creates a box out of the intersecting area of both boxes (intersection). Equivalent to the engine's FLOATaabbox3D::operator&=().

Right-side operand: FLOATaabbox3D

Return value: FLOATaabbox3D

---

clone()

Creates a copy of the box instance.

Return value: FLOATaabbox3D

---

tostring()

Returns box values formatted as box[%g, %g, %g; %g, %g, %g].

Return value: string

Methods

Equal(other)

Compares this box with another box. A helper method for the lack of the == operator overloading.

Arguments:

• other - Another FLOATaabbox3D to compare this one with.

Return value: bool

---

SetToNormalizedEmpty()

Resets the box to an "empty" state. Equivalent to the engine's FLOATaabbox3D::SetToNormalizedEmpty().

Return value: null

---

Size()

Returns the overall size of the box. Equivalent to the engine's FLOATaabbox3D::Size().

Return value: FLOAT3D

---

Center()

Returns the center point of the box. Equivalent to the engine's FLOATaabbox3D::Center().

Return value: FLOAT3D

---

IsEmpty()

Checks whether a box is empty (i.e. constructed with no arguments or after calling SetToNormalizedEmpty()). Equivalent to the engine's FLOATaabbox3D::IsEmpty().

Return value: bool

---

Contains(other)

Checks whether another box is contained within this one. Equivalent to the engine's FLOATaabbox3D::operator>=().

Arguments:

• other - FLOATaabbox3D with another box that's supposed to be fully inside this one.

Return value: bool

---

IsInside(other)

Checks whether this box is contained within another one. Equivalent to the engine's FLOATaabbox3D::operator<=().

Arguments:

• other - FLOATaabbox3D with another box that's supposed to fully contain this one.

Return value: bool

---

HasContactWith(other, epsilon = 0.0)

Checks whether this box intersects another box with an optional epsilon value for expanding the edges. Equivalent to the engine's FLOATaabbox3D::HasContactWith().

Arguments:

• other - FLOATaabbox3D with another box to check the intersection with.
• epsilon (optional) - How much to expand the edges of each box by to eliminate potential floating point imprecision with boxes adjacent to each other.

Return value: bool

---

TouchesSphere(center, radius)

Checks whether this box intersects a sphere at a certain point with a certain radius. Equivalent to the engine's FLOATaabbox3D::TouchesSphere().

Arguments:

• center - FLOAT3D with the center point of the sphere.
• radius - Radius of the sphere.

Return value: bool

---

Expand(offset)

Expands the edges of the box by the specified length in meters. Equivalent to the engine's FLOATaabbox3D::Expand().

Arguments:

• offset - Distance to expand each side of the box by.

Return value: null

---

ExpandByFactor(factor)

Expands the edges of the box by the ratio of the box, e.g. 0.5 will make the box 150% larger and -0.5 will half its size. Equivalent to the engine's FLOATaabbox3D::ExpandByFactor().

Arguments:

• factor - Multiplication factor to expand each side of the box by.

Return value: null

---

StretchByFactor(factor)

Multiplies min and max points by the specified amount, which scales and moves the box relative to center of the world. Equivalent to the engine's FLOATaabbox3D::StretchByFactor().

Arguments:

• factor - Multiplication factor to stretch the box by.

Return value: null

---

StretchByVector(vector)

Multiplies min and max points by the amount from the respective axis of the specified vector, which scales and moves the box relative to center of the world. Equivalent to the engine's FLOATaabbox3D::StretchByVector().

Arguments:

• vector - FLOAT3D with the vector values per axis to stretch the box by.

Return value: null

Variables

min

Minimum corner of the box.

Type	Readable	Writeable
FLOAT3D	Yes	Yes

---

max

Maximum corner of the box.

Type	Readable	Writeable
FLOAT3D	Yes	Yes

CPlacement3D

Class for representing position and rotation in 3D space.

Metamethods

CPlacement3D(pos = FLOAT3D(0, 0, 0), rot = FLOAT3D(0, 0, 0))

Constructs a placement with a position vector and orientation angles. Unspecified vector values are zeroed.

Arguments:

• pos (optional) - FLOAT3D with the placement position.
• rot (optional) - FLOAT3D with the placement rotation.

---

clone()

Creates a copy of the placement instance.

Return value: CPlacement3D

---

tostring()

Returns placement values formatted as pl([%g, %g, %g]; [%g, %g, %g]).

Return value: string

Methods

Rotate_TrackBall(angle)

Rotate the placement using a trackball method. Equivalent to the engine's CPlacement3D::Rotate_TrackBall().

Arguments:

• angle - FLOAT3D with Euler angles to rotate the placement with.

Return value: null

---

Rotate_Airplane(angle)

Rotate the placement using an airplane method. Equivalent to the engine's CPlacement3D::Rotate_Airplane().

Arguments:

• angle - FLOAT3D with Euler angles to rotate the placement with.

Return value: null

---

Rotate_HPB(angle)

Rotate the placement by adding specified Euler angles to each angle. Equivalent to the engine's CPlacement3D::Rotate_HPB().

Arguments:

• angle - FLOAT3D with Euler angles to rotate the placement with.

Return value: null

---

Translate_OwnSystem(offset)

Move the placement by the specified position offset relative to its own rotation. Equivalent to the engine's CPlacement3D::Translate_OwnSystem().

Arguments:

• offset - FLOAT3D with the position offset to move the placement with.

Return value: null

---

Translate_AbsoluteSystem(offset)

Move the placement by the specified position offset regardless of its own rotation (relative to the world). Equivalent to the engine's CPlacement3D::Translate_AbsoluteSystem().

Arguments:

• offset - FLOAT3D with the position offset to move the placement with.

Return value: null

---

GetDirectionVector()

Retrieve a direction vector based on the placement rotation. Equivalent to the engine's CPlacement3D::GetDirectionVector().

Return value: FLOAT3D

---

AbsoluteToRelative(system)

Convert placement from the absolute coordinate system to the system of another placement. Equivalent to the engine's CPlacement3D::AbsoluteToRelative().

Arguments:

• system - CPlacement3D with another coordinate system to convert this one to.

Return value: null

---

AbsoluteToRelativeSmooth(system)

Convert placement from the absolute coordinate system to the system of another placement. Equivalent to the engine's CPlacement3D::AbsoluteToRelativeSmooth().

Arguments:

• system - CPlacement3D with another coordinate system to convert this one to.

Return value: null

---

RelativeToAbsolute(system)

Convert placement from the coordinate system relative to another placement to the absolute system. Equivalent to the engine's CPlacement3D::RelativeToAbsolute().

Arguments:

• system - CPlacement3D with another coordinate system to convert this one from.

Return value: null

---

RelativeToAbsoluteSmooth(system)

Convert placement from the coordinate system relative to another placement to the absolute system. Equivalent to the engine's CPlacement3D::RelativeToAbsoluteSmooth().

Arguments:

• system - CPlacement3D with another coordinate system to convert this one from.

Return value: null

---

RelativeToRelative(system1, system2)

Convert placement from the coordinate system of one placement to the system of another placement. Equivalent to the engine's CPlacement3D::RelativeToRelative().

Arguments:

• system1 - CPlacement3D with the current coordinate system to convert this one from.
• system2 - CPlacement3D with the another coordinate system to convert this one to.

Return value: null

---

RelativeToRelativeSmooth(system1, system2)

Convert placement from the coordinate system of one placement to the system of another placement. Equivalent to the engine's CPlacement3D::RelativeToRelativeSmooth().

Arguments:

• system1 - CPlacement3D with the current coordinate system to convert this one from.
• system2 - CPlacement3D with the another coordinate system to convert this one to.

Return value: null

---

Lerp(placement0, placement1, factor)

Set this placement to the interpolation between two different placements using specified lerp factor. Equivalent to the engine's CPlacement3D::Lerp().

Arguments:

• placement0 - CPlacement3D with the first placement.
• placement1 - CPlacement3D with the second placement.
• factor - Linear interpolation factor between the two placements from 0.0 to 1.0.

Return value: null

Variables

pos / pl_PositionVector

Position in 3D space (XYZ).

Type	Readable	Writeable
FLOAT3D	Yes	Yes

---

rot / pl_OrientationAngle

Rotation in Euler angles (HPB).

Type	Readable	Writeable
FLOAT3D	Yes	Yes

Functions

Math.NormFloatToByte(number)

Converts a float from the range of 0.0 .. 1.0 to an integer in the range of 0x00 .. 0xFF. Equivalent to the engine's NormFloatToByte() function.

Arguments:

• number - float value to convert.

Return value: integer

---

Math.NormByteToFloat(number)

Converts an integer from the range of 0x00 .. 0xFF to a float in the range of 0.0 .. 1.0. Equivalent to the engine's NormByteToFloat() function.

Arguments:

• number - integer value to convert.

Return value: float

---

Math.WrapAngle(number)

Wraps around the specified angle in degrees to be in the +0.0 .. +360.0 range. Equivalent to the engine's WrapAngle() function.

Arguments:

• number - float value with the angle in degrees.

Return value: float

---

Math.NormalizeAngle(number)

Wraps around the specified angle in degrees to be in the -180.0 .. +180.0 range. Equivalent to the engine's NormalizeAngle() function.

Arguments:

• number - float value with the angle in degrees.

Return value: float

---

Math.RadToDeg(number)

Converts the specified angle in radians to degrees. Equivalent to the engine's AngleRad() function.

Arguments:

• number - float value to convert.

Return value: float

---

Math.DegToRad(number)

Converts the specified angle in degrees to radians. Equivalent to the engine's RadAngle() function.

Arguments:

• number - float value to convert.

Return value: float

---

Math.MakeRotationMatrix(angles)

Converts specified Euler angles to a 3D rotation matrix. Equivalent to the engine's MakeRotationMatrix() function.

Arguments:

• angles - FLOAT3D with Euler angles.

Return value: FLOATmatrix3D

---

Math.MakeInverseRotationMatrix(angles)

Converts specified Euler angles to an inverse 3D rotation matrix. Equivalent to the engine's MakeInverseRotationMatrix() function.

Arguments:

• angles - FLOAT3D with Euler angles.

Return value: FLOATmatrix3D

---

Math.DecomposeRotationMatrix(matrix)

Converts specified 3D rotation matrix to Euler angles with snapping to 0.25 degrees. Equivalent to the engine's DecomposeRotationMatrix() function.

Arguments:

• matrix - FLOATmatrix3D with the rotation matrix.

Return value: FLOAT3D

---

Math.DecomposeRotationMatrixNoSnap(matrix)

Converts specified 3D rotation matrix to Euler angles without snapping. Equivalent to the engine's DecomposeRotationMatrixNoSnap() function.

Arguments:

• matrix - FLOATmatrix3D with the rotation matrix.

Return value: FLOAT3D

---

Math.AnglesToDirectionVector(angles)

Converts specified Euler angles to a direction vector. Equivalent to the engine's AnglesToDirectionVector() function.

Arguments:

• angles - FLOAT3D with Euler angles.

Return value: FLOAT3D

---

Math.DirectionVectorToAngles(direction)

Converts specified direction vector to Euler angles with snapping to 0.25 degrees. Equivalent to the engine's DirectionVectorToAngles() function.

Arguments:

• direction - FLOAT3D with the direction vector.

Return value: FLOAT3D

---

Math.DirectionVectorToAnglesNoSnap(direction)

Converts specified direction vector to Euler angles without snapping. Equivalent to the engine's DirectionVectorToAnglesNoSnap() function.

Arguments:

• direction - FLOAT3D with the direction vector.

Return value: FLOAT3D

---

Math.UpVectorToAngles(vector)

Converts specified upward vector to Euler angles facing forward. Equivalent to the engine's UpVectorToAngles() function.

Arguments:

• vector - FLOAT3D with the upward vector.

Return value: FLOAT3D