API Docs for: 1.4.0
Show:

Kiwi.Utils.GameMath Class

Module: Utils
Parent Module: Kiwi

Adds a set of extra Math functions and extends a few commonly used ones. Includes some methods written by Dylan Engelman.

Item Index

Methods

Properties

Methods

angleBetween

(
  • x1
  • y1
  • x2
  • y2
)
Number public static

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

Parameters:

  • x1 Number
  • y1 Number
  • x2 Number
  • y2 Number

Returns:

Number:

angleLimit

(
  • angle
  • min
  • max
)
Number public static

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

Parameters:

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

Returns:

Number:

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

arithWrap

(
  • val
  • max
  • [min=0]
)
Number public static

Arithmetic version of wrap.

Parameters:

  • val Number
  • max Number
  • [min=0] Number optional

Returns:

Number:

average

(
  • [args]
)
Number public static

Computes the mean of any number of parameters. For example, average(1,2,3) returns 2.

Parameters:

  • [args] Any optional multiple

Returns:

Number:

bernstein

(
  • n
  • i
)
Number public static

Bernstein polynomial for constructing Bezier curves. Returns n! / i! / (n-i)!

Parameters:

  • n Any
  • i Any

Returns:

Number:

bezierInterpolation

(
  • v
  • k
)
Number public static

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 Array

    An array of values through which to interpolate

  • k Number

    The position to interpolate, in the range 0-1

Returns:

Number:

binCoef

(
  • n
  • k
)
Number public static

Binomial coefficient.

Parameters:

  • n Number
  • k Number

Returns:

Number:

catmullRom

(
  • p0
  • p1
  • p2
  • p3
  • t
)
Number public static

Function used to construct a Catmull-Rom interpolation: see catmullRomInterpolation()

Parameters:

  • p0 Any
  • p1 Any
  • p2 Any
  • p3 Any
  • t Any

Returns:

Number:

catmullRomInterpolation

(
  • v
  • k
)
Number public static

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 Array

    An array of values through which to interpolate

  • k Number

    The position to interpolate, in the range 0-1

Returns:

Number:

ceilTo

(
  • value
  • [place=0]
  • [base=10]
)
Number public static

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:

Number:

changeRoll

(
  • [chance=50]
)
Boolean public static

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 optional

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

Returns:

Boolean:

true if the roll passed, or false

clamp

(
  • input
  • max
  • [min=0]
)
Number public static

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:

Number:

computeMachineEpsilon

() Number public static

Computes the maximum relative error for this machine.

Returns:

Number:

degreesToRadians

(
  • angle
)
Number public static

Convert degrees to radians

Parameters:

  • angle Number

Returns:

Number:

difference

(
  • a
  • b
)
Number public static

Returns the difference between a and b.

Parameters:

  • a Number
  • b Number

Returns:

Number:

factorial

(
  • value
)
Number public static

Factorial - N! Simple product series. By definition: 0! == 1

Parameters:

  • value Number

Returns:

Number:

fallingFactorial

(
  • base
  • exp
)
Number public static

Falling factorial. Defined: (N)! / (N - x)! Written subscript: (N)x OR (base)exp

Parameters:

  • base Number
  • exp Number

Returns:

Number:

floorTo

(
  • value
  • [place=0]
  • [base=10]
)
Number public static

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:

Number:

fuzzyCeil

(
  • val
  • [epsilon=0.0001]
)
Number public static

Computes the integer ceiling of the first parameter, minus a rounding margin defined by epsilon.

Parameters:

  • val Number
  • [epsilon=0.0001] Number optional

Returns:

Number:

fuzzyEqual

(
  • a
  • b
  • [epsilon=0.0001]
)
Boolean public static

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:

Boolean:

fuzzyFloor

(
  • val
  • [epsilion=0.0001]
)
Number public static

Computes the integer floor of the first parameter, plus a rounding margin defined by epsilon.

Parameters:

  • val Number
  • [epsilion=0.0001] Number optional

Returns:

Number:

fuzzyGreaterThan

(
  • a
  • b
  • [epsilon=0.0001]
)
Boolean public static

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:

Boolean:

fuzzyLessThan

(
  • a
  • b
  • [epsilon=0.0001]
)
Boolean public static

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:

Boolean:

gammaFunction

(
  • value
)
Number public static

Gamma function. Defined: gamma(N) == (N - 1)!

Parameters:

  • value Number

Returns:

Number:

GCD

(
  • m
  • n
)
Number public static

Greatest Common Denominator using Euclid's algorithm.

Parameters:

  • m Number
  • n Number

Returns:

Number:

interpolateAngles

(
  • a1
  • a2
  • weight
  • [radians=true]
  • [ease=null]
)
Number public static

Interpolate across the shortest arc between two angles.

Parameters:

  • a1 Number
  • a2 Number
  • weight Number
  • [radians=true] Boolean optional
  • [ease=null] Any optional

Returns:

Number:

interpolateFloat

(
  • a
  • b
  • weight
)
Number public static

A one dimensional linear interpolation of a value.

