object:remove()

Type Function

Object GroupObject

Library display.*

Return value DisplayObject

Revision Release 2022.3683

Keywords remove, remove child

See also object:removeSelf()

display.remove()

Group Programming (guide)

Overview

Remove an object from a group by either an index number or a reference to the object.

Gotchas

If an object is being removed (deleted), it is recommended to use object:removeSelf() or display.remove() instead.
Using this method will delete the specified child object, not simply remove it from the group. If you want to remove an object from a group, insert it into a different group, or insert it into the global stage group instead.
When an object is removed, the rendering-related resources of the removed object are deleted immediately. What remains of the object is simply a plain Lua table with all non-display object properties — the metatable is set to nil and all properties relating to display object are removed. Thus, if there are still references to object in Lua, they will simply be references to a normal Lua table.

Syntax

object:remove( indexOrChild )

indexOrChild _^(required)

Number or DisplayObject. Removes the display object specified from the group, shifting down other elements as needed. The argument is either the index position of the child within group (number) or the child display object itself.

Example

-- Remove the second object from the group
display.getCurrentStage():remove( 2 )