Multi Theft Auto: Wiki - User contributions [en]

User:VRocker

2007-05-31T17:11:35Z

VRocker2:

Too lazy to write anything here...

GetElementsByType

2007-05-07T13:45:31Z

VRocker2: /* Example */

{{Needs_Checking|I don't think any of the "colcube", "colsphere", "coltube", "colcircle" or "colsquare work at all. I've only been able to use "colshape" which isnt even listed here.}}

__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. It can be used with either the built in types (listed below) or with any type used in the .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==
<syntaxhighlight lang="lua">
table getElementsByType ( string type, [ element startat=getRootElement() ] )
</syntaxhighlight>

===Required Arguments===
*'''type:''' 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 are:
**'''"player":''' A player connected to the server
**'''"vehicle":''': A vehicle
**'''"object":''' An object
**'''"pickup":''' A pickup
**'''"marker":''' A marker
**'''"colcube":''' A cube collision shape
**'''"colsphere":''' A sphere collision shape
**'''"coltube":''' A tube collision shape
**'''"colcircle":''' A circle collision shape
**'''"colsquare":''' A square collision shape
**'''"blip":''' A blip
**'''"radararea":''' A radar area
**'''"team":''' A team
**'''"spawnpoint":''' A spawnpoint
**'''"remoteclient":''' A remote client connected to the server
**'''"console":''' The server Console

==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.

===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==
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">
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 ( getClientName ( thePlayer ) .. " is in a vehicle" )
else -- if the player isn't in a vehicle, announce that he/she is on foot
outputChatBox ( getClientName ( thePlayer ) .. " is on foot" )
end
end
</syntaxhighlight>

==See Also==
{{Element_functions}}

SpawnPlayer

2007-05-06T22:52:18Z

VRocker2: /* Example */

__NOTOC__
This function spawns the player at an arbitary point on the map.

==Syntax==
<syntaxhighlight lang="lua">
bool spawnPlayer ( player thePlayer, float x, float y, float z, int rotation, int skinID, [ int interior = 0, int dimension = 0, team theTeam = nil ] )
</syntaxhighlight>

===Required Arguments===
*'''x:''' The x co-ordinate to spawn the player at
*'''y:''' The y co-ordinate to spawn the player at
*'''z:''' The z co-ordinate to spawn the player at
*'''rotation:''' rotation of the player on spawn
*'''skinID:''' players skin on spawn

===Optional Arguments===
*'''interior:''' interior the player will spawn into
*'''dimension:''' The ID of the [[dimension]] that the player should be in
*'''theTeam:''' the team the player will join

===Returns===
Returns ''true'' if the player was spawned successfully, ''false'' otherwise.

==Example==
This example spawns all the players in the map at the first spawnpoint there is.
<syntaxhighlight lang="lua">
-- Get a table of all the players
players = getElementsByType ( "player" )
-- Go through every player
for playerKey, playerValue in ipairs(players) do
-- Spawn them at the desired coordinates
spawnPlayer ( playerValue, 0.0, 0.0, 0.0, 90.0, 7 )
end
</syntaxhighlight>

==See Also==
{{Player_functions}}

SetVehicleFrozen

2007-05-06T22:40:17Z

VRocker2: /* Example */

__NOTOC__
This function freezes a vehicle (stops it in its position and disables movement) or unfreezes it.

==Syntax==
<syntaxhighlight lang="lua">
bool setVehicleFrozen ( vehicle theVehicle, bool freezeStatus )
</syntaxhighlight>

===Required Arguments===
*'''theVehicle:''' the [[vehicle]] whose freeze status we want to change.
*'''freezeStatus:''' whether we want to freeze or unfreeze it.

===Returns===
*Returns ''true'' if the vehicle was frozen, ''false'' if it wasn't or if invalid arguments are passed.

