These archived docs are for Phaser 2.4.3 Phaser 3 docs can be found on newdocs.phaser.io.
Phaser CE docs can be found on the Phaser CE Documentation site.

## Phaser. Math

#### new Math()

A collection of useful mathematical functions.

These are normally accessed through `game.math`.

Source code: math/Math.js (Line 17)
See

### Public Properties

#### <static> PI2

Twice PI.

##### Properties:
Name Type Description
`Phaser.Math#PI2` number
Default Value
• ~6.283
Source code: math/Math.js (Line 24)

### Public Methods

#### angleBetween(x1, y1, x2, y2) → {number}

Find the angle of a segment from (x1, y1) -> (x2, y2).

##### Parameters
Name Type Description
`x1` number
`y1` number
`x2` number
`y2` number
##### Returns
number -

Source code: math/Math.js (Line 282)

#### angleBetweenPoints(point1, point2) → {number}

Find the angle of a segment from (point1.x, point1.y) -> (point2.x, point2.y).

##### Parameters
Name Type Description
`point1` Phaser.Point
`point2` Phaser.Point
##### Returns
number -

Source code: math/Math.js (Line 311)

#### angleBetweenPointsY(point1, point2) → {number}

Find the angle of a segment from (point1.x, point1.y) -> (point2.x, point2.y).

##### Parameters
Name Type Description
`point1` Phaser.Point
`point2` Phaser.Point
##### Returns
number -

Source code: math/Math.js (Line 322)

#### angleBetweenY(x1, y1, x2, y2) → {number}

Find the angle of a segment from (x1, y1) -> (x2, y2). Note that the difference between this method and Math.angleBetween is that this assumes the y coordinate travels down the screen.

##### Parameters
Name Type Description
`x1` number
`y1` number
`x2` number
`y2` number
##### Returns
number -

Source code: math/Math.js (Line 295)

#### average() → {number}

Averages all values passed to the function and returns the result.

##### Returns
number -

The average of all given values.

Source code: math/Math.js (Line 92)

#### <internal> bernstein(n, i) → {number}

##### Parameters
Name Type Description
`n` number
`i` number
##### Returns
number -
Internal:
• This member is internal (protected) and may be modified or removed in the future.
Source code: math/Math.js (Line 701)

#### bezierInterpolation(v, k) → {number}

A Bezier Interpolation Method, mostly used by Phaser.Tween.

##### Parameters
Name Type Description
`v` Array

The input array of values to interpolate between.

`k` number

The percentage of interpolation, between 0 and 1.

##### Returns
number -

The interpolated value

Source code: math/Math.js (Line 626)

#### <internal> catmullRom(p0, p1, p2, p3, t) → {number}

Calculates a catmum rom value.

##### Parameters
Name Type Description
`p0` number
`p1` number
`p2` number
`p3` number
`t` number
##### Returns
number -
Internal:
• This member is internal (protected) and may be modified or removed in the future.
Source code: math/Math.js (Line 735)

#### catmullRomInterpolation(v, k) → {number}

A Catmull Rom Interpolation Method, mostly used by Phaser.Tween.

##### Parameters
Name Type Description
`v` Array

The input array of values to interpolate between.

`k` number

The percentage of interpolation, between 0 and 1.

##### Returns
number -

The interpolated value

Source code: math/Math.js (Line 648)

#### ceilTo(value, place, base) → {number}

##### Parameters
Name Type Description
`value` number

The value to round.

`place` number

The place to round to.

`base` number

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

##### Returns
number -
Source code: math/Math.js (Line 264)

#### chanceRoll(chance) → {boolean}

Generate a random bool result based on the chance value.

Returns true or false based on the chance value (default 50%). For example if you wanted a player to have a 30% chance of getting a bonus, call chanceRoll(30) - true means the chance passed, false means it failed.

##### Parameters
Name Type Description
`chance` number

The chance of receiving the value. A number between 0 and 100 (effectively 0% to 100%).

##### Returns
boolean -

True if the roll passed, or false otherwise.

Source code: utils/Utils.js (Line 77)

#### clamp(x, a, b) → {number}

Force a value within the boundaries by clamping `x` to the range `[a, b]`.

##### Parameters
Name Type Description
`x` number
`a` number
`b` number
##### Returns
number -
Source code: math/Math.js (Line 879)

#### clampBottom(x, a) → {number}

Clamp `x` to the range `[a, Infinity)`. Roughly the same as `Math.max(x, a)`, except for NaN handling.

##### Parameters
Name Type Description
`x` number
`a` number
##### Returns
number -
Source code: math/Math.js (Line 892)

##### Parameters
Name Type Description
`degrees` number

Angle in degrees.

##### Returns
number -

