Phaser API Documentation

  Version: 
Filter
This is a beta release of our new docs system. Found an issue?
Please tell us about it in the #📖-newdocs-feedback channel on the Phaser Discord
Namespace: Math
Phaser.Math
Source: src/math/index.js (Line 10)

Classes

Namespace

Members

<static> DEG_TO_RAD: number
Focus
Focus

Description:

For converting degrees to radians (PI / 180)

Type:
number
Since: 3.0.0
Source: src/math/const.js (Line 36)
Focus
Focus
<static> EPSILON: number
Focus
Focus

Description:

An epsilon value (1.0e-6)

Type:
number
Since: 3.0.0
Source: src/math/const.js (Line 27)
Focus
Focus
<static> MAX_SAFE_INTEGER: number
Focus
Focus

Description:

The maximum safe integer this browser supports. We use a const for backward compatibility with Internet Explorer.

Type:
number
Since: 3.21.0
Source: src/math/const.js (Line 74)
Focus
Focus
<static> MIN_SAFE_INTEGER: number
Focus
Focus

Description:

The minimum safe integer this browser supports. We use a const for backward compatibility with Internet Explorer.

Type:
number
Since: 3.21.0
Source: src/math/const.js (Line 64)
Focus
Focus
<static> PI2: number
Focus
Focus

Description:

The value of PI * 2.

Type:
number
Since: 3.0.0
Source: src/math/const.js (Line 9)
Focus
Focus
<static> RAD_TO_DEG: number
Focus
Focus

Description:

For converting radians to degrees (180 / PI)

Type:
number
Since: 3.0.0
Source: src/math/const.js (Line 45)
Focus
Focus

Description:

An instance of the Random Number Generator. This is not set until the Game boots.

Type:
Since: 3.0.0
Source: src/math/const.js (Line 54)
Focus
Focus
<static> TAU: number
Focus
Focus

Description:

The value of PI * 0.5.

Type:
number
Since: 3.0.0
Source: src/math/const.js (Line 18)
Focus
Focus

Methods

<static> Average(values)
Focus
Focus

Description:

Calculate the mean average of the given values.

Parameters:

name type description
values Array.<number>

The values to average.

Returns:
Description:

The average value.

Type:
  • number
Examples:
Since: 3.0.0
Source: src/math/Average.js (Line 7)
Focus
Focus
<static> Bernstein(n, i)
Focus
Focus

Description:

Calculates the Bernstein basis from the three factorial coefficients.

Parameters:

name type description
n number

The first value.

i number

The second value.

Returns:
Description:

The Bernstein basis of Factorial(n) / Factorial(i) / Factorial(n - i)

Type:
  • number
Examples:
Since: 3.0.0
Source: src/math/Bernstein.js (Line 9)
Focus
Focus
<static> Between(min, max)
Focus
Focus

Description:

Compute a random integer between the min and max values, inclusive.

Parameters:

name type description
min number

The minimum value.

max number

The maximum value.

Returns:
Description:

The random integer.

Type:
  • number
Examples:
Since: 3.0.0
Source: src/math/Between.js (Line 7)
Focus
Focus
<static> CatmullRom(t, p0, p1, p2, p3)
Focus
Focus

Description:

Calculates a Catmull-Rom value from the given points, based on an alpha of 0.5.

Parameters:

name type description
t number

The amount to interpolate by.

p0 number

The first control point.

p1 number

The second control point.

p2 number

The third control point.

p3 number

The fourth control point.

Returns:
Description:

The Catmull-Rom value.

Type:
  • number
Examples:
Since: 3.0.0
Source: src/math/CatmullRom.js (Line 7)
Focus
Focus
<static> CeilTo(value, [place], [base])
Focus
Focus

Description:

Ceils to some place comparative to a base, default is 10 for decimal place.

The place is represented by the power applied to base to get that place.

Parameters:

name type arguments Default description
value number

The value to round.

place number <optional> 0

The place to round to.

base number <optional> 10

The base to round in. Default is 10 for decimal.

Returns:
Description:

The rounded value.

Type:
  • number
Examples:
Since: 3.0.0
Source: src/math/CeilTo.js (Line 7)
Focus
Focus
<static> Clamp(value, min, max)
Focus
Focus

