Phaser API Documentation

  Version: 
Filter
This is a beta release of our new docs system. Found an issue?
Please tell us about it in the #📖-newdocs-feedback channel on the Phaser Discord

Phaser . Structs . List

This is a beta release of our new docs system. Found an issue?
Please tell us about it in the #📖-newdocs-feedback channel on the Phaser Discord

Phaser . Structs . List

List is a generic implementation of an ordered list which contains utility methods for retrieving, manipulating, and iterating items.

Constructor:

new List(parent)

Parameters:

name type description
parent *

The parent of this list.

Since: 3.0.0
Source: src/structs/List.js (Line 19)

Members

_sortKey: string
Focus
Focus

Description:

The property key to sort by.

Type:
string
Since: 3.4.0
Source: src/structs/List.js (Line 89)
Focus
Focus
addCallback: function
Focus
Focus

Description:

A callback that is invoked every time a child is added to this list.

Type:
function
Since: 3.4.0
Source: src/structs/List.js (Line 71)
Focus
Focus
<readonly> first: *
Focus
Focus

Description:

The first item in the List or null for an empty List.

Type:
*
Since: 3.0.0
Source: src/structs/List.js (Line 696)
Focus
Focus
<readonly> last: *
Focus
Focus

Description:

The last item in the List, or null for an empty List.

Type:
*
Since: 3.0.0
Source: src/structs/List.js (Line 723)
Focus
Focus
<readonly> length: number
Focus
Focus

Description:

The number of items inside the List.

Type:
number
Since: 3.0.0
Source: src/structs/List.js (Line 679)
Focus
Focus
list: Array.<*>
Focus
Focus

Description:

The objects that belong to this collection.

Type:
Array.<*>
Default: []
Since: 3.0.0
Source: src/structs/List.js (Line 47)
Focus
Focus
parent: *
Focus
Focus

Description:

The parent of this list.

Type:
*
Since: 3.0.0
Source: src/structs/List.js (Line 38)
Focus
Focus
position: number
Focus
Focus

Description:

The index of the current element.

This is used internally when iterating through the list with the #first, #last, #get, and #previous properties.

Type:
number
Default: 0
Since: 3.0.0
Source: src/structs/List.js (Line 59)
Focus
Focus
removeCallback: function
Focus
Focus

Description:

A callback that is invoked every time a child is removed from this list.

Type:
function
Since: 3.4.0
Source: src/structs/List.js (Line 80)
Focus
Focus

Methods

add(child, [skipCallback])
Focus
Focus

Description:

Adds the given item to the end of the list. Each item must be unique.

Parameters:

name type arguments Default description
child * | Array.<*>

The item, or array of items, to add to the list.

skipCallback boolean <optional> false

Skip calling the List.addCallback if this child is added successfully.

Returns:
Description:

The list's underlying array.

Type:
  • *
Examples:
Since: 3.0.0
Source: src/structs/List.js (Line 99)
Focus
Focus
addAt(child, [index], [skipCallback])
Focus
Focus

Description:

Adds an item to list, starting at a specified index. Each item must be unique within the list.

Parameters:

name type arguments Default description
child *

The item, or array of items, to add to the list.

index number <optional> 0

The index in the list at which the element(s) will be inserted.

skipCallback boolean <optional> false

Skip calling the List.addCallback if this child is added successfully.

Returns:
Description:

The List's underlying array.

Type:
  • *
Examples:
Since: 3.0.0
Source: src/structs/List.js (Line 124)
Focus
Focus
bringToTop(child)
Focus
Focus

Description:

Brings the given child to the top of this List.

Parameters:

name type description
child *

The item to bring to the top of the List.

Returns:
Description:

The item which was moved.

Type:
  • *
Examples:
Since: 3.0.0
Source: src/structs/List.js (Line 461)
Focus
Focus
count(property, value)
Focus
Focus

Description:

Returns the total number of items in the List which have a property matching the given value.

Parameters:

name type description
property string

The property to test on each item.

value *

The value to test the property against.

Returns:
Description:

The total number of matching elements.

Type:
  • number
Examples:
Since: 3.0.0
Source: src/structs/List.js (Line 309)
Focus
Focus
destroy()
Focus
Focus

Description:

Destroys this List.

Examples:
Since: 3.0.0
Source: src/structs/List.js (Line 664)
Focus
Focus
each(callback, [context], [args])
Focus
Focus

Description:

Passes all children to the given callback.

