Skip to main content
Version: Phaser v4.0.0

Phaser.Utils

NOOP​

<static> NOOP()​

Description:

A NOOP (No Operation) callback function.

Used internally by Phaser when it's more expensive to determine if a callback exists than it is to just invoke an empty function.

Source: src/utils/NOOP.js#L7
Since: 3.0.0

NULL​

<static> NULL()​

Description:

A NULL OP callback function.

This function always returns null.

Used internally by Phaser when it's more expensive to determine if a callback exists than it is to just invoke an empty function.

Source: src/utils/NULL.js#L7
Since: 3.60.0

Phaser.Utils.Array

Add​

<static> Add(array, item, [limit], [callback], [context])​

Description:

Adds the given item, or array of items, to the array.

Each item must be unique within the array.

The array is modified in-place. The added item, or array of added items, is returned. Returns null if no items were added (e.g. the array is already at the limit, or all items already exist in the array).

You can optionally specify a limit to the maximum size of the array. If the quantity of items being added will take the array length over this limit, it will stop adding once the limit is reached.

You can optionally specify a callback to be invoked for each item successfully added to the array.

Parameters:

nametypeoptionaldescription
arrayarrayNoThe array to be added to.
itemany | Array.<any>NoThe item, or array of items, to add to the array. Each item must be unique within the array.
limitnumberYesOptional limit which caps the size of the array.
callbackfunctionYesA callback to be invoked for each item successfully added to the array.
contextobjectYesThe context in which the callback is invoked.

Returns: array - The item, or array of items, that were successfully added to the array, or null if nothing was added.

Source: src/utils/array/Add.js#L7
Since: 3.4.0

AddAt​

<static> AddAt(array, item, [index], [limit], [callback], [context])​

Description:

Adds the given item, or array of items, to the array starting at the index specified.

Each item must be unique within the array.

Existing elements in the array are shifted up.

The array is modified in-place. The inserted item, or array of inserted items, is returned. Returns null if no items were added (e.g. the array is full, or all items were already present).

You can optionally specify a limit to the maximum size of the array. If the quantity of items being added will take the array length over this limit, it will stop adding once the limit is reached.

You can optionally specify a callback to be invoked for each item successfully added to the array.

Parameters:

nametypeoptionaldefaultdescription
arrayarrayNoThe array to be added to.
itemany | Array.<any>NoThe item, or array of items, to add to the array.
indexnumberYes0The index in the array where the item will be inserted.
limitnumberYesOptional limit which caps the size of the array.
callbackfunctionYesA callback to be invoked for each item successfully added to the array.
contextobjectYesThe context in which the callback is invoked.

Returns: array - The item, or array of items, that were successfully inserted, or null if nothing was added.

Source: src/utils/array/AddAt.js#L7
Since: 3.4.0

BringToTop​

<static> BringToTop(array, item)​

Description:

Moves the given element to the top of the array. The array is modified in-place.

Parameters:

nametypeoptionaldescription
arrayarrayNoThe array to modify.
item*NoThe element to move to the top of the array.

Returns: * - The element that was moved.

Source: src/utils/array/BringToTop.js#L7
Since: 3.4.0

CountAllMatching​

<static> CountAllMatching(array, property, value, [startIndex], [endIndex])​

Description:

Returns the total number of elements in the array which have a property matching the given value.

Parameters:

nametypeoptionaldescription
arrayarrayNoThe array to search.
propertystringNoThe property to test on each array element.
value*NoThe value to test the property against. Must pass a strict (===) comparison check.
startIndexnumberYesAn optional start index to search from.
endIndexnumberYesAn optional end index to search to.

Returns: number - The total number of elements with properties matching the given value.

Source: src/utils/array/CountAllMatching.js#L9
Since: 3.4.0

Each​

<static> Each(array, callback, context, [args])​

Description:

Passes each element in the array to the given callback.

Parameters:

nametypeoptionaldescription
arrayarrayNoThe array to iterate over.
callbackfunctionNoA callback to be invoked for each item in the array.
contextobjectNoThe context in which the callback is invoked.
args*YesAdditional arguments that will be passed to the callback, after the current array item.

Returns: array - The input array.

Source: src/utils/array/Each.js#L7
Since: 3.4.0

EachInRange​

<static> EachInRange(array, callback, context, startIndex, endIndex, [args])​

Description:

Passes each element in the array, between the start and end indexes, to the given callback.

Parameters:

nametypeoptionaldescription
arrayarrayNoThe array to iterate over.
callbackfunctionNoA callback to be invoked for each item in the array.
contextobjectNoThe context in which the callback is invoked.
startIndexnumberNoThe start index to iterate from.
endIndexnumberNoThe end index to iterate to.
args*YesAdditional arguments that will be passed to the callback, after the child.

Returns: array - The input array.

Source: src/utils/array/EachInRange.js#L9
Since: 3.4.0

FindClosestInSorted​

<static> FindClosestInSorted(value, array, [key])​

Description:

Searches a pre-sorted array for the closest value to the given number.

If the key argument is given it will assume the array contains objects that all have the required key property name, and will check for the closest value of those to the given number.

Parameters:

nametypeoptionaldescription
valuenumberNoThe value to search for in the array.
arrayarrayNoThe array to search, which must be sorted.
keystringYesAn optional property key. If specified the array element's property will be checked against value.

Returns: number, any - The nearest value found in the array, or if a key was given, the nearest object with the matching property value.

Source: src/utils/array/FindClosestInSorted.js#L7
Since: 3.0.0

Flatten​

<static> Flatten(array, [output])​

Description:

Takes an array and deeply flattens it, recursively unpacking any nested arrays into a single flat array. The original array is not modified. An optional output array can be provided to collect the results, which is useful when calling this function recursively or when appending to an existing array.

Parameters:

nametypeoptionaldescription
arrayarrayNoThe array to flatten.
outputarrayYesAn array to hold the results in.

Returns: array - The flattened output array.

Source: src/utils/array/Flatten.js#L7
Since: 3.60.0

GetAll​

<static> GetAll(array, [property], [value], [startIndex], [endIndex])​

Description:

Returns all elements in the array.

You can optionally specify a matching criteria using the property and value arguments.

