Multi Theft Auto: Wiki - User contributions [en]

CreateProjectile

2007-07-07T09:35:05Z

TDHBoss:

__NOTOC__
This creates a projectile of the specified type on the specified coords.

==Usage==
Client-side only.

==Syntax==
<syntaxhighlight lang="lua">
bool createProjectile ( element creator, int weapon, [ float x = x, float y = y, float z = z, float force = 1.0, element target = nil ] )
</syntaxhighlight>

==Required Arguments==
*'''creator:''' The [[element]] representing creator of the projectile. In case you want the projectile to be synced for everybody creator must be [[getLocalPlayer]]().
*'''weapon:''' [[int]] representing the projectile weapon ID. Valid IDs are:
{{Projectiles}}

==Optional Arguments==
{{OptionalArg}}
*'''x''','''y''','''z''': [[float]] starting coordinates for the projectile. They are coordinates of creator by default.
*'''force''': [[float]] representing the starting force of the projectile.
*'''target''': [[element]] target used for heat seeking rockets.

==Returns==
Returns ''true'' if projectile creation was succesfull. Returns ''false'' if unable to create a projectile (wrong weapon ID or projectiles limit was reached).

==Example==
This example makes a rocket minigun (minigun shooting with rockets).
<syntaxhighlight lang="lua">
-- This function gets triggered everytime player shoots.
function onClientPlayerWeaponFireFunc(weapon,ammo,ammoInClip,hitX,hitY,hitZ,hitElement)
if source == getLocalPlayer() and weapon == 38 then -- if source is a local player and he uses minigun...
if not createProjectile(getLocalPlayer(),19,getElementPosition(getLocalPlayer()),200) then -- then we either create a projectile...
outputChatBox ( "Rocket minigun overheated! Give it a rest pal!", source ) -- or if projectile limit is reached we output player a chat message
end
end
end
-- Don't forget to add the onClientPlayerWeaponFireFunc function as a handler for onClientPlayerWeaponFire.
addEventHandler("onClientPlayerWeaponFire",getRootElement(),onClientPlayerWeaponFireFunc)
</syntaxhighlight>

PlaySoundFrontEnd

2007-07-07T09:30:36Z

TDHBoss:

__NOTOC__
This function plays a frontend sound for the specified player.

==Usage==
Both server-side and client-side. "thePlayer" argument isn't used in client-side version of this function.

==Syntax==
<syntaxhighlight lang="lua">
bool playSoundFrontEnd ( player thePlayer, int sound )
</syntaxhighlight>

===Required Arguments===
*'''thePlayer:''' The [[player]] you want the sound to play for.
*'''sound:''' A whole [[int]] specifying the sound id to play. Valid values are:
{{Sounds}}

===Returns===
Returns ''true'' if the sound was successfully played , ''false'' otherwise.

==Example==
This example plays a sound when a player spawns
<syntaxhighlight lang="lua">
function onPlayerSpawn ( spawnpoint, team ) --when a player spawns
playSoundFrontEnd ( source, 16 ) --play a sound for him
end
addEventHandler ( "onPlayerSpawn", getElementRoot(), onPlayerSpawn ) --add an event for onPlayerSpawn
</syntaxhighlight>

==See Also==
{{Audio_functions}}

PreloadMissionAudio

2007-07-07T07:21:33Z

TDHBoss:

__NOTOC__
This function preloads a game sound into a specific sound slot. The sound can then be played with [[PlayMissionAudio]].

==Syntax==
<syntaxhighlight lang="lua">
bool preloadMissionAudio ( player thePlayer, int sound, int slot )
</syntaxhighlight>

===Required Arguments===
*'''thePlayer''': the [[player]] you want to play the sound for.
*'''sound''': the [[int]] sound id to play (interpreted as unsigned short). Valid values are those from the '''data/AudioEvents.txt''' file.
*'''slot''': [[int]] sound slot in which you preloaded the sound.

===Returns===
Returns ''true'' if the sound was successfully preloaded, ''false'' otherwise.

==Example==
See [[PlayMissionAudio]].

==See Also==
{{Audio_functions}}

CreateProjectile

2007-07-06T22:29:13Z

TDHBoss:

__NOTOC__
This creates a projectile of the specified type on the specified coords.

==Syntax==
<syntaxhighlight lang="lua">
bool createProjectile ( element creator, int weapon, [ float x = x, float y = y, float z = z, float force = 1.0, element target = nil ] )
</syntaxhighlight>

==Required Arguments==
*'''creator:''' The [[element]] representing creator of the projectile. In case you want the projectile to be synced for everybody creator must be [[getLocalPlayer]]().
*'''weapon:''' [[int]] representing the [[projectiles|projectile weapon ID]].

==Optional Arguments==
{{OptionalArg}}
*'''x''','''y''','''z''': [[float]] starting coordinates for the projectile. They are coordinates of creator by default.
*'''force''': [[float]] representing the starting force of the projectile.
*'''target''': [[element]] target used for heat seeking rockets.

==Returns==
Returns ''true'' if projectile creation was succesfull. Returns ''false'' if unable to create a projectile (wrong weapon ID or projectiles limit was reached).

==Example==
This example makes a rocket minigun (minigun shooting with rockets).
<syntaxhighlight lang="lua">
-- This function gets triggered everytime player shoots.
function onClientPlayerWeaponFireFunc(weapon,ammo,ammoInClip,hitX,hitY,hitZ,hitElement)
if source == getLocalPlayer() and weapon == 38 then -- if source is a local player and he uses minigun...
if not createProjectile(getLocalPlayer(),19,getElementPosition(getLocalPlayer()),200) then -- then we either create a projectile...
outputChatBox ( "Rocket minigun overheated! Give it a rest pal!", source ) -- or if projectile limit is reached we output player a chat message
end
end
end
-- Don't forget to add the onClientPlayerWeaponFireFunc function as a handler for onClientPlayerWeaponFire.
addEventHandler("onClientPlayerWeaponFire",getRootElement(),onClientPlayerWeaponFireFunc)
</syntaxhighlight>

CreateProjectile

2007-07-06T22:26:22Z

TDHBoss:

__NOTOC__
This creates a projectile of the specified type on the specified coords. Returns [[true]] if creation was succesfull or [[false]] otherwise.

==Syntax==
<syntaxhighlight lang="lua">
bool createProjectile ( element creator, int weapon, [ float x = x, float y = y, float z = z, float force = 1.0, element target = nil ] )
</syntaxhighlight>

==Required Arguments==
*'''creator:''' The [[element]] representing creator of the projectile. In case you want the projectile to be synced for everybody creator must be [[getLocalPlayer]]().
*'''weapon:''' [[int]] representing the [[projectiles|projectile weapon ID]].

==Optional Arguments==
{{OptionalArg}}
*'''x''','''y''','''z''': [[float]] starting coordinates for the projectile. They are coordinates of creator by default.
*'''force''': [[float]] representing the starting force of the projectile.
*'''target''': [[element]] target used for heat seeking rockets.

==Example==
This example makes a rocket minigun (minigun shooting with rockets).
<syntaxhighlight lang="lua">
-- This function gets triggered everytime player shoots.
function onClientPlayerWeaponFireFunc(weapon,ammo,ammoInClip,hitX,hitY,hitZ,hitElement)
if source == getLocalPlayer() and weapon == 38 then -- if source is a local player and he uses minigun...
if not createProjectile(getLocalPlayer(),19,getElementPosition(getLocalPlayer()),200) then -- then we either create a projectile...
outputChatBox ( "Rocket minigun overheated! Give it a rest pal!", source ) -- or if projectile limit is reached we output player a chat message
end
end
end
-- Don't forget to add the onClientPlayerWeaponFireFunc function as a handler for onClientPlayerWeaponFire.
addEventHandler("onClientPlayerWeaponFire",getRootElement(),onClientPlayerWeaponFireFunc)
</syntaxhighlight>

OnClientPlayerWeaponFire

2007-07-06T22:01:57Z

TDHBoss:

__NOTOC__
This event is called when player shoots a weapon.

==Syntax==
<syntaxhighlight lang="lua">
void onClientPlayerWeaponFire ( int weapon, int ammo, int ammoInClip, float hitX, float hitY, float hitZ, element hitElement )
</syntaxhighlight>

==Parameters==
*The '''source''' of this event refers to the player who made a shot.
*'''weapon''': an [[int]] representing [[weapons|weapon]] used for making a shot.
*'''ammo''': an [[int]] ammount of ammo left for this weapon type.
*'''ammoInClip''': an [[int]] ammount of ammo left for this weapon type in clip.
*'''hitX''', '''hitY''', '''hitZ''': [[float]] world coordinates representing a hit point.
*'''hitElement''': an [[element]] which was hit by a shot.

==Example==
This example shows player a warning if he hits any other player with minigun.
<syntaxhighlight lang="lua">
-- trigger the event every time player shots
function onClientPlayerWeaponFireFunc(weapon, ammo, ammoInClip, hitX, hitY, hitZ, hitElement )
if weapon == 38 and getElementType(hitElement)=="player" then -- if player shots from minigun and he hits another player...
outputChatBox ( "Don't kill people with minigun, it's lame!", source ) -- then we output him a warning
end
end
-- don't forget to add the onClientPlayerWeaponFireFunc function as a handler for onClientPlayerWeaponFire
addEventHandler ( "onPlayerSpawn", getRootElement(), onClientPlayerWeaponFireFunc )
</syntaxhighlight>

OnClientPlayerWeaponFire

2007-07-06T22:00:12Z

TDHBoss:

__NOTOC__
This event is called when player shoots a weapon.

==Syntax==
<syntaxhighlight lang="lua">
void onClientPlayerWeaponFire ( int weapon, int ammo, int ammoInClip, float hitX, float hitY, float hitZ, element hitElement )
</syntaxhighlight>

==Parameters==
*The '''source''' of this event refers to the player who made a shot.
*'''weapon''': a [[weapons|weapon]] [[integer]] of a weapon used.
*'''ammo''': an [[integer]] ammount of ammo left for this weapon type.
*'''ammoInClip''': an [[integer]] ammount of ammo left for this weapon type in clip.
*'''hitX''', '''hitY''', '''hitZ''': [[float]] world coordinates representing a hit point.
*'''hitElement''': an [[element]] which was hit by a shot.

==Example==
This example shows player a warning if he hits any other player with minigun.
<syntaxhighlight lang="lua">
-- trigger the event every time player shots
function onClientPlayerWeaponFireFunc(weapon, ammo, ammoInClip, hitX, hitY, hitZ, hitElement )
if weapon == 38 and getElementType(hitElement)=="player" then -- if player shots from minigun and he hits another player...
outputChatBox ( "Don't kill people with minigun, it's lame!", source ) -- then we output him a warning
end
end
-- don't forget to add the onClientPlayerWeaponFireFunc function as a handler for onClientPlayerWeaponFire
addEventHandler ( "onPlayerSpawn", getRootElement(), onClientPlayerWeaponFireFunc )
</syntaxhighlight>

==See also==
{{Projectile functions}}

OnClientPlayerWeaponFire

2007-07-06T21:59:17Z

TDHBoss:

__NOTOC__
This event is called when player shoots a weapon.

==Syntax==
<syntaxhighlight lang="lua">
void onClientPlayerWeaponFire ( int weapon, int ammo, int ammoInClip, float hitX, float hitY, float hitZ, element hitElement )
</syntaxhighlight>

==Parameters==
*The '''source''' of this event refers to the player who made a shot.
*'''weapon''': a [[weapons|weapon]] [[integer]] of a weapon used.
*'''ammo''': an [[integer]] ammount of ammo left for this weapon type.
*'''ammoInClip''': an [[integer]] ammount of ammo left for this weapon type in clip.
*'''hitX''', '''hitY''', '''hitZ''': [[float]] world coordinates representing a hit point.
*'''hitElement''': an [[element]] which was hit by a shot.