==Example==
This example binds the "p" key to a function to freeze/unfreeze the player's current vehicle.
<syntaxhighlight lang="lua">
-- we store all players in a table
local connectedPlayers = getElementsByType ( "player" )
-- for each one in it,
for i, aPlayer in ipairs(connectedPlayers) do
-- bind the player's "p" key to the toggleFreezeStatus function
bindKey ( aPlayer, "p", "down", "toggleFreezeStatus" )
end

-- this function freezes the specified player's vehicle, if he's in one
function toggleFreezeStatus ( thePlayer )
-- if he is in a vehicle,
if isPlayerInVehicle ( thePlayer ) then
-- get the vehicle element
local playerVehicle = getPlayerOccupiedVehicle ( thePlayer )
-- get the current freeze status
local currentFreezeStatus = isVehicleFrozen ( playerVehicle )
-- get the new freeze status (the opposite of the previous)
local newFreezeStatus = not currentFreezeStatus
-- set the new freeze status
setVehicleFrozen ( playerVehicle, newFreezeStatus )
end
end
</syntaxhighlight>

==See Also==
{{Vehicle_functions}}

BlowVehicle

2007-05-06T22:37:37Z

VRocker2: /* Example */

__NOTOC__
This function will blow up a vehicle. This will cause an explosion and will kill the driver and any passengers inside it.

==Syntax==
<syntaxhighlight lang="lua">
bool blowVehicle ( vehicle vehicleToBlow, [ bool explode=true ] )
</syntaxhighlight>

===Required Arguments===
*'''vehicleToBlow:''' The vehicle that you wish to blow up.

===Optional Arguments===
{{OptionalArg}}
*'''explode:''' If this argument is ''true'' then the vehicle will explode, otherwise it will just be blown up silently.

===Returns===
Returns ''true'' if the vehicle was blown up, ''false'' if invalid arguments were passed to the function.

==Example==
This example will blow up every vehicle in the game.
<syntaxhighlight lang="lua">
vehicles = getElementsByType ( "vehicle" )
for vehicleKey, vehicleValue in ipairs(vehicles) do
blowVehicle ( vehicleValue )
end
</syntaxhighlight>

It is worth noting that the same could be achieved with the following:
<syntaxhighlight lang="lua">
root = getRootElement ()
blowVehicle ( root )
</syntaxhighlight>

==See Also==
{{Vehicle_Functions}}

GetVehicleUpgrades

2007-05-06T22:36:10Z

VRocker2: /* Example */

__NOTOC__
This function returns a table of all the upgrades on a specifed vehicle.

==Syntax==
<syntaxhighlight lang="lua">
table getVehicleUpgrades ( vehicle theVehicle )
</syntaxhighlight>

===Required Arguments===
*'''theVehicle:''' The [[vehicle]] you wish to retrieve the upgrades of.

===Returns===
Returns a ''table'' of all the upgrades on each slot of a vehicle, which may be empty, or ''false'' if a valid vehicle is not passed.

==Example==
<syntaxhighlight lang="lua">
addEventHandler ( "onPlayerEnterVehicle", root, "onPlayerEnterVehicle" )
function onPlayerEnterVehicle ( invehicle, seat, jacked )
upgrades = getVehicleUpgrades ( invehicle )
for upgradeKey, upgradeValue in ipairs(upgrades) do
outputChatBox ( getVehicleUpgradeSlotName ( upgradeKey - 1 ) .. ": " .. upgradeValue )
end
end
</syntaxhighlight>

==See Also==
{{Vehicle_functions}}

GetVehicleUpgradeSlotName

2007-05-06T22:35:50Z

VRocker2: /* Example */

__NOTOC__
This function returns the name of an upgrade slot name (e.g. roof, spoiler).

==Syntax==
There are two ways of using this function, the parameter can either be the slot ID (0 to 16) or an upgrade ID (1000 to 1193)
<syntaxhighlight lang="lua">
string getVehicleUpgradeSlotName ( int slot/upgrade )
</syntaxhighlight>

===Required Arguments===
*'''slot/upgrade:''' the slot ID or corresponding upgrade ID of which you want the name.

===Returns===
Returns a ''string'' with the slot name if a valid slot or upgrade ID was given, ''false'' otherwise.

