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

• table|false: elements

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.

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