Phaser.Math - 2.6.2

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	The x coordinate of the first value.
`y1`	number	The y coordinate of the first value.
`x2`	number	The x coordinate of the second value.
`y2`	number	The y coordinate of the second value.

Returns

number -

The angle, in radians.

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

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	The first point.
`point2`	Phaser.Point	The second point.

Returns

number -

The angle between the two points, in radians.

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

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 -

The angle, in radians.

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

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

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

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	The x coordinate of the first value.
`y1`	number	The y coordinate of the first value.
`x2`	number	The x coordinate of the second value.
`y2`	number	The y coordinate of the second value.

Returns

number -

The angle, in radians.

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

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 123)

<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 846)

between(min, max) → {number}

Returns a number between the min and max values.

Parameters

Name	Type	Description
`min`	number	The minimum value. Must be positive, and less than 'max'.
`max`	number	The maximum value. Must be position, and greater than 'min'.

Returns

number -

A value between the range min to max.

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

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 769)

<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 882)

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 791)

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

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	Argument	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

number -

The rounded value.

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

clamp(v, min, max) → {number}

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

Parameters

Name	Type	Description
`v`	float	The value to be clamped.
`min`	float	The minimum bounds.
`max`	float	The maximum bounds.

Returns

number -

The clamped value.

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

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 1054)

degToRad(degrees) → {number}

Convert degrees to radians.

Parameters

Name	Type	Description
`degrees`	number	Angle in degrees.

Returns

number -

Angle in radians.

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

difference(a, b) → {number}

The absolute difference between two values.

Parameters

Name	Type	Description
`a`	number	The first value to check.
`b`	number	The second value to check.

Returns

number -

The absolute difference between the two values.

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

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 970)

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

Returns

number -

The distance between the two sets of coordinates.

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

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 989)

factorial(value) → {number}

Parameters

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

Returns

number -

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

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

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	Argument	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

number -

The rounded value.

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

fuzzyCeil(val, epsilon) → {number}

Applies a fuzzy ceil to the given value.

Parameters

Name	Type	Argument	Default	Description
`val`	number			The value to ceil.
`epsilon`	number	<optional>	0.0001	The epsilon (a small value used in the calculation)

Returns

number -

ceiling(val-epsilon)

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

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

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

Parameters

Name	Type	Argument	Default	Description
`a`	number			The first number to compare.
`b`	number			The second number to compare.
`epsilon`	number	<optional>	0.0001	The epsilon (a small value used in the calculation)

Returns

boolean -

True if | a-b | <epsilon

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

fuzzyFloor(val, epsilon) → {number}

Applies a fuzzy floor to the given value.

Parameters

Name	Type	Argument	Default	Description
`val`	number			The value to floor.
`epsilon`	number	<optional>	0.0001	The epsilon (a small value used in the calculation)

Returns

number -

floor(val+epsilon)

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

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

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

Parameters

Name	Type	Argument	Default	Description
`a`	number			The first number to compare.
`b`	number			The second number to compare.
`epsilon`	number	<optional>	0.0001	The epsilon (a small value used in the calculation)

Returns

boolean -

True if a>b+epsilon

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

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

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

Parameters

Name	Type	Argument	Default	Description
`a`	number			The first number to compare.
`b`	number			The second number to compare.
`epsilon`	number	<optional>	0.0001	The epsilon (a small value used in the calculation)

Returns

boolean -

True if a<b+epsilon

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

getShortestAngle(angle1, angle2) → {number}

Gets the shortest angle between angle1 and angle2.
Both angles must be in the range -180 to 180, which is the same clamped
range that sprite.angle uses, so you can pass in two sprite angles to
this method, and get the shortest angle back between the two of them.

The angle returned will be in the same range. If the returned angle is
greater than 0 then it's a counter-clockwise rotation, if < 0 then it's
a clockwise rotation.

Parameters

Name	Type	Description
`angle1`	number	The first angle. In the range -180 to 180.
`angle2`	number	The second angle. In the range -180 to 180.

Returns

number -