Parameters:

  • a Number
  • b Number
  • weight Number

Returns:

Number:

isEven

(
  • n
)
Boolean public static

Returns true if the number given is even.

Parameters:

  • n Number

    The number to check

Returns:

Boolean:

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

isOdd

(
  • n
)
Boolean public static

Returns true if the number given is odd.

Parameters:

  • n Number

    The number to check

Returns:

Boolean:

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

LCM

(
  • m
  • n
)
Number public static

Lowest Common Multiple

Parameters:

  • m Number
  • n Number

Returns:

Number:

linear

(
  • p0
  • p1
  • t
)
Number public static

Simple linear interpolation, identical to interpolateFloat.

Parameters:

  • p0 Any
  • p1 Any
  • t Any

Returns:

Number:

linearInterpolation

(
  • v
  • k
)
Number public static

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 Array

    An array of values through which to interpolate

  • k Number

    The position to interpolate, in the range 0-1

Returns:

Number:

logBaseOf

(
  • value
  • base
)
Number public static

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:

Number:

maxAdd

(
  • value
  • amount
  • max
)
Number public static

Adds the given amount to the value, but never lets the value go over the specified maximum.

Parameters:

  • 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:

minSub

(
  • value
  • amount
  • min
)
Number public static

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

Parameters:

  • 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:

nearestAngleBetween

(
  • a1
  • a2
  • [radians=true]
)
Number public static

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:

Number:

normalizeAngle

(
  • angle
  • [radians=true]
)
Number public static

Returns an equivalent angle within the bounds of -PI (inclusive) to PI (exclusive).

Parameters:

  • angle Number
  • [radians=true] Boolean optional

Returns:

Number:

normalizeAngleAfterAnother

(
  • dep
  • ind
  • [radians=true]
)
Number public static

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:

Number:

normalizeAngleBeforeAnother

(
  • dep
  • ind
  • [radians=true]
)
Number public static

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:

Number:

normalizeAngleToAnother

(
  • dep
  • ind
  • [radians=true]
)
Number public static

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:

Number:

objType

() String public

The type of object that this is.

Returns:

String:

"GameMath"

percentageMinMax

(
  • val
  • max
  • [min=0]
)
Number public static

Ratio of value to a range.

Parameters:

  • val Number
  • max Number
  • [min=0] Number optional

Returns:

Number:

radiansToDegrees

(
  • angle
)
Number public static

Convert radians to degrees

Parameters:

  • angle Number

Returns:

Number:

randomSign

() Number public static

Randomly returns either a 1 or -1

Returns:

Number:

Either 1 or -1.

risingBinCoef

(
  • n
  • k
)
Number public static

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:

Number:

risingFactorial

(
  • base
  • exp
)
Number public static

Rising factorial. Defined: (N + x - 1)! / (N - 1)! Written superscript N^(x) OR base^(exp)

Parameters:

  • base Number
  • exp Number

Returns:

Number:

roundTo

(
  • value
  • [place=0]
  • [base=10]
)
Number public static

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 Number

    The value to round

  • [place=0] Number optional

    The place to round to

  • [base=10] Number optional

    The base to round in... default is 10 for decimal

Returns:

Number:

shear

(
  • n
)
Number public static

Removes all non-decimal data from the value.

Parameters:

  • n Number

Returns:

Number:

sign

(
  • n
)
Number public static

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

Parameters:

  • n Number

Returns:

Number:

slam

(
  • value
  • target
  • [epsilon=0.0001]
)
Number public static

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:

Number:

snapTo

(
  • input
  • gap
  • [start=0]
)
Number public static

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 Number

    The value to snap

  • gap Number

    The interval gap of the grid

  • [start=0] Number optional

    Optional starting offset for gap

Returns:

Number:

snapToCeil

(
  • input
  • gap
  • [start=0]
)
Number public static

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 Number

    The value to snap

  • gap Number

    The interval gap of the grid

  • [start=0] Number optional

    optional starting offset for gap

Returns:

Number:

snapToFloor

(
  • input
  • gap
  • [start=0]
)
Number public static

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 Number

    The value to snap

  • gap Number

    The interval gap of the grid

  • [start=0] Number optional

    Optional starting offset for gap

Returns:

Number:

snapToInArray

(
  • input
  • arr
  • [sort=true]
)
Number public static

Snaps a value to the nearest value in an array.

Parameters:

  • input Number
  • arr Number
  • [sort=true] Boolean optional

Returns:

Number:

truncate

(
  • n
)
Number public static

Truncates a value by removing all decimal data.

Parameters:

  • n Number

Returns:

Number:

wrap

(
  • val
  • max
  • [min=0]
)
Number public static

Wrap a value around a range, similar to modulus with a floating minimum

Parameters:

  • val Number
  • max Number
  • [min=0] Number optional

Returns:

Number:

wrapAngle

(
  • angle
)
Number public static

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 Number

    The angle value to check

Returns:

Number:

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

wrapValue

(
  • value
  • amount
  • max
)
Number public static

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

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