Source code: math/Math.js (Line 1008)

#### difference(a, b) → {number}

The (absolute) difference between two values.

##### Parameters
Name Type Description
`a` number
`b` number
##### Returns
number -
Source code: math/Math.js (Line 755)

#### distance(x1, y1, x2, y2) → {number}

Returns the euclidian distance between the two given set of coordinates.

##### Parameters
Name Type Description
`x1` number
`y1` number
`x2` number
`y2` number
##### Returns
number -

The distance between the two sets of coordinates.

Source code: math/Math.js (Line 821)

#### distancePow(x1, y1, x2, y2, pow) → {number}

Returns the distance between the two given set of coordinates at the power given.

##### Parameters
Name Type Argument Default Description
`x1` number
`y1` number
`x2` number
`y2` number
`pow` number <optional>
2
##### Returns
number -

The distance between the two sets of coordinates.

Source code: math/Math.js (Line 860)

#### distanceSq(x1, y1, x2, y2) → {number}

Returns the euclidean distance squared between the two given set of coordinates (cuts out a square root operation before returning).

##### Parameters
Name Type Description
`x1` number
`y1` number
`x2` number
`y2` number
##### Returns
number -

The distance squared between the two sets of coordinates.

Source code: math/Math.js (Line 840)

#### factorial(value) → {number}

##### Parameters
Name Type Description
`value` number

the number you want to evaluate

##### Returns
number -
Source code: math/Math.js (Line 712)

#### floorTo(value, place, base) → {number}

##### Parameters
Name Type Description
`value` number

The value to round.

`place` number

The place to round to.

`base` number

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

##### Returns
number -
Source code: math/Math.js (Line 246)

#### fuzzyCeil(val, epsilon) → {boolean}

##### Parameters
Name Type Argument Default Description
`val` number
`epsilon` number <optional>
(small value)
##### Returns
boolean -

ceiling(val-epsilon)

Source code: math/Math.js (Line 68)

#### fuzzyEqual(a, b, epsilon) → {boolean}

Two number are fuzzyEqual if their difference is less than epsilon.

##### Parameters
Name Type Argument Default Description
`a` number
`b` number
`epsilon` number <optional>
(small value)
##### Returns
boolean -

True if | a-b | <epsilon

Source code: math/Math.js (Line 26)

#### fuzzyFloor(val, epsilon) → {boolean}

##### Parameters
Name Type Argument Default Description
`val` number
`epsilon` number <optional>
(small value)
##### Returns
boolean -

floor(val-epsilon)

Source code: math/Math.js (Line 80)

#### fuzzyGreaterThan(a, b, epsilon) → {boolean}

`a` is fuzzyGreaterThan `b` if it is more than b - epsilon.

##### Parameters
Name Type Argument Default Description
`a` number
`b` number
`epsilon` number <optional>
(small value)
##### Returns
boolean -

True if a>b+epsilon

Source code: math/Math.js (Line 54)

#### fuzzyLessThan(a, b, epsilon) → {boolean}

`a` is fuzzyLessThan `b` if it is less than b + epsilon.

##### Parameters
Name Type Argument Default Description
`a` number
`b` number
`epsilon` number <optional>
(small value)
##### Returns
boolean -

True if a<b+epsilon

Source code: math/Math.js (Line 40)

#### isEven(n) → {boolean}

Returns true if the number given is even.

##### Parameters
Name Type Description
`n` integer

The number to check.

##### Returns
boolean -

True if the given number is even. False if the given number is odd.

Source code: math/Math.js (Line 448)

#### isOdd(n) → {boolean}

Returns true if the number given is odd.

##### Parameters
Name Type Description
`n` integer

The number to check.

##### Returns
boolean -

True if the given number is odd. False if the given number is even.

Source code: math/Math.js (Line 436)

#### linear(p0, p1, t) → {number}

Calculates a linear (interpolation) value over t.

##### Parameters
Name Type Description
`p0` number
`p1` number
`t` number
##### Returns
number -
Source code: math/Math.js (Line 688)

#### linearInterpolation(v, k) → {number}

A Linear Interpolation Method, mostly used by Phaser.Tween.

##### Parameters
Name Type Description
`v` Array

The input array of values to interpolate between.

`k` number

The percentage of interpolation, between 0 and 1.

##### Returns
number -

The interpolated value

Source code: math/Math.js (Line 598)

#### mapLinear(x, a1, a2, b1, b2) → {number}

Linear mapping from range to range

##### Parameters
Name Type Description
`x` number

the value to map

`a1` number

first endpoint of the range

`a2` number

final endpoint of the range

`b1` number

first endpoint of the range

`b2` number

final endpoint of the range

##### Returns
number -
Source code: math/Math.js (Line 919)