For example: GetAll('visible', true) would return only elements that have their visible property set to true.

Optionally you can specify a start and end index. For example if the array had 100 elements, and you set startIndex to 0 and endIndex to 50, it would return matches from only the first 50 elements.

Parameters:

nametypeoptionaldescription
arrayarrayNoThe array to search.
propertystringYesThe property to test on each array element.
value*YesThe value to test the property against. Must pass a strict (===) comparison check.
startIndexnumberYesAn optional start index to search from.
endIndexnumberYesAn optional end index to search to.

Returns: array - All matching elements from the array.

Source: src/utils/array/GetAll.js#L9
Since: 3.4.0

GetFirst​

<static> GetFirst(array, [property], [value], [startIndex], [endIndex])​

Description:

Returns the first element in the array.

You can optionally specify a matching criteria using the property and value arguments.

For example: GetFirst('visible', true) would return the first element that had its visible property set to true.

Optionally you can specify a start and end index. For example if the array had 100 elements, and you set startIndex to 0 and endIndex to 50, it would search only the first 50 elements.

You can also specify a negative startIndex, such as -1, which would start the search at the end of the array

Parameters:

nametypeoptionaldefaultdescription
arrayarrayNoThe array to search.
propertystringYesThe property to test on each array element.
value*YesThe value to test the property against. Must pass a strict (===) comparison check.
startIndexnumberYes0An optional start index to search from. You can also set startIndex to -1 to start the search from the end of the array.
endIndexnumberYes"array.length"An optional end index to search up to (but not included)

Returns: object - The first matching element from the array, or null if no element could be found in the range given.

Source: src/utils/array/GetFirst.js#L9
Since: 3.4.0

GetRandom​

<static> GetRandom(array, [startIndex], [length])​

Description:

Returns a Random element from the array.

Tags:

  • generic
  • genericUse
  • genericUse

Parameters:

nametypeoptionaldefaultdescription
arrayArray.<T>NoThe array to select the random entry from.
startIndexnumberYes0An optional start index.
lengthnumberYes"array.length"An optional length, the total number of elements (from the startIndex) to choose from.

Returns: T - A random element from the array, or null if no element could be found in the range given.

Source: src/utils/array/GetRandom.js#L7
Since: 3.0.0

MoveAbove​

<static> MoveAbove(array, item1, item2)​

Description:

Moves the given array element above another one in the array. If the given element is already above the other, it isn't moved. Above means toward the end of the array. The array is modified in-place.

Parameters:

nametypeoptionaldescription
arrayarrayNoThe input array.
item1*NoThe element to move above the base element.
item2*NoThe base element.

Returns: array - The input array.

Source: src/utils/array/MoveAbove.js#L7
Since: 3.55.0

MoveBelow​

<static> MoveBelow(array, item1, item2)​

Description:

Moves the given array element below another one in the array. If the given element is already below the other, it isn't moved. Below means toward the start of the array. The array is modified in-place.

Parameters:

nametypeoptionaldescription
arrayarrayNoThe input array.
item1*NoThe element to move below the base element.
item2*NoThe base element.

Returns: array - The input array.

Source: src/utils/array/MoveBelow.js#L7
Since: 3.55.0

MoveDown​

<static> MoveDown(array, item)​

Description:

Moves the given array element down one place in the array. The array is modified in-place.

Parameters:

nametypeoptionaldescription
arrayarrayNoThe input array.
item*NoThe element to move down the array.

Returns: array - The input array, with the item moved down one place.

Source: src/utils/array/MoveDown.js#L7
Since: 3.4.0

MoveTo​

<static> MoveTo(array, item, index)​

Description:

Moves an element in an array to a new position within the same array. The array is modified in-place.

Parameters:

nametypeoptionaldescription
arrayarrayNoThe array.
item*NoThe element to move.
indexnumberNoThe new index that the element will be moved to.

Returns: * - The element that was moved.

Source: src/utils/array/MoveTo.js#L7
Since: 3.4.0

MoveUp​

<static> MoveUp(array, item)​

Description:

Moves the given array element up one place in the array. The array is modified in-place.

Parameters:

nametypeoptionaldescription
arrayarrayNoThe input array.
item*NoThe element to move up the array.

Returns: array - The input array.

Source: src/utils/array/MoveUp.js#L7
Since: 3.4.0

NumberArray​

<static> NumberArray(start, end, [prefix], [suffix])​

Description:

Create an array representing the range of numbers (usually integers), between, and inclusive of, the given start and end arguments. For example:

var array = Phaser.Utils.Array.NumberArray(2, 4); // array = [2, 3, 4] var array = Phaser.Utils.Array.NumberArray(0, 9); // array = [0, 1, 2, 3, 4, 5, 6, 7, 8, 9] var array = Phaser.Utils.Array.NumberArray(8, 2); // array = [8, 7, 6, 5, 4, 3, 2]

This is equivalent to Phaser.Utils.Array.NumberArrayStep(start, end, 1).

You can optionally provide a prefix and / or suffix string. If given the array will contain strings, not integers. For example:

var array = Phaser.Utils.Array.NumberArray(1, 4, 'Level '); // array = ["Level 1", "Level 2", "Level 3", "Level 4"] var array = Phaser.Utils.Array.NumberArray(5, 7, 'HD-', '.png'); // array = ["HD-5.png", "HD-6.png", "HD-7.png"]

Parameters:

nametypeoptionaldescription
startnumberNoThe minimum value the array starts with.
endnumberNoThe maximum value the array contains.
prefixstringYesOptional prefix to place before the number. If provided the array will contain strings, not integers.
suffixstringYesOptional suffix to place after the number. If provided the array will contain strings, not integers.

Returns: Array.<number>, Array.<string> - The array of number values, or strings if a prefix or suffix was provided.

Source: src/utils/array/NumberArray.js#L7
Since: 3.0.0

NumberArrayStep​

<static> NumberArrayStep([start], [end], [step])​

Description:

Create an array of numbers (positive and/or negative) progressing from start up to but not including end by advancing by step.

If start is greater than end a zero-length range is created unless a negative step is specified.

Certain values for start and end (eg. NaN/undefined/null) are currently coerced to 0; for forward compatibility make sure to pass in actual numbers.

