Phaser CE Class: Math

new Math()

A collection of useful mathematical functions.

These are normally accessed through game.math.

Source:

src/math/Math.js line 17

See:

Members

<static> DEG_TO_RAD

Degrees to Radians factor.

Source:: src/math/Math.js line 37

<static> HALF_PI

Name	Type	Description
`Phaser.Math#DEG_TO_RAD`	number

Half PI.

Properties:

Name	Type	Description
`Phaser.Math#HALF_PI`	number

Default Value:

~1.570

Source:

src/math/Math.js line 31

<static> PI2

Twice PI.

Properties:

Name	Type	Description
`Phaser.Math#PI2`	number

Default Value:

~6.283

Source:

src/math/Math.js line 24

<static> RAD_TO_DEG

Degrees to Radians factor.

Source:: src/math/Math.js line 43

Name	Type	Description
`Phaser.Math#RAD_TO_DEG`	number

Methods

angleBetween(x1, y1, x2, y2)

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.

Source:: src/math/Math.js line 541

Returns:

The angle, in radians.

Type: number

angleBetweenPoints(point1, point2)

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.

Source:: src/math/Math.js line 574

Returns:

The angle between the two points, in radians.

Type: number

angleBetweenPointsY(point1, point2)

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:: src/math/Math.js line 587

Returns:

The angle, in radians.

Type: number

angleBetweenY(x1, y1, x2, y2)

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.

Source:: src/math/Math.js line 556

Returns:

The angle, in radians.

Type: number

average()

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

Source:: src/math/Math.js line 249

Returns:

The average of all given values.

Type: number

<protected> bernstein(n, i)

Parameters:

Name	Type	Description
`n`	number
`i`	number

Source:: src/math/Math.js line 962

Returns:

Type: number

between(min, max)

Returns a random integer in the range [min, max]. If these parameters are not in order than they will be put in order. Default is 0 for min and 1 for max.

Parameters:

Name	Type	Description
`min`	number	The minimum value. Must be a Number.
`max`	number	The maximum value. Must be a Number.

Source:: src/math/Math.js line 139

Returns:

An integer between min (inclusive) and max (inclusive).

Type: number

bezierInterpolation(v, k)

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.

Source:: src/math/Math.js line 888

Returns:

The interpolated value

Type: number

<protected> catmullRom(p0, p1, p2, p3, t)

Calculates a catmum rom value.

Parameters:

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

Source:: src/math/Math.js line 996

Returns:

Type: number

catmullRomInterpolation(v, k)

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.

Source:: src/math/Math.js line 909

Returns:

The interpolated value

Type: number

ceilTo(value [, place] [, base])

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.

Source:: src/math/Math.js line 424

Returns:

The rounded value.

Type: number

clamp(v, min, max)

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.

Source:: src/math/Math.js line 1150

Returns:

The clamped value.

Type: number

clampBottom(x, a)

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

Source:: src/math/Math.js line 1175

Returns:

Type: number

degToRad(degrees)

Convert degrees to radians.

Parameters:

Name	Type	Description
`degrees`	number	Angle in degrees.

Source:: src/math/Math.js line 45

Returns:

Angle in radians.

Type: number

difference(a, b)

The absolute difference between two values.

Parameters:

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

Source:: src/math/Math.js line 1018

Returns:

The absolute difference between the two values.

Type: number

distance(x1, y1, x2, y2)

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

Parameters:

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

Source:: src/math/Math.js line 1095

Returns:

The distance between the two sets of coordinates.

Type: number

distancePow(x1, y1, x2, y2 [, pow])

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:: src/math/Math.js line 1132

Returns:

The distance between the two sets of coordinates.

Type: number

distanceSq(x1, y1, x2, y2)

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

Source:: src/math/Math.js line 1113

Returns:

The distance squared between the two sets of coordinates.

Type: number

factorial(value)

Parameters:

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

Source:: src/math/Math.js line 974

Returns:

Type: number

floorTo(value [, place] [, base])

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.

Source:: src/math/Math.js line 404

Returns:

The rounded value.

Type: number

fuzzyCeil(val [, epsilon])

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)

Source:: src/math/Math.js line 219

Returns:

ceiling(val-epsilon)

Type: number

fuzzyEqual(a, b [, epsilon])

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)

Source:: src/math/Math.js line 171

Returns:

True if |a-b|<epsilon

Type: boolean

fuzzyFloor(val [, epsilon])

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)

Source:: src/math/Math.js line 234

Returns:

floor(val+epsilon)

Type: number

fuzzyGreaterThan(a, b [, epsilon])

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)

Source:: src/math/Math.js line 203

Returns:

True if a>b+epsilon

Type: boolean

fuzzyLessThan(a, b [, epsilon])

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)

Source:: src/math/Math.js line 187

Returns:

True if a<b+epsilon

Type: boolean

getNextPowerOfTwo(value)

Given a number, this function returns the closest number that is a power of two. This function is from the Starling Framework.

Parameters:

Name	Type	Description
`value`	number	The value to get the closest power of two from.

Source:: src/math/Math.js line 69

Returns:

The closest number that is a power of two.

Type: number

getShortestAngle(angle1, angle2)

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.

Source:: src/math/Math.js line 512

Returns:

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

Type: number

hypot(a, b)

Returns the length of the hypotenuse connecting two segments of given lengths.