#### max() → {number}

Variation of Math.max that can be passed either an array of numbers or the numbers as parameters.

Prefer the standard `Math.max` function when appropriate.

##### Returns
number -

The largest value from those given.

Source code: math/Math.js (Line 492)
See

#### maxAdd(value, amount, max) → {number}

Adds the given amount to the value, but never lets the value go over the specified maximum.

##### Parameters
Name Type Description
`value` number

The value to add the amount to.

`amount` number

The amount to add to the value.

`max` number

The maximum the value is allowed to be.

##### Returns
number -
Source code: math/Math.js (Line 356)

#### maxProperty() → {number}

Variation of Math.max that can be passed a property and either an array of objects or the objects as parameters. It will find the largest matching property value from the given objects.

##### Returns
number -

The largest value from those given.

Source code: math/Math.js (Line 554)

#### min() → {number}

Variation of Math.min that can be passed either an array of numbers or the numbers as parameters.

Prefer the standard `Math.min` function when appropriate.

##### Returns
number -

The lowest value from those given.

Source code: math/Math.js (Line 460)
See

#### minProperty() → {number}

Variation of Math.min that can be passed a property and either an array of objects or the objects as parameters. It will find the lowest matching property value from the given objects.

##### Returns
number -

The lowest value from those given.

Source code: math/Math.js (Line 524)

#### minSub(value, amount, min) → {number}

Subtracts the given amount from the value, but never lets the value go below the specified minimum.

##### Parameters
Name Type Description
`value` number

The base value.

`amount` number

The amount to subtract from the base value.

`min` number

The minimum the value is allowed to be.

##### Returns
number -

The new value.

Source code: math/Math.js (Line 369)

Normalizes an angle to the [0,2pi) range.

##### Parameters
Name Type Description
`angleRad` number

The angle to normalize, in radians.

##### Returns
number -

Returns the angle, fit within the [0,2pi] range, in radians.

Source code: math/Math.js (Line 343)

#### percent(a, b, base) → {number}

Work out what percentage value `a` is of value `b` using the given base.

##### Parameters
Name Type Argument Default Description
`a` number

The value to work out the percentage for.

`b` number

The value you wish to get the percentage of.

`base` number <optional>
0

The base value.

##### Returns
number -

The percentage a is of b, between 0 and 1.

Source code: math/Math.js (Line 975)

##### Parameters
Name Type Description
`radians` number

##### Returns
number -

Angle in degrees

Source code: math/Math.js (Line 1019)

Reverses an angle.

##### Parameters
Name Type Description
`angleRad` number

The angle to reverse, in radians.

##### Returns
number -

Returns the reverse angle, in radians.

Source code: math/Math.js (Line 333)

#### roundAwayFromZero(value) → {integer}

Round to the next whole number away from zero.

##### Parameters
Name Type Description
`value` number

Any number.

##### Returns
integer -

The rounded value of that number.

Source code: math/Math.js (Line 767)

#### roundTo(value, place, base) → {number}

Round 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.

``````e.g. 2000/7 ~= 285.714285714285714285714 ~= (bin)100011101.1011011011011011

roundTo(2000/7,3) === 0
roundTo(2000/7,2) == 300
roundTo(2000/7,1) == 290
roundTo(2000/7,0) == 286
roundTo(2000/7,-1) == 285.7
roundTo(2000/7,-2) == 285.71
roundTo(2000/7,-3) == 285.714
roundTo(2000/7,-4) == 285.7143
roundTo(2000/7,-5) == 285.71429

roundTo(2000/7,3,2)  == 288       -- 100100000
roundTo(2000/7,2,2)  == 284       -- 100011100
roundTo(2000/7,1,2)  == 286       -- 100011110
roundTo(2000/7,0,2)  == 286       -- 100011110
roundTo(2000/7,-1,2) == 285.5     -- 100011101.1
roundTo(2000/7,-2,2) == 285.75    -- 100011101.11
roundTo(2000/7,-3,2) == 285.75    -- 100011101.11
roundTo(2000/7,-4,2) == 285.6875  -- 100011101.1011
roundTo(2000/7,-5,2) == 285.71875 -- 100011101.10111``````

Note what occurs when we round to the 3rd space (8ths place), 100100000, this is to be assumed because we are rounding 100011.1011011011011011 which rounds up.

##### Parameters
Name Type Description
`value` number

The value to round.

`place` number

The place to round to.

`base` number

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

##### Returns
number -
Source code: math/Math.js (Line 200)

#### shear(n) → {number}

##### Parameters
Name Type Description
`n` number
##### Returns
number -

n mod 1

Source code: math/Math.js (Line 111)

#### sign(x) → {integer}