Parameters:

nametypeoptionaldefaultdescription
startnumberYes0The start of the range.
endnumberYesnullThe end of the range.
stepnumberYes1The value to increment or decrement by.

Returns: Array.<number> - The array of number values.

Source: src/utils/array/NumberArrayStep.js#L9
Since: 3.0.0

QuickSelect​

<static> QuickSelect(arr, k, [left], [right], [compare])​

Description:

A Floyd-Rivest quick selection algorithm.

Rearranges the array items so that all items in the [left, k] range are smaller than all items in [k, right]; The k-th element will have the (k - left + 1)th smallest value in [left, right].

The array is modified in-place.

Based on code by Vladimir Agafonkin

Parameters:

nametypeoptionaldefaultdescription
arrarrayNoThe array to rearrange in-place.
knumberNoThe k-th element index.
leftnumberYes0The index of the left part of the range.
rightnumberYesThe index of the right part of the range.
comparefunctionYesAn optional comparison function. Is passed two elements and should return a negative number if the first is less than the second, zero if they are equal, or a positive number if the first is greater.

Source: src/utils/array/QuickSelect.js#L25
Since: 3.0.0

Range​

<static> Range(a, b, [options])​

Description:

Creates an array populated with a range of values, based on the given arguments and configuration object.

Range ([a,b,c], [1,2,3]) = a1, a2, a3, b1, b2, b3, c1, c2, c3

Range ([a,b], [1,2,3], qty = 3) = a1, a1, a1, a2, a2, a2, a3, a3, a3, b1, b1, b1, b2, b2, b2, b3, b3, b3

Range ([a,b,c], [1,2,3], repeat x1) = a1, a2, a3, b1, b2, b3, c1, c2, c3, a1, a2, a3, b1, b2, b3, c1, c2, c3

Range ([a,b], [1,2], repeat -1 = endless, max = 14) = a1, a2, b1, b2, a1, a2, b1, b2, a1, a2, b1, b2, a1, a2 (capped at 14 elements)

Range ([a], [1,2,3,4,5], random = true) = a4, a1, a5, a2, a3

Range ([a, b], [1,2,3], random = true) = b3, a2, a1, b1, a3, b2

Range ([a, b, c], [1,2,3], randomB = true) = a3, a1, a2, b2, b3, b1, c1, c3, c2

Range ([a], [1,2,3,4,5], yoyo = true) = a1, a2, a3, a4, a5, a5, a4, a3, a2, a1

Range ([a, b], [1,2,3], yoyo = true) = a1, a2, a3, b1, b2, b3, b3, b2, b1, a3, a2, a1

Parameters:

nametypeoptionaldescription
aarrayNoThe first array of range elements.
barrayNoThe second array of range elements.
optionsobjectYesA range configuration object. Supports the following properties: qty (number of times each pair is duplicated, default 1), repeat (number of times the entire range is repeated, use -1 for endless), random (shuffle the full output array), randomB (shuffle array b before building pairs), yoyo (append the range in reverse after the forward pass), max (cap the total number of elements in the output).

Returns: array - An array of { a, b } pair objects built from the cartesian product of the two input arrays, arranged according to the given options.

Source: src/utils/array/Range.js#L28
Since: 3.0.0

Remove​

<static> Remove(array, item, [callback], [context])​

Description:

Removes the given item, or array of items, from the array.

The array is modified in-place.

You can optionally specify a callback to be invoked for each item successfully removed from the array.

Parameters:

nametypeoptionaldescription
arrayarrayNoThe array to be modified.
item* | Array.<*>NoThe item, or array of items, to be removed from the array.
callbackfunctionYesA callback to be invoked for each item successfully removed from the array.
contextobjectYesThe context in which the callback is invoked.

Returns: , Array.<> - The item, or array of items, that were successfully removed from the array.

Source: src/utils/array/Remove.js#L9
Since: 3.4.0

RemoveAt​

<static> RemoveAt(array, index, [callback], [context])​

Description:

Removes the item from the given position in the array.

The array is modified in-place.

You can optionally specify a callback to be invoked for the item if it is successfully removed from the array.

Parameters:

nametypeoptionaldescription
arrayarrayNoThe array to be modified.
indexnumberNoThe array index to remove the item from. The index must be in bounds or it will throw an error.
callbackfunctionYesA callback to be invoked for the item removed from the array.
contextobjectYesThe context in which the callback is invoked.

Returns: * - The item that was removed.

Source: src/utils/array/RemoveAt.js#L9
Since: 3.4.0

RemoveBetween​

<static> RemoveBetween(array, startIndex, endIndex, [callback], [context])​

Description:

Removes all items within the given index range from the array.

The array is modified in-place.

You can optionally specify a callback to be invoked for the item/s successfully removed from the array.

Parameters:

nametypeoptionaldescription
arrayarrayNoThe array to be modified.
startIndexnumberNoThe start index to remove from.
endIndexnumberNoThe end index to remove up to (exclusive).
callbackfunctionYesA callback to be invoked for each item successfully removed from the array.
contextobjectYesThe context in which the callback is invoked.

Returns: Array.<*> - An array of items that were removed.

Source: src/utils/array/RemoveBetween.js#L9
Since: 3.4.0

RemoveRandomElement​

<static> RemoveRandomElement(array, [start], [length])​

Description:

Removes a random object from the given array and returns it. Will return null if there are no array items that fall within the specified range or if there is no item for the randomly chosen index.

Parameters:

nametypeoptionaldefaultdescription
arrayarrayNoThe array to remove a random element from.
startnumberYes0The array index to start the search from.
lengthnumberYes"array.length"Optional restriction on the number of elements to randomly select from.

Returns: object - The random element that was removed, or null if there were no array elements that fell within the given range.

Source: src/utils/array/RemoveRandomElement.js#L9
Since: 3.0.0

Replace​

<static> Replace(array, oldChild, newChild)​

Description:

Replaces an element of the array with the new element. The new element cannot already be a member of the array. The array is modified in-place.

Parameters:

nametypeoptionaldescription
arrayarrayNoThe array to search within.
oldChild*NoThe element in the array that will be replaced.
newChild*NoThe element to be inserted into the array at the position of oldChild.

