GetElementsWithinRange: Difference between revisions

From Multi Theft Auto: Wiki
Jump to navigation Jump to search
(Created page with "{{Server client function}} __NOTOC__ This function is used to retrieve a list of all elements within a range of 3D coordinates. Please note that this function doesn't verify...")
 
 
(24 intermediate revisions by 8 users not shown)
Line 1: Line 1:
{{Server client function}}
{{Server client function}}
__NOTOC__
__NOTOC__
This function is used to retrieve a list of all elements within a range of 3D coordinates.
This function is used to retrieve a list of all elements of specified type within a range of 3D coordinates.
{{Deprecated items|3.0160|1.5.9|
* Z argument isn't in use currently, but make your scripts like it is for future compatibility reasons.
|21438}}
{{New feature/item|3.0160|1.5.9|21438|
* Z argument is now being taken into consideration when checking for elements.
}}
{{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.
}}


Please note that this function doesn't verify whether elements are in the same dimension and interior, additional checks could be implemented manually if they are needed.
==Syntax==
 
==Syntax==  
<syntaxhighlight lang="lua">
<syntaxhighlight lang="lua">
table getElementsWithinRange ( float x, float y, float z, float range )  
table getElementsWithinRange ( float x, float y, float z, float range [, string elemType = "", int interior, int dimension ] )
</syntaxhighlight>  
</syntaxhighlight>
{{OOP| |[[Element]].getWithinRange}}
{{OOP| |[[Element]].getWithinRange}}
===Required Arguments===  
===Required Arguments===
*'''x:''' the x coordinate at which to retrieve elements
*'''x:''' the x coordinate at which to retrieve elements.
*'''y:''' the y coordinate at which to retrieve elements
*'''y:''' the y coordinate at which to retrieve elements.
*'''z:''' the z 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
*'''range:''' the range at the coordinates in which to retrieve elements.
 
===Optional Arguments===
*'''elemType:''' The type of element you want a list of. This can be any element type, such as:
**'''"player":''' A player connected to the server.
**'''"ped":''' A ped.
**'''"vehicle":''' A vehicle.
**'''"object":''' An object.
**'''"pickup":''' A pickup.
**'''"marker":''' A marker.
{{Added feature/item|1.5.9|1.5.8|20797|
*'''interior:''' The [[interior]] you want to limit the search to. If not specified, it can return elements in any interior.
*'''dimension:''' The [[dimension]] you want to limit the search to. If not specified, it can return elements in any dimension.
}}


===Returns===
===Returns===
Returns a [[table]] containing all the elements within range. Returns an empty [[table]] if there are no elements within range. Returns ''false'' if the arguments are invalid.
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.
 
==Example==
This example allows admins to destroy all vehicles in close proximity.
<syntaxhighlight lang="lua">
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)


==Example==  
for vehicleID = 1, #nearbyVehicles do
local vehicleElement = nearbyVehicles[vehicleID]
local validElement = isElement(vehicleElement)
 
if (validElement) then
destroyElement(vehicleElement)
end
end
end
addCommandHandler("deletenearbyvehs", deleteNearbyVehicles)
</syntaxhighlight>
 
==Example==
This example retrieves a table of players within range of the 3D coordinates and prints their name to the chat.
This example retrieves a table of players within range of the 3D coordinates and prints their name to the chat.
<syntaxhighlight lang="lua">
<syntaxhighlight lang="lua">
local elements = getElementsWithinRange( 0, 0, 3, 20 )                   -- get all elements within 20 units of 0, 0, 3
local playersTable = getElementsWithinRange(0, 0, 3, 20, "player") -- get all player elements within 20 units of 0, 0, 3
for _, element in ipairs( elements ) do                                   -- use a generic for loop to step through each player
 
    if ( getElementType( element ) == "player" ) then                    -- if the element is a player
for _, playerElement in pairs(playersTable) do -- use a generic for loop to step through each player
        outputChatBox( getPlayerName( element ) .. " is within range" ) -- print their name to the chat
local playerName = getPlayerName(playerElement) -- get player name
    end
 
outputChatBox(playerName.." is within range") -- print their name to the chat
end
end
</syntaxhighlight>
</syntaxhighlight>

Latest revision as of 15:38, 3 May 2024

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

BEFORE VERSION 1.5.9 r21438:
  • Z argument isn't in use currently, but make your scripts like it is for future compatibility reasons.
  • Z argument is now being taken into consideration when checking for elements.
[[{{{image}}}|link=|]] 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.

Syntax

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

OOP Syntax Help! I don't understand this!

Method: Element.getWithinRange(...)


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

  • elemType: The type of element you want a list of. This can be any element type, such as:
    • "player": A player connected to the server.
    • "ped": A ped.
    • "vehicle": A vehicle.
    • "object": An object.
    • "pickup": A pickup.
    • "marker": A marker.
  • interior: The interior you want to limit the search to. If not specified, it can return elements in any interior.
  • dimension: 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.

Example

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)

Example

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

See Also


Retrieved from "https://wiki.multitheftauto.com/wiki/GetElementsWithinRange?oldid=79283"