==Example==
This example shows player a warning if he hits any other player with minigun.
<syntaxhighlight lang="lua">
-- trigger the event every time player shots
function onClientPlayerWeaponFireFunc(weapon, ammo, ammoInClip, hitX, hitY, hitZ, hitElement )
if weapon == 38 and getElementType(hitElement)=="player" then -- if player shots from minigun and he hits another player...
outputChatBox ( "Don't kill people with minigun, it's lame!", source ) -- then we output him a warning
end
end
-- add the onClientPlayerWeaponFireFunc function as a handler for onClientPlayerWeaponFire
addEventHandler ( "onPlayerSpawn", getRootElement(), onClientPlayerWeaponFireFunc )
</syntaxhighlight>

==See also==
{{Projectiles functions}}

OnPlayerSpawn

2007-07-06T21:59:11Z

TDHBoss:

__NOTOC__
This event is called when a player spawns.

==Syntax==
<syntaxhighlight lang="lua">
void onPlayerSpawn ( spawnpoint theSpawnpoint, team theTeam )
</syntaxhighlight>

==Parameters==
*The '''source''' of this event refers to the player who spawned.
*'''theSpawnpoint''': a [[spawnpoint]] element representing the spawnpoint at which the player was spawned.
*'''theTeam''': a [[team]] element representing the team of the spawnpoint.

==Example==
This example plays a sound when a player spawns.
<syntaxhighlight lang="lua">
-- when a player spawns,
function player_Spawn ( inSpawnpoint, inTeam )
-- play a frontend sound for him
playSoundFrontEnd ( source, 16 )
end
-- add the player_Spawn function as a handler for onPlayerSpawn
addEventHandler ( "onPlayerSpawn", getRootElement(), player_Spawn )
</syntaxhighlight>

==See also==
{{Event functions}}

CancelEvent

2007-07-06T21:25:37Z

TDHBoss:

__NOTOC__
This function is used to stop the automatic internal handling of events, for example this can be used to prevent an item being given to a player when they walk over a pickup, by canceling the [[onPickupUse]] event.

[[cancelEvent]] does not have an effect on all events, see the individual event's pages for information on what happens when the event is canceled. [[cancelEvent]] does not stop further event handlers from being called, as the order of event handlers being called is undefined in many cases. Instead, you can see if the currently active event has been cancelled using [[wasEventCanceled]].

The use of cancelEvent outside of an event handler has no effect.

If you implement your own custom events and want to handle them being cancelled, you should call [[wasEventCanceled]] to check after your call to [[triggerEvent]].

==Syntax==
<syntaxhighlight lang="lua">
bool cancelEvent ()
</syntaxhighlight>

===Returns===
Always returns ''true''.

==Example==
This example stops the player ''huntedPlayer'' from entering a vehicle:
<syntaxhighlight lang="lua">
-- call 'stopVehicleEntry' whenever hunterPlayer is about to enter a vehicle:
addEventHandler ( "onVehicleStartEnter", huntedPlayer, "stopVehicleEntry" )
function stopVehicleEntry ( theplayer, seat, jacked )
cancelEvent () -- stop the event from occuring
end
</syntaxhighlight>

==See Also==
{{Event functions}}

Id

2007-07-06T21:00:03Z

TDHBoss:

'''Note: this page needs to link functions they apply to'''