The shortest angle, in degrees. If greater than zero it's a counter-clockwise rotation.

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

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 589)

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 575)

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

Calculates a linear (interpolation) value over t.

Parameters

Name	Type	Description
`p0`	number
`p1`	number
`t`	number	A value between 0 and 1.

Returns

number -

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

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 741)

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 1085)

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 635)

See

http://jsperf.com/math-s-min-max-vs-homemade

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 -

The new value.

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

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 697)

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 603)

See

http://jsperf.com/math-s-min-max-vs-homemade

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 667)

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 506)

normalizeAngle(angleRad) → {number}

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

Parameters

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

Returns

number -

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

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

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 1153)

radToDeg(radians) → {number}

Convert radians to degrees.

Parameters

Name	Type	Description
`radians`	number	Angle in radians.

Returns

number -

Angle in degrees

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

reverseAngle(angleRad) → {number}

Reverses an angle.

Parameters

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

Returns

number -

The reverse angle, in radians.

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

rotateToAngle(currentAngle, targetAngle, lerp) → {number}

Rotates currentAngle towards targetAngle, taking the shortest rotation distance.
The lerp argument is the amount to rotate by in this call.

Parameters

Name	Type	Argument	Default	Description
`currentAngle`	number			The current angle, in radians.
`targetAngle`	number			The target angle to rotate to, in radians.
`lerp`	number	<optional>	0.05	The lerp value to add to the current angle.

Returns

number -

The adjusted angle.

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

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 916)

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	Argument	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

number -

The rounded value.

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

shear(n) → {number}

Parameters

Name	Type	Description
`n`	number

Returns

number -

n mod 1

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

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 1138)

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 930)

smootherstep(x, min, max) → {float}

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

Parameters

Name	Type	Description
`x`	float	The input value.
`min`	float	The left edge. Should be smaller than the right edge.
`max`	float	The right edge.

Returns

float -

A value between 0 and 1.

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

smoothstep(x, min, max) → {float}

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

Parameters

Name	Type	Description
`x`	float	The input value.
`min`	float	The left edge. Should be smaller than the right edge.
`max`	float	The right edge.

Returns

float -

A value between 0 and 1.

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

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	Default	Description
`input`	number			The value to snap.
`gap`	number			The interval gap of the grid.
`start`	number	<optional>	0	Optional starting offset for gap.

Returns

number -

The snapped value.

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

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	Default	Description
`input`	number			The value to snap.
`gap`	number			The interval gap of the grid.
`start`	number	<optional>	0	Optional starting offset for gap.

Returns

number -

The snapped value.

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

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	Default	Description
`input`	number			The value to snap.
`gap`	number			The interval gap of the grid.
`start`	number	<optional>	0	Optional starting offset for gap.

Returns

number -

The snapped value.

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

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 1069)

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 521)

wrapAngle(angle, radians) → {number}

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 727)

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 552)

Navigation

Constructor

new Math()

Public Properties

<static> PI2

Properties:

Public Methods

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

Parameters

Returns

angleBetweenPoints(point1, point2) → {number}

Parameters

Returns

angleBetweenPointsY(point1, point2) → {number}

Parameters

Returns

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

Parameters

Returns

average() → {number}

Returns

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

Parameters

Returns

between(min, max) → {number}

Parameters

Returns

bezierInterpolation(v, k) → {number}

Parameters

Returns

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

Parameters

Returns

catmullRomInterpolation(v, k) → {number}

Parameters

Returns

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

Parameters

Returns

clamp(v, min, max) → {number}

Parameters

Returns

clampBottom(x, a) → {number}

Parameters

Returns

degToRad(degrees) → {number}

Parameters

Returns

difference(a, b) → {number}

Parameters

Returns

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

Parameters

Returns

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

Parameters

Returns

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

Parameters

Returns

factorial(value) → {number}

Parameters

Returns

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

Parameters

Returns

fuzzyCeil(val, epsilon) → {number}

Parameters

Returns

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

Parameters

Returns

fuzzyFloor(val, epsilon) → {number}

Parameters

Returns

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

Parameters

Returns

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

Parameters