Parameters:

Name	Type	Description
`a`	number
`b`	number

Source:: src/math/Math.js line 1082

Returns:

The length of the hypotenuse connecting the given lengths.

Type: number

isEven(n)

Returns true if the number given is even.

Parameters:

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

Source:: src/math/Math.js line 715

Returns:

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

Type: boolean

isOdd(n)

Returns true if the number given is odd.

Parameters:

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

Source:: src/math/Math.js line 702

Returns:

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

Type: boolean

isPowerOfTwo(width, height)

Checks if the given dimensions make a power of two texture.

Parameters:

Name	Type	Description
`width`	number	The width to check.
`height`	number	The height to check.

Source:: src/math/Math.js line 97

Returns:

True if the width and height are a power of two.

Type: boolean

linear(p0, p1, t)

Calculates a linear (interpolation) value over t.

Parameters:

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

Source:: src/math/Math.js line 948

Returns:

Type: number

linearInterpolation(v, k)

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 amount of interpolation, between 0 (start) and 1 (end).

Source:: src/math/Math.js line 861

Returns:

The interpolated value

Type: number

mapLinear(x, a1, a2, b1, b2)

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:: src/math/Math.js line 1204

Returns:

Type: number

max()

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.

Source:

src/math/Math.js line 759

See:

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

Returns:

The largest value from those given.

Type: number

maxAdd(value, amount, max)

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:: src/math/Math.js line 622

Returns:

The new value.

Type: number

maxProperty()

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.

Source:: src/math/Math.js line 819

Returns:

The largest value from those given.

Type: number

min()

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.

Source:

src/math/Math.js line 728

See:

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

Returns:

The lowest value from those given.

Type: number

minProperty()

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.

Source:: src/math/Math.js line 790

Returns:

The lowest value from those given.

Type: number

minSub(value, amount, min)

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:: src/math/Math.js line 636

Returns:

The new value.

Type: number

normalizeAngle(angleRad)

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

Parameters:

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

Source:: src/math/Math.js line 610

Returns:

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

Type: number

percent(a, b [, base])

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:: src/math/Math.js line 1268

Returns:

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

Type: number

radToDeg(radians)

Convert radians to degrees.

Parameters:

Name	Type	Description
`radians`	number	Angle in radians.

Source:: src/math/Math.js line 57

Returns:

Angle in degrees

Type: number

random(min, max)

Returns a random float in the range [min, max). If these parameters are not in order than they will be put in order. Default is 0 for min and 1 for max.

Parameters:

Name	Type	Description
`min`	number	The minimum value. Must be a Number.
`max`	number	The maximum value. Must be a Number.

Source:: src/math/Math.js line 110

Returns:

A floating point number between min (inclusive) and max (exclusive).

Type: number

reverseAngle(angleRad)

Reverses an angle.

Parameters:

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

Source:: src/math/Math.js line 599

Returns:

The reverse angle, in radians.

Type: number

rotateToAngle(currentAngle, targetAngle [, lerp])

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.

Source:: src/math/Math.js line 462

Returns:

The adjusted angle.

Type: number

roundAwayFromZero(value)

Round to the next whole number away from zero.

Parameters:

Name	Type	Description
`value`	number	Any number.

Source:: src/math/Math.js line 1031

Returns:

The rounded value of that number.

Type: integer

roundTo(value [, place] [, base])

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.

Source:: src/math/Math.js line 359

Returns:

The rounded value.

Type: number

shear(n)

Parameters:

Name	Type	Description
`n`	number

Source:: src/math/Math.js line 269

Returns:

n mod 1

Type: number

sign(x)

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

Source:: src/math/Math.js line 1254

Returns:

An integer in {-1, 0, 1}

Type: integer

sinCosGenerator(length, sinAmplitude, cosAmplitude, frequency)

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

Source:: src/math/Math.js line 1044

Returns:

Returns the table data.

Type: Object

smootherstep(x, min, max)

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.

Source:: src/math/Math.js line 1238

Returns:

A value between 0 and 1.

Type: float

smoothstep(x, min, max)

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.

Source:: src/math/Math.js line 1220

Returns:

A value between 0 and 1.

Type: float

snapTo(input, gap [, start])

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.

Source:: src/math/Math.js line 279

Returns:

The snapped value.

Type: number

snapToCeil(input, gap [, start])

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.

Source:: src/math/Math.js line 332

Returns:

The snapped value.

Type: number

snapToFloor(input, gap [, start])

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.

Source:: src/math/Math.js line 305

Returns:

The snapped value.

Type: number

trunc(value)

Truncates a number, removing any fractional part. Same as round-towards-zero.

Parameters:

Name	Type	Description
`value`	number	The value to truncate.

Source:: src/math/Math.js line 444

Returns:

The truncated value.

Type: number

within(a, b, tolerance)

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:

src/math/Math.js line 1189

See:

Phaser.Math.fuzzyEqual

Returns:

True if a is <= tolerance of b.

Type: boolean

wrap(value, min, max)

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

Source:: src/math/Math.js line 650

Returns:

The wrapped value.

Type: number

wrapAngle(angle [, radians])

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.

Source:: src/math/Math.js line 848

Returns:

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

Type: number

wrapValue(value, amount, max)

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.

Source:: src/math/Math.js line 680

Returns:

The wrapped value.

Type: number