Returns: boolean - Returns true if the oldChild was successfully replaced, otherwise returns false.

Source: src/utils/array/Replace.js#L7
Since: 3.4.0

RotateLeft​

<static> RotateLeft(array, [total])​

Description:

Moves the element at the start of the array to the end, shifting all items in the process. The "rotation" happens to the left.

Parameters:

nametypeoptionaldefaultdescription
arrayarrayNoThe array to shift to the left. This array is modified in place.
totalnumberYes1The number of times to shift the array.

Returns: * - The most recently shifted element.

Source: src/utils/array/RotateLeft.js#L7
Since: 3.0.0

RotateRight​

<static> RotateRight(array, [total])​

Description:

Moves the element at the end of the array to the start, shifting all items in the process. The "rotation" happens to the right.

Parameters:

nametypeoptionaldefaultdescription
arrayarrayNoThe array to shift to the right. This array is modified in place.
totalnumberYes1The number of times to shift the array.

Returns: * - The most recently shifted element.

Source: src/utils/array/RotateRight.js#L7
Since: 3.0.0

SafeRange​

<static> SafeRange(array, startIndex, endIndex, [throwError])​

Description:

Tests if the start and end indexes define a valid, safe range within the given array.

A range is considered safe when startIndex is zero or greater, startIndex is less than endIndex, and endIndex does not exceed the length of the array.

Parameters:

nametypeoptionaldefaultdescription
arrayarrayNoThe array to check.
startIndexnumberNoThe inclusive start index of the range. Must be zero or greater and less than endIndex.
endIndexnumberNoThe exclusive end index of the range. Must be greater than startIndex and no greater than the array length.
throwErrorbooleanYesfalseIf true, a Range Error is thrown when the range is out of bounds instead of returning false.

Returns: boolean - True if the range is safe, otherwise false.

Source: src/utils/array/SafeRange.js#L7
Since: 3.4.0

SendToBack​

<static> SendToBack(array, item)​

Description:

Moves the given element to the bottom of the array (index 0), shifting all other elements up by one position. The array is modified in-place. If the element is not found in the array, or is already at index 0, the array is left unchanged.

Parameters:

nametypeoptionaldescription
arrayarrayNoThe array to search and modify.
item*NoThe element to move to the bottom of the array.

Returns: * - The element that was moved.

Source: src/utils/array/SendToBack.js#L7
Since: 3.4.0

SetAll​

<static> SetAll(array, property, value, [startIndex], [endIndex])​

Description:

Scans the array for elements with the given property. If found, the property is set to the value.

For example: SetAll(array, 'visible', true) would set all elements that have a visible property to true.

Optionally you can specify a start and end index. For example if the array had 100 elements, and you set startIndex to 0 and endIndex to 50, it would update only the first 50 elements.

Parameters:

nametypeoptionaldescription
arrayarrayNoThe array to search.
propertystringNoThe property to test for on each array element.
value*NoThe value to set the property to.
startIndexnumberYesAn optional start index to search from.
endIndexnumberYesAn optional end index to search to.

Returns: array - The input array.

Source: src/utils/array/SetAll.js#L9
Since: 3.4.0

Shuffle​

<static> Shuffle(array)​

Description:

Shuffles the contents of the given array using the Fisher-Yates implementation.

The original array is modified directly and returned.

Tags:

  • generic
  • genericUse

Parameters:

nametypeoptionaldescription
arrayArray.<T>NoThe array to shuffle. This array is modified in place.

Returns: Array.<T> - The shuffled array.

Source: src/utils/array/Shuffle.js#L7
Since: 3.0.0

SortByDigits​

<static> SortByDigits(array)​

Description:

Takes the given array and runs a numeric sort on it, ignoring any non-digits that may be in the entries.

You should only run this on arrays containing strings.

Parameters:

nametypeoptionaldescription
arrayArray.<string>NoThe input array of strings.

Returns: Array.<string> - The sorted input array.

Source: src/utils/array/SortByDigits.js#L7
Since: 3.50.0

SpliceOne​

<static> SpliceOne(array, index)​

Description:

Removes a single item from an array and returns it without creating gc, like the native splice does. Based on code by Mike Reinstein.

Parameters:

nametypeoptionaldescription
arrayarrayNoThe array to splice from.
indexnumberNoThe index of the item which should be spliced.

Returns: * - The item which was spliced (removed).

Source: src/utils/array/SpliceOne.js#L7
Since: 3.0.0

StableSort​

<static> StableSort(array, [compare])​

Description:

An in-place stable array sort, because Array#sort() is not guaranteed stable.

This is an implementation of merge sort, without recursion.

Function based on the Two-Screen/stable sort 0.1.8 from https://github.com/Two-Screen/stable

Parameters:

nametypeoptionaldescription
arrayarrayNoThe input array to be sorted.
comparefunctionYesThe comparison function.

Returns: array - The sorted result.

Source: src/utils/array/StableSort.js#L142
Since: 3.0.0

Swap​

<static> Swap(array, item1, item2)​

Description:

Swaps the position of two elements in the given array. The elements must exist in the same array. The array is modified in-place.

Parameters:

nametypeoptionaldescription
arrayarrayNoThe input array.
item1*NoThe first element to swap.
item2*NoThe second element to swap.

Returns: array - The input array.

Source: src/utils/array/Swap.js#L7
Since: 3.4.0

Phaser.Utils.Array.Matrix

CheckMatrix​

<static> CheckMatrix([matrix])​

Description:

Checks if an array can be used as a matrix.

A matrix is a two-dimensional array (array of arrays), where all sub-arrays (rows) have the same length. This is an example matrix:


[

   [ 1, 1, 1, 1, 1, 1 ],

   [ 2, 0, 0, 0, 0, 4 ],

   [ 2, 0, 1, 2, 0, 4 ],

   [ 2, 0, 3, 4, 0, 4 ],

   [ 2, 0, 0, 0, 0, 4 ],

   [ 3, 3, 3, 3, 3, 3 ]

]

Tags:

  • generic
  • genericUse

Parameters:

nametypeoptionaldescription
matrixArray.<Array.<T>>YesThe array to check.