Description:

Force a value within the boundaries by clamping it to the range min, max.

Parameters:

name type description
value number

The value to be clamped.

min number

The minimum bounds.

max number

The maximum bounds.

Returns:
Description:

The clamped value.

Type:
  • number
Examples:
Since: 3.0.0
Source: src/math/Clamp.js (Line 7)
Focus
Focus
<static> DegToRad(degrees)
Focus
Focus

Description:

Convert the given angle from degrees, to the equivalent angle in radians.

Parameters:

name type description
degrees number

The angle (in degrees) to convert to radians.

Returns:
Description:

The given angle converted to radians.

Type:
  • number
Examples:
Since: 3.0.0
Source: src/math/DegToRad.js (Line 9)
Focus
Focus
<static> Difference(a, b)
Focus
Focus

Description:

Calculates the positive difference of two given numbers.

Parameters:

name type description
a number

The first number in the calculation.

b number

The second number in the calculation.

Returns:
Description:

The positive difference of the two given numbers.

Type:
  • number
Examples:
Since: 3.0.0
Source: src/math/Difference.js (Line 7)
Focus
Focus
<static> Factorial(value)
Focus
Focus

Description:

Calculates the factorial of a given number for integer values greater than 0.

Parameters:

name type description
value number

A positive integer to calculate the factorial of.

Returns:
Description:

The factorial of the given number.

Type:
  • number
Examples:
Since: 3.0.0
Source: src/math/Factorial.js (Line 7)
Focus
Focus
<static> FloatBetween(min, max)
Focus
Focus

Description:

Generate a random floating point number between the two given bounds, minimum inclusive, maximum exclusive.

Parameters:

name type description
min number

The lower bound for the float, inclusive.

max number

The upper bound for the float exclusive.

Returns:
Description:

A random float within the given range.

Type:
  • number
Examples:
Since: 3.0.0
Source: src/math/FloatBetween.js (Line 7)
Focus
Focus
<static> FloorTo(value, [place], [base])
Focus
Focus

Description:

Floors to some place comparative to a base, default is 10 for decimal place.

The place is represented by the power applied to base to get that place.

Parameters:

name type arguments Default description
value number

The value to round.

place number <optional> 0

The place to round to.

base number <optional> 10

The base to round in. Default is 10 for decimal.

Returns:
Description:

The rounded value.

Type:
  • number
Examples:
Since: 3.0.0
Source: src/math/FloorTo.js (Line 7)
Focus
Focus
<static> FromPercent(percent, min, [max])
Focus
Focus

Description:

Return a value based on the range between min and max and the percentage given.

Parameters:

name type arguments description
percent number

A value between 0 and 1 representing the percentage.

min number

The minimum value.

max number <optional>

The maximum value.

Returns:
Description:

The value that is percent percent between min and max.

Type:
  • number
Examples:
Since: 3.0.0
Source: src/math/FromPercent.js (Line 9)
Focus
Focus
<static> GetSpeed(distance, time)
Focus
Focus

Description:

Calculate a per-ms speed from a distance and time (given in seconds).

Parameters:

name type description
distance number

The distance.

time number

The time, in seconds.

Returns:
Description:

The speed, in distance per ms.

Type:
  • number
Examples:
// 400px over 1 second is 0.4 px/ms
Phaser.Math.GetSpeed(400, 1) // -> 0.4
Since: 3.0.0
Source: src/math/GetSpeed.js (Line 7)
Focus
Focus
<static> IsEven(value)
Focus
Focus

Description:

Check if a given value is an even number.

Parameters:

name type description
value number

The number to perform the check with.

Returns:
Description:

Whether the number is even or not.

Type:
  • boolean
Examples:
Since: 3.0.0
Source: src/math/IsEven.js (Line 7)
Focus
Focus
<static> IsEvenStrict(value)
Focus
Focus

Description:

Check if a given value is an even number using a strict type check.

Parameters:

name type description
value number

The number to perform the check with.

Returns:
Description:

Whether the number is even or not.

Type:
  • boolean
