Phaser.Math

new Math()

A collection of useful mathematical functions.

These are normally accessed through game.math.

See:

: - Phaser.Utils - Phaser.ArrayUtils

Members

<static> DEG_TO_RAD

Degrees to Radians factor.

Name Type Description
Phaser.Math#DEG_TO_RAD number

Source - math/Math.js, line 37

<static>HALF_PI

Half PI.

Name Type Description
Phaser.Math#HALF_PI number

Default Value: - ~1.570

Source - math/Math.js, line 31

<static> PI2

Twice PI.

Name Type Description
Phaser.Math#PI2 number

Default Value: - ~6.283

Source - math/Math.js, line 24

<static>RAD_TO_DEG

Degrees to Radians factor.

Name Type Description
Phaser.Math#RAD_TO_DEG number

Source - math/Math.js, line 43

Methods

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

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

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.

number-

The angle, in radians.

Source - math/Math.js, line 541

angleBetweenPoints(point1, point2)→ {number}

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

Name

Type

Description

point1

Phaser.Point

The first point.

point2

Phaser.Point

The second point.

number-

The angle between the two points, in radians.

Source - math/Math.js, line 576

angleBetweenPointsY(point1, point2)→ {number}

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

Name Type Description
point1 Phaser.Point
point2 Phaser.Point

number-

The angle, in radians.

Source - math/Math.js, line 590

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.

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.

number-

The angle, in radians.

Source - math/Math.js, line 557

average()→

{number}

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

number-

The average of all given values.

Source - math/Math.js, line 260

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

Name Type Description
n number
i number

number-

Internal: - This member is internal (protected) and may be modified or removed in the future.

Source - math/Math.js, line 983

between(min,max)→ {number}

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.

Name

Type

Description

min

number

The minimum value. Must be a Number.

max

number

The maximum value. Must be a Number.

number-

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

Source - math/Math.js, line 144

bezierInterpolation(v, k)→ {number}

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

Name

Type

Description

v

Array

The input array of values to interpolate between.

k

number

The percentage of interpolation, between 0 and 1.

number-

The interpolated value

Source - math/Math.js, line 906

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

Calculates a catmum rom value.

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

number-

Internal: - This member is internal (protected) and may be modified or removed in the future.

Source - math/Math.js, line 1019

catmullRomInterpolation(v, k)→ {number}

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

Name

Type

Description

v

Array

The input array of values to interpolate between.

k

number

The percentage of interpolation, between 0 and 1.

number-

The interpolated value

Source - math/Math.js, line 928

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.

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.

number-

The rounded value.

Source - math/Math.js, line 439

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

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

Name

Type

Description

v

float

The value to be clamped.

min

float

The minimum bounds.

max

float

The maximum bounds.

number-

The clamped value.

Source - math/Math.js, line 1179

clampBottom(x, a)→ {number}

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

Name Type Description
x number
a number

number-

Source - math/Math.js, line 1205

degToRad(degrees)→ {number}

Convert degrees to radians.

Name

Type

Description

degrees

number

Angle in degrees.

number-

Angle in radians.

Source - math/Math.js, line 45

difference(a, b)→

{number}

The absolute difference between two values.

Name

Type

Description

a

number

The first value to check.

b

number

The second value to check.

number-

The absolute difference between the two values.

Source - math/Math.js, line 1039

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

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

Name Type Description
x1 number
y1 number
x2 number
y2 number

number-

The distance between the two sets of coordinates.

Source - math/Math.js, line 1121

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

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

Name

Type

Argument

Default

Description

x1

number

y1

number

x2

number

y2

number

pow

number

<optional>

2

number-

The distance between the two sets of coordinates.

Source - math/Math.js, line 1160

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

Name Type Description
x1 number
y1 number
x2 number
y2 number

number-

The distance squared between the two sets of coordinates.

Source - math/Math.js, line 1140

factorial(value)→ {number}

Name

Type

Description

value

number

the number you want to evaluate

number-

Source - math/Math.js, line 996

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.

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.

number-

The rounded value.

Source - math/Math.js, line 418

fuzzyCeil(val,epsilon)→ {number}

Applies a fuzzy ceil to the given value.

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)

number-

ceiling(val-epsilon)

Source - math/Math.js, line 228

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

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

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)

boolean-

True if |a-b|<epsilon Source - math/Math.js, line 177

fuzzyFloor(val,epsilon)→ {number}

