Math Guide

Introduction

Torque2D exposes a set of built-in math functions to TorqueScript. Use these whenever possible — they run much faster than the equivalent written in script. They cover everyday arithmetic (rounding, powers, trig), random numbers, and vector/matrix math.

Two conventions trip people up, so keep them in mind:

• Trigonometry works in degrees, not radians. mSin, mCos, and mTan expect an angle in degrees, and mAsin/mAcos/mAtan return degrees. This matches the rest of the engine, where object angles are in degrees. (Use mDegToRad / mRadToDeg if you need to convert.)
• Vectors are plain strings of space-separated numbers — "x y z". The vector functions are inherited from Torque's 3D lineage and work on up to three components; in a 2D game you'll typically pass "x y 0" (or just "x y", which treats z as 0).

Numbers and rounding

Function	Returns	Description
mFloor(val)	int	The next lowest whole number (rounds down).
mCeil(val)	int	The next highest whole number (rounds up).
mRound(val)	int	The nearest whole number (0.5 rounds up).
mAbs(val)	float	The absolute value (magnitude) of val.
mClamp(val, min, max)	float	val constrained to the range [min, max].
mGetMin(a, b)	float	The smaller of the two values.
mGetMax(a, b)	float	The larger of the two values.
mFloatLength(val, numDecimals)	string	val limited to numDecimals decimal places (0–9).

Powers and roots

Function	Returns	Description
mSqrt(val)	float	The square root of val.
mPow(val, power)	float	val raised to power (i.e. val ^ power).
mLog(val)	float	The natural logarithm (base e) of val.

Trigonometry (degrees)

Function	Returns	Description
mSin(deg)	float	Sine of the angle, in the range [-1, 1].
mCos(deg)	float	Cosine of the angle, in the range [-1, 1].
mTan(deg)	float	Tangent of the angle.
mAsin(val)	float (deg)	Inverse sine, in the range [-90, 90].
mAcos(val)	float (deg)	Inverse cosine, in the range [0, 180].
mAtan(x, y)	float (deg)	Arc-tangent of a line with horizontal run x and vertical rise y. May also be called as mAtan("x y").
mDegToRad(val)	float	Convert degrees to radians.
mRadToDeg(val)	float	Convert radians to degrees.

%y = mSin(30);          // 0.5
%angle = mAtan(1, 1);   // 45  (direction of the vector 1,1)

Equation solvers

These solve polynomial equations and return a string whose first value is the number of real solutions, followed by the solutions themselves. Only read as many solutions as the count says are valid — the rest are undefined.

Function	Returns	Solves
mSolveQuadratic(a, b, c)	"count x0 x1"	a·x² + b·x + c = 0 (0–2 solutions)
mSolveCubic(a, b, c, d)	"count x0 x1 x2"	a·x³ + b·x² + c·x + d = 0 (0–3 solutions)
mSolveQuartic(a, b, c, d, e)	"count x0 x1 x2 x3"	a·x⁴ + … + e = 0 (0–4 solutions)

%result = mSolveQuadratic(1, -3, 2);   // "2 1 2"  -> two roots: x = 1 and x = 2
%count  = getWord(%result, 0);         // 2

Random numbers

Function	Returns	Description
getRandom()	float	A random float from 0.0 to 1.0.
getRandom(max)	int	A random integer from 0 to max, inclusive.
getRandom(min, max)	int	A random integer from min to max, inclusive.
getRandomF(min, max)	float	A random float from min to max.
getRandomBell(min, max [, mean] [, stdDev])	int	A random integer from min to max following a normal (bell-curve) distribution. mean defaults to the center; stdDev defaults to 1/6 of the range.
setRandomSeed([seed])	—	Seed the random generator. With no argument it seeds from the current time.
getRandomSeed()	int	The generator's current seed.

%damage = getRandom(5, 10);     // an integer 5..10
%chance = getRandom();          // a float 0.0..1.0

Reproducible sequences: save getRandomSeed(), run your random sequence, then later call setRandomSeed() with the saved value to replay the exact same sequence of random numbers — handy for deterministic gameplay or debugging.

Vectors

Vectors are space-separated strings of up to three components ("x y z"). Functions that return a vector give back the same string form. In 2D, pass "x y 0".

Function	Returns	Description
VectorAdd(a, b)	vector	a + b.
VectorSub(a, b)	vector	a - b.
VectorScale(vec, scale)	vector	vec multiplied by the scalar scale.
VectorNormalize(vec)	vector	The unit (length-1) vector pointing the same way as vec.
VectorLen(vec)	float	The length (magnitude) of vec.
VectorDist(a, b)	float	The distance between the two points a and b.
VectorDot(a, b)	float	The dot product. Normalize both inputs first if you want to read it as an angle: >0 means < 90° apart, 0 means perpendicular, <0 means > 90° apart.
VectorCross(a, b)	vector	The cross product — a vector at right angles to both inputs (inherently 3D).
VectorOrthoBasis("ax ay az theta")	matrix	A 3×3 row-major orthonormal basis for the given axis/angle (3D).

// Midpoint between two positions:
%mid = VectorScale(VectorAdd("2 2 0", "6 4 0"), 0.5);   // "4 3 0"

// Distance between two objects:
%dist = VectorDist(%objA.getPosition(), %objB.getPosition());

Matrices and boxes (3D heritage)

These functions operate on 3D transform matrices and are inherited from Torque's 3D lineage. A 2D game almost never needs them — for moving and rotating objects, use the object's own fields and methods (Position, Angle, setPosition, setAngle) instead. They are listed here for completeness.

A transform matrix is the 7-element string "PosX PosY PosZ RotX RotY RotZ theta".

Function	Returns	Description
MatrixCreate(posVec, rotVec)	matrix	A transform from a 3-element position and a 4-element axis/angle rotation.
MatrixCreateFromEuler(rotVec)	matrix	A transform from a 3-element Euler rotation "RotX RotY RotZ".
MatrixMultiply(a, b)	matrix	The product of two transform matrices.
MatrixMulVector(transform, vec)	vector	vec rotated by transform (direction only).
MatrixMulPoint(transform, point)	vector	point transformed by transform (rotation + translation).
getBoxCenter("x1 y1 z1 x2 y2 z2")	vector	The center point of the box defined by two opposite corners.

See also

• Easing — the mEase() function and the available easing curves, for smooth non-linear interpolation.
• Noise Generation — the NoiseGenerator object, for procedural noise.