Examples:
Since: 3.0.0
Source: src/math/IsEvenStrict.js (Line 7)
Focus
Focus
<static> Linear(p0, p1, t)
Focus
Focus

Description:

Calculates a linear (interpolation) value over t.

Parameters:

name type description
p0 number

The first point.

p1 number

The second point.

t number

The percentage between p0 and p1 to return, represented as a number between 0 and 1.

Returns:
Description:

The step t% of the way between p0 and p1.

Type:
  • number
Examples:
Since: 3.0.0
Source: src/math/Linear.js (Line 7)
Focus
Focus
<static> MaxAdd(value, amount, max)
Focus
Focus

Description:

Add an amount to a value, limiting the maximum result to max.

Parameters:

name type description
value number

The value to add to.

amount number

The amount to add.

max number

The maximum value to return.

Returns:
Description:

The resulting value.

Type:
  • number
Examples:
Since: 3.0.0
Source: src/math/MaxAdd.js (Line 7)
Focus
Focus
<static> MinSub(value, amount, min)
Focus
Focus

Description:

Subtract an amount from value, limiting the minimum result to min.

Parameters:

name type description
value number

The value to subtract from.

amount number

The amount to subtract.

min number

The minimum value to return.

Returns:
Description:

The resulting value.

Type:
  • number
Examples:
Since: 3.0.0
Source: src/math/MinSub.js (Line 7)
Focus
Focus
<static> Percent(value, min, [max], [upperMax])
Focus
Focus

Description:

Work out what percentage value is of the range between min and max. If max isn't given then it will return the percentage of value to min.

You can optionally specify an upperMax value, which is a mid-way point in the range that represents 100%, after which the % starts to go down to zero again.

Parameters:

name type arguments description
value number

The value to determine the percentage of.

min number

The minimum value.

max number <optional>

The maximum value.

upperMax number <optional>

The mid-way point in the range that represents 100%.

Returns:
Description:

A value between 0 and 1 representing the percentage.

Type:
  • number
Examples:
Since: 3.0.0
Source: src/math/Percent.js (Line 7)
Focus
Focus
<static> RadToDeg(radians)
Focus
Focus

Description:

Convert the given angle in radians, to the equivalent angle in degrees.

Parameters:

name type description
radians number

The angle in radians to convert ot degrees.

Returns:
Description:

The given angle converted to degrees.

Type:
  • number
Examples:
Since: 3.0.0
Source: src/math/RadToDeg.js (Line 9)
Focus
Focus
<static> RandomXY(vector, [scale])
Focus
Focus

Description:

Compute a random unit vector.

Computes random values for the given vector between -1 and 1 that can be used to represent a direction.

Optionally accepts a scale value to scale the resulting vector by.

Parameters:

name type arguments Default description
vector Phaser.Math.Vector2

The Vector to compute random values for.

scale number <optional> 1

The scale of the random values.

Returns:
Description:

The given Vector.

Examples:
Since: 3.0.0
Source: src/math/RandomXY.js (Line 7)
Focus
Focus
<static> RandomXYZ(vec3, [radius])
Focus
Focus

Description:

Compute a random position vector in a spherical area, optionally defined by the given radius.

Parameters:

name type arguments Default description
vec3 Phaser.Math.Vector3

The Vector to compute random values for.

radius number <optional> 1

The radius.

Returns:
Description:

The given Vector.

Examples:
Since: 3.0.0
Source: src/math/RandomXYZ.js (Line 7)
Focus
Focus
<static> RandomXYZW(vec4, [scale])
Focus
Focus

Description:

Compute a random four-dimensional vector.

Parameters:

name type arguments Default description
vec4 Phaser.Math.Vector4

The Vector to compute random values for.

scale number <optional> 1

The scale of the random values.

Returns:
Description:

The given Vector.

Examples:
Since: 3.0.0
Source: src/math/RandomXYZW.js (Line 7)
Focus
Focus
<static> Rotate(point, angle)
Focus
Focus

Description:

Rotate a given point by a given angle around the origin (0, 0), in an anti-clockwise direction.

Parameters:

name type description
point object | Phaser.Geom.Point

The point to be rotated.

angle number

The angle to be rotated by in an anticlockwise direction.

