Phaser Class: Math

new Math()

A collection of mathematical methods.

Source:

math/Math.js, line 3

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

Source:

math/Math.js, line 329

Returns:

Type: number

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

Source:

math/Math.js, line 358

Returns:

Type: number

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

Source:

math/Math.js, line 369

Returns:

Type: number

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

Source:

math/Math.js, line 342

Returns:

Type: number

angleLimit(angle, min, max) → {number}

Keeps an angle value between the given min and max values.

Parameters:

Name	Type	Description
`angle`	number	The angle value to check. Must be between -180 and +180.
`min`	number	The minimum angle that is allowed (must be -180 or greater).
`max`	number	The maximum angle that is allowed (must be 180 or less).

Source:

math/Math.js, line 902

Returns:

The new angle value, returns the same as the input angle if it was within bounds

Type: number

average() → {number}

Averages all values passed to the function and returns the result. You can pass as many parameters as you like.

Source:

math/Math.js, line 81

Returns:

The average of all given values.

Type: number

bernstein(n, i) → {number}

Parameters:

Name	Type	Description
`n`	number
`i`	number

Source:

math/Math.js, line 1028

Returns:

Type: number

bezierInterpolation(v, k) → {number}

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

Parameters:

Name	Type	Description
`v`	Array
`k`	number

Source:

math/Math.js, line 955

Returns:

Type: number

catmullRom(p0, p1, p2, p3, t) → {number}

Description.

Parameters:

Name	Type	Description
`p0`	number
`p1`	number
`p2`	number
`p3`	number
`t`	number

Source:

math/Math.js, line 1060

Returns:

Type: number

catmullRomInterpolation(v, k) → {number}

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

Parameters:

Name	Type	Description
`v`	Array
`k`	number

Source:

math/Math.js, line 976

Returns:

Type: number

ceil(value) → {number}

Round up to the next whole number. E.g. ceil(1.3) == 2, and ceil(-2.3) == -3.

Parameters:

Name	Type	Description
`value`	number	Any number.

Source:

math/Math.js, line 1173

Returns:

The rounded value of that number.

Type: number

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.

Source:

math/Math.js, line 299

Returns:

Type: number

chanceRoll(chance) → {boolean}

Generate a random bool result based on the chance value.

<p> 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. </p>

Parameters:

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

Source:

math/Math.js, line 435

Returns:

True if the roll passed, or false otherwise.

Type: boolean

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

Force a value within the boundaries of two values. Clamp value to range <a, b>

Parameters:

Name	Type	Description
`x`	number
`a`	number
`b`	number

Source:

math/Math.js, line 1316

Returns:

Type: number

clampBottom(x, a) → {number}

Clamp value to range <a, inf).

Parameters:

Name	Type	Description
`x`	number
`a`	number

Source:

math/Math.js, line 1332

Returns:

Type: number

degToRad() → {function}

Convert degrees to radians.

Source:

math/Math.js, line 1452

Returns:

Type: function

difference(a, b) → {number}

Parameters:

Name	Type	Description
`a`	number
`b`	number

Source:

math/Math.js, line 1078

Returns:

Type: number

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

Returns the distance between the two given set of coordinates.

Parameters:

Name	Type	Description
`x1`	number
`y1`	number
`x2`	number
`y2`	number

Source:

math/Math.js, line 1262

Returns:

The distance between the two sets of coordinates.

Type: number

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
`x1`	number
`y1`	number
`x2`	number
`y2`	number
`pow`	number	<optional>	2

Source:

math/Math.js, line 1281

Returns:

The distance between the two sets of coordinates.

Type: number

distanceRounded(x1, y1, x2, y2) → {number}

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

Parameters:

Name	Type	Description
`x1`	number
`y1`	number
`x2`	number
`y2`	number

Source:

math/Math.js, line 1300

Returns:

The distance between this Point object and the destination Point object.

Type: number

factorial(value) → {number}

Parameters:

Name	Type	Description
`value`	number	the number you want to evaluate

Source:

math/Math.js, line 1038

Returns:

Type: number

floor(Value) → {number}

Round down to the next whole number. E.g. floor(1.7) == 1, and floor(-2.7) == -2.