Parameters:

name type arguments description
callback EachListCallback

The function to call.

context * <optional>

Value to use as this when executing callback.

args * <optional>

Additional arguments that will be passed to the callback, after the child.

Examples:
Since: 3.0.0
Source: src/structs/List.js (Line 622)
Focus
Focus
exists(child)
Focus
Focus

Description:

Checks if an item exists within the List.

Parameters:

name type description
child *

The item to check for the existence of.

Returns:
Description:

true if the item is found in the list, otherwise false.

Type:
  • boolean
Examples:
Since: 3.0.0
Source: src/structs/List.js (Line 585)
Focus
Focus
getAll([property], [value], [startIndex], [endIndex])
Focus
Focus

Description:

Returns all children in this List.

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

For example: getAll('parent') would return only children that have a property called parent.

You can also specify a value to compare the property to:

getAll('visible', true) would return only children that have their visible property set to true.

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

Parameters:

name type arguments description
property string <optional>

An optional property to test against the value argument.

value * <optional>

If property is set then Child.property must strictly equal this value to be included in the results.

startIndex number <optional>

The first child index to start the search from.

endIndex number <optional>

The last child index to search up until.

Returns:
Description:

All items of the List which match the given criterion, if any.

Type:
  • Array.<*>
Examples:
Since: 3.0.0
Source: src/structs/List.js (Line 276)
Focus
Focus
getAt(index)
Focus
Focus

Description:

Retrieves the item at a given position inside the List.

Parameters:

name type description
index number

The index of the item.

Returns:
Description:

The retrieved item, or undefined if it's outside the List's bounds.

Type:
  • *
Examples:
Since: 3.0.0
Source: src/structs/List.js (Line 150)
Focus
Focus
getByName(name)
Focus
Focus

Description:

Searches for the first instance of a child with its name property matching the given argument. Should more than one child have the same name only the first is returned.

Parameters:

name type description
name string

The name to search for.

Returns:
Description:

The first child with a matching name, or null if none were found.

Type:
  • *
Examples:
Since: 3.0.0
Source: src/structs/List.js (Line 219)
Focus
Focus
getFirst(property, value, [startIndex], [endIndex])
Focus
Focus

Description:

Returns the first element in a given part of the List which matches a specific criterion.

Parameters:

name type arguments description
property string

The name of the property to test or a falsey value to have no criterion.

value *

The value to test the property against, or undefined to allow any value and only check for existence.

startIndex number <optional>

The position in the List to start the search at.

endIndex number <optional>

The position in the List to optionally stop the search at. It won't be checked.

Returns:
Description:

The first item which matches the given criterion, or null if no such item exists.

Type:
  • *
Examples:
Since: 3.0.0
Source: src/structs/List.js (Line 256)
Focus
Focus
getIndex(child)
Focus
Focus

Description:

Locates an item within the List and returns its index.

Parameters:

name type description
child *

The item to locate.

Returns:
Description:

The index of the item within the List, or -1 if it's not in the List.

Type:
  • number
Examples:
Since: 3.0.0
Source: src/structs/List.js (Line 167)
Focus
Focus
getRandom([startIndex], [length])
Focus
Focus

Description:

Returns a random child from the group.

Parameters:

name type arguments Default description
startIndex number <optional> 0

Offset from the front of the group (lowest child).

length number <optional> (to top)

Restriction on the number of values you want to randomly select from.

Returns:
Description:

A random child of this Group.

Type:
  • *
Examples:
Since: 3.0.0
Source: src/structs/List.js (Line 238)
Focus
Focus
moveDown(child)
Focus
Focus

Description:

Moves the given child down one place in this group unless it's already at the bottom.

Parameters:

name type description
child *

The item to move down.

Returns:
Description:

The item which was moved.

Type:
  • *
Examples:
Since: 3.0.0
Source: src/structs/List.js (Line 514)
Focus
Focus
moveTo(child, index)
Focus
Focus

Description:

Moves an item in the List to a new position.

Parameters:

name type description
child *

The item to move.

index number

Moves an item in the List to a new position.

Returns:
Description:

The item that was moved.

Type:
  • *
Examples:
Since: 3.0.0
Source: src/structs/List.js (Line 343)
Focus
Focus
moveUp(child)
Focus
Focus

Description:

Moves the given child up one place in this group unless it's already at the top.

Parameters:

name type description
child *

The item to move up.

Returns:
Description:

The item which was moved.

Type:
  • *
