GetElementsWithinRange: Difference between revisions

From Multi Theft Auto: Wiki
Jump to navigation Jump to search
No edit summary
(added script example)
Line 8: Line 8:
* This function doesn't work with elements which is created by createElement.}}
* This function doesn't work with elements which is created by createElement.}}


==Syntax==  
==Syntax==
<syntaxhighlight lang="lua">
<syntaxhighlight lang="lua">
table getElementsWithinRange ( float x, float y, float z, float range [, string elemType = "" ] )  
table getElementsWithinRange ( float x, float y, float z, float range [, string elemType = "" ] )
</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
Line 19: Line 19:
*'''range:''' the range at the coordinates in which to retrieve elements
*'''range:''' the range at the coordinates in which to retrieve elements


===Optional Arguments===  
===Optional Arguments===
*'''elemType:''' The type of element you want a list of. This can be any element type, such as:
*'''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
**'''"player":''' A player connected to the server
Line 31: Line 31:
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.
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==  
==Example==
This example allows admins to destroy all vehicles in close proximity.
<syntaxhighlight lang="lua">
function deleteNearbyVehicles(p)
local acc = getPlayerAccount(p)
if not isGuestAccount(acc) and isObjectInACLGroup("user."..getAccountName(acc), aclGetGroup("Admin")) then
local x, y, z = getElementPosition(p)
local nearbyVehicles = getElementsWithinRange(x, y, z, 300, "vehicle")
for i,v in ipairs(nearbyVehicles) do
if v and isElement(v) then
destroyElement(v)
end
end
end
end
addCommandHandler ("delnearvehs", 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">

Revision as of 21:26, 23 January 2019

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

[[{{{image}}}|link=|]] Note:
  • This function doesn't verify whether elements are in the same dimension and interior, additional checks could be implemented manually if they are needed.
  • This function checks if elements are in a box, not in a circle.
  • Z argument isn't in use currently, but make your scripts like it is for future compatibility reasons.
  • This function doesn't work with elements which is created by createElement.

Syntax

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

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

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(p)
	local acc = getPlayerAccount(p)
	if not isGuestAccount(acc) and isObjectInACLGroup("user."..getAccountName(acc), aclGetGroup("Admin")) then
		local x, y, z = getElementPosition(p)
		local nearbyVehicles = getElementsWithinRange(x, y, z, 300, "vehicle")
		for i,v in ipairs(nearbyVehicles) do
			if v and isElement(v) then
				destroyElement(v)
			end
		end
	end
end
addCommandHandler ("delnearvehs", deleteNearbyVehicles)

Example

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

local players = getElementsWithinRange( 0, 0, 3, 20, "player" )    -- get all player elements within 20 units of 0, 0, 3
for _, player in pairs( players ) do                               -- use a generic for loop to step through each player
    outputChatBox( getPlayerName( player ) .. " is within range" ) -- print their name to the chat
end

See Also


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