Manual Review Required

Please finish this page using the corresponding Old Wiki article. Go to Contribution guidelines for more information.

---

This function destroys an element and all elements within it in the hierarchy (its children, the children of those children etc). Player elements cannot be destroyed using this function. A player can only be removed from the hierarchy when they quit or are kicked. The root element also cannot be destroyed, however, passing the root as an argument will wipe all elements from the server, except for the players and clients, which will become direct descendants of the root node, and other elements that cannot be destroyed, such as resource root elements.

Note

There is bug when you try to destroy webbrowser that returned from guiGetBrowser so instead of that destroy the gui-element one that returned from guiCreateBrowser otherwise the game will be crushed (By Master_MTA).

Note

As element ids are eventually recycled, always make sure you nil variables containing the element after calling this function

Note

If a streamed-in element is destroyed then it is NOT streamed out, i.e. the onClientElementStreamOut client-side event is NOT triggered. Thus it is wrong to assume a clean stream-in and stream-out sequence on the client-side. Additionally to onClientElementStreamOut use a onClientElementDestroy event handler to detect the destruction of streamed-in elements.

OOP Syntax Help! I don't understand this!

• Method:element:destroy(...)

Syntax

bool destroyElement ( element elementToDestroy )

Required Arguments

• elementToDestroy: The element you wish to destroy.

Returns

• bool: value

Returns true if the element was destroyed successfully, false if either the element passed to it was invalid or it could not be destroyed for some other reason (for example, clientside destroyElement can't destroy serverside elements).

Code Examples

Example 1 Example 2 Example 3 Example 4

shared

Example 1:This example would destroy every element in the map, with the exception of players and the root element itself.

-- Destroy all its children, except players.
destroyElement ( root )

shared

Example 2:This example destroys all vehicles of the specified model:

function destroyVehiclesOfModel(modelID)
  -- get a table of all the vehicles that exist and loop through it
  local vehicles = getElementsByType("vehicle")
  for i,v in ipairs(vehicles) do
    -- if the vehicle's ID is the one provided, destroy it
    if (getElementModel(v) == modelID) then
      destroyElement(v)
    end
  end
end

destroyVehiclesOfModel(445)

shared

Example 3:This example allows creation of claymores, which trigger and explode. When they explode, the colshape and object for the claymore are destroyed.

function createClaymore ( x,y,z, creator )
  local claymoreObject = createObject ( 1945, x, y, z - 1, 0, 0, 90 )  -- create an object which looks like a claymore
  local claymoreCol = createColSphere ( x, y, z, 1 )                   -- create a col sphere with radius 1
  setElementData ( claymoreCol, "object", claymoreObject )             -- store the object of the claymore
  setElementData ( claymoreCol, "creatorPlayer", creator )             -- store the person who created it
  addEventHandler ( "onColShapeHit", claymoreCol, claymoreHit )        -- add an event handler to the colshape
end

function claymoreHit ( thePlayer, matchingDimension )
  -- retrieve the object associated to the claymore, and who created it
  local claymoreObject = getElementData ( source, "object" )
  local claymoreCreator = getElementData ( source, "creatorPlayer" )
  -- get the position of the claymore
  local x,y,z = getElementPosition ( source )
  createExplosion ( x,y,z, 12, claymoreCreator ) -- create an explosion, associated to the creator, of a small size at the col's position
  -- remove the event handler for the colshape
  removeEventHandler ( "onColShapeHit", source, claymoreHit )
  -- destroy the claymore object, and the col shape so it doesn't trigger again.
  destroyElement ( claymoreObject )
  destroyElement ( source )
end

shared

Example 4:This example destroys all vehicles, regardless of ID, name, etc:

function allvehiclesaredoomed()
  -- get a table of all the vehicles that exist and loop through it
  vehicles = getElementsByType("vehicle")
  for i,v in ipairs(vehicles) do
    -- destroy every vehicle.
    destroyElement(v)
  end
end
--The command handler below will destroy all vehicles once
--you enter /vdoom in the chat box or vdoom in the game console.
addCommandHandler("vdoom", allvehiclesaredoomed)
--This is very useful if you use the freeroam resource and some
--heartless players start spawn spamming.
--You can also set it on a timer to have your server clear all
--vehicles ever 60 minutes, (1 hour).  Timer below:
setTimer(allvehiclesaredoomed, 3600000, 0)

See Also

Element Functions

• addElementDataSubscriber
• attachElements
• clearElementVisibleTo
• cloneElement
• createElement
• destroyElement
• detachElements
• getAllElementData
• getAttachedElements
• getElementAlpha
• getElementAngularVelocity
• getElementAttachedOffsets
• getElementAttachedTo
• getElementBonePosition
• getElementBoneQuaternion
• getElementBoneRotation
• getElementBoundingBox
• getElementByID
• getElementByIndex
• getElementChild
• getElementChildren
• getElementChildrenCount
• getElementCollisionsEnabled
• getElementColShape
• getElementData
• getElementDimension
• getElementDistanceFromCentreOfMassToBaseOfModel
• getElementHealth
• getElementID
• getElementInterior
• getElementLighting
• getElementModel
• getElementParent
• getElementPosition
• getElementRadius
• getElementRotation
• getElementsByType
• getElementsWithinColShape
• getElementsWithinRange
• getElementSyncer
• getElementType
• getElementVelocity
• getElementZoneName
• getLowLODElement
• getRootElement
• hasElementData
• hasElementDataSubscriber
• isElement
• isElementAttached
• isElementCallPropagationEnabled
• isElementCollidableWith
• isElementDoubleSided
• isElementFrozen
• isElementInWater
• isElementLocal
• isElementLowLOD
• isElementOnFire
• isElementOnScreen
• isElementStreamable
• isElementStreamedIn
• isElementSyncer
• isElementVisibleTo
• isElementWaitingForGroundToLoad
• isElementWithinColShape
• isElementWithinMarker
• removeElementData
• removeElementDataSubscriber
• setElementAlpha
• setElementAngularVelocity
• setElementAttachedOffsets
• setElementBonePosition
• setElementBoneQuaternion
• setElementBoneRotation
• setElementCallPropagationEnabled
• setElementCollidableWith
• setElementCollisionsEnabled
• setElementData
• setElementDimension
• setElementDoubleSided
• setElementFrozen
• setElementHealth
• setElementID
• setElementInterior
• setElementLighting
• setElementModel
• setElementOnFire
• setElementParent
• setElementPosition
• setElementRotation
• setElementStreamable
• setElementSyncer
• setElementVelocity
• setElementVisibleTo
• setLowLODElement
• updateElementRpHAnim

Element Events

• onClientElementColShapeHit
• onClientElementColShapeLeave
• onClientElementDataChange
• onClientElementDestroy
• onClientElementDimensionChange
• onClientElementInteriorChange
• onClientElementModelChange
• onClientElementStreamIn
• onClientElementStreamOut
• onElementClicked
• onElementColShapeHit
• onElementColShapeLeave
• onElementDataChange
• onElementDestroy
• onElementDimensionChange
• onElementInteriorChange
• onElementModelChange
• onElementStartSync
• onElementStopSync

Reference

• Scripting Functions