List

A List is a generic, ordered collection of items that provides a rich set of utility methods for adding, removing, sorting, searching, and iterating its contents. Unlike a plain array, a List supports optional add and remove callbacks, stable sorting, named item lookup, positional traversal via the first, last, next, and previous properties, and safe in-place manipulation (swap, move, replace, shuffle). It is used throughout Phaser as the backing structure for display lists, camera lists, and other ordered collections where items must remain unique and ordered.

Constructor

new List(parent)

Parameters

name	type	optional	description
parent	*	No	The parent of this list.

---

Scope: static

Source: src/structs/List.js#L19
Since: 3.0.0

Public Members

_sortKey

_sortKey: string

Description:

The property key to sort by.

Source: src/structs/List.js#L95
Since: 3.4.0

---

addCallback

addCallback: function

Description:

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

Source: src/structs/List.js#L77
Since: 3.4.0

---

first

first: *

Description:

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

Tags:

• genericUse

Source: src/structs/List.js#L731
Since: 3.0.0

---

last

last: *

Description:

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

Tags:

• genericUse

Source: src/structs/List.js#L758
Since: 3.0.0

---

length

length: number

Description:

The number of items inside the List.

Source: src/structs/List.js#L714
Since: 3.0.0

---

list

list: Array.<*>

Description:

The objects that belong to this collection.

Tags:

• genericUse

Source: src/structs/List.js#L53
Since: 3.0.0

---

next

next: *

Description:

The next item in the List, or null if the entire List has been traversed.

This property can be read successively after reading #first or manually setting the #position to iterate the List.

Tags:

• genericUse

Source: src/structs/List.js#L785
Since: 3.0.0

---

parent

parent: *

Description:

The parent of this list.

Source: src/structs/List.js#L44
Since: 3.0.0

---

position

position: number

Description:

The index of the current element.

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

Source: src/structs/List.js#L65
Since: 3.0.0

---

previous

previous: *

Description:

The previous item in the List, or null if the entire List has been traversed.

This property can be read successively after reading #last or manually setting the #position to iterate the List backwards.

Tags:

• genericUse

Source: src/structs/List.js#L814
Since: 3.0.0

---

removeCallback

removeCallback: function

Description:

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

Source: src/structs/List.js#L86
Since: 3.4.0

---

Public Methods

add

<instance> add(child, [skipCallback])

Description:

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

Parameters:

name	type	optional	default	description
child	* | Array.<*>	No		The item, or array of items, to add to the list.
skipCallback	boolean	Yes	false	Skip calling the List.addCallback if this child is added successfully.

Returns: * - The list's underlying array.

Source: src/structs/List.js#L105
Since: 3.0.0

---

addAt

<instance> addAt(child, [index], [skipCallback])

Description:

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

Tags:

• genericUse

Parameters:

name	type	optional	default	description
child	*	No		The item, or array of items, to add to the list.
index	number	Yes	0	The index in the list at which the element(s) will be inserted.
skipCallback	boolean	Yes	false	Skip calling the List.addCallback if this child is added successfully.

Returns: * - The List's underlying array.

Source: src/structs/List.js#L128
Since: 3.0.0

---

bringToTop

<instance> bringToTop(child)

Description:

Brings the given child to the top of this List.

Tags:

• genericUse

Parameters:

name	type	optional	description
child	*	No	The item to bring to the top of the List.

Returns: * - The item which was moved.

Source: src/structs/List.js#L496
Since: 3.0.0

---

count

<instance> count(property, value)

Description:

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

Tags:

• genericUse

Parameters:

name	type	optional	description
property	string	No	The property to test on each item.
value	*	No	The value to test the property against.

Returns: number - The total number of matching elements.

Source: src/structs/List.js#L312
Since: 3.0.0

---

destroy

<instance> destroy()

Description:

Destroys this List.

Source: src/structs/List.js#L699
Since: 3.0.0

---

each

<instance> each(callback, [context], [args])

Description:

Passes all children to the given callback.

Tags:

• genericUse

Parameters:

name	type	optional	description
callback	EachListCallback	No	The function to call.
context	*	Yes	Value to use as this when executing callback.
args	*	Yes	Additional arguments that will be passed to the callback, after the child.