Returns: boolean - true if the given matrix array is a valid matrix.

Source: src/utils/array/matrix/CheckMatrix.js#L7
Since: 3.0.0

MatrixToString​

<static> MatrixToString([matrix])​

Description:

Generates a formatted string representation of the given Array Matrix, suitable for logging to the console via console.log. Each row is rendered on its own line with cell values separated by |, and rows are divided by a ---+ separator line.

A matrix is a two-dimensional array (array of arrays), where all sub-arrays (rows) have the same length. There must be at least two rows. This is an example matrix:


[

   [ 1, 1, 1, 1, 1, 1 ],

   [ 2, 0, 0, 0, 0, 4 ],

   [ 2, 0, 1, 2, 0, 4 ],

   [ 2, 0, 3, 4, 0, 4 ],

   [ 2, 0, 0, 0, 0, 4 ],

   [ 3, 3, 3, 3, 3, 3 ]

]

Tags:

  • generic
  • genericUse

Parameters:

nametypeoptionaldescription
matrixArray.<Array.<T>>YesA 2-dimensional array representing the matrix to convert.

Returns: string - A formatted string representing the matrix, with columns separated by | and rows separated by ---+ divider lines. Returns an empty string if the matrix is invalid.

Source: src/utils/array/matrix/MatrixToString.js#L10
Since: 3.0.0

ReverseColumns​

<static> ReverseColumns([matrix])​

Description:

Reverses the row order of the given Array Matrix, which has the effect of reversing the sequence of values within each column from top to bottom.

A matrix is a two-dimensional array (array of arrays), where all sub-arrays (rows) have the same length. There must be at least two rows. This is an example matrix:


[

   [ 1, 1, 1, 1, 1, 1 ],

   [ 2, 0, 0, 0, 0, 4 ],

   [ 2, 0, 1, 2, 0, 4 ],

   [ 2, 0, 3, 4, 0, 4 ],

   [ 2, 0, 0, 0, 0, 4 ],

   [ 3, 3, 3, 3, 3, 3 ]

]

Tags:

  • generic
  • genericUse

Parameters:

nametypeoptionaldescription
matrixArray.<Array.<T>>YesThe array matrix whose row order will be reversed.

Returns: Array.<Array.<T>> - The column reversed matrix.

Source: src/utils/array/matrix/ReverseColumns.js#L7
Since: 3.0.0

ReverseRows​

<static> ReverseRows([matrix])​

Description:

Reverses the order of elements in each row of the given Array Matrix.

A matrix is a two-dimensional array (array of arrays), where all sub-arrays (rows) have the same length. There must be at least two rows. This is an example matrix:


[

   [ 1, 1, 1, 1, 1, 1 ],

   [ 2, 0, 0, 0, 0, 4 ],

   [ 2, 0, 1, 2, 0, 4 ],

   [ 2, 0, 3, 4, 0, 4 ],

   [ 2, 0, 0, 0, 0, 4 ],

   [ 3, 3, 3, 3, 3, 3 ]

]

Tags:

  • generic
  • genericUse

Parameters:

nametypeoptionaldescription
matrixArray.<Array.<T>>YesThe array matrix to reverse the elements of each row for.

Returns: Array.<Array.<T>> - The matrix with each row's elements reversed in place.

Source: src/utils/array/matrix/ReverseRows.js#L7
Since: 3.0.0

Rotate180​

<static> Rotate180([matrix])​

Description:

Rotates the array matrix 180 degrees.

A matrix is a two-dimensional array (array of arrays), where all sub-arrays (rows) have the same length. There must be at least two rows. This is an example matrix:


[

   [ 1, 1, 1, 1, 1, 1 ],

   [ 2, 0, 0, 0, 0, 4 ],

   [ 2, 0, 1, 2, 0, 4 ],

   [ 2, 0, 3, 4, 0, 4 ],

   [ 2, 0, 0, 0, 0, 4 ],

   [ 3, 3, 3, 3, 3, 3 ]

]

Tags:

  • generic
  • genericUse

Parameters:

nametypeoptionaldescription
matrixArray.<Array.<T>>YesThe array to rotate.

Returns: Array.<Array.<T>> - The rotated matrix array. The source matrix should be discarded for the returned matrix.

Source: src/utils/array/matrix/Rotate180.js#L9
Since: 3.0.0

RotateLeft​

<static> RotateLeft([matrix], [amount])​

Description:

Rotates the array matrix to the left (counter-clockwise) by 90 degrees per step.

A matrix is a two-dimensional array (array of arrays), where all sub-arrays (rows) have the same length. There must be at least two rows. This is an example matrix:


[

   [ 1, 1, 1, 1, 1, 1 ],

   [ 2, 0, 0, 0, 0, 4 ],

   [ 2, 0, 1, 2, 0, 4 ],

   [ 2, 0, 3, 4, 0, 4 ],

   [ 2, 0, 0, 0, 0, 4 ],

   [ 3, 3, 3, 3, 3, 3 ]

]

Tags:

  • generic
  • genericUse

Parameters:

nametypeoptionaldefaultdescription
matrixArray.<Array.<T>>YesThe array to rotate.
amountnumberYes1The number of times to rotate the matrix 90 degrees to the left.

Returns: Array.<Array.<T>> - The rotated matrix array. The source matrix should be discarded for the returned matrix.

Source: src/utils/array/matrix/RotateLeft.js#L9
Since: 3.0.0

RotateMatrix​

<static> RotateMatrix([matrix], [direction])​

Description:

Rotates the array matrix based on the given rotation value.

The value can be given in degrees: 90, -90, 270, -270, 180 or -180, or a string command: rotateLeft, rotateRight or rotate180.

Based on the routine from http://jsfiddle.net/MrPolywhirl/NH42z/.

A matrix is a two-dimensional array (array of arrays), where all sub-arrays (rows) have the same length. There must be at least two rows. This is an example matrix:


[

   [ 1, 1, 1, 1, 1, 1 ],

   [ 2, 0, 0, 0, 0, 4 ],

   [ 2, 0, 1, 2, 0, 4 ],

   [ 2, 0, 3, 4, 0, 4 ],

   [ 2, 0, 0, 0, 0, 4 ],

   [ 3, 3, 3, 3, 3, 3 ]

]

