GetElementsByType: Difference between revisions

From Multi Theft Auto: Wiki
Jump to navigation Jump to search
m (→‎Required Arguments: Added more element types)
m (Removed "remoteclient" as it was 0 on both client and server when there were players.)
 
(38 intermediate revisions by 20 users not shown)
Line 1: Line 1:
{{Needs_Checking|Is it compatible with team, radararea, textdisplay, and textitem elements? [[User:Erorr404|Erorr404]]}}
{{Server_client_function}}
 
__NOTOC__  
__NOTOC__  
This function is used to retreive a list of all elemets of the specified type. This can be useful, as it disregards ''where'' in the element table it is in the element heirarchy.
This function is used to retrieve a list of all elements of the specified type. This can be useful, as it disregards ''where'' in the element tree it is. It can be used with either the built in types (listed below) or with any custom type used in a .map file. For example, if there is an element of type "flag" (e.g. <flag />) in the .map file, the using "flag" as the type argument would find it.


==Syntax==  
==Syntax==  
<section name="Server" class="server" show="true">
<syntaxhighlight lang="lua">
table getElementsByType ( string theType, [ element startat=getRootElement() ] )
</syntaxhighlight>
</section>
<section name="Client" class="client" show="true">
<syntaxhighlight lang="lua">
<syntaxhighlight lang="lua">
table getElementsByType ( string type )  
table getElementsByType ( string theType, [ element startat=getRootElement(), bool streamedIn=false ] )  
</syntaxhighlight>  
</syntaxhighlight>
</section>
 
{{OOP|This function is a static function underneath the Element class.|[[Element]].getAllByType||}}


===Required Arguments===  
===Required Arguments===  
*'''type:''' The type of element you want a list of. This can be any one of the following things MTA is programmed to understand:
*'''theType:''' The type of element you want a list of. This is the same as the tag name in the .map file, so this can be used with a custom element type if desired. Built in types can be found here: [[Element]]
**'''"player":''' A player connected to the server
**'''"player":''' A player connected to the server
**'''"vehicle":''': A vehicle
**'''"ped":''' A ped
**'''"water":''' A water polygon
**'''"sound":''' A playing sound
**'''"vehicle":''' A vehicle
**'''"object":''' An object
**'''"object":''' An object
**'''"pickup":''' A pickup
**'''"pickup":''' A pickup
**'''"marker":''' A marker
**'''"marker":''' A marker
**'''"colshape":''' A collision shape
**'''"blip":''' A blip
**'''"blip":''' A blip
**'''"radararea":''' A radar area
**'''"radararea":''' A radar area
**'''"team":''' A team
**'''"team":''' A team
**'''"spawnpoint":''' A spawnpoint
**'''"spawnpoint":''' A spawnpoint
**'''"remoteclient":''' A remote client connected to the server
**'''"console":''' The server Console
**'''"console":''' The server Console
**'''"unknown":''' Unknown element type
**'''"projectile":''' A clientside projectile
**'''"effect":''' A clientside effect
**'''"light":''' A clientside light
**'''"searchlight":''' A clientside searchlight
**'''"shader":''' A shader
**'''"texture":''' A texture
 
==Optional Arguments==
{{OptionalArg}}
*'''startat:''' The [[element]] the search should start at. Children of this element are searched, siblings or parents will not be found. By default, this is the root element which should suit most uses.
 
<section name="Client" class="client" show="true">
*'''streamedIn:''' If true, function will only return elements that are streamed in.
</section>


===Returns===
===Returns===
Line 28: Line 53:


==Example==  
==Example==  
This example retrieves a table of the players in the server, and checks whether or not each one is in a vehicle:
'''Example 1:''' This example retrieves a table of the players in the server, and checks whether or not each one is in a vehicle:
<syntaxhighlight lang="lua">
<syntaxhighlight lang="lua">
local players = getElementsByType ( "player" ) -- get a table of all the players in the server
local players = getElementsByType ( "player" ) -- get a table of all the players in the server
for theKey,thePlayer in players do -- use a generic for loop to step through each player
for theKey,thePlayer in ipairs(players) do -- use a generic for loop to step through each player
   if ( isPlayerInVehicle ( thePlayer ) ) then -- if the player is in a vehicle, announce it
   if ( isPlayerInVehicle ( thePlayer ) ) then -- if the player is in a vehicle, announce it
       outputChatBox ( getClientName ( thePlayer ) .. " is in a vehicle" )
       outputChatBox ( getPlayerName ( thePlayer ) .. " is in a vehicle" )
   else -- if the player isn't in a vehicle, announce that he/she is on foot
   else -- if the player isn't in a vehicle, announce that he/she is on foot
       outputChatBox ( getClientName ( thePlayer ) .. " is on foot" )
       outputChatBox ( getPlayerName ( thePlayer ) .. " is on foot" )
   end
   end
end
end
</syntaxhighlight>
'''Example 2:''' This example retrieves a table of the teams in the server, and display them in chat:
<syntaxhighlight lang="lua">
local teams = getElementsByType("team")
for i,team in ipairs(teams) do
  local teamName = getTeamName(team) -- get the team name
  outputChatBox(teamName) -- display the team name in chat
end
</syntaxhighlight>
'''Example 3:''' This shows how you could create a new element to describe a gas station:
<syntaxhighlight lang="lua">
function createGasStations(below)
    local gasstations = getElementsByType ( "gasstation", below ) -- get a table of all the gas station elements in the element tree
    for theKey,theGasStation in ipairs(gasstations) do
        local x = getElementData(theGasStation, "posX") -- get the position of the element
        local y = getElementData(theGasStation, "posY")
        local z = getElementData(theGasStation, "posZ")
        setElementParent(createColSphere(x, y, z, 10), theGasStation) -- create a colshape for the gas station at the gas station's position
        addEventHandler("onColShapeHit", theGasStation, giveGas) -- when the player hits
    end
end
function mapLoad()
    createGasStations(source) -- create gas stations for the map that's just loaded
end
addEventHandler("onResourceStart", resourceRoot, mapLoad)
function giveGas(hittingElement)
    local theGasStation = source
    if getElementType(hittingElement) == "vehicle" then
        local gas_left = getElementData(theGasStation, "amount")
        local gas_speed = getElementData(theGasStation, "speed")
        if gas_left > 0 then
            local gas_to_remove = gas_speed
            if gas_left < gas_speed then
                gas_to_remove = gas_left
            local current_vehicle_gas = getElementData(hittingElement, "gas")
            current_vehicle_gas = current_vehicle_gas + gas_to_remove
            gas_left = gas_left - gas_to_remove
            setElementData(hittingElement, "gas", current_vehicle_gas)
            setElementData(theGasStation, "amount", gas_left)
        else
            outputChatBox("Pump is out of gas!")
        end
    end
end
</syntaxhighlight>
'''Example 4:''' This example loops trough all connected players and redirects them to another server host:
<syntaxhighlight lang="lua">
local serverIP = "99.88.77.66" -- Change to your server IP to redirect everyone
local serverPort = 22005 -- The destination server's port
function redirectAllPlayers()
for _,p in ipairs (getElementsByType("player")) do
if p then
redirectPlayer (p, serverIP, serverPort)
end
end
end
addEventHandler ("onResourceStart", resourceRoot, redirectAllPlayers)
</syntaxhighlight>
</syntaxhighlight>


==See Also==
==See Also==
{{Element_functions}}
{{Element_functions}}

Latest revision as of 20:00, 14 October 2018

This function is used to retrieve a list of all elements of the specified type. This can be useful, as it disregards where in the element tree it is. It can be used with either the built in types (listed below) or with any custom type used in a .map file. For example, if there is an element of type "flag" (e.g. <flag />) in the .map file, the using "flag" as the type argument would find it.

Syntax

Click to collapse [-]
Server
table getElementsByType ( string theType, [ element startat=getRootElement() ] ) 
Click to collapse [-]
Client
table getElementsByType ( string theType, [ element startat=getRootElement(), bool streamedIn=false ] ) 


OOP Syntax Help! I don't understand this!

Note: This function is a static function underneath the Element class.
Method: Element.getAllByType(...)


