This function is used to retrieve a list of all elements of specified type within a range of 3D coordinates.

Note

• This function checks if elements are in a box, not in a sphere.
• This function doesn't work with elements which are created by createElement.

OOP Syntax Help! I don't understand this!

• Method:Element.getWithinRange(...)

Syntax

​table|false getElementsWithinRange ( ​float x, ​float y, ​float z, ​float range, [ ​string elemType = "", ​int interior = nil, ​int dimension = nil ] )

Required arguments

• x: The x coordinate at which to retrieve elements.
• y: The y coordinate at which to retrieve elements.
• z: The z coordinate at which to retrieve elements.
• range: The range at the coordinates in which to retrieve elements.

Optional arguments

Note: when using optional arguments, you might need to supply all arguments before the one you wish to use.

• elemType (default: ""): The type of element you want a list of.
• interior (default: nil): The interior you want to limit the search to. If not specified, it can return elements in any interior.
• dimension (default: nil): The dimension you want to limit the search to. If not specified, it can return elements in any dimension.

Returns

Returns a table containing all the elements of the specified type within range. Returns an empty table if there are no elements within range. Returns false if the arguments are invalid.

• table|false: elements

Code Examples

Example 1 Example 2 (OOP) Example 3

shared

This example retrieves a table of players within range of the 3D coordinates and prints their name to the chat.

local playersTable = getElementsWithinRange(0, 0, 3, 20, "player") -- get all player elements within 20 units of 0, 0, 3

for _, playerElement in pairs(playersTable) do -- use a generic for loop to step through each player
    local playerName = getPlayerName(playerElement) -- get player name

    outputChatBox(playerName .. " is within range") -- print their name to the chat
end

shared

OOP Required

This example retrieves a table of players within range of the 3D coordinates and prints their name to the chat.

local playersTable = Element.getWithinRange(0, 0, 3, 20, "player") -- get all player elements within 20 units of 0, 0, 3

for _, playerElement in pairs(playersTable) do -- use a generic for loop to step through each player
    local playerName = playerElement.name -- get player name

    outputChatBox(playerName .. " is within range") -- print their name to the chat
end

server

This example allows admins to destroy all vehicles in close proximity.

function deleteNearbyVehicles(playerElement)
  local playerAccount = getPlayerAccount(playerElement)

  if (not playerAccount) then
    return false
  end

  local guestAccount = isGuestAccount(playerAccount)

  if (guestAccount) then
    return false
  end

  local accountName = getAccountName(playerAccount)
  local aclObject = "user."..accountName
  local adminGroup = aclGetGroup("Admin")
  local playerAdmin = isObjectInACLGroup(aclObject, adminGroup)

  if (not playerAdmin) then
    return false
  end

  local playerX, playerY, playerZ = getElementPosition(playerElement)
  local playerInterior = getElementInterior(playerElement)
  local playerDimension = getElementDimension(playerElement)
  local searchRange = 300
  local nearbyVehicles = getElementsWithinRange(playerX, playerY, playerZ, searchRange, "vehicle", playerInterior, playerDimension)

  for vehicleID = 1, #nearbyVehicles do
    local vehicleElement = nearbyVehicles[vehicleID]
    local validElement = isElement(vehicleElement)

    if (validElement) then
      destroyElement(vehicleElement)
    end
  end
end
addCommandHandler("deletenearbyvehs", deleteNearbyVehicles)

Changelog

1.5.9 r21438

Z argument is now being taken into consideration when checking for elements.

See Also

Element Functions

• addElementDataSubscriber
• attachElements
• clearElementVisibleTo
• cloneElement
• createElement
• destroyElement
• detachElements
• getAllElementDataUpdated
• getAttachedElements
• getElementAlpha
• getElementAngularVelocity
• getElementAttachedOffsets
• getElementAttachedTo
• getElementBonePosition
• getElementBoneQuaternionNew
• getElementBoneRotation
• getElementBoundingBox
• getElementByID
• getElementByIndex
• getElementChild
• getElementChildren
• getElementChildrenCount
• getElementCollisionsEnabled
• getElementColShape
• getElementData
• getElementDimension
• getElementDistanceFromCentreOfMassToBaseOfModel
• getElementHealth
• getElementID
• getElementInterior
• getElementLighting
• getElementMatrix
• 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
• isElementOnFireNew
• isElementOnScreen
• isElementStreamable
• isElementStreamedIn
• isElementSyncer
• isElementVisibleTo
• isElementWaitingForGroundToLoad
• isElementWithinColShape
• isElementWithinMarker
• removeElementData
• removeElementDataSubscriber
• setElementAlpha
• setElementAngularVelocity
• setElementAttachedOffsets
• setElementBonePosition
• setElementBoneQuaternionNew
• setElementBoneRotation
• setElementCallPropagationEnabled
• setElementCollidableWith
• setElementCollisionsEnabled
• setElementDataUpdated
• setElementDimension
• setElementDoubleSided
• setElementFrozen
• setElementHealth
• setElementID
• setElementInterior
• setElementLightingNew
• setElementMatrix
• setElementModel
• setElementOnFireNew
• 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