Tags:

  • generic
  • genericUse

Parameters:

nametypeoptionaldefaultdescription
matrixArray.<Array.<T>>YesThe array to rotate.
directionnumber | stringYes90The amount to rotate the matrix by. Must be a degree value of 90, -90, 270, -270, 180 or -180, or a string command of rotateLeft, rotateRight or rotate180. If an unrecognized value is given the matrix will not be rotated.

Returns: Array.<Array.<T>> - The rotated matrix array. The source matrix should be discarded for the returned matrix.

Source: src/utils/array/matrix/RotateMatrix.js#L10
Since: 3.0.0

RotateRight​

<static> RotateRight([matrix], [amount])​

Description:

Rotates the array matrix 90 degrees to the right (clockwise).

A matrix is a two-dimensional array (array of arrays), where all sub-arrays (rows) have the same length. There must be at least two rows. This is an example matrix:


[

   [ 1, 1, 1, 1, 1, 1 ],

   [ 2, 0, 0, 0, 0, 4 ],

   [ 2, 0, 1, 2, 0, 4 ],

   [ 2, 0, 3, 4, 0, 4 ],

   [ 2, 0, 0, 0, 0, 4 ],

   [ 3, 3, 3, 3, 3, 3 ]

]

Tags:

  • generic
  • genericUse

Parameters:

nametypeoptionaldefaultdescription
matrixArray.<Array.<T>>YesThe array to rotate.
amountnumberYes1The number of times to rotate the matrix 90 degrees clockwise.

Returns: Array.<Array.<T>> - The rotated matrix array. The source matrix should be discarded for the returned matrix.

Source: src/utils/array/matrix/RotateRight.js#L9
Since: 3.0.0

Translate​

<static> Translate([matrix], [x], [y])​

Description:

Translates the given Array Matrix by shifting its rows and the elements within each row by the amounts specified. The translation wraps cyclically: elements shifted off one edge of the matrix reappear on the opposite edge.

A positive x value shifts elements within each row to the right, and a negative value shifts them to the left. A positive y value shifts rows downward, and a negative value shifts them upward.

A matrix is a two-dimensional array (array of arrays), where all sub-arrays (rows) have the same length. There must be at least two rows. This is an example matrix:


[

   [ 1, 1, 1, 1, 1, 1 ],

   [ 2, 0, 0, 0, 0, 4 ],

   [ 2, 0, 1, 2, 0, 4 ],

   [ 2, 0, 3, 4, 0, 4 ],

   [ 2, 0, 0, 0, 0, 4 ],

   [ 3, 3, 3, 3, 3, 3 ]

]

Tags:

  • generic
  • genericUse

Parameters:

nametypeoptionaldefaultdescription
matrixArray.<Array.<T>>YesThe array matrix to translate.
xnumberYes0The amount to horizontally translate the matrix by.
ynumberYes0The amount to vertically translate the matrix by.

Returns: Array.<Array.<T>> - The translated matrix.

Source: src/utils/array/matrix/TranslateMatrix.js#L10
Since: 3.50.0

TransposeMatrix​

<static> TransposeMatrix([array])​

Description:

Transposes the elements of the given matrix (array of arrays).

The transpose of a matrix is a new matrix whose rows are the columns of the original.

A matrix is a two-dimensional array (array of arrays), where all sub-arrays (rows) have the same length. There must be at least one row. This is an example matrix:


[

   [ 1, 1, 1, 1, 1, 1 ],

   [ 2, 0, 0, 0, 0, 4 ],

   [ 2, 0, 1, 2, 0, 4 ],

   [ 2, 0, 3, 4, 0, 4 ],

   [ 2, 0, 0, 0, 0, 4 ],

   [ 3, 3, 3, 3, 3, 3 ]

]

Tags:

  • generic
  • genericUse

Parameters:

nametypeoptionaldescription
arrayArray.<Array.<T>>YesThe array matrix to transpose.

Returns: Array.<Array.<T>> - A new array matrix which is a transposed version of the given array.

Source: src/utils/array/matrix/TransposeMatrix.js#L7
Since: 3.0.0

Phaser.Utils.Base64

ArrayBufferToBase64​

<static> ArrayBufferToBase64(arrayBuffer, [mediaType])​

Description:

Converts an ArrayBuffer into a base64 string.

The resulting string can optionally be a data uri if the mediaType argument is provided.

See https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/Data_URIs for more details.

Parameters:

nametypeoptionaldescription
arrayBufferArrayBufferNoThe Array Buffer to encode.
mediaTypestringYesAn optional media type, i.e. audio/ogg or image/jpeg. If included the resulting string will be a data URI.

Returns: string - The base64 encoded Array Buffer.

Source: src/utils/base64/ArrayBufferToBase64.js#L10
Since: 3.18.0

Base64ToArrayBuffer​

<static> Base64ToArrayBuffer(base64)​

Description:

Converts a base64 string, either with or without a data uri, into an Array Buffer.

Parameters:

nametypeoptionaldescription
base64stringNoThe base64 string to be decoded. Can optionally contain a data URI header, which will be stripped out prior to decoding.

Returns: ArrayBuffer - An ArrayBuffer decoded from the base64 data.

Source: src/utils/base64/Base64ToArrayBuffer.js#L18
Since: 3.18.0

Phaser.Utils.Objects

Clone​

<static> Clone(obj)​

Description:

Shallow Object Clone. Will not clone nested objects.

Parameters:

nametypeoptionaldescription
objobjectNoThe object to clone.

Returns: object - A new object with the same properties as the input object.

Source: src/utils/object/Clone.js#L7
Since: 3.0.0

DeepCopy​

<static> DeepCopy(inObject)​

Description:

Recursively deep copies the given object or array, returning a brand new instance with all nested objects and arrays also cloned. The original object is not modified. If a non-object value is passed (such as a string, number, boolean, or null), it is returned as-is.

Parameters:

nametypeoptionaldescription
inObjectobjectNoThe object or array to deep copy.

Returns: object - A deep copy of the original object or array.

Source: src/utils/object/DeepCopy.js#L7
Since: 3.50.0

Extend​

<static> Extend([args])​

Description:

Merges the properties of one or more source objects into a target object, returning the modified target. This is a slightly modified version of jQuery.extend.

The function accepts a variadic argument list. If the first argument is a boolean true, a deep (recursive) copy is performed, and the second argument is treated as the target. Otherwise, the first argument is the target and all subsequent arguments are source objects. Properties from each source object are copied onto the target in order; later sources overwrite earlier ones for the same key. Nested plain objects and arrays are cloned rather than referenced during a deep copy, preventing mutation of the originals. undefined values on a source are never copied to the target.

Parameters:

nametypeoptionaldescription
args*YesAn optional leading boolean for deep-copy mode, followed by the target object, then one or more source objects whose properties will be merged into the target.

Returns: object - The extended object.

Source: src/utils/object/Extend.js#L13
Since: 3.0.0

GetAdvancedValue​

<static> GetAdvancedValue(source, key, defaultValue)​

Description:

Retrieves a value from an object. Extends GetValue with support for dynamic and randomized value types, making it useful for configuration objects where values may be fixed, procedural, or randomly selected at the point of use (for example, particle emitter configs or group configs).

The following value types are supported for the retrieved property:

Explicit value:

{

x: 4

}

Function — invoked with the property key as its argument; its return value is used:

{

x: function (key) { return 4; }

}

Array — one element is picked at random from the array:

{

x: [a, b, c, d, e, f]

}

Random integer between min and max (inclusive):

{

x: { randInt: [min, max] }

}

Random float between min and max:

{

x: { randFloat: [min, max] }

}

Parameters:

nametypeoptionaldescription
sourceobjectNoThe object to retrieve the value from.
keystringNoThe name of the property to retrieve from the object. If a property is nested, the names of its preceding properties should be separated by a dot (.) - banner.hideBanner would return the value of the hideBanner property from the object stored in the banner property of the source object.
defaultValue*NoThe value to return if the key isn't found in the source object.

Returns: * - The value of the requested key.

Source: src/utils/object/GetAdvancedValue.js#L10
Since: 3.0.0

GetFastValue​

<static> GetFastValue(source, key, [defaultValue])​

Description:

Retrieves the value of the given key from the top level of the source object. If the source is not an object (i.e. it is falsy, a number, or a string), or if the key does not exist on the source, the defaultValue is returned instead.

Parameters:

nametypeoptionaldescription
sourceobjectNoThe object to search
keystringNoThe key for the property on source. Must exist at the top level of the source object (no periods)
defaultValue*YesThe default value to use if the key does not exist.

Returns: * - The value if found; otherwise, defaultValue (null if none provided)

Source: src/utils/object/GetFastValue.js#L7
Since: 3.0.0

GetMinMaxValue​

<static> GetMinMaxValue(source, key, min, max, defaultValue)​

Description:

Retrieves a numerical value from a source object using the given key, then clamps it to the inclusive range defined by min and max. If the property does not exist on the source object, the defaultValue is used instead. Nested properties can be accessed by separating key names with a dot. The returned value is always within the specified bounds.

Parameters:

nametypeoptionaldescription
sourceobjectNoThe object to retrieve the value from.
keystringNoThe name of the property to retrieve from the object. If a property is nested, the names of its preceding properties should be separated by a dot (.).
minnumberNoThe minimum value which can be returned.
maxnumberNoThe maximum value which can be returned.
defaultValuenumberNoThe value to return if the property doesn't exist. If not provided, defaults to min. It's also constrained to the given bounds.

Returns: number - The clamped value from the source object.

Source: src/utils/object/GetMinMaxValue.js#L10
Since: 3.0.0

GetValue​

<static> GetValue(source, key, defaultValue, [altSource])​

Description:

Retrieves a value from an object, or an alternative object, falling to a back-up default value if not found.

The key is a string, which can be split based on the use of the period character.

For example:


const source = {

  lives: 3,

  render: {

    screen: {

      width: 1024

    }

  }

}



const lives = GetValue(source, 'lives', 1);

const width = GetValue(source, 'render.screen.width', 800);

const height = GetValue(source, 'render.screen.height', 600);

In the code above, lives will be 3 because it's defined at the top level of source. The width value will be 1024 because it can be found inside the render.screen object. The height value will be 600, the default value, because it is missing from the render.screen object.

Parameters:

nametypeoptionaldescription
sourceobjectNoThe primary object to try to retrieve the value from. If not found in here, altSource is checked.
keystringNoThe name of the property to retrieve from the object. If a property is nested, the names of its preceding properties should be separated by a dot (.) - banner.hideBanner would return the value of the hideBanner property from the object stored in the banner property of the source object.
defaultValue*NoThe value to return if the key isn't found in the source object.
altSourceobjectYesAn alternative object to retrieve the value from. If the property exists in source then altSource will not be used.

Returns: * - The value of the requested key.

Source: src/utils/object/GetValue.js#L7
Since: 3.0.0

HasAll​

<static> HasAll(source, keys)​

Description:

Verifies that an object contains all requested keys

Parameters:

nametypeoptionaldescription
sourceobjectNoAn object on which to check for key existence.
keysArray.<string>NoAn array of keys to ensure the source object contains.

Returns: boolean - true if the source object contains all keys, false otherwise.

Source: src/utils/object/HasAll.js#L7
Since: 3.0.0

HasAny​

<static> HasAny(source, keys)​

Description:

Verifies that an object contains at least one of the requested keys

Parameters:

nametypeoptionaldescription
sourceobjectNoAn object on which to check for key existence.
keysArray.<string>NoAn array of keys to search the object for.

Returns: boolean - true if the source object contains at least one of the keys, otherwise false.

Source: src/utils/object/HasAny.js#L7
Since: 3.0.0

HasValue​

<static> HasValue(source, key)​

Description:

Determine whether the source object has its own property with the specified key. This uses hasOwnProperty internally, so only own (non-inherited) properties are checked.

Parameters:

nametypeoptionaldescription
sourceobjectNoThe source object to be checked.
keystringNoThe property to check for within the object.

Returns: boolean - true if the provided key exists on the source object, otherwise false.

Source: src/utils/object/HasValue.js#L7
Since: 3.0.0

IsPlainObject​