Required Arguments

  • theType: The type of element you want a list of. This is the same as the tag name in the .map file, so this can be used with a custom element type if desired. Built in types can be found here: Element
    • "player": A player connected to the server
    • "ped": A ped
    • "water": A water polygon
    • "sound": A playing sound
    • "vehicle": A vehicle
    • "object": An object
    • "pickup": A pickup
    • "marker": A marker
    • "colshape": A collision shape
    • "blip": A blip
    • "radararea": A radar area
    • "team": A team
    • "spawnpoint": A spawnpoint
    • "console": The server Console
    • "projectile": A clientside projectile
    • "effect": A clientside effect
    • "light": A clientside light
    • "searchlight": A clientside searchlight
    • "shader": A shader
    • "texture": A texture

Optional Arguments

NOTE: When using optional arguments, you might need to supply all arguments before the one you wish to use. For more information on optional arguments, see optional arguments.

  • startat: The element the search should start at. Children of this element are searched, siblings or parents will not be found. By default, this is the root element which should suit most uses.
Click to collapse [-]
Client
  • streamedIn: If true, function will only return elements that are streamed in.

Returns

Returns a table containing all the elements of the specified type. Returns an empty table if there are no elements of the specified type. Returns false if the string specified is invalid (or not a string).

Example

Example 1: This example retrieves a table of the players in the server, and checks whether or not each one is in a vehicle:

local players = getElementsByType ( "player" ) -- get a table of all the players in the server
for theKey,thePlayer in ipairs(players) do -- use a generic for loop to step through each player
   if ( isPlayerInVehicle ( thePlayer ) ) then -- if the player is in a vehicle, announce it
      outputChatBox ( getPlayerName ( thePlayer ) .. " is in a vehicle" )
   else -- if the player isn't in a vehicle, announce that he/she is on foot
      outputChatBox ( getPlayerName ( thePlayer ) .. " is on foot" )
   end
end

Example 2: This example retrieves a table of the teams in the server, and display them in chat:

local teams = getElementsByType("team")
for i,team in ipairs(teams) do
   local teamName = getTeamName(team) -- get the team name
   outputChatBox(teamName) -- display the team name in chat
end

Example 3: This shows how you could create a new element to describe a gas station:

function createGasStations(below)
    local gasstations = getElementsByType ( "gasstation", below ) -- get a table of all the gas station elements in the element tree
    for theKey,theGasStation in ipairs(gasstations) do 
        local x = getElementData(theGasStation, "posX") -- get the position of the element
        local y = getElementData(theGasStation, "posY")
        local z = getElementData(theGasStation, "posZ")
        setElementParent(createColSphere(x, y, z, 10), theGasStation) -- create a colshape for the gas station at the gas station's position
        addEventHandler("onColShapeHit", theGasStation, giveGas) -- when the player hits
    end
end

function mapLoad()
    createGasStations(source) -- create gas stations for the map that's just loaded
end
addEventHandler("onResourceStart", resourceRoot, mapLoad)

function giveGas(hittingElement)
    local theGasStation = source
    if getElementType(hittingElement) == "vehicle" then
        local gas_left = getElementData(theGasStation, "amount")
        local gas_speed = getElementData(theGasStation, "speed")
        if gas_left > 0 then

            local gas_to_remove = gas_speed 
            if gas_left < gas_speed then
                gas_to_remove = gas_left

            local current_vehicle_gas = getElementData(hittingElement, "gas")
            current_vehicle_gas = current_vehicle_gas + gas_to_remove
            gas_left = gas_left - gas_to_remove

            setElementData(hittingElement, "gas", current_vehicle_gas)
            setElementData(theGasStation, "amount", gas_left)
        else
            outputChatBox("Pump is out of gas!")
        end
    end
end

Example 4: This example loops trough all connected players and redirects them to another server host:

local serverIP = "99.88.77.66" -- Change to your server IP to redirect everyone
local serverPort = 22005 -- The destination server's port

function redirectAllPlayers()
	for _,p in ipairs (getElementsByType("player")) do
		if p then
			redirectPlayer (p, serverIP, serverPort)
		end
	end
end
addEventHandler ("onResourceStart", resourceRoot, redirectAllPlayers)

See Also