Source: src/structs/List.js#L657
Since: 3.0.0

---

exists

<instance> exists(child)

Description:

Checks if an item exists within the List.

Tags:

• genericUse

Parameters:

name	type	optional	description
child	*	No	The item to check for the existence of.

Returns: boolean - true if the item is found in the list, otherwise false.

Source: src/structs/List.js#L620
Since: 3.0.0

---

getAll

<instance> getAll([property], [value], [startIndex], [endIndex])

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.

Tags:

• genericUse

Parameters:

name	type	optional	description
property	string	Yes	An optional property to test against the value argument.
value	any	Yes	If property is set then Child.property must strictly equal this value to be included in the results.
startIndex	number	Yes	The first child index to start the search from.
endIndex	number	Yes	The last child index to search up until.

Returns: Array.<*> - All items of the List which match the given criterion, if any.

Source: src/structs/List.js#L280
Since: 3.0.0

---

getAt

<instance> getAt(index)

Description:

Retrieves the item at a given position inside the List.

Tags:

• genericUse

Parameters:

name	type	optional	description
index	number	No	The index of the item.

Returns: * - The retrieved item, or undefined if it's outside the List's bounds.

Source: src/structs/List.js#L154
Since: 3.0.0

---

getByName

<instance> getByName(name)

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.

Tags:

• genericUse

Parameters:

name	type	optional	description
name	string	No	The name to search for.

Returns: * - The first child with a matching name, or null if none were found.

Source: src/structs/List.js#L223
Since: 3.0.0

---

getFirst

<instance> getFirst(property, value, [startIndex], [endIndex])

Description:

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

Tags:

• genericUse

Parameters:

name	type	optional	default	description
property	string	No		The name of the property to test or a falsey value to have no criterion.
value	*	No		The value to test the property against, or undefined to allow any value and only check for existence.
startIndex	number	Yes	0	The position in the List to start the search at.
endIndex	number	Yes		The position in the List to optionally stop the search at. It won't be checked.

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

Source: src/structs/List.js#L260
Since: 3.0.0

---

getIndex

<instance> getIndex(child)

Description:

Locates an item within the List and returns its index.

Tags:

• genericUse

Parameters:

name	type	optional	description
child	*	No	The item to locate.

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

Source: src/structs/List.js#L171
Since: 3.0.0

---

getRandom

<instance> getRandom([startIndex], [length])

Description:

Returns a random child from the list.

Tags:

• genericUse

Parameters:

name	type	optional	default	description
startIndex	number	Yes	0	Offset from the front of the list (lowest child).
length	number	Yes	"(to top)"	Restriction on the number of values you want to randomly select from.

Returns: * - A random child of this List.

Source: src/structs/List.js#L242
Since: 3.0.0

---

moveAbove

<instance> moveAbove(child1, child2)

Description:

Moves an item above another one in the List. If the given item is already above the other, it isn't moved. Above means toward the end of the List.

Tags:

• genericUse

Parameters:

name	type	optional	description
child1	*	No	The element to move above base element.
child2	*	No	The base element.

Source: src/structs/List.js#L364
Since: 3.55.0

---

moveBelow

<instance> moveBelow(child1, child2)

Description:

Moves an item below another one in the List. If the given item is already below the other, it isn't moved. Below means toward the start of the List.

Tags:

• genericUse

Parameters:

name	type	optional	description
child1	*	No	The element to move below base element.
child2	*	No	The base element.

Source: src/structs/List.js#L382
Since: 3.55.0

---

moveDown

<instance> moveDown(child)

Description:

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

Tags:

• genericUse

Parameters:

name	type	optional	description
child	*	No	The item to move down.

Returns: * - The item which was moved.

Source: src/structs/List.js#L549
Since: 3.0.0

---

moveTo

<instance> moveTo(child, index)

Description:

Moves an item in the List to a new position.

Tags:

• genericUse

Parameters:

name	type	optional	description
child	*	No	The item to move.
index	number	No	The new position to move the item to.

Returns: * - The item that was moved.

Source: src/structs/List.js#L346
Since: 3.0.0

---

moveUp

<instance> moveUp(child)

Description:

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

Tags:

• genericUse