==Example==
This example prints the name and upgrades on each slot of an entered vehicle to the chat.
<syntaxhighlight lang="lua">
addEventHandler ( "onPlayerEnterVehicle", root, "onPlayerEnterVehicle" )
function onPlayerEnterVehicle ( vehicle, seat, jacked )
upgrades = getVehicleUpgrades ( vehicle )
for upgradeKey, upgradeValue in ipairs(upgrades) do
outputChatBox ( getVehicleUpgradeSlotName ( upgradeKey - 1 ) .. ": " .. upgradeValue )
end
end
</syntaxhighlight>

==See Also==
{{Vehicle_functions}}

GetVehicleTurretPosition

2007-05-06T22:35:16Z

VRocker2: /* Example */

__NOTOC__
This function gets the position of a vehicle's turret, if it has one. Vehicles with turrets include firetrucks and tanks.

==Syntax==
<syntaxhighlight lang="lua">float float getVehicleTurretPosition ( vehicle turretVehicle )</syntaxhighlight>

This function also has two variants that allow you to retrieve data from just one of the two axes.

===Required Arguments===
*'''turretVehicle''': The [[vehicle]] whose rotation you want to retrieve. This should be a vehicle with a turret with a player in.

===Returns===
Returns two [[float]]s for the X (horizontal) and Y (vertical) axis rotation respectively. These values are in radians. The function will return ''false'' in the first return value if the vehicle does not have a driver or the vehicle is not a vehicle with a turret.

{{UsingRadians}}