Parameters:

Name	Type	Description
`Value`	number	Any number.

Source:

math/Math.js, line 1158

Returns:

The rounded value of that number.

Type: number

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.

Source:

math/Math.js, line 281

Returns:

Type: number

fuzzyCeil(val, epsilon) → {boolean}

Parameters:

Name	Type	Description
`val`	number
`epsilon`	number

Source:

math/Math.js, line 59

Returns:

ceiling(val-ε)

Type: boolean

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

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

Parameters:

Name	Type	Description
`a`	number
`b`	number
`epsilon`	number

Source:

math/Math.js, line 20

Returns:

True if |a-b|<ε

Type: boolean

fuzzyFloor(val, epsilon) → {boolean}

Parameters:

Name	Type	Description
`val`	number
`epsilon`	number

Source:

math/Math.js, line 70

Returns:

floor(val-ε)

Type: boolean

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

a is fuzzyGreaterThan b if it is more than b - ε.

Parameters:

Name	Type	Description
`a`	number
`b`	number
`epsilon`	number

Source:

math/Math.js, line 46

Returns:

True if a>b+ε

Type: boolean

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

a is fuzzyLessThan b if it is less than b + ε.

Parameters:

Name	Type	Description
`a`	number
`b`	number
`epsilon`	number

Source:

math/Math.js, line 33

Returns:

True if a<b+ε

Type: boolean

getRandom(objects, startIndex, length) → {object}

Fetch a random entry from the given array. Will return null if random selection is missing, or array has no entries.

Parameters:

Name	Type	Description
`objects`	array	An array of objects.
`startIndex`	number	Optional offset off the front of the array. Default value is 0, or the beginning of the array.
`length`	number	Optional restriction on the number of values you want to randomly select from.

Source:

math/Math.js, line 1088

Returns:

The random object that was selected.

Type: object

interpolateAngles(a1, a2, weight, radians, ease) → {number}

Interpolate across the shortest arc between two angles.

Parameters:

Name	Type	Description
`a1`	number	Description.
`a2`	number	Description.
`weight`	number	Description.
`radians`	boolean	True if angle sizes are expressed in radians.
`ease`	Description	Description.

Source:

math/Math.js, line 433

Returns:

interpolateAngles: function (a1, a2, weight, radians, ease) {

    if (typeof radians === "undefined") { radians = true; }
    if (typeof ease === "undefined") { ease = null; }

    a1 = this.normalizeAngle(a1, radians);
    a2 = this.normalizeAngleToAnother(a2, a1, radians);

    return (typeof ease === 'function') ? ease(weight, a1, a2 - a1, 1) : this.interpolateFloat(a1, a2, weight);

},

Type: number

interpolateFloat(a, b, weight) → {number}

A one dimensional linear interpolation of a value.

Parameters:

Name	Type	Description
`a`	number
`b`	number
`weight`	number

Source:

math/Math.js, line 317

Returns:

Type: number

isEven(n) → {boolean}

Returns true if the number given is even.

Parameters:

Name	Type	Description
`n`	number	The number to check.

Source:

math/Math.js, line 748

Returns:

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

Type: boolean

isOdd(n) → {boolean}

Returns true if the number given is odd.

Parameters:

Name	Type	Description
`n`	number	The number to check.

Source:

math/Math.js, line 735

Returns:

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

Type: boolean

limitValue(value, min, max) → {number}

Ensures the given value is between min and max inclusive.

Parameters:

Name	Type	Description
`value`	number	The value to limit.
`min`	number	The minimum the value can be.
`max`	number	The maximum the value can be.

Source:

math/Math.js, line 708

Returns:

The limited value.

Type: number

Linear(p0, p1, t) → {number}

Description.

Parameters:

Name	Type	Description
`p0`	number
`p1`	number
`t`	number

Source:

math/Math.js, line 1016

Returns:

Type: number

linearInterpolation(v, k) → {number}

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

Parameters:

Name	Type	Description
`v`	Array
`k`	number

Source:

math/Math.js, line 928

Returns:

Type: number

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

Linear mapping from range <a1, a2> to range <b1, b2>

Parameters:

Name	Type	Description
`x`	number	the value to map
`a1`	number	first endpoint of the range <a1, a2>
`a2`	number	final endpoint of the range <a1, a2>
`b1`	number	first endpoint of the range <b1, b2>
`b2`	number	final endpoint of the range <b1, b2>

Source:

math/Math.js, line 1361

Returns:

Type: number

max() → {number}

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

Source:

math/Math.js, line 798

Returns:

The largest value from those given.

Type: number

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.

Source:

math/Math.js, line 612

Returns:

Type: number

maxProperty() → {number}

Updated version 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.

Source:

math/Math.js, line 857

Returns:

The largest value from those given.

Type: number

min() → {number}

Updated version of Math.min that can be passed either an array of numbers or the numbers as parameters. See http://jsperf.com/math-s-min-max-vs-homemade/5

Source:

math/Math.js, line 768

Returns:

The lowest value from those given.

Type: number

minProperty() → {number}

Updated version 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.

Source:

math/Math.js, line 827

Returns:

The lowest value from those given.

Type: number

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.

Source:

math/Math.js, line 634

Returns:

The new value.

Type: number

nearestAngleBetween(a1, a2, radians) → {number}

Closest angle between two angles from a1 to a2 absolute value the return for exact angle

Parameters:

Name	Type	Description
`a1`	number
`a2`	number
`radians`	boolean	True if angle sizes are expressed in radians.

Source:

math/Math.js, line 431

Returns:

nearestAngleBetween: function (a1, a2, radians) {

    if (typeof radians === "undefined") { radians = true; }

    var rd = (radians) ? Math.PI : 180;
    a1 = this.normalizeAngle(a1, radians);
    a2 = this.normalizeAngle(a2, radians);

    if (a1 < -rd / 2 && a2 > rd / 2)
    {
        a1 += rd * 2;
    }

    if (a2 < -rd / 2 && a1 > rd / 2)
    {
        a2 += rd * 2;
    }

    return a2 - a1;

},

Type: number

normalizeAngle(angleRad) → {number}

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

Parameters:

Name	Type	Description
`angleRad`	number	The angle to normalize, in radians.

Source:

math/Math.js, line 390

Returns:

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

Type: number

normalizeLatitude(lat) → {number}

Normalizes a latitude to the [-90,90] range. Latitudes above 90 or below -90 are capped, not wrapped.

Parameters:

Name	Type	Description
`lat`	number	The latitude to normalize, in degrees.

Source:

math/Math.js, line 403

Returns:

Returns the latitude, fit within the [-90,90] range.

Type: number

normalizeLongitude(lng) → {number}

Normalizes a longitude to the [-180,180] range. Longitudes above 180 or below -180 are wrapped.

Parameters:

Name	Type	Description
`lng`	number	The longitude to normalize, in degrees.

Source:

math/Math.js, line 413

Returns:

Returns the longitude, fit within the [-180,180] range.

Type: number

numberArray(min, max) → {array}

Returns an Array containing the numbers from min to max and inclusive of both values. If you need exclusive of max then see Phaser.Math.numberArrayEx.

Parameters:

Name	Type	Description
`min`	number	The minimum value the array starts with.
`max`	number	The maximum value the array contains.

Source:

math/Math.js, line 519

Returns:

The array of number values.

Type: array

numberArrayStep(start, end, step) → {Array}

Creates an array of numbers (positive and/or negative) progressing from start up to but not including end. If start is less than stop a zero-length range is created unless a negative step is specified.

Parameters:

Name	Type	Argument	Default	Description
`start`	number	<optional>	0	The start of the range.
`end`	number			The end of the range.
`step`	number	<optional>	1	The value to increment or decrement by.

Source:

math/Math.js, line 541

Returns:

Returns the new array of numbers.

Type: Array

Example

Phaser.Math.numberArrayStep(4);
// => [0, 1, 2, 3]

Phaser.Math.numberArrayStep(1, 5);
// => [1, 2, 3, 4]

Phaser.Math.numberArrayStep(0, 20, 5);
// => [0, 5, 10, 15]

Phaser.Math.numberArrayStep(0, -4, -1);
// => [0, -1, -2, -3]

Phaser.Math.numberArrayStep(1, 4, 0);
// => [1, 1, 1]