ID stands for identification. It is a whole-number integer that refers to many mechanics of San Andreas.
----
Game elements using IDs:
''Note: does not include small ID lists related to specific functions or IDs created by MTA''
*[[Character Skins]]
*Clothing Styles
*[[Projectiles|Projectiles]]
*[[Template:Blip_Icons|Radar Blips]]
*[[Template:Sounds|Sounds]]
*[http://vces.net/info/CarIDs.html Vehicles]
* [[Template:Vehicle_colors|Vehicle Colors]]
*Vehicle Upgrades
*[[Weapons|Weapons]]
*[http://vces.net/info/WeatherIDs.html Weather] '''brophy needs to use 1-19 only''' ''Note: blended weather allows for many more undocumented effects''

==See Also==
{{IDs}}

'''Credit for information contained in the pages:'''
Ransom (initial creation, formatting, and all lists not credited to others) eAi (vehicle colors list) erorr404/Talidan/Brophy (sound list) Talidan (radar blip pictures/vehicle list) Hellfish (skin pictures [http://www.gtaforums.com/index.php?showtopic=205220 SOURCE]) Brophy/Ratt/Panther/Twig (lots of inital ID data) GTAForums (Allowing Ransom to find IDs for lists)

Id

2007-07-06T20:59:35Z

TDHBoss:

'''Note: this page needs to link functions they apply to'''

ID stands for identification. It is a whole-number integer that refers to many mechanics of San Andreas.
----
Game elements using IDs:
''Note: does not include small ID lists related to specific functions or IDs created by MTA''
*[[Character Skins]]
*Clothing Styles
*[[Template:Blip_Icons|Radar Blips]]
*[[Projectiles|Projectiles]]
*[[Template:Sounds|Sounds]]
*[http://vces.net/info/CarIDs.html Vehicles]
* [[Template:Vehicle_colors|Vehicle Colors]]
*Vehicle Upgrades
*[[Weapons|Weapons]]
*[http://vces.net/info/WeatherIDs.html Weather] '''brophy needs to use 1-19 only''' ''Note: blended weather allows for many more undocumented effects''

==See Also==
{{IDs}}

'''Credit for information contained in the pages:'''
Ransom (initial creation, formatting, and all lists not credited to others) eAi (vehicle colors list) erorr404/Talidan/Brophy (sound list) Talidan (radar blip pictures/vehicle list) Hellfish (skin pictures [http://www.gtaforums.com/index.php?showtopic=205220 SOURCE]) Brophy/Ratt/Panther/Twig (lots of inital ID data) GTAForums (Allowing Ransom to find IDs for lists)

BindKey

2007-06-28T19:38:42Z

TDHBoss: /* Example */

__NOTOC__
Binds a player's key to a console command, which will be triggered when the key is pressed. Keys that are bound to actual keyboard keys are displayed and can be modified by the user from the settings window.

==Syntax==
<syntaxhighlight lang="lua">bindKey ( player thePlayer, string key, string keyState, string name, function functionName, [ var aguments, ... ] ) </syntaxhighlight>

===Required Arguments===
*'''thePlayer:''' The player you wish to bind the key of.
*'''key:''' The key or control you wish to bind to the command. See [[key names]] for a list of possible keys and [[control names]] for a list of possible controls.
*'''keyState:''' A string that has one of the following values:
**'''"up":''' If the bound key should trigger the function when the key is released
**'''"down":''' If the bound key should trigger the function when the key is pressed
**'''"both":''' If the bound key should trigger the function when the key is pressed or released
*'''name:''' The name for this key bind when it appears in the client's settings dialog.
*'''functionName:''' The function that will be triggered when the player's key is pressed. Function name IS NOT a string, so you shouldn't use "". This function should have the form:
:<syntaxhighlight lang="lua">function functionName ( source, key, keyState, [ var arguments, ... ] )</syntaxhighlight>
:The values passed to this function are:
:*'''source:''' The player who pressed the key
:*'''key:''' The key that was pressed
:*'''keyState:''' The state of the key that was pressed, ''down'' if it was pressed, ''up'' if it was released.
:*'''arguments''' The optional arguments you specified when calling [[bindKey]] (see below).

===Optional Arguments===
{{OptionalArg}}
*'''arguments:''' Any arguments you may want to pass to the function when the key is pressed by the user. Any number of arguments of can be specified, each being passed to the designated function.

==Example==
'''Example 1:''' This example will bind a player's 'F1' key and 'fire' control to 1 input function.
<syntaxhighlight lang="lua">
function funcInput ( source, key, keyState )
local state = "let go of"
if ( keyState == "down" ) then
state = "pressed"
end
outputChatBox ( getClientName ( source ) .. " " .. state .. " the " .. key .. " key!" )
end

function bindthekeys ( source )
bindKey ( source, "F1", "down", funcInput ) -- bind the player's F1 down key
bindKey ( source, "F1", "up", funcInput ) -- bind the player's F1 up key
bindKey ( source, "fire", "both", funcInput ) -- bind the player's fire down and up control
end
addCommandHandler ( "bindme", bindthekeys )
</syntaxhighlight>

==See Also==
{{Input functions}}

BindKey

2007-06-28T19:37:09Z

TDHBoss: /* Syntax */

__NOTOC__
Binds a player's key to a console command, which will be triggered when the key is pressed. Keys that are bound to actual keyboard keys are displayed and can be modified by the user from the settings window.

==Syntax==
<syntaxhighlight lang="lua">bindKey ( player thePlayer, string key, string keyState, string name, function functionName, [ var aguments, ... ] ) </syntaxhighlight>

===Required Arguments===
*'''thePlayer:''' The player you wish to bind the key of.
*'''key:''' The key or control you wish to bind to the command. See [[key names]] for a list of possible keys and [[control names]] for a list of possible controls.
*'''keyState:''' A string that has one of the following values:
**'''"up":''' If the bound key should trigger the function when the key is released
**'''"down":''' If the bound key should trigger the function when the key is pressed
**'''"both":''' If the bound key should trigger the function when the key is pressed or released
*'''name:''' The name for this key bind when it appears in the client's settings dialog.
*'''functionName:''' The function that will be triggered when the player's key is pressed. Function name IS NOT a string, so you shouldn't use "". This function should have the form:
:<syntaxhighlight lang="lua">function functionName ( source, key, keyState, [ var arguments, ... ] )</syntaxhighlight>
:The values passed to this function are:
:*'''source:''' The player who pressed the key
:*'''key:''' The key that was pressed
:*'''keyState:''' The state of the key that was pressed, ''down'' if it was pressed, ''up'' if it was released.
:*'''arguments''' The optional arguments you specified when calling [[bindKey]] (see below).

===Optional Arguments===
{{OptionalArg}}
*'''arguments:''' Any arguments you may want to pass to the function when the key is pressed by the user. Any number of arguments of can be specified, each being passed to the designated function.

==Example==
'''Example 1:''' This example will bind a player's 'F1' key and 'fire' control to 1 input function.
<syntaxhighlight lang="lua">
addCommandHandler ( "bindme", "bindthekeys" )
function bindthekeys ( source )
bindKey ( source, "F1", "down", "funcInput" ) -- bind the player's F1 down key
bindKey ( source, "F1", "up", "funcInput" ) -- bind the player's F1 up key
bindKey ( source, "fire", "both", "funcInput" ) -- bind the player's fire down and up control
end

function funcInput ( source, key, keyState )
local state = "let go of"
if ( keyState == "down" ) then
state = "pressed"
end
outputChatBox ( getClientName ( source ) .. " " .. state .. " the " .. key .. " key!" )
end
</syntaxhighlight>

==See Also==
{{Input functions}}

BindKey

2007-06-28T19:35:52Z

TDHBoss: /* Syntax */

__NOTOC__
Binds a player's key to a console command, which will be triggered when the key is pressed. Keys that are bound to actual keyboard keys are displayed and can be modified by the user from the settings window.

==Syntax==
<syntaxhighlight lang="lua">bindKey ( player thePlayer, string key, string keyState, string name, function function functionName, [ var aguments, ... ] ) </syntaxhighlight>

===Required Arguments===
*'''thePlayer:''' The player you wish to bind the key of.
*'''key:''' The key or control you wish to bind to the command. See [[key names]] for a list of possible keys and [[control names]] for a list of possible controls.
*'''keyState:''' A string that has one of the following values:
**'''"up":''' If the bound key should trigger the function when the key is released
**'''"down":''' If the bound key should trigger the function when the key is pressed
**'''"both":''' If the bound key should trigger the function when the key is pressed or released
*'''name:''' The name for this key bind when it appears in the client's settings dialog.
*'''function functionName:''' The function that will be triggered when the player's key is pressed. Function name IS NOT a string, so you shouldn't use "". This function should have the form:
:<syntaxhighlight lang="lua">function functionName ( source, key, keyState, [ var arguments, ... ] )</syntaxhighlight>
:The values passed to this function are:
:*'''source:''' The player who pressed the key
:*'''key:''' The key that was pressed
:*'''keyState:''' The state of the key that was pressed, ''down'' if it was pressed, ''up'' if it was released.
:*'''arguments''' The optional arguments you specified when calling [[bindKey]] (see below).

===Optional Arguments===
{{OptionalArg}}
*'''arguments:''' Any arguments you may want to pass to the function when the key is pressed by the user. Any number of arguments of can be specified, each being passed to the designated function.

==Example==
'''Example 1:''' This example will bind a player's 'F1' key and 'fire' control to 1 input function.
<syntaxhighlight lang="lua">
addCommandHandler ( "bindme", "bindthekeys" )
function bindthekeys ( source )
bindKey ( source, "F1", "down", "funcInput" ) -- bind the player's F1 down key
bindKey ( source, "F1", "up", "funcInput" ) -- bind the player's F1 up key
bindKey ( source, "fire", "both", "funcInput" ) -- bind the player's fire down and up control
end

function funcInput ( source, key, keyState )
local state = "let go of"
if ( keyState == "down" ) then
state = "pressed"
end
outputChatBox ( getClientName ( source ) .. " " .. state .. " the " .. key .. " key!" )
end
</syntaxhighlight>

==See Also==
{{Input functions}}

AddCommandHandler

2007-06-28T15:16:23Z

TDHBoss: /* Example */

__NOTOC__
{{Note_box|It is strongly advised that you do not use the same name for your handler function as the command name, as this can lead to confusion if multiple handler functions are used.}}
This function will attach a scripting function (handler) to a console command, so that whenever a player or administrator uses the command the function is called.

Multiple command handlers can be attached to a single command, and they will be called in the order that the handlers were attached. Equally, multiple commands can be handled by a single function, and the ''commandName'' parameter used to decide the course of action.

==Syntax==
<syntaxhighlight lang="lua">
bool addCommandHandler ( string commandName, function handlerFunction )
</syntaxhighlight>

===Required Arguments===
*'''commandName:''' This is the name of the command you wish to attach a handler to. This is what must be typed into the console to trigger the function.
*'''handlerFunction:''' This is the name of the function that you want the command to trigger. This function can take two parameters, playerSource and commandName, followed by as many parameters you expect after your command. These are all optional. Function name IS NOT a string, so you shouldn't use "".

<syntaxhighlight lang="lua">player playerSource, string commandName, [string arg1, string arg2, ...] </syntaxhighlight>

* '''playerSource:''' The player who triggered the command. If not triggered by a player (e.g. by admin), this will be ''false''.
* '''commandName:''' The name of the command triggered. This is useful if multiple commands go through one function.
* '''arg1, arg2, ...:''' Each word after command name in the original command is passed here in a seperate variable. If there is no value for an argument, its variable will contain [[nil]]. You can deal with a variable number of arguments using the vararg expression, as shown in '''Example 3''' below.

===Returns===
Returns ''true'' if the command handler was added successfully, ''false'' otherwise.

==Example==
'''Example 1:''' This example defines a command handler for the command ''createmarker''. This will create a red marker at the position of the player player who uses it.
<syntaxhighlight lang="lua">
-- Define our function that will handle this command
function consoleCreateMarker ( playerSource, commandName )
-- If a player triggered it (rather than the admin) then
if ( playerSource ) then
-- Get that player's position
local x, y, z = getElementPosition ( playerSource )
-- Create a size 2, red checkpoint marker at their position
createMarker ( x, y, z, "checkpoint", 2, 255, 0, 0, 255 )
-- Output it in the chat box
outputChatBox ( "You got a red marker", playerSource )
end
end
-- Register the command and attach it to the 'consoleCreateMarker' function
-- You must add a handler ONLY after function definition.
addCommandHandler ( "createmarker", consoleCreateMarker )
</syntaxhighlight>

'''Example 2:''' This example implements a ''set_vehicle_color'' command.
<syntaxhighlight lang="lua">
-- Define our function that will handle this command
function consoleSetVehicleColor ( playerSource, commandName, col1, col2, col3, col4 )
-- If a player triggered this in-game
if ( playerSource ) then
-- Get the player's vehicle
local playerVehicle = getPlayerOccupiedVehicle ( playerSource )
-- If the player is in a vehicle and we've got at least 1 parameter
if ( playerVehicle and col1 ) then
-- Get the vehicle's existing color and use it if fewer than 4 arguments were passed
local exCol1, exCol2, exCol3, exCol4 = getVehicleColor ( playerVehicle )

if not col2 then col2 = exCol2 end
if not col3 then col3 = exCol3 end
if not col4 then col4 = exCol4 end

-- Set the vehicle's color
setVehicleColor ( playerVehicle, col1, col2, col3, col4 )
else
-- If we didn't get at least 1 parameter or the player doesn't have a vehicle, display some help text
outputConsole ( "This function will set your current vehicle's colors. A vehicle can have up to 4 colors.", playerSource )
outputConsole ( "Syntax: set_vehicle_color color1 [ color2 color3 color4 ]", playerSource )
outputConsole ( "You must be in a vehicle to use this function.", playerSource )
end
end
end
-- Register the command and attach it to the 'consoleSetVehicleColor' function
-- You must add a handler ONLY after function definition.
addCommandHandler ( "set_vehicle_color", consoleSetVehicleColor )
</syntaxhighlight>

'''Example 3:''' This example makes use of Lua's vararg expression to output the number of parameters passed, merge them all into a single string and output it.
<syntaxhighlight lang="lua">
-- Define our function that will handle this command (which can accept a variable number of arguments after commandName)
function consoleCheckParameters ( playerSource, commandName, ... )
-- If a player, not an admin, triggered it,
if playerSource then
-- Pack all extra arguments passed in a table
local parametersTable = {...}
-- Get the number of arguments in that table
local parameterCount = #parametersTable
-- Output it to the player's chatbox
outputChatBox ( "Number of parameters: " .. parameterCount, playerSource )
-- Join them together in a single comma-separated string
local stringWithAllParameters = table.concat( parametersTable, ", " )
-- Output this parameter list to the player's chatbox
outputChatBox ( "Parameters passed: " .. stringWithAllParameter, playerSource )
end
end
-- Register the command and attach it to the 'consoleCheckParameters' function
-- You must add a handler ONLY after function definition.
addCommandHandler ( "check_parameters", consoleCheckParamters )
</syntaxhighlight>

==See Also==
{{Server functions}}

AddCommandHandler

2007-06-28T15:15:23Z

TDHBoss: /* Example */

__NOTOC__
{{Note_box|It is strongly advised that you do not use the same name for your handler function as the command name, as this can lead to confusion if multiple handler functions are used.}}
This function will attach a scripting function (handler) to a console command, so that whenever a player or administrator uses the command the function is called.

Multiple command handlers can be attached to a single command, and they will be called in the order that the handlers were attached. Equally, multiple commands can be handled by a single function, and the ''commandName'' parameter used to decide the course of action.

==Syntax==
<syntaxhighlight lang="lua">
bool addCommandHandler ( string commandName, function handlerFunction )
</syntaxhighlight>

===Required Arguments===
*'''commandName:''' This is the name of the command you wish to attach a handler to. This is what must be typed into the console to trigger the function.
*'''handlerFunction:''' This is the name of the function that you want the command to trigger. This function can take two parameters, playerSource and commandName, followed by as many parameters you expect after your command. These are all optional. Function name IS NOT a string, so you shouldn't use "".

<syntaxhighlight lang="lua">player playerSource, string commandName, [string arg1, string arg2, ...] </syntaxhighlight>

* '''playerSource:''' The player who triggered the command. If not triggered by a player (e.g. by admin), this will be ''false''.
* '''commandName:''' The name of the command triggered. This is useful if multiple commands go through one function.
* '''arg1, arg2, ...:''' Each word after command name in the original command is passed here in a seperate variable. If there is no value for an argument, its variable will contain [[nil]]. You can deal with a variable number of arguments using the vararg expression, as shown in '''Example 3''' below.

===Returns===
Returns ''true'' if the command handler was added successfully, ''false'' otherwise.

==Example==
'''Example 1:''' This example defines a command handler for the command ''createmarker''. This will create a red marker at the position of the player player who uses it.
<syntaxhighlight lang="lua">
-- Define our function that will handle this command
function consoleCreateMarker ( playerSource, commandName )
-- If a player triggered it (rather than the admin) then
if ( playerSource ) then
-- Get that player's position
local x, y, z = getElementPosition ( playerSource )
-- Create a size 2, red checkpoint marker at their position
createMarker ( x, y, z, "checkpoint", 2, 255, 0, 0, 255 )
-- Output it in the chat box
outputChatBox ( "You got a red marker", playerSource )
end
end
-- Register the command and attach it to the 'consoleCreateMarker' function
-- You must add a handler ONLY after function definition.
addCommandHandler ( "createmarker", consoleCreateMarker )
</syntaxhighlight>

'''Example 2:''' This example implements a ''set_vehicle_color'' command.
<syntaxhighlight lang="lua">
-- Register the command and attach it to the 'consoleSetVehicleColor' function
addCommandHandler ( "set_vehicle_color", "consoleSetVehicleColor" )
-- Define our function that will handle this command
function consoleSetVehicleColor ( playerSource, commandName, col1, col2, col3, col4 )
-- If a player triggered this in-game
if ( playerSource ) then
-- Get the player's vehicle
local playerVehicle = getPlayerOccupiedVehicle ( playerSource )
-- If the player is in a vehicle and we've got at least 1 parameter
if ( playerVehicle and col1 ) then
-- Get the vehicle's existing color and use it if fewer than 4 arguments were passed
local exCol1, exCol2, exCol3, exCol4 = getVehicleColor ( playerVehicle )

if not col2 then col2 = exCol2 end
if not col3 then col3 = exCol3 end
if not col4 then col4 = exCol4 end

-- Set the vehicle's color
setVehicleColor ( playerVehicle, col1, col2, col3, col4 )
else
-- If we didn't get at least 1 parameter or the player doesn't have a vehicle, display some help text
outputConsole ( "This function will set your current vehicle's colors. A vehicle can have up to 4 colors.", playerSource )
outputConsole ( "Syntax: set_vehicle_color color1 [ color2 color3 color4 ]", playerSource )
outputConsole ( "You must be in a vehicle to use this function.", playerSource )
end
end
end
</syntaxhighlight>

'''Example 3:''' This example makes use of Lua's vararg expression to output the number of parameters passed, merge them all into a single string and output it.
<syntaxhighlight lang="lua">
-- Register the command and attach it to the 'consoleCheckParameters' function
addCommandHandler ( "check_parameters", "consoleCheckParamters" )
-- Define our function that will handle this command (which can accept a variable number of arguments after commandName)
function consoleCheckParameters ( playerSource, commandName, ... )
-- If a player, not an admin, triggered it,
if playerSource then
-- Pack all extra arguments passed in a table
local parametersTable = {...}
-- Get the number of arguments in that table
local parameterCount = #parametersTable
-- Output it to the player's chatbox
outputChatBox ( "Number of parameters: " .. parameterCount, playerSource )
-- Join them together in a single comma-separated string
local stringWithAllParameters = table.concat( parametersTable, ", " )
-- Output this parameter list to the player's chatbox
outputChatBox ( "Parameters passed: " .. stringWithAllParameter, playerSource )
end
end
</syntaxhighlight>

==See Also==
{{Server functions}}

AddCommandHandler

2007-06-28T15:13:06Z

TDHBoss: /* Syntax */

__NOTOC__
{{Note_box|It is strongly advised that you do not use the same name for your handler function as the command name, as this can lead to confusion if multiple handler functions are used.}}
This function will attach a scripting function (handler) to a console command, so that whenever a player or administrator uses the command the function is called.

Multiple command handlers can be attached to a single command, and they will be called in the order that the handlers were attached. Equally, multiple commands can be handled by a single function, and the ''commandName'' parameter used to decide the course of action.

==Syntax==
<syntaxhighlight lang="lua">
bool addCommandHandler ( string commandName, function handlerFunction )
</syntaxhighlight>

===Required Arguments===
*'''commandName:''' This is the name of the command you wish to attach a handler to. This is what must be typed into the console to trigger the function.
*'''handlerFunction:''' This is the name of the function that you want the command to trigger. This function can take two parameters, playerSource and commandName, followed by as many parameters you expect after your command. These are all optional. Function name IS NOT a string, so you shouldn't use "".

<syntaxhighlight lang="lua">player playerSource, string commandName, [string arg1, string arg2, ...] </syntaxhighlight>

* '''playerSource:''' The player who triggered the command. If not triggered by a player (e.g. by admin), this will be ''false''.
* '''commandName:''' The name of the command triggered. This is useful if multiple commands go through one function.
* '''arg1, arg2, ...:''' Each word after command name in the original command is passed here in a seperate variable. If there is no value for an argument, its variable will contain [[nil]]. You can deal with a variable number of arguments using the vararg expression, as shown in '''Example 3''' below.

===Returns===
Returns ''true'' if the command handler was added successfully, ''false'' otherwise.

==Example==
'''Example 1:''' This example defines a command handler for the command ''createmarker''. This will create a red marker at the position of the player player who uses it.
<syntaxhighlight lang="lua">
-- Register the command and attach it to the 'consoleCreateMarker' function
addCommandHandler ( "createmarker", "consoleCreateMarker" )
-- Define our function that will handle this command
function consoleCreateMarker ( playerSource, commandName )
-- If a player triggered it (rather than the admin) then
if ( playerSource ) then
-- Get that player's position
local x, y, z = getElementPosition ( playerSource )
-- Create a size 2, red checkpoint marker at their position
createMarker ( x, y, z, "checkpoint", 2, 255, 0, 0, 255 )
-- Output it in the chat box
outputChatBox ( "You got a red marker", playerSource )
end
end
</syntaxhighlight>

'''Example 2:''' This example implements a ''set_vehicle_color'' command.
<syntaxhighlight lang="lua">
-- Register the command and attach it to the 'consoleSetVehicleColor' function
addCommandHandler ( "set_vehicle_color", "consoleSetVehicleColor" )
-- Define our function that will handle this command
function consoleSetVehicleColor ( playerSource, commandName, col1, col2, col3, col4 )
-- If a player triggered this in-game
if ( playerSource ) then
-- Get the player's vehicle
local playerVehicle = getPlayerOccupiedVehicle ( playerSource )
-- If the player is in a vehicle and we've got at least 1 parameter
if ( playerVehicle and col1 ) then
-- Get the vehicle's existing color and use it if fewer than 4 arguments were passed
local exCol1, exCol2, exCol3, exCol4 = getVehicleColor ( playerVehicle )

if not col2 then col2 = exCol2 end
if not col3 then col3 = exCol3 end
if not col4 then col4 = exCol4 end

-- Set the vehicle's color
setVehicleColor ( playerVehicle, col1, col2, col3, col4 )
else
-- If we didn't get at least 1 parameter or the player doesn't have a vehicle, display some help text
outputConsole ( "This function will set your current vehicle's colors. A vehicle can have up to 4 colors.", playerSource )
outputConsole ( "Syntax: set_vehicle_color color1 [ color2 color3 color4 ]", playerSource )
outputConsole ( "You must be in a vehicle to use this function.", playerSource )
end
end
end
</syntaxhighlight>

'''Example 3:''' This example makes use of Lua's vararg expression to output the number of parameters passed, merge them all into a single string and output it.
<syntaxhighlight lang="lua">
-- Register the command and attach it to the 'consoleCheckParameters' function
addCommandHandler ( "check_parameters", "consoleCheckParamters" )
-- Define our function that will handle this command (which can accept a variable number of arguments after commandName)
function consoleCheckParameters ( playerSource, commandName, ... )
-- If a player, not an admin, triggered it,
if playerSource then
-- Pack all extra arguments passed in a table
local parametersTable = {...}
-- Get the number of arguments in that table
local parameterCount = #parametersTable
-- Output it to the player's chatbox
outputChatBox ( "Number of parameters: " .. parameterCount, playerSource )
-- Join them together in a single comma-separated string
local stringWithAllParameters = table.concat( parametersTable, ", " )
-- Output this parameter list to the player's chatbox
outputChatBox ( "Parameters passed: " .. stringWithAllParameter, playerSource )
end
end
</syntaxhighlight>

==See Also==
{{Server functions}}

AddEventHandler

2007-06-28T14:49:34Z

TDHBoss: /* Example */

__NOTOC__
{{Note_box|It is strongly advised that you do not use the same name for your handler function as the event name, as this can lead to confusion if multiple handler functions are used.}}
This function will add an [[event]] handler. An event handler is a function that will be called when an event is triggered. See [[event system]] for more information on how the event system works.

==Syntax==
<syntaxhighlight lang="lua">
bool addEventHandler ( string eventName, element attachedTo, function functionName )
</syntaxhighlight>

===Required Arguments===
*'''eventName:''' The name of the [[event]] you want to attach the handler function to.
*'''attachedTo:''' The [[element]] you wish to attach the handler to. The handler will only be called when the event it is attached to is triggered for this element, or one of its children. Often, this can be the root element (meaning the handler will be called when the event is triggered for ''any'' element).
*'''functionName:''' The name of the handler function you wish to call. This function should have the correct number of parameters defined for the event you are using, but it isn't required that it takes all of them. Function name IS NOT a string, so you shouldn't use "".

===Returns===
Returns ''true'' if the event handler was attached successfully. Returns ''false'' if the event specified could not be found or the ''attachedTo'' [[element]] specified is invalid.

==Example==
This example sends a message to everyone in the server when a player spawns.
<syntaxhighlight lang="lua">
-- Get the root element
rootElement = getRootElement ()
-- Define our handler function
function onSpawnpointUseHandler(thePlayer)
-- Get the player's name
local playerName = getClientName( thePlayer )
-- Output in the chat box that they've spawned
outputChatBox ( playerName .. "has spawned!" )
end
-- Add an event handler to the onSpawnPointUse event (triggered when a player spawns at a spawnpoint)
-- You must add a handler ONLY after function definition.
addEventHandler ( "onSpawnpointUse", rootElement, onSpawnpointUseHandler )
</syntaxhighlight>

==See Also==
{{Event_functions}}

AddEventHandler

2007-06-28T14:48:40Z

TDHBoss: /* Example */

__NOTOC__
{{Note_box|It is strongly advised that you do not use the same name for your handler function as the event name, as this can lead to confusion if multiple handler functions are used.}}
This function will add an [[event]] handler. An event handler is a function that will be called when an event is triggered. See [[event system]] for more information on how the event system works.

==Syntax==
<syntaxhighlight lang="lua">
bool addEventHandler ( string eventName, element attachedTo, function functionName )
</syntaxhighlight>

===Required Arguments===
*'''eventName:''' The name of the [[event]] you want to attach the handler function to.
*'''attachedTo:''' The [[element]] you wish to attach the handler to. The handler will only be called when the event it is attached to is triggered for this element, or one of its children. Often, this can be the root element (meaning the handler will be called when the event is triggered for ''any'' element).
*'''functionName:''' The name of the handler function you wish to call. This function should have the correct number of parameters defined for the event you are using, but it isn't required that it takes all of them. Function name IS NOT a string, so you shouldn't use "".

===Returns===
Returns ''true'' if the event handler was attached successfully. Returns ''false'' if the event specified could not be found or the ''attachedTo'' [[element]] specified is invalid.

==Example==
This example sends a message to everyone in the server when a player spawns.
<syntaxhighlight lang="lua">
-- Get the root element
rootElement = getRootElement ()
-- Define our handler function
function onSpawnpointUseHandler(thePlayer)
-- Get the player's name
local playerName = getClientName( thePlayer )
-- Output in the chat box that they've spawned
outputChatBox ( playerName .. "has spawned!" )
end
-- Add an event handler to the onSpawnPointUse event (triggered when a player spawns at a spawnpoint). You must add a handler '''only''' after function definition.
addEventHandler ( "onSpawnpointUse", rootElement, onSpawnpointUseHandler )
</syntaxhighlight>

==See Also==
{{Event_functions}}

AddEventHandler

2007-06-28T14:47:46Z

TDHBoss: /* Example */

__NOTOC__
{{Note_box|It is strongly advised that you do not use the same name for your handler function as the event name, as this can lead to confusion if multiple handler functions are used.}}
This function will add an [[event]] handler. An event handler is a function that will be called when an event is triggered. See [[event system]] for more information on how the event system works.

==Syntax==
<syntaxhighlight lang="lua">
bool addEventHandler ( string eventName, element attachedTo, function functionName )
</syntaxhighlight>

===Required Arguments===
*'''eventName:''' The name of the [[event]] you want to attach the handler function to.
*'''attachedTo:''' The [[element]] you wish to attach the handler to. The handler will only be called when the event it is attached to is triggered for this element, or one of its children. Often, this can be the root element (meaning the handler will be called when the event is triggered for ''any'' element).
*'''functionName:''' The name of the handler function you wish to call. This function should have the correct number of parameters defined for the event you are using, but it isn't required that it takes all of them. Function name IS NOT a string, so you shouldn't use "".

===Returns===
Returns ''true'' if the event handler was attached successfully. Returns ''false'' if the event specified could not be found or the ''attachedTo'' [[element]] specified is invalid.

==Example==
This example sends a message to everyone in the server when a player spawns.
<syntaxhighlight lang="lua">
-- Get the root element
rootElement = getRootElement ()
-- Define our handler function
function onSpawnpointUseHandler(thePlayer)
-- Get the player's name
local playerName = getClientName( thePlayer )
-- Output in the chat box that they've spawned
outputChatBox ( playerName .. "has spawned!" )
end
</syntaxhighlight>
-- Add an event handler to the onSpawnPointUse event (triggered when a player spawns at a spawnpoint). You must add a handler '''only''' after function definition.
addEventHandler ( "onSpawnpointUse", rootElement, onSpawnpointUseHandler )

==See Also==
{{Event_functions}}

AddEventHandler

2007-06-28T14:44:50Z

TDHBoss: /* Syntax */

__NOTOC__
{{Note_box|It is strongly advised that you do not use the same name for your handler function as the event name, as this can lead to confusion if multiple handler functions are used.}}
This function will add an [[event]] handler. An event handler is a function that will be called when an event is triggered. See [[event system]] for more information on how the event system works.

==Syntax==
<syntaxhighlight lang="lua">
bool addEventHandler ( string eventName, element attachedTo, function functionName )
</syntaxhighlight>

===Required Arguments===
*'''eventName:''' The name of the [[event]] you want to attach the handler function to.
*'''attachedTo:''' The [[element]] you wish to attach the handler to. The handler will only be called when the event it is attached to is triggered for this element, or one of its children. Often, this can be the root element (meaning the handler will be called when the event is triggered for ''any'' element).
*'''functionName:''' The name of the handler function you wish to call. This function should have the correct number of parameters defined for the event you are using, but it isn't required that it takes all of them. Function name IS NOT a string, so you shouldn't use "".

===Returns===
Returns ''true'' if the event handler was attached successfully. Returns ''false'' if the event specified could not be found or the ''attachedTo'' [[element]] specified is invalid.

==Example==
This example sends a message to everyone in the server when a player spawns.
<syntaxhighlight lang="lua">
-- Get the root element
rootElement = getRootElement ()
-- Add an event handler to the onSpawnPointUse event (triggered when a player spawns at a spawnpoint)
addEventHandler ( "onSpawnpointUse", rootElement, "onSpawnpointUseHandler" )
-- Define our handler function
function onSpawnpointUseHandler( thePlayer )
-- Get the player's name
local playerName = getClientName( thePlayer )
-- Output in the chat box that they've spawned
outputChatBox ( playerName .. "has spawned!" )
end
</syntaxhighlight>

==See Also==
{{Event_functions}}

OnClientClick

2007-06-16T17:54:14Z

TDHBoss: /* Syntax */

[[Category:Incomplete Event]]

__NOTOC__
This event is blahblah and is used for blahblah.

==Syntax==
<syntaxhighlight lang="lua">void onClientClick ( string button, string state, int absoluteX, int absoluteY, float worldX, float worldY, float worldZ, element clickedWorld, bool clickedGUI )
</syntaxhighlight>

==Example==
This example does...
<syntaxhighlight lang="lua">
--This line does...
blabhalbalhb --abababa
--This line does this...
mooo
</syntaxhighlight>