==Example==
<syntaxhighlight lang="lua">
-- Find all the vehicles, and store them in a vehicles variable
vehicles = getElementsByType ( "vehicle" )
-- Loop through the vehicle list
for vehicleKey, vehicleValue in ipairs(vehicles) do
-- Get the vehicle's turret position
x, y = getVehicleTurretPosition ( vehicleValue )
-- If the vehicle has a turret (the function will return false if it doesn't) then
if ( x ~= false )
-- Tell everyone in the chat the turret's position
outputChatBox ( "Turret position: " .. x .. ", " .. y .. "." )
end
end
</syntaxhighlight>

==See Also==
{{Vehicle functions}}

IsVehicleFrozen

2007-05-06T22:33:36Z

VRocker2: /* Example */

__NOTOC__
This function checks if a vehicle has been frozen.

==Syntax==
<syntaxhighlight lang="lua">
bool isVehicleFrozen ( vehicle theVehicle )
</syntaxhighlight>

===Required Arguments===
*'''theVehicle:''' the vehicle whose freeze status we want to check.

===Returns===
*Returns ''true'' if the vehicle is frozen, ''false'' if it isn't or if invalid arguments are passed.

==Example==
This example binds the "p" key to a function to freeze/unfreeze the player's current vehicle.
<syntaxhighlight lang="lua">
-- we store all players in a table
local connectedPlayers = getElementsByType ( "player" )
-- for each one in it,
for i, aPlayer in ipairs(connectedPlayers) do
-- bind the player's "p" key to the toggleFreezeStatus function
bindKey ( aPlayer, "p", "down", "toggleFreezeStatus" )
end

-- this function freezes the specified player's vehicle, if he's in one
function toggleFreezeStatus ( thePlayer )
-- if he is in a vehicle,
if isPlayerInVehicle ( thePlayer ) then
-- get the vehicle element
local playerVehicle = getPlayerOccupiedVehicle ( thePlayer )
-- get the current freeze status
local currentFreezeStatus = isVehicleFrozen ( playerVehicle )
-- get the new freeze status (the opposite of the previous)
local newFreezeStatus = not currentFreezeStatus
-- set the new freeze status
setVehicleFrozen ( playerVehicle, newFreezeStatus )
end
end
</syntaxhighlight>

==See Also==
{{Vehicle_functions}}

FixVehicle

2007-05-06T22:32:58Z

VRocker2: /* Example */

__NOTOC__
This function will set a [[vehicle]]'s health to full and fix it's damage model. If you wish to just change the vehicle's health, without affecting it's damage model, use [[setVehicleHealth]].

==Syntax==
<syntaxhighlight lang="lua">
bool fixVehicle ( vehicle theVehicle )
</syntaxhighlight>

===Required Arguments===
*'''theVehicle:''' The vehicle you wish to fix

===Returns===
Returns ''true'' if the vehicle was fixed, ''false'' if ''theVehicle'' is invalid.

==Example==
This example fixes all the vehicles that exist in the map.
<syntaxhighlight lang="lua">
-- Retrieve a table containing all the vehicles that exist
vehicles = getElementsByType ( "vehicle" )
-- Loop through the list, storing the vehicle from the table in the variable vehicleValue
for vehicleKey, vehicleValue in ipairs(blips) do
-- fix the vehicle
fixVehicle ( vehicleHealth )
end
</syntaxhighlight>

==See Also==
{{Vehicle_functions}}

GetTimers

2007-05-06T22:31:56Z

VRocker2: /* Example */

__NOTOC__
This function returns a table of all the timers (with the remaining time left below or equal to the time specified)

==Syntax==
<syntaxhighlight lang="lua">
table getTimers ( [ time ] )
</syntaxhighlight>

===Optional Arguments===
*'''time:''' The maximum time left(ms) on the timers you wish to add to the table.

===Returns===
Returns a table of all the active timers.

==Example==
<syntaxhighlight lang="lua">
-- Find and kill all the timers with less than 1 minute to go
timers = getTimers ( 60000 )
-- Loop through the timer list
for timerKey, timerValue in ipairs(timers) do
-- kill the timer
killTimer ( timerValue )
end
</syntaxhighlight>

==See Also==
{{Utility functions}}

Split

2007-05-06T22:31:14Z

VRocker2: /* Example */

__NOTOC__
This function splits a string into sub-strings. You specify a character that will act as a separating character; this will determine where to split the sub-strings. For example, it can split the string "Hello World" into two strings containing the two words, by spliting using a space as a seperating character.

'''Note:''' You can use the function [[gettok]] to retrieve a single token from the string at a specific index. This may be faster for one-off lookups, but considerably slower if you are going to check each token in a long string.

==Syntax==
<syntaxhighlight lang="lua">table split ( string stringToSplit, int separatingChar )</syntaxhighlight>

===Required Arguments===
* '''stringToSplit''' The string you wish to split into parts.
* '''separatingChar''' The character you want to use to split (ASCII number)

===Returns===
Returns a table of the sub-strings.

==Example==
This examples takes any console text input and splits it into parts.
<syntaxhighlight lang="lua">
function onConsole ( player, text )
splittext = split ( text, 32 ) -- Grab the table of tokens
for splitKey, splitVal in ipairs(splittext) do -- for each token there..
outputChatBox ( "key: " .. splitKey .. " val: " .. splitVal ) -- output the index and token
end
end
</syntaxhighlight>

==See Also==
{{Utility functions}}

GetPlayersInTeam

2007-05-06T22:30:35Z

VRocker2: /* Example */

__NOTOC__
This function is for retrieving all the players in the specified team.

==Syntax==
<syntaxhighlight lang="lua">
table getPlayersInTeam ( team theTeam )
</syntaxhighlight>

===Optional Arguments===
*'''theTeam:''' The team you wish to retrieve all the players from.

===Returns===
Returns a table of all the players in the team.

==Example==
<syntaxhighlight lang="lua">
-- Find and kill all the players in a team called "red"
redTeam = getTeamFromName ( "red" )
if ( redTeam ) then
players = getPlayersInTeam ( redTeam )
-- Loop through the player table
for playerKey, playerValue in ipairs(players) do
-- kill the player
killPlayer ( playerValue )
end
end
</syntaxhighlight>

==See Also==
{{Team functions}}

GetTeamFriendlyFire

2007-05-06T22:30:05Z

VRocker2: /* Example */

__NOTOC__
This function returns the friendly fire value for the specified team.

==Syntax==
<syntaxhighlight lang="lua">
bool getTeamFriendlyFire ( team theTeam )
</syntaxhighlight>

===Required Arguments===
*'''theTeam:''' The team that will be checked

===Returns===
Returns ''true'' if friendly fire is on for the specified team, ''false'' if friendly fire is turned off for the specified team or if invalid arguments are specified.

==Example==
This example checks if friendly fire is on for every team, and toggles it on if it isn't.
<syntaxhighlight lang="lua">
--for every team,
for index, theTeam in ipairs(getElementsByType ( "team" )) do
--if friendly fire is off,
if ( getTeamFriendlyFire ( theTeam ) == false ) then
--switch it on
setTeamFriendlyFire ( theTeam, true )
end
end
</syntaxhighlight>

==See Also==
{{Team functions}}

GetBlipColor

2007-05-06T22:23:35Z

VRocker2: /* Example */

__NOTOC__
This function will tell you what color a blip is. This color is only applicable to the default blip icon. All other icons will ignore this.

==Syntax==
<syntaxhighlight lang="lua">int int int int getBlipColor ( blip theBlip )</syntaxhighlight>

===Required Arguments===
*'''theBlip:''' The blip whos color you wish to get.

===Returns===
Returns four integers in RGBA format, with a maximum value of 255 for each. Each stands for ''red'', ''green'', ''blue'', and ''alpha''. Alpha decides transparancy where 255 is opaque and 0 is transparent. ''false'' is returned if the blip is invalid.

==Example==
This example will find all the blips that exist and set them all to white if they aren't white already.
<syntaxhighlight lang="lua">
-- Retrieve a table containing all the blips that exist
blips = getElementsByType ( "blip" )
-- Loop through the list, storing the blip from the table in the variable blipValue
for blipKey, blipValue in ipairs(blips) do
-- Retrieve the blip's colors into the variables red, green, blue and alpha
red, green, blue, alpha = getBlipColor ( blipValue )
-- If the blip's icon isn't white already
if ( red ~= 255 or green ~= 255 or blue ~= 255 or alpha ~= 255 ) then
-- Set the blip's color to white
setBlipColor ( blipValue, 255, 255, 255, 255 )
end
end
</syntaxhighlight>

==See Also==
{{Blip_functions}}

GetBlipSize

2007-05-06T22:23:10Z

VRocker2: /* Example */

__NOTOC__
This function gets the size of a blip.

==Syntax==
<syntaxhighlight lang="lua">int getBlipSize ( blip theBlip )</syntaxhighlight>

===Required Arguments===
*'''theBlip:''' The blip you wish to get the size of.

===Returns===
Returns an [[int]] indicating the size of the blip. The default value is 2.

==Example==
This example will reset the size of all blips to the default.
<syntaxhighlight lang="lua">
-- Retrieve a table containing all the blips that exist
blips = getElementsByType ( "blip" )
-- Loop through the list, storing the blip from the table in the variable blipValue
for blipKey, blipValue in ipairs(blips) do
-- Retrieve the blip's size into the variable 'blipSize'
blipSize = getBlipSize ( blipValue )
-- If the blip's size wasn't 2 (the default size) already
if ( blipSize ~= 2 ) then
-- Set the blip's icon to the default
setBlipSize ( blipValue, 2 )
end
end
</syntaxhighlight>

==See Also==
{{Blip_functions}}

GetBlipIcon

2007-05-06T22:22:38Z

VRocker2: /* Example */

__NOTOC__
This function returns the icon a blip currently has.
==Syntax==
<syntaxhighlight lang="lua">int getBlipIcon ( blip theBlip )</syntaxhighlight>

===Required Arguments===
*'''theBlip''': the blip we're getting the icon number of.

===Returns===
Returns an [[int]] indicating which icon the blip has. Valid values are:
{{Blip_Icons}}

==Example==
This example will find all the blips that exist and set them all to the default blip icon.
<syntaxhighlight lang="lua">
-- Retrieve a table containing all the blips that exist
blips = getElementsByType ( "blip" )
-- Loop through the list, storing the blip from the table in the variable blipValue
for blipKey, blipValue in ipairs(blips) do
-- Retrieve the blip's icon into the variable 'blipIcon'
blipIcon = getBlipIcon ( blipValue )
-- If the blip's icon wasn't the default already
if ( blipIcon ~= 0 ) then
-- Set the blip's icon to the default
setBlipIcon ( blipValue, 0 )
end
end
</syntaxhighlight>

==See Also==
{{Blip_functions}}

GetThisResource

2007-05-06T22:20:04Z

VRocker2: /* Example */

__NOTOC__
This function retrieves the resource from which the function call was made.

==Syntax==
<syntaxhighlight lang="lua">
resource getThisResource ( )
</syntaxhighlight>

===Returns===
Returns the resource in which the current script is.

==Example==
<syntaxhighlight lang="lua">
addEventHandler("onResourceStart", getRootElement(), "onStartInScoresResource")
function onStartInScoresResource(resource)
local thisResource = getThisResource() -- get the resource that this script is a part of
if (resource == thisResource) then -- make sure the resource that started is the one this script is a part of
-- Note: without this check, the operations below would execute whenever ANY resource is loaded
-- perform some operations this script will be used for, in this case keeping track of player scores and money:
local players = getElementsByType("player")
for playerKey, playerValue in ipairs(players) do
setPlayerMoney(playerValue, 500)
setElementData(playerValue, "score", 0)
end
end
end
</syntaxhighlight>

==See Also==
{{Resource_functions}}
[[Category:Needs_Checking]]

RestartResource

2007-05-06T22:19:30Z

VRocker2: /* Example */

__NOTOC__
This function restarts a running resource.

==Syntax==
<syntaxhighlight lang="lua">
bool restartResource ( resource theResource )
</syntaxhighlight>

===Required Arguments===
*'''theResource:''' the [[resource]] we want to restart.

===Returns===
Returns ''true'' if the resource was restarted, ''false'' if the restart failed, or an invalid resource was passed.

==Example==
This function restarts all running resources.
<syntaxhighlight lang="lua">
function restartAllResources()
--we store a table of resources
local allResources = getResources()
--for each one of them,
for index, resource in ipairs(allResources) do
--if it's running,
if getResourceState(resource) == "running" then
--then restart it
restartResource(resource)
end
end
end
</syntaxhighlight>

==See Also==
{{Resource_functions}}

GetResources

2007-05-06T22:18:24Z

VRocker2: /* Example */

__NOTOC__
This function retrieves a table of all the resources that exist on the server.

==Syntax==
<syntaxhighlight lang="lua">
table getResources ()
</syntaxhighlight>

===Returns===
Returns a table of resources.

==Example==
<syntaxhighlight lang="lua">
function displayResources()
outputConsole("List of resources:")
local resourceTable = getResources() -- get a table of resources
for resourceKey, resourceValue in ipairs(resourceTable) do
-- iterate through the table and output each resource's name
local name = getResourceName(resourceValue)
outputConsole(" " .. name)
end
end
</syntaxhighlight>

==See Also==
{{Resource_functions}}

StopResource

2007-05-06T22:17:32Z

VRocker2: /* Example */

__NOTOC__
This function stops a running resource.

==Syntax==
<syntaxhighlight lang="lua">
bool stopResource ( resource theResource )
</syntaxhighlight>

===Required Arguments===
*'''theResource:''' the [[resource]] we want to stop.

===Returns===
Returns ''true'' if the resource was stopped, ''false'' if the stopping failed, or an invalid resource was passed.

==Example==
This function stops all running resources.
<syntaxhighlight lang="lua">
function stopAllResources()
--we store a table of resources
local allResources = getResources()
--for each one of them,
for index, resource in ipairs(allResources) do
--if it's running,
if getResourceState(resource) == "running" then
--then stop it
stopResource(resource)
end
end
end
</syntaxhighlight>

==See Also==
{{Resource_functions}}