Legacy:Object (UT3)/Numeric Functions

UT3 :: Object (UT3) (Numeric Functions)

These are the numeric functions from the Object class. All of them are declared final and most of them are also native and/or static. The few exceptions will be mentioned individually.

Since Object is the top-most class of the UT3 class hierarchy, all the functions described here can be used in all other classes. You could basically call them "global functions", though that somewhat waters down the OOP aspect.

See Legacy:Object (UT3)/Functions for other final functions that mainly deal with colors, strings and objects.
See Legacy:Object (UT3)/Operators for additional operations on numeric values.
See Object (UT3) for other members of the object class, including non-final function stubs and events.

Int Functions

int Clamp (int V, int A, int B) 

Returns A if V is smaller than A, B if V is larger than B, otherwise V.
If A is smaller than B, this function has the effect of restricting V to the interval [A, B].

int Max (int A, int B) 

Returns the arithmetically larger of the two values.

int Min (int A, int B) 

Returns the arithmetically smaller of the two values.

string ToHex (int A) 

Returns the unsigned 8-digit uppercase hexadecimal representation of A. The result will be prefixed with zeroes if it consists of less than eight hexadecimal digits.

Float Functions

float Abs (float A) 

Returns the absolute value of A, i.e. -A- if A is smaller than 0, otherwise A itself.

float FClamp (float V, float A, float B) 

Returns A if V is smaller than A, B if V is larger than B, otherwise V.
If A is smaller than B, this function has the effect of restricting V to the interval [A, B].

float FMax (float A, float B) 

Returns the arithmetically larger of the two values.

float FMin (float A, float B) 

Returns the arithmetically smaller of the two values.

int Round (float A) 

Rounds A to the nearest integer value using the round-to-even method. (see Wikipedia:Rounding)
This and typecasting to int or byte are the only built-in ways to convert a float value to integer. An int typecast behaves like the floor function for positive values and like the ceiling function for negative values, i.e. it simply truncates the value at the decimal point. (see Wikipedia:Floor and ceiling functions)

byte FloatToByte (float inputFloat, optional bool bSigned) 

Converts a float value to a 0-255 byte, assuming the interval [0.0, 1.0] if bSigned is false or omitted, or the interval [-1.0, 1.0] if bSigned is true. Float values outside this range will result in byte values of 0 or 255.

float ByteToFloat (byte inputByte, optional bool bSigned) 

Converts a 0-255 byte to a float value in the interval [0.0, 1.0] if bSigned is false or omitted or in the interval [-1.0, 1.0] if bSigned it true.

Trigonometric Functions

float Sin (float A)

float Cos (float A)

float Tan (float A) 

Sine, cosine and tangent functions, see Wikipedia:Trigonometric functions.

float Asin (float A)

float Acos (float A) 

Arcsine and arccosine functions, see Wikipedia:Inverse trigonometric functions.

float Atan (float A, float B) 

Two-argument version of the arctangent function, also known as Wikipedia:atan2.

Exponentiation Functions

float Exp (float A) 

Returns the Wikipedia:exponential function of A.

float Loge (float A) 

Returns the Wikipedia:natural logarithm of A.

float Sqrt (float A) 

Returns the Wikipedia:square root of A.

float Square (float A) 

Returns the square of A, i.e. A multiplied by itself.

Vector Functions

float VSize (vector A) 

Returns the length of the vector.

float VSize2D (vector A) 

Returns the length of the vector projected onto the XY plane.

float VSizeSq (vector A) 

Returns the squared length of the vector. This function has performance advantages over VSize since it doesn't need to calculate a square root.

float VSizeSq2D (vector A) 

Returns the squared length of the vector projected onto the XY plane. This function has performance advantages over VSize2D since it doesn't need to calculate a square root.

vector Normal (vector A) 

Returns a vector with the same direction as the input, but with length 1. If the input is the null vector, the null vector is returned.

bool IsZero (vector A) 

Returns true if A is the null vector, i.e. all components are 0. The null vector is the only vector with a length of 0.

vector ClampLength (vector V, float MaxLength) 

If the length of V is equal to or smaller than MaxLength, then V is returned. Otherwise a vector with the same direction as V and length MaxLength is returned.

vector2d vect2d (float InX, float InY) [non-native] 

Constructs a Vector2D value. This function is the analog of the vector literal vect(X,Y,Z). Unlike the vector literal this is a "real" function and you can pass complex expressions as its parameters.
The Vector2D struct is rarely used as a "real" vector and often only as a set of two float values that "somehow belong together".

Advanced Vector Functions

vector MirrorVectorByNormal (vector InVect, vector InNormal) 

Calculates a vector of the same length as InVect, whose direction is a result of reflection of InVect on a plane defined through the normal vector InNormal.
Note that this definition is only accurate if InNormal has length 1.

vector ProjectOnTo (vector x, vector y) 

Projects vector x onto vector y. The result is a vector with the same or opposite direction as y. If z is the result vector then (z - x) is a vector that is orthogonal to y and in the same plane as x and y.