Examples:
Since: 3.0.0
Source: src/structs/List.js (Line 495)
Focus
Focus
remove(child, [skipCallback])
Focus
Focus

Description:

Removes one or many items from the List.

Parameters:

name type arguments Default description
child *

The item, or array of items, to remove.

skipCallback boolean <optional> false

Skip calling the List.removeCallback.

Returns:
Description:

The item, or array of items, which were successfully removed from the List.

Type:
  • *
Examples:
Since: 3.0.0
Source: src/structs/List.js (Line 361)
Focus
Focus
removeAll([skipCallback])
Focus
Focus

Description:

Removes all the items.

Parameters:

name type arguments Default description
skipCallback boolean <optional> false

Skip calling the List.removeCallback.

Returns:
Description:

This List object.

Examples:
Since: 3.0.0
Source: src/structs/List.js (Line 437)
Focus
Focus
removeAt(index, [skipCallback])
Focus
Focus

Description:

Removes the item at the given position in the List.

Parameters:

name type arguments Default description
index number

The position to remove the item from.

skipCallback boolean <optional> false

Skip calling the List.removeCallback.

Returns:
Description:

The item that was removed.

Type:
  • *
Examples:
Since: 3.0.0
Source: src/structs/List.js (Line 386)
Focus
Focus
removeBetween([startIndex], [endIndex], [skipCallback])
Focus
Focus

Description:

Removes the items within the given range in the List.

Parameters:

name type arguments Default description
startIndex number <optional> 0

The index to start removing from.

endIndex number <optional>

The position to stop removing at. The item at this position won't be removed.

skipCallback boolean <optional> false

Skip calling the List.removeCallback.

Returns:
Description:

An array of the items which were removed.

Type:
  • Array.<*>
Examples:
Since: 3.0.0
Source: src/structs/List.js (Line 411)
Focus
Focus
replace(oldChild, newChild)
Focus
Focus

Description:

Replaces a child of this List with the given newChild. The newChild cannot be a member of this List.

Parameters:

name type description
oldChild *

The child in this List that will be replaced.

newChild *

The child to be inserted into this List.

Returns:
Description:

Returns the oldChild that was replaced within this group.

Type:
  • *
Examples:
Since: 3.0.0
Source: src/structs/List.js (Line 567)
Focus
Focus
reverse()
Focus
Focus

Description:

Reverses the order of all children in this List.

Returns:
Description:

This List object.

Examples:
Since: 3.0.0
Source: src/structs/List.js (Line 533)
Focus
Focus
sendToBack(child)
Focus
Focus

Description:

Sends the given child to the bottom of this List.

Parameters:

name type description
child *

The item to send to the back of the list.

Returns:
Description:

The item which was moved.

Type:
  • *
Examples:
Since: 3.0.0
Source: src/structs/List.js (Line 478)
Focus
Focus
setAll(property, value, [startIndex], [endIndex])
Focus
Focus

Description:

Sets the property key to the given value on all members of this List.

Parameters:

name type arguments description
property string

The name of the property to set.

value *

The value to set the property to.

startIndex number <optional>

The first child index to start the search from.

endIndex number <optional>

The last child index to search up until.

Examples:
Since: 3.0.0
Source: src/structs/List.js (Line 602)
Focus
Focus
shuffle()
Focus
Focus

Description:

Shuffles the items in the list.

Returns:
Description:

This List object.

Examples:
Since: 3.0.0
Source: src/structs/List.js (Line 550)
Focus
Focus
shutdown()
Focus
Focus

Description:

Clears the List and recreates its internal array.

Examples:
Since: 3.0.0
Source: src/structs/List.js (Line 651)
Focus
Focus
sort(property, [handler])
Focus
Focus

Description:

Sort the contents of this List so the items are in order based on the given property. For example, sort('alpha') would sort the List contents based on the value of their alpha property.

Parameters:

name type arguments description
property string

The property to lexically sort by.

handler function <optional>

Provide your own custom handler function. Will receive 2 children which it should compare and return a boolean.

Returns:
Description:

This List object.

Examples:
Since: 3.0.0
Source: src/structs/List.js (Line 185)
Focus
Focus
swap(child1, child2)
Focus
Focus

Description:

Swaps the positions of two items in the list.

Parameters:

name type description
child1 *

The first item to swap.

child2 *

The second item to swap.

Examples:
Since: 3.0.0
Source: src/structs/List.js (Line 327)
Focus
Focus