Parameters:

name	type	optional	description
child	*	No	The item to move up.

Returns: * - The item which was moved.

Source: src/structs/List.js#L530
Since: 3.0.0

---

remove

<instance> remove(child, [skipCallback])

Description:

Removes one or many items from the List.

Parameters:

name	type	optional	default	description
child	*	No		The item, or array of items, to remove.
skipCallback	boolean	Yes	false	Skip calling the List.removeCallback.

Returns: * - The item, or array of items, which were successfully removed from the List.

Source: src/structs/List.js#L400
Since: 3.0.0

---

removeAll

<instance> removeAll([skipCallback])

Description:

Removes all the items.

Parameters:

name	type	optional	default	description
skipCallback	boolean	Yes	false	Skip calling the List.removeCallback.

Returns: Phaser.Structs.List - This List object.

Source: src/structs/List.js#L474
Since: 3.0.0

---

removeAt

<instance> removeAt(index, [skipCallback])

Description:

Removes the item at the given position in the List.

Tags:

• genericUse

Parameters:

name	type	optional	default	description
index	number	No		The position to remove the item from.
skipCallback	boolean	Yes	false	Skip calling the List.removeCallback.

Returns: * - The item that was removed.

Source: src/structs/List.js#L423
Since: 3.0.0

---

removeBetween

<instance> removeBetween([startIndex], [endIndex], [skipCallback])

Description:

Removes the items within the given range in the List.

Tags:

• genericUse

Parameters:

name	type	optional	default	description
startIndex	number	Yes	0	The index to start removing from.
endIndex	number	Yes		The position to stop removing at. The item at this position won't be removed.
skipCallback	boolean	Yes	false	Skip calling the List.removeCallback.

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

Source: src/structs/List.js#L448
Since: 3.0.0

---

replace

<instance> replace(oldChild, newChild)

Description:

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

Tags:

• genericUse

Parameters:

name	type	optional	description
oldChild	*	No	The child in this List that will be replaced.
newChild	*	No	The child to be inserted into this List.

Returns: * - Returns the oldChild that was replaced within this List.

Source: src/structs/List.js#L602
Since: 3.0.0

---

reverse

<instance> reverse()

Description:

Reverses the order of all children in this List.

Tags:

• genericUse

Returns: Phaser.Structs.List - This List object.

Source: src/structs/List.js#L568
Since: 3.0.0

---

sendToBack

<instance> sendToBack(child)

Description:

Sends the given child to the bottom of this List.

Tags:

• genericUse

Parameters:

name	type	optional	description
child	*	No	The item to send to the back of the list.

Returns: * - The item which was moved.

Source: src/structs/List.js#L513
Since: 3.0.0

---

setAll

<instance> setAll(property, value, [startIndex], [endIndex])

Description:

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

Tags:

• genericUse

Parameters:

name	type	optional	description
property	string	No	The name of the property to set.
value	*	No	The value to set the property to.
startIndex	number	Yes	The first child index to start the search from.
endIndex	number	Yes	The last child index to search up until.

Source: src/structs/List.js#L637
Since: 3.0.0

---

shuffle

<instance> shuffle()

Description:

Shuffles the items in the list.

Tags:

• genericUse

Returns: Phaser.Structs.List - This List object.

Source: src/structs/List.js#L585
Since: 3.0.0

---

shutdown

<instance> shutdown()

Description:

Clears the List and recreates its internal array.

Source: src/structs/List.js#L686
Since: 3.0.0

---

sort

<instance> sort(property, [handler])

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.

Tags:

• genericUse

Parameters:

name	type	optional	description
property	string	No	The property to lexically sort by.
handler	function	Yes	Provide your own custom handler function. Will receive 2 children which it should compare and return a number (negative if the first should come before the second, positive if after, zero if equal).

Returns: Phaser.Structs.List - This List object.

Source: src/structs/List.js#L189
Since: 3.0.0

---

swap

<instance> swap(child1, child2)

Description:

Swaps the positions of two items in the list.

Tags:

• genericUse

Parameters:

name	type	optional	description
child1	*	No	The first item to swap.
child2	*	No	The second item to swap.

Source: src/structs/List.js#L330
Since: 3.0.0

---