float PointDistToLine (vector Point, vector Line, vector Origin, optional out vector OutClosestPoint) 

Returns the distance of Point to a line that is given by direction Line and point Origin. The function also calculates the point on the line that is closest to Point and returns it in OutClosestPoint.

float PointDistToPlane (vector Point, rotator Orientation, vector Origin, optional out vector out_ClosestPoint) [non-native] 

Returns the distance of Point to a plane that is given by Orientation and point Origin. The function also calculates the point on the plane that is closest to Point and returns it in out_ClosestPoint.

bool PointInBox (vector Point, vector Location, vector Extent) [non-native] 

Returns true if Point is within (including on a side, edge or corner) the axis-oriented box given by center Location and twice the side length of Extent.

Rotator Functions

rotator Normalize (rotator Rot) 

Normalizes the rotator's component values to the interval [-32768, 32767].

int NormalizeRotAxis (int Angle) 

Normalizes a single rotator component to the interval [-32768, 32767].

float RDiff (rotator A, rotator B) 

Gives the rotation difference between two Rotators, taking the shortest route between them in degrees.

float RSize (rotator R) [non-native] 

Applies vector definitions to rotators and calculate their "length" as the square root of the sum of the squares of the normalized pitch, yaw and roll components.

ClampRotAxis (int ViewAxis, out int out_DeltaViewAxis, int MaxLimit, int MinLimit) [non-native] 

Clamp a rotation axis. The ViewAxis rotation component will be normalized to the interval [-32768,+32767].
This function will set out_DeltaViewAxis to the delta needed to bring ViewAxis within the [MinLimit,MaxLimit] range.

Quaternion Functions

quat QuatProduct (quat A, quat B) 

Calculates the quaternion product of A and B.

float QuatDot (quat A, quat B) 

quat QuatInvert (quat A) 

Inverts the quaternion.

vector QuatRotateVector (quat A, vector B) 

Rotates vector B in the way described by quaternion A.

quat QuatFindBetween (vector A, vector B) 

Calculates a quaternion that describes the smallest rotation from A to B.

quat QuatFromAxisAndAngle (vector Axis, float Angle) 

Constructs a quaternion from a rotation axis vector and a rotation angle.

quat QuatFromRotator (rotator A) 

Converts a rotator into a quaternion.

rotator QuatToRotator (quat A) 

Converts a quaternion to a rotator.

Coordinate System and Angular Functions

A coordinate system is defined by an origin vector and three (usually orthogonal) axis vectors that usually are unit vectors, i.e. their length is 1. Rotators can define a Cartesian coordinate system with an unspecified origin.

GetAxes (rotator A, out vector X, out vector Y, out vector Z) 

Returns the axis vectors of the Cartesian coordinate system described by rotator A.

GetUnAxes (rotator A, out vector X, out vector Y, out vector Z) 

rotator OrthoRotation (vector X, vector Y, vector Z) 

Constructs a rotator that describes the coordinate system represented by the three given axis vectors.

Consider coordinate system 'O' the first person view of the player, and 'Direction' a vector pointing to an enemy. Then in an angular distance consisting of azimuth and elevation:

• positive azimuth means enemy is on the right of crosshair, negative means left.
• positive elevation means enemy is above the crosshair, negative means below.

bool GetDotDistance (out Vector2D OutDotDist, vector Direction, vector AxisX, vector AxisY, vector AxisZ) 

Calculates the dotted distance of vector 'Direction' to coordinate system O(AxisX,AxisY,AxisZ). Returns true if Direction is faces forward (relative to AxisX), false if it faces backward.
OutDotDist.X is (Direction dot AxisX) relative to plane (AxisX,AxisZ), which equals Cos(Azimuth). Note that the sign actually represents left/right, not front/behind.
OutDotDist.Y is (Direction dot AxisX) relative to plane (AxisX,AxisY), which equals Cos(Elevation).

bool GetAngularDistance (out Vector2D OutAngularDist, vector Direction, vector AxisX, vector AxisY, vector AxisZ) 

Calculates the angular distance of vector 'Direction' to coordinate system O(AxisX,AxisY,AxisZ). Returns true if Direction is faces forward (relative to AxisX), false if it faces backward.
OutAngularDist.X is the Azimuth angle (in radians) of Direction vector compared to plane (AxisX,AxisZ).
OutAngularDist.Y is the Elevation angle (in radians) of Direction vector compared to plane (AxisX,AxisY).

GetAngularFromDotDist (out Vector2D OutAngDist, Vector2D DotDist) 

Converts Dot distance to angular distance.

GetAngularDegreesFromRadians (out Vector2D OutFOV) [non-native] 

Transforms angular distance in radians to degrees.

float GetHeadingAngle (vector Dir) [non-native] 

Returns world space angle (in radians) of given vector.

float FindDeltaAngle (float A1, float A2) [non-native] 

Gets the difference in world space angles in the interval [-π,π].