Returns:
Description:

The given point, rotated by the given angle in an anticlockwise direction.

Examples:
Since: 3.0.0
Source: src/math/Rotate.js (Line 7)
Focus
Focus
<static> RotateAround(point, x, y, angle)
Focus
Focus

Description:

Rotate a point around x and y to the given angle, at the same distance.

In polar notation, this maps a point from (r, t) to (r, angle), vs. the origin (x, y).

Parameters:

name type description
point object | Phaser.Geom.Point

The point to be rotated.

x number

The horizontal coordinate to rotate around.

y number

The vertical coordinate to rotate around.

angle number

The angle of rotation in radians.

Returns:
Description:

The given point.

Examples:
Since: 3.0.0
Source: src/math/RotateAround.js (Line 7)
Focus
Focus
<static> RotateAroundDistance(point, x, y, angle, distance)
Focus
Focus

Description:

Rotate a point around x and y by the given angle and distance.

In polar notation, this maps a point from (r, t) to (distance, t + angle), vs. the origin (x, y).

Parameters:

name type description
point object | Phaser.Geom.Point

The point to be rotated.

x number

The horizontal coordinate to rotate around.

y number

The vertical coordinate to rotate around.

angle number

The angle of rotation in radians.

distance number

The distance from (x, y) to place the point at.

Returns:
Description:

The given point.

Examples:
Since: 3.0.0
Focus
Focus
<static> RotateTo(point, x, y, angle, distance)
Focus
Focus

Description:

Position a point at the given angle and distance to (x, y).

Parameters:

name type description
point Phaser.Types.Math.Vector2Like

The point to be positioned.

x number

The horizontal coordinate to position from.

y number

The vertical coordinate to position from.

angle number

The angle of rotation in radians.

distance number

The distance from (x, y) to place the point at.

Returns:
Description:

The given point.

Examples:
Since: 3.24.0
Source: src/math/RotateTo.js (Line 7)
Focus
Focus
<static> RotateVec3(vec, axis, radians)
Focus
Focus

Description:

Rotates a vector in place by axis angle.

This is the same as transforming a point by an axis-angle quaternion, but it has higher precision.

Parameters:

name type description
vec Phaser.Math.Vector3

The vector to be rotated.

axis Phaser.Math.Vector3

The axis to rotate around.

radians number

The angle of rotation in radians.

Returns:
Description:

The given vector.

Examples:
Since: 3.0.0
Source: src/math/RotateVec3.js (Line 15)
Focus
Focus
<static> RoundAwayFromZero(value)
Focus
Focus

Description:

Round a given number so it is further away from zero. That is, positive numbers are rounded up, and negative numbers are rounded down.

Parameters:

name type description
value number

The number to round.

Returns:
Description:

The rounded number, rounded away from zero.

Type:
  • number
Examples:
Since: 3.0.0
Focus
Focus
<static> RoundTo(value, [place], [base])
Focus
Focus

Description:

Round a value to the given precision.

For example:

RoundTo(123.456, 0) = 123
RoundTo(123.456, 1) = 120
RoundTo(123.456, 2) = 100

To round the decimal, i.e. to round to precision, pass in a negative place:

RoundTo(123.456789, 0) = 123
RoundTo(123.456789, -1) = 123.5
RoundTo(123.456789, -2) = 123.46
RoundTo(123.456789, -3) = 123.457

Parameters:

name type arguments Default description
value number

The value to round.

place number <optional> 0

The place to round to. Positive to round the units, negative to round the decimal.

base number <optional> 10

The base to round in. Default is 10 for decimal.

Returns:
Description:

The rounded value.

Type:
  • number
Examples:
Since: 3.0.0
Source: src/math/RoundTo.js (Line 7)
Focus
Focus
<static> SinCosTableGenerator(length, [sinAmp], [cosAmp], [frequency])
Focus
Focus

Description:

Generate a series of sine and cosine values.

Parameters:

name type arguments Default description
length number

The number of values to generate.

sinAmp number <optional> 1

The sine value amplitude.

cosAmp number <optional> 1

The cosine value amplitude.

frequency number <optional> 1

The frequency of the values.

Returns:
Description:

The generated values.

Examples:
Since: 3.0.0
Focus
Focus
<static> SmootherStep(x, min, max)
Focus
Focus

Description:

Calculate a smoother interpolation percentage of x between min and max.

The function receives the number x as an argument and returns 0 if x is less than or equal to the left edge, 1 if x is greater than or equal to the right edge, and smoothly interpolates, using a Hermite polynomial, between 0 and 1 otherwise.

Produces an even smoother interpolation than Phaser.Math.SmoothStep.

Parameters:

name type description
x number

The input value.

min number

The minimum value, also known as the 'left edge', assumed smaller than the 'right edge'.

max number

The maximum value, also known as the 'right edge', assumed greater than the 'left edge'.

Returns:
Description:

The percentage of interpolation, between 0 and 1.

Type:
  • number
Examples:
Since: 3.0.0
Source: src/math/SmootherStep.js (Line 7)
Focus
Focus
<static> SmoothStep(x, min, max)
Focus
Focus

Description:

Calculate a smooth interpolation percentage of x between min and max.

The function receives the number x as an argument and returns 0 if x is less than or equal to the left edge, 1 if x is greater than or equal to the right edge, and smoothly interpolates, using a Hermite polynomial, between 0 and 1 otherwise.

Parameters:

name type description
x number

The input value.

min number

The minimum value, also known as the 'left edge', assumed smaller than the 'right edge'.

max number

The maximum value, also known as the 'right edge', assumed greater than the 'left edge'.

Returns:
Description:

The percentage of interpolation, between 0 and 1.

Type:
  • number
Examples:
Since: 3.0.0
Source: src/math/SmoothStep.js (Line 7)
Focus
Focus
<static> ToXY(index, width, height, [out])
Focus
Focus

Description:

Returns a Vector2 containing the x and y position of the given index in a width x height sized grid.

For example, in a 6 x 4 grid, index 16 would equal x: 4 y: 2.

If the given index is out of range an empty Vector2 is returned.

Parameters:

name type arguments description
index number

The position within the grid to get the x/y value for.

width number

The width of the grid.

height number

The height of the grid.

out Phaser.Math.Vector2 <optional>

An optional Vector2 to store the result in. If not given, a new Vector2 instance will be created.

Returns:
Description:

A Vector2 where the x and y properties contain the given grid index.

Examples:
Since: 3.19.0
Source: src/math/ToXY.js (Line 9)
Focus
Focus
<static> TransformXY(x, y, positionX, positionY, rotation, scaleX, scaleY, [output])
Focus
Focus

Description:

Takes the x and y coordinates and transforms them into the same space as defined by the position, rotation and scale values.

Parameters:

name type arguments description
x number

The x coordinate to be transformed.

y number

The y coordinate to be transformed.

positionX number

Horizontal position of the transform point.

positionY number

Vertical position of the transform point.

rotation number

Rotation of the transform point, in radians.

scaleX number

Horizontal scale of the transform point.

scaleY number

Vertical scale of the transform point.

output object | Phaser.Math.Vector2 | Phaser.Geom.Point <optional>

The output vector, point or object for the translated coordinates.

Returns:
Description:

The translated point.

Examples:
Since: 3.0.0
Source: src/math/TransformXY.js (Line 9)
Focus
Focus
<static> Within(a, b, tolerance)
Focus
Focus

Description:

Checks if the two values are within the given tolerance of each other.

Parameters:

name type description
a number

The first value to use in the calculation.

b number

The second value to use in the calculation.

tolerance number

The tolerance. Anything equal to or less than this value is considered as being within range.

Returns:
Description:

Returns true if a is less than or equal to the tolerance of b.

Type:
  • boolean
Examples:
Since: 3.0.0
Source: src/math/Within.js (Line 7)
Focus
Focus
<static> Wrap(value, min, max)
Focus
Focus

Description:

Wrap the given value between min and `max.

Parameters:

name type description
value number

The value to wrap.

min number

The minimum value.

max number

The maximum value.

Returns:
Description:

The wrapped value.

Type:
  • number
Examples:
Since: 3.0.0
Source: src/math/Wrap.js (Line 7)
Focus
Focus