A value representing the sign of the value: -1 for negative, +1 for positive, 0 if value is 0.

This works differently from `Math.sign` for values of NaN and -0, etc.

##### Parameters
Name Type Description
`x` number
##### Returns
integer -

An integer in {-1, 0, 1}

Source code: math/Math.js (Line 962)

#### sinCosGenerator(length, sinAmplitude, cosAmplitude, frequency) → {Object}

Generate a sine and cosine table simultaneously and extremely quickly. The parameters allow you to specify the length, amplitude and frequency of the wave. This generator is fast enough to be used in real-time. Code based on research by Franky of scene.at

##### Parameters
Name Type Description
`length` number

The length of the wave

`sinAmplitude` number

The amplitude to apply to the sine table (default 1.0) if you need values between say -+ 125 then give 125 as the value

`cosAmplitude` number

The amplitude to apply to the cosine table (default 1.0) if you need values between say -+ 125 then give 125 as the value

`frequency` number

The frequency of the sine and cosine table data

##### Returns
Object -

Returns the table data.

Source code: math/Math.js (Line 781)

#### smootherstep(x, min, max) → {number}

Smootherstep function as detailed at http://en.wikipedia.org/wiki/Smoothstep

##### Parameters
Name Type Description
`x` number
`min` number
`max` number
##### Returns
number -
Source code: math/Math.js (Line 948)

#### smoothstep(x, min, max) → {number}

Smoothstep function as detailed at http://en.wikipedia.org/wiki/Smoothstep

##### Parameters
Name Type Description
`x` number
`min` number
`max` number
##### Returns
number -
Source code: math/Math.js (Line 934)

#### snapTo(input, gap, start) → {number}

Snap a value to nearest grid slice, using rounding.

Example: if you have an interval gap of 5 and a position of 12... you will snap to 10 whereas 14 will snap to 15.

##### Parameters
Name Type Argument Description
`input` number

The value to snap.

`gap` number

The interval gap of the grid.

`start` number <optional>

Optional starting offset for gap.

##### Returns
number -
Source code: math/Math.js (Line 120)

#### snapToCeil(input, gap, start) → {number}

Snap a value to nearest grid slice, using ceil.

Example: if you have an interval gap of 5 and a position of 12... you will snap to 15. As will 14 will snap to 15... but 16 will snap to 20.

##### Parameters
Name Type Argument Description
`input` number

The value to snap.

`gap` number

The interval gap of the grid.

`start` number <optional>

Optional starting offset for gap.

##### Returns
number -
Source code: math/Math.js (Line 173)

#### snapToFloor(input, gap, start) → {number}

Snap a value to nearest grid slice, using floor.

Example: if you have an interval gap of 5 and a position of 12... you will snap to 10. As will 14 snap to 10... but 16 will snap to 15.

##### Parameters
Name Type Argument Description
`input` number

The value to snap.

`gap` number

The interval gap of the grid.

`start` number <optional>

Optional starting offset for gap.

##### Returns
number -
Source code: math/Math.js (Line 146)

#### within(a, b, tolerance) → {boolean}

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

##### Parameters
Name Type Description
`a` number

The first number to check

`b` number

The second number to check

`tolerance` number

The tolerance. Anything equal to or less than this is considered within the range.

##### Returns
boolean -

True if a is <= tolerance of b.

Source code: math/Math.js (Line 905)
See
• Phaser.Math.fuzzyEqual

#### wrap(value, min, max) → {number}

Ensures that the value always stays between min and max, by wrapping the value around.

If `max` is not larger than `min` the result is 0.

##### Parameters
Name Type Description
`value` number

The value to wrap.

`min` number

The minimum the value is allowed to be.

`max` number

The maximum the value is allowed to be, should be larger than `min`.

##### Returns
number -

The wrapped value.

Source code: math/Math.js (Line 382)

Keeps an angle value between -180 and +180; or -PI and PI if radians.

##### Parameters
Name Type Argument Default Description
`angle` number

The angle value to wrap

`radians` boolean <optional>
false

Set to `true` if the angle is given in radians, otherwise degrees is expected.

##### Returns
number -

The new angle value; will be the same as the input angle if it was within bounds.

Source code: math/Math.js (Line 584)

#### wrapValue(value, amount, max) → {number}

Adds value to amount and ensures that the result always stays between 0 and max, by wrapping the value around.

Values must be positive integers, and are passed through Math.abs. See Phaser.Math#wrap for an alternative.

##### Parameters
Name Type Description
`value` number

The value to add the amount to.

`amount` number

The amount to add to the value.

`max` number

The maximum the value is allowed to be.

##### Returns
number -

The wrapped value.

Source code: math/Math.js (Line 413)