float UnwindHeading (float a) [non-native] 

Brings the angle in radians into the interval [-π,π] by adding or subtracting multiples of 2π.

vector TransformVectorByRotation (rotator SourceRotation, vector SourceVector, optional bool bInverse) 

"Script hook to FRotationMatrix::TransformFVector()."
With bInverse set to false the result seems to be the same as "SourceVector >> SourceRotation". With bInverse set to true the result seems to be the same as "SourceVector << SourceRotation".

Random Functions

int Rand (int Max) 

Returns a Wikipedia:pseudorandom integer value in the interval [0, x] where x is Max-1 clamped to the interval [0, 0x7fff]. (0x7fff in decimal is 32767)

float FRand ( ) 

Returns a pseudorandom float value in the interval [0.0, 1.0].

float RandRange (float InMin, float InMax) [non-native] 

Returns a pseudorandom float value in the interval [InMin, InMax].

vector VRand ( ) 

Returns a vector with random direction and a random length in the interval [0.0, 1.0]. Normalize the result if you only want a random direction.

rotator RotRand (optional bool bRoll) 

Returns a rotator with random pitch and yaw values in the interval [0, 65535]. If bRoll is true a random roll value in the interval [0, 65535] is generated, otherwise the roll value is set to 0.

Interpolation Functions

Alpha values are the "position" that should be calculated. The value 0 means the starting point, the value 1 the end point. The interpolation functions may not return meaningful results if alpha values outside the interval [0.0, 1.0] are passed.

Float Interpolation

float Lerp (float A, float B, float Alpha) 

Linear interpolation between A and B.

float GetRangeValueByPct (Vector2D Range, float Pct) [non-native] 

Returns the value in the Range, relative to Pct. This is basically a non-native version of Lerp that takes a Vector2D instead of two separate float values.

float GetRangePctByValue (Vector2D Range, float Value) [non-native] 

Returns the relative percentage position Value is in the Range. This is the inverse function to GetRangeValueByPct and is very similar to the FPctByRange function, which specifies the range with two float values instead of a Vector2D.

float FPctByRange (float Value, float InMin, float InMax) [non-native] 

Returns the relative percentage position Value is in the range [Min,Max]. This is basically the inverse function to Lerp with this function's Value being the Lerp function's result and the Lerp function's Alpha being this function's result.

float FCubicInterp (float P0, float T0, float P1, float T1, float A) 

Cubic spline interpolation between P0 and P1. T0 and T1 are the tangent directions at P0 and P1 respectively, A is the alpha value.

float FInterpEaseIn (float A, float B, float Alpha, float Exp) [non-native] 

Interpolates from A to B with ease-in (smoothly approaches B). Higher Exp values result in more rapid deceleration.

float FInterpEaseOut (float A, float B, float Alpha, float Exp) [non-native] 

Interpolates from A to B with ease-out (smoothly departs A). Higher Exp values result in more rapid acceleration.

float FInterpEaseInOut (float A, float B, float Alpha, float Exp) 

Interpolates from A to B with both ease-in and ease-out (smoothly departs A, smoothly approaches B). Higher Exp values result in more rapid acceleration and deceleration.

float FInterpTo (float Current, float Target, float DeltaTime, float InterpSpeed) 

Tries to reach Target based on distance from Current position, giving a nice smooth feeling when tracking a position.

Vector Interpolation

vector VLerp (vector A, vector B, float Alpha) 

Linear interpolation between A and B.

vector VSmerp (vector A, vector B, float Alpha) 

Smooth (cubic?) interpolation between A and B.

vector VInterpTo (vector Current, vector Target, float DeltaTime, float InterpSpeed) 

Tries to reach Target based on distance from Current position, giving a nice smooth feeling when tracking a position. (Doesn't work well when target teleports.)

Rotation Interpolation

Rotators can either be interpolated using the shortest rotation path or the actual component values. Shortest rotation interpolation should be used when interpolating actual rotations, while actual component interpolation should be used for rotation rates.

rotator RLerp (rotator A, rotator B, float Alpha, optional bool bShortestPath) 

Linear interpolation between A and B.

rotator RSmerp (rotator A, rotator B, float Alpha, optional bool bShortestPath) 

Smooth (cubic?) interpolation between A and B.

rotator RInterpTo (rotator Current, rotator Target, float DeltaTime, float InterpSpeed) 

Tries to reach Target based on distance from Current position, giving a nice smooth feeling when tracking a position.

bool SClampRotAxis (float DeltaTime, int ViewAxis, out int out_DeltaViewAxis, int MaxLimit, int MinLimit, float InterpolationSpeed) 

Smooth clamp a rotator axis. This is mainly used to bring smoothly a rotator component within a certain range [MinLimit,MaxLimit], for example to smoothly limit the player's ViewRotation Pitch or Yaw component.

quat QuatSlerp (quat A, quat B, float Alpha, optional bool bShortestPath) 

Spherical linear interpolation between A and B.