<static> IsPlainObject(obj)​

Description:

This is a slightly modified version of jQuery.isPlainObject. A plain object is an object whose internal [[Class]] property is [object Object], meaning it was created via {}, new Object(), or Object.create(null). Objects such as DOM nodes, the window object, and instances of custom classes are not considered plain objects and will cause this function to return false.

Parameters:

nametypeoptionaldescription
objobjectNoThe object to inspect.

Returns: boolean - true if the object is plain, otherwise false.

Source: src/utils/object/IsPlainObject.js#L7
Since: 3.0.0

Merge​

<static> Merge(obj1, obj2)​

Description:

Performs a shallow merge of two plain objects, returning a brand new object that contains all properties from both. Neither input object is modified. When the same key exists in both objects, the value from obj1 takes precedence over the value from obj2.

This is a shallow copy only. Deeply nested objects are not cloned, so be sure to only use this function on objects with a single level of nesting.

Parameters:

nametypeoptionaldescription
obj1objectNoThe base object. Its properties take precedence in the event of a key conflict.
obj2objectNoThe secondary object. Properties unique to this object are added to the result.

Returns: object - A new object containing the merged properties of obj1 and obj2.

Source: src/utils/object/Merge.js#L9
Since: 3.0.0

MergeRight​

<static> MergeRight(obj1, obj2)​

Description:

Creates a new object by cloning obj1, then merging values from obj2 into it using a "right wins" strategy.

Only keys that exist in obj1 are considered. For each key in obj2 that also exists in obj1, the value from obj2 overwrites the cloned value. Keys present in obj2 but absent from obj1 are ignored entirely. This differs from a standard merge in that obj2 cannot introduce new keys — it can only override existing ones.

Parameters:

nametypeoptionaldescription
obj1objectNoThe first object to merge.
obj2objectNoThe second object to merge. Keys from this object which also exist in obj1 will be copied to obj1.

Returns: object - The merged object. obj1 and obj2 are not modified.

Source: src/utils/object/MergeRight.js#L9
Since: 3.0.0

Pick​

<static> Pick(object, keys)​

Description:

Returns a new object that only contains the keys that were found on the object provided. If no keys are found, an empty object is returned.

Parameters:

nametypeoptionaldescription
objectobjectNoThe object to pick the provided keys from.
keysarrayNoAn array of properties to retrieve from the provided object.

Returns: object - A new object that only contains the keys that were found on the provided object. If no keys were found, an empty object will be returned.

Source: src/utils/object/Pick.js#L9
Since: 3.18.0

SetValue​

<static> SetValue(source, key, value)​

Description:

Sets a value in an object, allowing for dot notation to control the depth of the property.

For example:


var data = {

  world: {

    position: {

      x: 200,

      y: 100

    }

  }

};



SetValue(data, 'world.position.y', 300);



console.log(data.world.position.y); // 300

Parameters:

nametypeoptionaldescription
sourceobjectNoThe object to set the value in.
keystringNoThe name of the property in the object. If a property is nested, the names of its preceding properties should be separated by a dot (.)
valueanyNoThe value to set into the property, if found in the source object.

Returns: boolean - true if the property key was valid and the value was set, otherwise false.

Source: src/utils/object/SetValue.js#L7
Since: 3.17.0

Phaser.Utils.String

Format​

<static> Format(string, values)​

Description:

Takes a string and replaces instances of markers with values in the given array. The markers take the form of %1, %2, etc. I.e.:

Format("The %1 is worth %2 gold", [ 'Sword', 500 ])

Parameters:

nametypeoptionaldescription
stringstringNoThe string containing the replacement markers.
valuesarrayNoAn array containing values that will replace the markers. If no value exists an empty string is inserted instead.

Returns: string - The string containing replaced values.

Source: src/utils/string/Format.js#L7
Since: 3.0.0

Pad​

<static> Pad(str, [len], [pad], [dir])​

Description:

Takes the given string and pads it out, to the length required, using the character specified. For example if you need a string to be 6 characters long, you can call:

pad('bob', 6, '-', 2)

This would return: bob--- as it has padded it out to 6 characters, using the - on the right.

You can also use it to pad numbers (they are always returned as strings):

pad(512, 6, '0', 1)

Would return: 000512 with the string padded to the left.

If you don't specify a direction it'll pad to both sides:

pad('c64', 7, '*')

Would return: **c64**

Parameters:

nametypeoptionaldefaultdescription
strstring | numberobjectNo
lennumberYes0The total length of the resulting padded string.
padstringYes"" ""The string to pad it out with (defaults to a space).
dirnumberYes3The direction dir = 1 (left), 2 (right), 3 (both).

Returns: string - The padded string.

Source: src/utils/string/Pad.js#L7
Since: 3.0.0

RemoveAt​

<static> RemoveAt(string, index)​

Description:

Takes a string and removes the character at the given index.

The index is zero based.

Parameters:

nametypeoptionaldescription
stringstringNoThe string to be worked on.
indexnumberNoThe index of the character to be removed. This value is zero-based.

Returns: string - The modified string.

Source: src/utils/string/RemoveAt.js#L7
Since: 3.50.0

Reverse​

<static> Reverse(string)​

Description:

Takes the given string and reverses it, returning the reversed string. For example if given the string Atari 520ST it would return TS025 iratA.

Parameters:

nametypeoptionaldescription
stringstringNoThe string to be reversed.

Returns: string - The reversed string.

Source: src/utils/string/Reverse.js#L7
Since: 3.0.0

UUID​

<static> UUID()​

Description:

Creates and returns an RFC4122 version 4 compliant UUID.

The string is in the form: xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx where each x is replaced with a random hexadecimal digit from 0 to f, and y is replaced with a random hexadecimal digit from 8 to b.

Returns: string - The UUID string.

Source: src/utils/string/UUID.js#L7
Since: 3.12.0

UppercaseFirst​

<static> UppercaseFirst(str)​

Description:

Capitalizes the first letter of a string if there is one.

Parameters:

nametypeoptionaldescription
strstringNoThe string to capitalize.

Returns: string - A new string, same as the first, but with the first letter capitalized.

Source: src/utils/string/UppercaseFirst.js#L7
Since: 3.0.0