Phaser.Math.numberArrayStep(0);
// => []

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.

Source:

math/Math.js, line 1424

Returns:

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

Type: number

PI2()

= 2 π

Source:

math/Math.js, line 14

radToDeg() → {function}

Convert degrees to radians.

Source:

math/Math.js, line 1470

Returns:

Type: function

randomSign() → {number}

Randomly returns either a 1 or -1.

Source:

math/Math.js, line 723

Returns:

1 or -1

Type: number

removeRandom(objects, startIndex, length) → {object}

Removes a random object from the given array and returns it. Will return null if random selection is missing, or array has no entries.

Parameters:

Name	Type	Description
`objects`	array	An array of objects.
`startIndex`	number	Optional offset off the front of the array. Default value is 0, or the beginning of the array.
`length`	number	Optional restriction on the number of values you want to randomly select from.

Source:

math/Math.js, line 1122

Returns:

The random object that was removed.

Type: object

reverseAngle(angleRad) → {number}

Reverses an angle.

Parameters:

Name	Type	Description
`angleRad`	number	The angle to reverse, in radians.

Source:

math/Math.js, line 380

Returns:

Returns the reverse angle, in radians.

Type: number

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

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

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

Source:

math/Math.js, line 234

Returns:

Type: number

shear(n) → {number}

Parameters:

Name	Type	Description
`n`	number

Source:

math/Math.js, line 113

Returns:

n mod 1

Type: number

shift(stack) → {any}

Removes the top element from the stack and re-inserts it onto the bottom, then returns it. The original stack is modified in the process. This effectively moves the position of the data from the start to the end of the table.

Parameters:

Name	Type	Description
`stack`	array	The array to shift.

Source:

math/Math.js, line 1225

Returns:

The shifted value.

Type: any

shuffleArray(array) → {array}

Shuffles the data in the given array into a new order

Parameters:

Name	Type	Description
`array`	array	The array to shuffle

Source:

math/Math.js, line 1242

Returns:

The array

Type: array

sign(x) → {number}

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

Parameters:

Name	Type	Description
`x`	number

Source:

math/Math.js, line 1410

Returns:

Type: number

sinCosGenerator(length, sinAmplitude, cosAmplitude, frequency) → {Array}

Generate a sine and cosine table simultaneously and extremely quickly. Based on research by Franky of scene.at

<p> The parameters allow you to specify the length, amplitude and frequency of the wave. Once you have called this function you should get the results via getSinTable() and getCosTable(). This generator is fast enough to be used in real-time. </p>

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

Source:

math/Math.js, line 1185

Returns:

Returns the sine table

Type: Array

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

Source:

math/Math.js, line 1394

Returns:

Type: number

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

Source:

math/Math.js, line 1378

Returns:

Type: number

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.

Source:

math/Math.js, line 122

Returns:

Type: number

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.

Source:

math/Math.js, line 174

Returns:

Type: number

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.

Source:

math/Math.js, line 148

Returns:

Type: number

snapToInArray(input, arr, sort) → {number}

Snaps a value to the nearest value in an array.

Parameters:

Name	Type	Description
`input`	number
`arr`	array
`sort`	boolean	True if the array needs to be sorted.

Source:

math/Math.js, line 201

Returns:

Type: number

truncate(n) → {number}

Parameters:

Name	Type	Description
`n`	number

Source:

math/Math.js, line 104

Returns:

Type: number

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.

Source:

math/Math.js, line 1346

Returns:

True if a is <= tolerance of b.

Type: boolean

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

Ensures that the value always stays between min and max, by wrapping the value around. max should be larger than min, or the function will return 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.

Source:

math/Math.js, line 656

Returns:

The wrapped value.

Type: number

wrapAngle(angle, radians) → {number}

Keeps an angle value between -180 and +180.

Parameters:

Name	Type	Description
`angle`	number	The angle value to check
`radians`	boolean	True if angle is given in radians.

Source:

math/Math.js, line 887

Returns:

The new angle value, returns the same as the input angle if it was within bounds.

Type: number

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.

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.

Source:

math/Math.js, line 686

Returns:

The wrapped value.

Type: number