Applies a fuzzy floor to the given value.

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)

number-

floor(val+epsilon)

Source - math/Math.js, line 244

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

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

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)

boolean-

True if a>b+epsilon

Source - math/Math.js, line 211

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

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

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)

boolean-

True if a<b+epsilon Source - math/Math.js, line 194

getNextPowerOfTwo(value)→ {number}

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

Name

Type

Description

value

number

The value to get the closest power of two from.

number-

The closest number that is a power of two.

Source - math/Math.js, line 71

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'sa clockwise rotation.

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.

number-

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

Source - math/Math.js, line 511

hypot(a, b)→

{number}

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

Name Type Description
a number
b number

number-

The length of the hypotenuse connecting the given lengths.

Source - math/Math.js, line 1107

isEven(n)→

{boolean}

Returns true if the number given is even.

Name

Type

Description

n

integer

The number to check.

boolean-

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

Source - math/Math.js, line 726

isOdd(n)→

{boolean}

Returns true if the number given is odd.

Name

Type

Description

n

integer

The number to check.

boolean-

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

Source - math/Math.js, line 712

isPowerOfTwo(width, height)→ {boolean}

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

Name

Type

Description

width

number

The width to check.

height

number

The height to check.

boolean-

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

Source - math/Math.js, line 100

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

Calculates a linear (interpolation) value over t.

Name

Type

Description

p0

number

p1

number

t

number

A value between 0 and 1.

number-

Source - math/Math.js, line 968

linearInterpolation(v, k)→ {number}

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

Name

Type

Description

v

Array

The input array of values to interpolate between.

k

number

The percentage of interpolation, between 0 and 1.

number-

The interpolated value

Source - math/Math.js, line 878

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

Linear mapping from range to range

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

number-

Source - math/Math.js, line 1236

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.

number-

The largest value from those given.

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.

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.

number-

The new value.

Source - math/Math.js, line 628

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.

number-

The largest value from those given.

Source - math/Math.js, line 834

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.

number-

The lowest value from those given.

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.

number-

The lowest value from those given.

Source - math/Math.js, line 804

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

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

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.

number-

The new value.

Source - math/Math.js, line 643

normalizeAngle(angleRad)→ {number}

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

Name

Type

Description

angleRad

number

The angle to normalize, in radians.

number-

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

Source - math/Math.js, line 615

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

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

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.

number-

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

Source - math/Math.js, line 1304

radToDeg(radians)→ {number}

Convert radians to degrees.

Name

Type

Description

radians

number

Angle in radians.

number-

Angle in degrees

Source - math/Math.js, line 58

random(min, max)→

{number}

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.

Name

Type

Description

min

number

The minimum value. Must be a Number.

max

number

The maximum value. Must be a Number.

number-

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

Source - math/Math.js, line 114

reverseAngle(angleRad)→ {number}

Reverses an angle.

Name

Type

Description

angleRad

number

The angle to reverse, in radians.

number-

The reverse angle, in radians.

Source - math/Math.js, line 603

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.

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.

number-

The adjusted angle.

Source - math/Math.js, line 460

roundAwayFromZero(value)→ {integer}

Round to the next whole number away from zero.

Name

Type

Description

value

number

Any number.

integer-

The rounded value of that number.

Source - math/Math.js, line 1053

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.

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.

number-

The rounded value.

Source - math/Math.js, line 372

shear(n)→

{number}

Name Type Description
n number

number-

n mod 1

Source - math/Math.js, line 281

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.

Name Type Description
x number

integer-

An integer in {-1, 0, 1}

Source - math/Math.js, line 1289

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

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

Object-

Returns the table data.

Source - math/Math.js, line 1067

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

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

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.

float-

A value between 0 and 1.

Source - math/Math.js, line 1272

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

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

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.

float-

A value between 0 and 1.

Source - math/Math.js, line 1253

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.

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.

number-

The snapped value.

Source - math/Math.js, line 292

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.

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.

number-

The snapped value.

Source - math/Math.js, line 345

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.

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.

number-

The snapped value.

Source - math/Math.js, line 318

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

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

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.

boolean-

True if a is <= tolerance of b. Source - math/Math.js, line 1220
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.

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.

number-

The wrapped value.

Source - math/Math.js, line 658

wrapAngle(angle, radians)→ {number}

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

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.

number-

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

Source - math/Math.js, line 864

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.

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.

number-

The wrapped value.

Source - math/Math.js, line 689