GetElementsWithinRange: Difference between revisions

From Multi Theft Auto: Wiki
Jump to navigation Jump to search
mNo edit summary
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.
{{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}}
{{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}}


==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 = "" ] )  
</syntaxhighlight>  
</syntaxhighlight>  
{{OOP| |[[Element]].getWithinRange}}
{{OOP| |[[Element]].getWithinRange}}
Line 14: Line 14:
*'''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


===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==  
==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 players = 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
for _, thePlayer in ipairs( players ) do                             -- use a generic for loop to step through each player
     if ( getElementType( element ) == "player" ) then                  -- if the element is a player
     outputChatBox( getPlayerName( thePlayer ) .. " is within range" ) -- print their name to the chat
        outputChatBox( getPlayerName( element ) .. " is within range" ) -- print their name to the chat
    end
end
end
</syntaxhighlight>
</syntaxhighlight>

Revision as of 06:41, 29 July 2018

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

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 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 _, thePlayer in ipairs( players ) do                              -- use a generic for loop to step through each player
    outputChatBox( getPlayerName( thePlayer ) .. " is within range" ) -- print their name to the chat
end

See Also


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