Kiwi.Utils.GameMath Class
Adds a set of extra Math functions and extends a few commonly used ones. Includes some methods written by Dylan Engelman.
Item Index
Methods
- angleBetween static
- angleLimit static
- arithWrap static
- average static
- bernstein static
- bezierInterpolation static
- binCoef static
- catmullRom static
- catmullRomInterpolation static
- ceilTo static
- changeRoll static
- clamp static
- computeMachineEpsilon static
- degreesToRadians static
- difference static
- factorial static
- fallingFactorial static
- floorTo static
- fuzzyCeil static
- fuzzyEqual static
- fuzzyFloor static
- fuzzyGreaterThan static
- fuzzyLessThan static
- gammaFunction static
- GCD static
- interpolateAngles static
- interpolateFloat static
- isEven static
- isOdd static
- LCM static
- linear static
- linearInterpolation static
- logBaseOf static
- maxAdd static
- minSub static
- nearestAngleBetween static
- normalizeAngle static
- normalizeAngleAfterAnother static
- normalizeAngleBeforeAnother static
- normalizeAngleToAnother static
- objType
- percentageMinMax static
- radiansToDegrees static
- randomSign static
- risingBinCoef static
- risingFactorial static
- roundTo static
- shear static
- sign static
- slam static
- snapTo static
- snapToCeil static
- snapToFloor static
- snapToInArray static
- truncate static
- wrap static
- wrapAngle static
- wrapValue static
Properties
- B_16 static
- B_31 static
- B_32 static
- B_48 static
- B_53 static
- B_64 static
- CIRCLE_ALPHA static
- COS_PI_3 static
- DEG_TO_RAD static
- E static
- EPSILON static
- LN10 static
- LN2 static
- LOG10E static
- LOG2E static
- LONG_EPSILON static
- OFF static
- ON static
- ONE_SIXTH static
- ONE_THIRD static
- PERC_EPSILON static
- PI static
- PI_16 static
- PI_2 static
- PI_4 static
- PI_8 static
- RAD_TO_DEG static
- SHORT_EPSILON static
- SIN_2PI_3 static
- SQRT1_2 static
- SQRT2 static
- THREE_PI_2 static
- TWO_PI static
- TWO_THIRDS static
Methods
angleBetween
-
x1
-
y1
-
x2
-
y2
Find the angle of a segment from (x1, y1) -> (x2, y2 )
Parameters:
-
x1
Number -
y1
Number -
x2
Number -
y2
Number
Returns:
angleLimit
-
angle
-
min
-
max
Keeps an angle value between the given min and max values.
Parameters:
-
angle
NumberThe angle value to check. Must be between -180 and +180
-
min
NumberThe minimum angle that is allowed (must be -180 or greater)
-
max
NumberThe maximum angle that is allowed (must be 180 or less)
Returns:
The new angle value, returns the same as the input angle if it was within bounds
arithWrap
-
val
-
max
-
[min=0]
Arithmetic version of wrap.
Parameters:
-
val
Number -
max
Number -
[min=0]
Number optional
Returns:
average
-
[args]
Computes the mean of any number of parameters. For example, average(1,2,3) returns 2.
Parameters:
-
[args]
Any optional multiple
Returns:
bernstein
-
n
-
i
Bernstein polynomial for constructing Bezier curves. Returns n! / i! / (n-i)!
Parameters:
-
n
Any -
i
Any
Returns:
bezierInterpolation
-
v
-
k
Interpolates between values in an array using Bezier curves. This treats the values in the array as control points on a spline. Unlike Catmull-Rom splines, the value is not guaranteed to intersect precisely with these points.
Parameters:
-
v
ArrayAn array of values through which to interpolate
-
k
NumberThe position to interpolate, in the range 0-1
Returns:
binCoef
-
n
-
k
Binomial coefficient.
Parameters:
-
n
Number -
k
Number
Returns:
catmullRom
-
p0
-
p1
-
p2
-
p3
-
t
Function used to construct a Catmull-Rom interpolation: see catmullRomInterpolation()
Parameters:
-
p0
Any -
p1
Any -
p2
Any -
p3
Any -
t
Any
Returns:
catmullRomInterpolation
-
v
-
k
Interpolates between values in an array using Catmull-Rom splines. This treats the values in the array as control points on a spline. Unlike Bezier curves, the value will intersect with every point in the array.
Parameters:
-
v
ArrayAn array of values through which to interpolate
-
k
NumberThe position to interpolate, in the range 0-1
Returns:
ceilTo
-
value
-
[place=0]
-
[base=10]
Round down 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
Parameters:
-
value
Number -
[place=0]
Number optional -
[base=10]
Number optional
Returns:
changeRoll
-
[chance=50]
Generate a random boolean result based on the chance value. Returns true or false based on the chance value (default 50%). For example if you wanted a player to have a 30% chance of getting a bonus, call chanceRoll(30) - true means the chance passed, false means it failed.
Parameters:
-
[chance=50]
Number optionalThe chance of receiving the value. A number between 0 and 100 (effectively 0% to 100%)
Returns:
true if the roll passed, or false
clamp
-
input
-
max
-
[min=0]
Force a value within the boundaries of two values If max < min, min is returned.
Parameters:
-
input
Number -
max
Number -
[min=0]
Number optional
Returns:
computeMachineEpsilon
()
Number
public
static
Computes the maximum relative error for this machine.
Returns:
degreesToRadians
-
angle
Convert degrees to radians
Parameters:
-
angle
Number
Returns:
difference
-
a
-
b
Returns the difference between a and b.
Parameters:
-
a
Number -
b
Number
Returns:
factorial
-
value
Factorial - N! Simple product series. By definition: 0! == 1
Parameters:
-
value
Number
Returns:
fallingFactorial
-
base
-
exp
Falling factorial. Defined: (N)! / (N - x)! Written subscript: (N)x OR (base)exp
Parameters:
-
base
Number -
exp
Number
Returns:
floorTo
-
value
-
[place=0]
-
[base=10]
Round down 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
Parameters:
-
value
Number -
[place=0]
Number optional -
[base=10]
Number optional
Returns:
fuzzyCeil
-
val
-
[epsilon=0.0001]
Computes the integer ceiling of the first parameter, minus a rounding margin defined by epsilon.
Parameters:
-
val
Number -
[epsilon=0.0001]
Number optional
Returns:
fuzzyEqual
-
a
-
b
-
[epsilon=0.0001]
Computes whether two numbers are identical to the limits of the computer's precision, as specified by the epsilon value.
Parameters:
-
a
Number -
b
Number -
[epsilon=0.0001]
Number optional
Returns:
fuzzyFloor
-
val
-
[epsilion=0.0001]
Computes the integer floor of the first parameter, plus a rounding margin defined by epsilon.
Parameters:
-
val
Number -
[epsilion=0.0001]
Number optional
Returns:
fuzzyGreaterThan
-
a
-
b
-
[epsilon=0.0001]
Computes whether the first parameter is greater than the second parameter, to the limits of the computer's precision, as specified by the epsilon value.
Parameters:
-
a
Number -
b
Number -
[epsilon=0.0001]
Number optional
Returns:
fuzzyLessThan
-
a
-
b
-
[epsilon=0.0001]
Computes whether the first parameter is less than the second parameter, to the limits of the computer's precision, as specified by the epsilon value.
Parameters:
-
a
Number -
b
Number -
[epsilon=0.0001]
Number optional
Returns:
gammaFunction
-
value
Gamma function. Defined: gamma(N) == (N - 1)!
Parameters:
-
value
Number
Returns:
GCD
-
m
-
n
Greatest Common Denominator using Euclid's algorithm.
Parameters:
-
m
Number -
n
Number
Returns:
interpolateAngles
-
a1
-
a2
-
weight
-
[radians=true]
-
[ease=null]
Interpolate across the shortest arc between two angles.
Parameters:
-
a1
Number -
a2
Number -
weight
Number -
[radians=true]
Boolean optional -
[ease=null]
Any optional
Returns:
interpolateFloat
-
a
-
b
-
weight
A one dimensional linear interpolation of a value.
Parameters:
-
a
Number -
b
Number -
weight
Number
Returns:
isEven
-
n
Returns true if the number given is even.
Parameters:
-
n
NumberThe number to check
Returns:
True if the given number is even. False if the given number is odd.
isOdd
-
n
Returns true if the number given is odd.
Parameters:
-
n
NumberThe number to check
Returns:
True if the given number is odd. False if the given number is even.
LCM
-
m
-
n
Lowest Common Multiple
Parameters:
-
m
Number -
n
Number
Returns:
linear
-
p0
-
p1
-
t
Simple linear interpolation, identical to interpolateFloat.
Parameters:
-
p0
Any -
p1
Any -
t
Any
Returns:
linearInterpolation
-
v
-
k
Interpolates between neighbouring values in an array using linear interpolation only. For example, linearInterpolation( [ 1,5,4 ], 0.5 ) = 5, and linearInterpolation( [ 1, 2 ], 0.3 ) = 1.3.
Parameters:
-
v
ArrayAn array of values through which to interpolate
-
k
NumberThe position to interpolate, in the range 0-1
Returns:
logBaseOf
-
value
-
base
Compute the logarithm of any value of any base. A logarithm is the exponent that some constant (base) would have to be raised to to be equal to value.
Parameters:
-
value
Number -
base
Number
Returns:
maxAdd
-
value
-
amount
-
max
Adds the given amount to the value, but never lets the value go over the specified maximum.
Parameters:
-
value
NumberThe value to add the amount to
-
amount
NumberThe amount to add to the value
-
max
NumberThe maximum the value is allowed to be
Returns:
minSub
-
value
-
amount
-
min
Subtracts the given amount from the value, but never lets the value go below the specified minimum.
Parameters:
-
value
NumberThe base value
-
amount
NumberThe amount to subtract from the base value
-
min
NumberThe minimum the value is allowed to be
Returns:
nearestAngleBetween
-
a1
-
a2
-
[radians=true]
Closest angle between two angles a1 and a2. In other words, the angle you must turn to go from facing a1 to facing a2. This will be a normalized angle between -PI and PI.
Parameters:
-
a1
Number -
a2
Number -
[radians=true]
Boolean optional
Returns:
normalizeAngle
-
angle
-
[radians=true]
Returns an equivalent angle within the bounds of -PI (inclusive) to PI (exclusive).
Parameters:
-
angle
Number -
[radians=true]
Boolean optional
Returns:
normalizeAngleAfterAnother
-
dep
-
ind
-
[radians=true]
Normalize independent and dependent and then set dependent to an angle relative to 'after/clockwise' independent. For instance dep=-170 and ind=170, then 190 will be reutrned as alternative to -170
Parameters:
-
dep
Number -
ind
Number -
[radians=true]
Boolean optional
Returns:
normalizeAngleBeforeAnother
-
dep
-
ind
-
[radians=true]
Normalizes indendent and dependent and then sets dependent to an angle relative to 'before/counterclockwise' independent. For instance dep = 190 and ind = 170, then -170 will be returned as an alternative to 190
Parameters:
-
dep
Number -
ind
Number -
[radians=true]
Boolean optional
Returns:
normalizeAngleToAnother
-
dep
-
ind
-
[radians=true]
Normalizes independent and then sets dep to the nearest value respective to independent. For instance if dep=-170 and ind=170 then 190 will be returned as an alternative to -170
Parameters:
-
dep
Number -
ind
Number -
[radians=true]
Boolean optional
Returns:
objType
()
String
public
The type of object that this is.
Returns:
"GameMath"
percentageMinMax
-
val
-
max
-
[min=0]
Ratio of value to a range.
Parameters:
-
val
Number -
max
Number -
[min=0]
Number optional
Returns:
radiansToDegrees
-
angle
Convert radians to degrees
Parameters:
-
angle
Number
Returns:
randomSign
()
Number
public
static
Randomly returns either a 1 or -1
Returns:
Either 1 or -1.
risingBinCoef
-
n
-
k
Rising binomial coefficient. As one can notice in the analysis of binCoef(...) that binCoef is the (N)k divided by k!. Similarly rising binCoef is merely N^(k) / k!
Parameters:
-
n
Number -
k
Number
Returns:
risingFactorial
-
base
-
exp
Rising factorial. Defined: (N + x - 1)! / (N - 1)! Written superscript N^(x) OR base^(exp)
Parameters:
-
base
Number -
exp
Number
Returns:
roundTo
-
value
-
[place=0]
-
[base=10]
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
Parameters:
-
value
NumberThe value to round
-
[place=0]
Number optionalThe place to round to
-
[base=10]
Number optionalThe base to round in... default is 10 for decimal
Returns:
shear
-
n
Removes all non-decimal data from the value.
Parameters:
-
n
Number
Returns:
sign
-
n
A value representing the sign of the value. -1 for negative, +1 for positive, 0 if value is 0
Parameters:
-
n
Number
Returns:
slam
-
value
-
target
-
[epsilon=0.0001]
Computes whether value and target are sufficiently close as to be within the computer's margin of error, as defined by epsilon. Returns the target if they are sufficiently close; returns the value if they are not.
In other words, slam prevents the target from exceeding epsilon.
Parameters:
-
value
Number -
target
Number -
[epsilon=0.0001]
Number optional
Returns:
snapTo
-
input
-
gap
-
[start=0]
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. Where as 14 will snap to 15
Parameters:
-
input
NumberThe value to snap
-
gap
NumberThe interval gap of the grid
-
[start=0]
Number optionalOptional starting offset for gap
Returns:
snapToCeil
-
input
-
gap
-
[start=0]
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:
-
input
NumberThe value to snap
-
gap
NumberThe interval gap of the grid
-
[start=0]
Number optionaloptional starting offset for gap
Returns:
snapToFloor
-
input
-
gap
-
[start=0]
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:
-
input
NumberThe value to snap
-
gap
NumberThe interval gap of the grid
-
[start=0]
Number optionalOptional starting offset for gap
Returns:
snapToInArray
-
input
-
arr
-
[sort=true]
Snaps a value to the nearest value in an array.
Parameters:
-
input
Number -
arr
Number -
[sort=true]
Boolean optional
Returns:
truncate
-
n
Truncates a value by removing all decimal data.
Parameters:
-
n
Number
Returns:
wrap
-
val
-
max
-
[min=0]
Wrap a value around a range, similar to modulus with a floating minimum
Parameters:
-
val
Number -
max
Number -
[min=0]
Number optional
Returns:
wrapAngle
-
angle
Keeps an angle value between -180 and +180. Should be called whenever the angle is updated on the Sprite to stop it from going insane.
Parameters:
-
angle
NumberThe angle value to check
Returns:
The new angle value, returns the same as the input angle if it was within bounds
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
Parameters:
-
value
NumberThe value to add the amount to
-
amount
NumberThe amount to add to the value
-
max
NumberThe maximum the value is allowed to be
Returns:
The wrapped value
Properties
B_16
Number
public
final
static
Holds the value for 2 to the power of 16 (2^16 = 65536). This is the number of values available in 2 bytes.
Default: 65536
B_31
Number
public
final
static
Holds the value for 2 to the power of 31 (2^31 = 2147483648). This is the number of values available to 31-bit memory addressing.
Default: 2147483648
B_32
Number
public
final
static
Holds the value for 2 to the power of 32 (2^32 = 4294967296). This is the number of values available in 4 bytes, such as certain forms of RGBA colour.
Default: 4294967296
B_48
Number
public
final
static
Holds the value for 2 to the power of 48 (2^48 = 281474976710656). 48-bit colour has 16 bits per channel.
Default: 281474976710656
B_53
Number
public
final
static
Holds the value for 2 to the power of 53 (2^53 = 9007199254740992). This is the largest accurate double-precision floating point whole number.
Default: 9007199254740992
B_64
Number
public
final
static
Holds the value for 2 to the power of 64 (2^64 = 18446744073709551616). This number cannot be accurately represented as a double-precision floating point whole number as it is greater than Kiwi.Utils.GameMath.B_53. It is represented as 18446744073709552000 in memory.
Default: 18446744073709551616
CIRCLE_ALPHA
Number
public
final
static
Holds the value for 4 * (Math.sqrt(2) - 1) / 3.0 (approximately 0.5522847).
This is useful for making circular arcs with Bezier curves. For an arc segment of 90 degrees (PI / 2 radians) or less, you can construct a nice approximation using CIRCLE_ALPHA. If the magic number k = CIRCLE_ALPHA, construct an arc using the following points: [1,0], [1,k], [k,1], [0,1].
For angles that are smaller by scale n, scale k by n, and displace k along tangents of the arc. For more information, see this article by Hans Muller: http://hansmuller-flex.blogspot.com/2011/04/approximating-circular-arc-with-cubic.html
Default: 0.5522847498307933984022516322796
COS_PI_3
Number
public
final
static
Holds the value of cos(pi / 3). This is the length of the shortest side of a triangle with angles in degrees 30, 60, and 90.
Default: 0.86602540378443864676372317075294
DEG_TO_RAD
Number
public
final
static
Holds the value for PI / 180 which is used to convert degrees to radians.
Default: 0.017453292519943294444444444444444
E
Number
public
final
static
Holds the value for "e": Euler's number or Napier's constant, to 15 significant figures. This is a mathematically useful number.
Default: 2.71828182845905
EPSILON
Number
public
final
static
Average relative error for single float values.
Default: 0.0001
LN10
Number
public
final
static
Holds the value for the natural logarithm of 10: ln(10). Accurate to 16 significant figures.
Default: 2.302585092994046
LN2
Number
public
final
static
Holds the value for the natural logarithm of 2: ln(10). Accurate to 16 significant figures.
Default: 0.6931471805599453
LOG10E
Number
public
final
static
Holds the value for the base 10 logarithm of e (Euler's number). Accurate to 16 significant figures.
Default: 0.4342944819032518
LOG2E
Number
public
final
static
Holds the value for the base 2 logarithm of e (Euler's number). Accurate to 19 significant figures.
Default: 1.442695040888963387
LONG_EPSILON
Number
public
final
static
Maximum relative error for 8-digit decimal values.
Default: 0.00000001
OFF
Boolean
public
final
static
A boolean that is false.
Default: false
ON
Boolean
public
final
static
A boolean that is true.
Default: true
ONE_SIXTH
Number
public
final
static
Holds the value for the fraction 1 / 6 as a number
Default: 0.166666666666666666666666666666666
ONE_THIRD
Number
public
final
static
Holds the value for the fraction 1 / 3 as a number.
Default: 0.333333333333333333333333333333333
PERC_EPSILON
Number
public
final
static
Maximum relative error for percentages (where 1% == 0.01).
Default: 0.001
PI
Number
public
final
static
Holds the value for PI. Only up to 16 significant figures.
Default: 3.141592653589793
PI_16
Number
public
final
static
Holds the value for PI / 16 OR 11.25 degrees. Only up to 17 significant figures.
Default: 0.19634954084936206
PI_2
Number
public
final
static
Holds the value for PI / 2 OR 90 degrees. Only up to 17 significant figures.
Default: 1.5707963267948965
PI_4
Number
public
final
static
Holds the value for PI / 4 OR 45 degrees. Only up to 16 significant figures.
Default: 0.7853981633974483
PI_8
Number
public
final
static
Holds the value for PI / 8 OR 22.5 degrees. Only up to 17 significant figures.
Default: 0.39269908169872413
RAD_TO_DEG
Number
public
final
static
Holds the value for 180 / PI which is used to convert radians to degrees.
Default: 57.295779513082325225835265587527
SHORT_EPSILON
Number
public
final
static
Maximum relative error for integers.
Default: 0.1
SIN_2PI_3
Number
public
final
static
Holds the value of sin(2 * pi / 3). This is the length of the second-shortest side of a triangle with andles in degrees 30, 60, and 90.
Default: 0.03654595
SQRT1_2
Number
public
final
static
Holds the value for the square root of 0.5 (1/2). Accurate to 16 significant figures.
Default: 0.7071067811865476
SQRT2
Number
public
final
static
Holds the value for the square root of 2. Accurate to 17 significant figures. This is the diagonal distance across a square with side length of 1.
Default: 1.4142135623730951
THREE_PI_2
Number
public
final
static
Holds the value for 3 * PI_2 OR 270 degrees. Only up to 17 significant figures.
Default: 4.7123889803846895
TWO_PI
Number
public
final
static
Holds the value for 2 * PI OR 180 degrees. Only up to 15 significant figures.
Default: 6.283185307179586
TWO_THIRDS
Number
public
final
static
Holds the value for the fraction 2 / 3 as a number.
Default: 0.666666666666666666666666666666666