Multi Theft Auto: Wiki - User contributions [en]

GetBans

2011-12-03T16:00:30Z

Wafamde: /* Example */

__NOTOC__
{{Server function}}
This function will return a table over all the [[ban]] values in the server.

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

===Returns===
Returns a [[table]] of all the [[ban]]s.

==Example==
<section name="Server" class="server" show="true">
'''Example 1:''' This example lists every ban when somebody types "/bans". WARNING: This will spam chat (for the player that executed the command) if the server has a lot of bans.
<syntaxhighlight lang="lua">
function listBans ( playerSource )
local banList = getBans() -- Return a table of all the bans.
--
for banID, ban in ipairs ( banList ) do -- For every ban do the following...
--
local nick = getBanNick ( ban ) -- Get the IP of the ban
--
if nick then
outputChatBox ( "Ban #" .. banID .. ": " .. nick, playerSource , 255, 0, 0, true ) -- Output the ban.
end
--
end
--
end
addCommandHandler ( "bans", listBans ) -- Add "/bans" as the trigger for the function.
</syntaxhighlight>
</section>

<section name="Server" class="server" show="false">
'''Example 2:''' <br>
This example shows you how you can make a commandHandler that can return data about bans on record.<br>
In this example there are several ways to get the info you want.<br>
You can find the ban you are looking for by providing one or more of the following arguments: <br>
- IP (The IP that has been banned)<br>
- Serial (The Serial that has been banned)<br>
- Nick (The Nick that has been banned)<br>
'''*You only have to provide ONE argument to find what you are looking for.*'''<br><br>

In this example there is also TWO ways of returning the info you want to see.<br>
Notice in the example that the ''' FORTH ''' argument is called ''' showOutput ''' .<br>
If ''' showOutput ''' is ' 1 ' then the server will return all the data on ONE line.<br>
If ''' showOutput ''' is anything else than ' 1 ' the server will return all data on seperate lines.<br><br>

An example of what the command could look like:<br>
''' /bans 192.168.0.10 0 0 1 ''' This example would look for the IP.<br>
''' /bans 0 NAME 0 1 ''' This example would look for the NAME.<br>
''' /bans 0 0 xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx 1 ''' This example would look for the Serial.<br>
'''*' xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx ' is not a serial. Replace it with the serial you want to find. (Amazing if you know one)*'''<br><br>

<syntaxhighlight lang="lua">
function findBanOnRecord( playerSource, cmd, iIp, iNick, iSerial, showOutput )
local allBans = getBans() -- Returns a table of all bans on record.
--
for banID, ban in ipairs ( allBans ) do -- Loop through all the bans to find our target.
--
local nick = getBanNick ( ban )
local ip = getBanIP ( ban )
local serial = getBanSerial( ban )
local banTime = getBanTime( ban )
local banReason = getBanReason ( ban )

-- If ' nick ' doesn't exist, we will use "N/A"
if not nick then
nick = "N/A"
end
-- If ' ip ' doesn't exist, we will use "N/A"
if not ip then --
ip = "N/A"
end
-- If ' serial ' doesn't exist, we will use "N/A"
if not serial then --
serial = "N/A"
end
-- If ' banReason ' doesn't exist, we will use "N/A"
if not banReason then
banReason = "N/A"
end

if nick == iNick or ip == iIp or serial == iSerial then -- If any of our input arguments match any bans.
--
if tonumber(showOutput) == 1 then -- If we use ' 1 ' in the forth argument, all the data will be output on ONE line.
outputChatBox ( "Ban #" .. banID .. " | Nick: " .. nick .. " | IP: " .. ip .. " | Serial: " .. serial .. " | BanTime: " .. banTime .. " | BanReason: " .. banReason, playerSource, 0, 153, 0, true )
else -- If nothing or anything other than ' 1 ' is used in the forth argument, all the data will be output on seperate lines.
outputChatBox ( "Ban #" .. banID, playerSource, 0, 153, 0, true )
outputChatBox ( "Nick: " .. nick, playerSource, 0, 153, 0, true )
outputChatBox ( "IP: " .. ip, playerSource, 0, 153, 0, true )
outputChatBox ( "Serial: " .. serial, playerSource, 0, 153, 0, true )
outputChatBox ( "BanTime: " .. banTime, playerSource, 0, 153, 0, true )
outputChatBox ( "BanReason: " .. banReason, playerSource, 0, 153, 0, true )
end
--
break -- Break the loop when we have found our target.
--
end
--
end
--
end
addCommandHandler ( "bans", listBans )
</syntaxhighlight>
</section>

==See Also==
{{Admin functions}}
[[ru:getBans]]

GetBans

2011-12-03T15:06:02Z

Wafamde: /* Example */

__NOTOC__
{{Server function}}
This function will return a table over all the [[ban]] values in the server.

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

===Returns===
Returns a [[table]] of all the [[ban]]s.

==Example==
<section name="Server" class="server" show="true">
'''Example 1:''' This example lists every ban when somebody types "/bans". WARNING: This will spam chat (for the player that executed the command) if the server has a lot of bans.
<syntaxhighlight lang="lua">
function listBans ( playerSource )
local banList = getBans() -- Return a table of all the bans.
--
for banID, ban in ipairs ( banList ) do -- For every ban do the following...
--
local nick = getBanNick ( ban ) -- Get the IP of the ban
--
if nick then
outputChatBox ( "Ban #" .. banID .. ": " .. nick, playerSource , 255, 0, 0 ) -- Output the ban.
end
--
end
--
end
addCommandHandler ( "bans", listBans ) -- Add "/bans" as the trigger for the function.
</syntaxhighlight>
</section>

<section name="Server" class="server" show="false">
'''Example 2:''' <br>
This example shows you how you can make a commandHandler that can return data about bans on record.<br>
In this example there are several ways to get the info you want.<br>
You can find the ban you are looking for by providing one or more of the following arguments: <br>
- IP (The IP that has been banned)<br>
- Serial (The Serial that has been banned)<br>
- Nick (The Nick that has been banned)<br>
'''*You only have to provide ONE argument to find what you are looking for.*'''<br><br>

In this example there is also TWO ways of returning the info you want to see.<br>
Notice in the example that the ''' FORTH ''' argument is called ''' showOutput ''' .<br>
If ''' showOutput ''' is ' 1 ' then the server will return all the data on ONE line.<br>
If ''' showOutput ''' is anything else than ' 1 ' the server will return all data on seperate lines.<br><br>

An example of what the command could look like:<br>
''' /bans 192.168.0.10 0 0 1 ''' This example would look for the IP.<br>
''' /bans 0 NAME 0 1 ''' This example would look for the NAME.<br>
''' /bans 0 0 xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx 1 ''' This example would look for the Serial.<br>
'''*' xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx ' is not a serial. Replace it with the serial you want to find. (Amazing if you know one)*'''<br><br>

<syntaxhighlight lang="lua">
function findBanOnRecord( playerSource, cmd, iIp, iNick, iSerial, showOutput )
local allBans = getBans() -- Returns a table of all bans on record.
--
for banID, ban in ipairs ( allBans ) do -- Loop through all the bans to find our target.
--
local nick = getBanNick ( ban )
local ip = getBanIP ( ban )
local serial = getBanSerial( ban )
local banTime = getBanTime( ban )
local banReason = getBanReason ( ban )

-- If ' nick ' doesn't exist, we will use "N/A"
if not nick then
nick = "N/A"
end
-- If ' ip ' doesn't exist, we will use "N/A"
if not ip then --
ip = "N/A"
end
-- If ' serial ' doesn't exist, we will use "N/A"
if not serial then --
serial = "N/A"
end
-- If ' banReason ' doesn't exist, we will use "N/A"
if not banReason then
banReason = "N/A"
end

if nick == iNick or ip == iIp or serial == iSerial then -- If any of our input arguments match any bans.
--
if tonumber(showOutput) == 1 then -- If we use ' 1 ' in the forth argument, all the data will be output on ONE line.
outputChatBox ( "Ban #" .. banID .. " | Nick: " .. nick .. " | IP: " .. ip .. " | Serial: " .. serial .. " | BanTime: " .. banTime .. " | BanReason: " .. banReason, playerSource, 0, 153, 0, true )
else -- If nothing or anything other than ' 1 ' is used in the forth argument, all the data will be output on seperate lines.
outputChatBox ( "Ban #" .. banID, playerSource, 0, 153, 0, true )
outputChatBox ( "Nick: " .. nick, playerSource, 0, 153, 0, true )
outputChatBox ( "IP: " .. ip, playerSource, 0, 153, 0, true )
outputChatBox ( "Serial: " .. serial, playerSource, 0, 153, 0, true )
outputChatBox ( "BanTime: " .. banTime, playerSource, 0, 153, 0, true )
outputChatBox ( "BanReason: " .. banReason, playerSource, 0, 153, 0, true )
end
--
break -- Break the loop when we have found our target.
--
end
--
end
--
end
addCommandHandler ( "bans", listBans )
</syntaxhighlight>
</section>

==See Also==
{{Admin functions}}
[[ru:getBans]]

GetBans

2011-12-03T15:01:31Z

Wafamde: /* Example */

__NOTOC__
{{Server function}}
This function will return a table over all the [[ban]] values in the server.

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

===Returns===
Returns a [[table]] of all the [[ban]]s.

==Example==
<section name="Server" class="server" show="true">
'''Example 1:''' This example lists every ban when somebody types "/bans". WARNING: This will spam chat (for the player that executed the command) if the server has a lot of bans.
<syntaxhighlight lang="lua">
function listBans ( playerSource )
local banList = getBans() -- Return a table of all the bans.
--
for banID, ban in ipairs ( banList ) do -- For every ban do the following...
--
local nick = getBanNick ( ban ) -- Get the IP of the ban
--
if nick then
outputChatBox ( "Ban #" .. banID .. ": " .. nick, playerSource , 255, 0, 0 ) -- Output the ban.
end
--
end
--
end
addCommandHandler ( "bans", listBans ) -- Add "/bans" as the trigger for the function.
</syntaxhighlight>
</section>

<section name="Server" class="server" show="false">
'''Example 2:''' <br>
This example shows you how you can make a commandHandler that can return data about bans on record.<br>
In this example there are several ways to get the info you want.<br>
You can find the ban you are looking for by providing one or more of the following arguments: <br>
- IP (The IP that has been banned)<br>
- Serial (The Serial that has been banned)<br>
- Nick (The Nick that has been banned)<br>
'''*You only have to provide ONE argument to find what you are looking for.*'''<br><br>

In this example there is also TWO ways of returning the info you want to see.<br>
Notice in the example that the ''' FORTH ''' argument is called ''' showOutput ''' .<br>
If ''' showOutput ''' is ' 1 ' then the server will return all the data on ONE line.<br>
If ''' showOutput ''' is anything else than ' 1 ' the server will return all data on seperate lines.<br><br>

An example of what the command could look like:<br>
''' /bans 192.168.0.10 0 0 1 ''' This example would look for the IP.<br>
''' /bans 0 NAME 0 1 ''' This example would look for the NAME.<br>
''' /bans 0 0 xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx 1 ''' This example would look for the Serial.<br>
'''*' xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx ' is not a serial. Replace it with the serial you want to find. (Amazing if you know one)*'''<br><br>

<syntaxhighlight lang="lua">
function findBanOnRecord( playerSource, cmd, iIp, iNick, iSerial, showOutput )
local allBans = getBans() -- Returns a table of all bans on record.
--
for banID, ban in ipairs ( allBans ) do -- Loop through all the bans to find our target.
--
local nick = getBanNick ( ban )
local ip = getBanIP ( ban )
local serial = getBanSerial( ban )
local banTime = getBanTime( ban )
local banReason = getBanReason ( ban )
--
if not nick then -- if ' nick ' doesn't exist, we will use "N/A"
nick = "N/A"
end
--
if not ip then -- if ' ip ' doesn't exist, we will use "N/A"
ip = "N/A"
end
--
if not serial then -- if ' serial ' doesn't exist, we will use "N/A"
serial = "N/A"
end
--
if not banReason then -- if ' banReason ' doesn't exist, we will use "N/A"
banReason = "N/A"
end
--
if nick == iNick or ip == iIp or serial == iSerial then -- If any of our input arguments match any bans.
--
if tonumber(showOutput) == 1 then -- If we use ' 1 ' in the forth argument, all the data will be output on ONE line.
outputChatBox ( "Ban #" .. banID .. " | Nick: " .. nick .. " | IP: " .. ip .. " | Serial: " .. serial .. " | BanTime: " .. banTime .. " | BanReason: " .. banReason, playerSource, 0, 153, 0, true )
else -- If nothing or anything other than ' 1 ' is used in the forth argument, all the data will be output on seperate lines.
outputChatBox ( "Ban #" .. banID, playerSource, 0, 153, 0, true )
outputChatBox ( "Nick: " .. nick, playerSource, 0, 153, 0, true )
outputChatBox ( "IP: " .. ip, playerSource, 0, 153, 0, true )
outputChatBox ( "Serial: " .. serial, playerSource, 0, 153, 0, true )
outputChatBox ( "BanTime: " .. banTime, playerSource, 0, 153, 0, true )
outputChatBox ( "BanReason: " .. banReason, playerSource, 0, 153, 0, true )
end
--
break -- Break the loop when we have found our target.
--
end
--
end
--
end
addCommandHandler ( "bans", listBans )
</syntaxhighlight>
</section>

==See Also==
{{Admin functions}}
[[ru:getBans]]

GetBans

2011-12-03T14:58:36Z

Wafamde: /* Example */

__NOTOC__
{{Server function}}
This function will return a table over all the [[ban]] values in the server.

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

===Returns===
Returns a [[table]] of all the [[ban]]s.

==Example==
<section name="Server" class="server" show="true">
'''Example 1:''' This example lists every ban when somebody types "/bans". WARNING: This will spam chat (for the player that executed the command) if the server has a lot of bans.
<syntaxhighlight lang="lua">
function listBans ( playerSource )
local banList = getBans() -- Return a table of all the bans.
--
for banID, ban in ipairs ( banList ) do -- For every ban do the following...
--
local nick = getBanNick ( ban ) -- Get the IP of the ban
--
if nick then
outputChatBox ( "Ban #" .. banID .. ": " .. nick, playerSource , 255, 0, 0 ) -- Output the ban.
end
--
end
--
end
addCommandHandler ( "bans", listBans ) -- Add "/bans" as the trigger for the function.
</syntaxhighlight>
</section>

<section name="Server" class="server" show="false">
'''Example 2:''' <br>
This example shows you how you can make a commandHandler that can return data about bans on record.<br>
In this example there are several ways to get the info you want.<br>
You can find the ban you are looking for by providing one or more of the following arguments: <br>
- IP (The IP that has been banned)<br>
- Serial (The Serial that has been banned)<br>
- Nick (The Nick that has been banned)<br>
'''*You only have to provide ONE argument to find what you are looking for.*'''<br><br>

In this example there is also TWO ways of returning the info you want to see.<br>
Notice in the example that the ''' FORTH ''' argument is called ''' showOutput ''' .<br>
If ''' showOutput ''' is ' 1 ' then the server will return all the data on ONE line.<br>
If ''' showOutput ''' is anything else than ' 1 ' the server will return all data on seperate lines.<br><br>

An example of what the command could look like:<br>
''' /bans 192.168.0.10 0 0 1 ''' This example would look for the IP.<br>
''' /bans 0 NAME 0 1 ''' This example would look for the NAME.<br>
''' /bans 0 0 xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx 1 ''' This example would look for the Serial.<br>
'''*' xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx ' is not a serial. Replace it with the serial you want to find. (Amazing if you know one)*'''<br><br>

<syntaxhighlight lang="lua">
function findBanOnRecord( playerSource, cmd, iIp, iNick, iSerial, showOutput )
local allBans = getBans() -- Returns a table of all bans on record.
--
for banID, ban in ipairs ( allBans ) do -- Loop through all the bans to find our target.
--
local nick = getBanNick ( ban )
local ip = getBanIP ( ban )
local serial = getBanSerial( ban )
local banTime = getBanTime( ban )
local banReason = getBanReason ( ban )

if not nick then -- if ' nick ' doesn't exist, we will use "N/A"
nick = "N/A"
end

if not ip then -- if ' ip ' doesn't exist, we will use "N/A"
ip = "N/A"
end

if not serial then -- if ' serial ' doesn't exist, we will use "N/A"
serial = "N/A"
end

if not banReason then -- if ' banReason ' doesn't exist, we will use "N/A"
banReason = "N/A"
end

if nick == iNick or ip == iIp or serial == iSerial then -- If any of our input arguments match any bans.
if tonumber(showOutput) == 1 then -- If we use ' 1 ' in the forth argument, all the data will be output on ONE line.
outputChatBox ( "Ban #" .. banID .. " | Nick: " .. nick .. " | IP: " .. ip .. " | Serial: " .. serial .. " | BanTime: " .. banTime .. " | BanReason: " .. banReason, playerSource, 0, 153, 0, true )
else -- If nothing or anything other than ' 1 ' is used in the forth argument, all the data will be output on seperate lines.
outputChatBox ( "Ban #" .. banID, playerSource, 0, 153, 0, true )
outputChatBox ( "Nick: " .. nick, playerSource, 0, 153, 0, true )
outputChatBox ( "IP: " .. ip, playerSource, 0, 153, 0, true )
outputChatBox ( "Serial: " .. serial, playerSource, 0, 153, 0, true )
outputChatBox ( "BanTime: " .. banTime, playerSource, 0, 153, 0, true )
outputChatBox ( "BanReason: " .. banReason, playerSource, 0, 153, 0, true )
end
break -- Break the loop when we have found our target.
end
end
end
addCommandHandler ( "bans", listBans )
</syntaxhighlight>
</section>

==See Also==
{{Admin functions}}
[[ru:getBans]]

GetBans

2011-12-03T06:35:13Z

Wafamde: /* Example */

AddCommandHandler

2011-11-30T17:20:33Z

Wafamde: /* Example */

__NOTOC__
{{Server client function}}
{{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. Use a name that describes your handler's purpose more specifically.}}
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.

For users, a command is in the format:

''commandName'' ''argument1'' ''argument2''

This can be triggered from the player's console or directly from the chat box by prefixing the message with a forward slash (''/''). For server side handlers, the server admin is also able to trigger these directly from the server's console in the same way as they are triggered from a player's console.

==Syntax==

<section name="Server" class="server" show="true">
<syntaxhighlight lang="lua">
bool addCommandHandler ( string commandName, function handlerFunction, [bool restricted = false, bool caseSensitive = true] )
</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 function that you want the command to trigger, which has to be defined before you add the handler. This function can take two parameters, playerSource and commandName, followed by as many parameters you expect after your command (see below). These are all optional.
===Optional Arguments===
{{OptionalArg}}
*'''restricted:''' Specify whether or not this command should be restricted by default. Use this on commands that should be inaccessible to everyone as default except special users specified in the ACL (Access Control List). This is to make sure admin commands such as ie. 'punish' won't be available to everyone if a server administrator forgets masking it in ACL. Make sure to add the command to your ACL under the proper group for it to be usefull (i.e <right name="command.killEveryone" access="true"></right>). This argument defaults to false if nothing is specified.
{{New feature|3|1.0|
*'''caseSensitive:''' Specifies if the command handler will ignore the case for this command name.
}}

</section>

<section name="Client" class="client" show="true">
<syntaxhighlight lang="lua">
bool addCommandHandler ( string commandName, function handlerFunction, [bool caseSensitive = true] )
</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 function that you want the command to trigger, which has to be defined before you add the handler. This function can take two parameters, playerSource and commandName, followed by as many parameters you expect after your command (see below). These are all optional.
===Optional Arguments===
{{OptionalArg}}
{{New feature|3|1.0|
*'''caseSensitive:''' Specifies if the command handler will ignore the case for this command name.
}}
</section>

====Handler function parameters====
These are the parameters for the handler function that is called when the command is used.
<section name="Server" class="server" show="true">
<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 4''' below.
</section>

<section name="Client" class="client" show="true">
<syntaxhighlight lang="lua"> string commandName, [string arg1, string arg2, ...] </syntaxhighlight>
* '''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 4''' below.
</section>

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

==Example==
<section name="Server" class="server" show="true">
'''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 )
-- 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 his chat box
outputChatBox ( "You got a red marker", playerSource )
end
end
-- Attach the 'consoleCreateMarker' function to the "createmarker" command
addCommandHandler ( "createmarker", consoleCreateMarker )
</syntaxhighlight>
</section>

<section name="Server" class="server" show="hide">
'''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 = getPedOccupiedVehicle ( 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
-- Attach the 'consoleSetVehicleColor' function to the "set_vehicle_color" command
addCommandHandler ( "set_vehicle_color", consoleSetVehicleColor )
</syntaxhighlight>
</section>

<section name="Server" class="server" show="hide">
'''Example 3:''' This example makes use of Lua's vararg expression to implement a ''check_parameters'' command to count the number of parameters passed, merge them all into a single string and output it. This is also shows you how you can use table.concat to merge all the passed arguments. This is particularly useful when you want to read in a sentence of text passed from the user.
<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
-- Get the number of arguments in the arg table (arg table is the same as: {...})
local parameterCount = #arg
-- 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( arg, ", " )
-- Output this parameter list to the player's chatbox
outputChatBox ( "Parameters passed: " .. stringWithAllParameters, playerSource )
end
end
-- Attach the 'consoleCheckParameters' function to the "check_parameters" command
addCommandHandler ( "check_parameters", consoleCheckParameters )
</syntaxhighlight>
</section>

<section name="Server" class="server" show="hide">
'''Example 4:''' This example shows using a single function to handle multiple command handlers. This isn't advised for general usage, as it makes code harder to understand, but where multiple command handlers share some logic, it can be a useful way of reducing duplicated code. Generally, it would be preferable to put this shared logic in a separate function instead, as this gives you more control over the flow.

<syntaxhighlight lang="lua">
-- make the function
function moneyCmd(player, cmd, amount)
if getElementData(player, "canUseMoneyFunctions") then -- the shared logic
if cmd == "givemoney" then
amount = tonumber(amount)
if amount then
givePlayerMoney(player, amount)
else
outputChatBox("[usage] /givemoney [amount]", player)
end
else if cmd == "takemoney" then
amount = tonumber(amount)
if amount then
takePlayerMoney(player, amount)
else
outputChatBox("[usage] /takemoney [amount]", player)
end
end
else
outputChatBox("You aren't able to use this command", player)
end
end

addCommandHandler("givemoney", moneyCmd);
addCommandHandler("takemoney", moneyCmd);
</syntaxhighlight>
</section>
<section name="Server" class="server" show="false">
'''Example 5:''' This example shows you how to create a function inside a commandHandler. This example creates an object, in this case a dildo, and attaches it to the player. Notice that unlike the other examples, we dont add 'addCommandHandler' after the function has been created. We create the function inside the commandHandler. This is not something you have to do, but it can save some work and space in the end in some cases.

<syntaxhighlight lang="lua">addCommandHandler("give_me_a_willy",function(player) -- Notice our function starts here
local x,y,z = getElementPosition(player)
local myObject = createObject(321,x,y,z)
setElementCollisionsEnabled(myObject ,false)
attachElements(myObject ,player,0.03,0.2,-0.45,0,0,90)
end) -- Remember to end the function before closing the commandHandler.
</syntaxhighlight>
</section>
<section name="Client" class="client" show="true">
'''Example 1:''' This creates a GUI window and allows a player to change its alpha (transparency) value with a command. Note that, in a clientside script, the player using the command is not passed as a parameter to the handler function, since it is always the local player.

<syntaxhighlight lang="lua">--Create a window
myWindow = guiCreateWindow ( 0.30, 0.10, 0.5, 0.60, "GUI window title", true )

--Add a command handler to change the alpha of the GUI window. Usage example: 'alpha 0.15'
function changeAlpha ( commandName, alphaAmount )
-- All command parameters are strings, so we'll convert the value to a number first
alphaAmount = tonumber(alphaAmount)
guiSetAlpha ( myWindow, alphaAmount )
end
addCommandHandler ( "alpha", changeAlpha )
</syntaxhighlight>
</section>
<section name="Client" class="client" show="false">
'''Example 2:''' This creates a GUI window and allows a player to change its alpha (transparency) value with a command. Note that, in a clientside script, the player using the command is not passed as a parameter to the handler function, since it is always the local player.

<syntaxhighlight lang="lua">function escapeMe ( commandName, taskType )
local x, y, z = getElementPosition ( getLocalPlayer() ) --Get player's position
setElementPosition ( getLocalPlayer(), x+(math.random(-10,10)), y+(math.random(-10,10)), z+(math.random(1,15)) ) --Move a player randomly to a nearby location. X is current x + a number between -10, 10 and so on.
end
addCommandHandler ( "escape", escapeMe ) --When player types "/escape" in chatbox or "escape" in console
</syntaxhighlight>
</section>

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

AddCommandHandler

2011-11-30T17:20:13Z

Wafamde: /* Example */

__NOTOC__
{{Server client function}}
{{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. Use a name that describes your handler's purpose more specifically.}}
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.

For users, a command is in the format:

''commandName'' ''argument1'' ''argument2''

This can be triggered from the player's console or directly from the chat box by prefixing the message with a forward slash (''/''). For server side handlers, the server admin is also able to trigger these directly from the server's console in the same way as they are triggered from a player's console.

==Syntax==

<section name="Server" class="server" show="true">
<syntaxhighlight lang="lua">
bool addCommandHandler ( string commandName, function handlerFunction, [bool restricted = false, bool caseSensitive = true] )
</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 function that you want the command to trigger, which has to be defined before you add the handler. This function can take two parameters, playerSource and commandName, followed by as many parameters you expect after your command (see below). These are all optional.
===Optional Arguments===
{{OptionalArg}}
*'''restricted:''' Specify whether or not this command should be restricted by default. Use this on commands that should be inaccessible to everyone as default except special users specified in the ACL (Access Control List). This is to make sure admin commands such as ie. 'punish' won't be available to everyone if a server administrator forgets masking it in ACL. Make sure to add the command to your ACL under the proper group for it to be usefull (i.e <right name="command.killEveryone" access="true"></right>). This argument defaults to false if nothing is specified.
{{New feature|3|1.0|
*'''caseSensitive:''' Specifies if the command handler will ignore the case for this command name.
}}

</section>

<section name="Client" class="client" show="true">
<syntaxhighlight lang="lua">
bool addCommandHandler ( string commandName, function handlerFunction, [bool caseSensitive = true] )
</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 function that you want the command to trigger, which has to be defined before you add the handler. This function can take two parameters, playerSource and commandName, followed by as many parameters you expect after your command (see below). These are all optional.
===Optional Arguments===
{{OptionalArg}}
{{New feature|3|1.0|
*'''caseSensitive:''' Specifies if the command handler will ignore the case for this command name.
}}
</section>

====Handler function parameters====
These are the parameters for the handler function that is called when the command is used.
<section name="Server" class="server" show="true">
<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 4''' below.
</section>

<section name="Client" class="client" show="true">
<syntaxhighlight lang="lua"> string commandName, [string arg1, string arg2, ...] </syntaxhighlight>
* '''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 4''' below.
</section>

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

==Example==
<section name="Server" class="server" show="true">
'''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 )
-- 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 his chat box
outputChatBox ( "You got a red marker", playerSource )
end
end
-- Attach the 'consoleCreateMarker' function to the "createmarker" command
addCommandHandler ( "createmarker", consoleCreateMarker )
</syntaxhighlight>
</section>

<section name="Server" class="server" show="hide">
'''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 = getPedOccupiedVehicle ( 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
-- Attach the 'consoleSetVehicleColor' function to the "set_vehicle_color" command
addCommandHandler ( "set_vehicle_color", consoleSetVehicleColor )
</syntaxhighlight>
</section>

<section name="Server" class="server" show="hide">
'''Example 3:''' This example makes use of Lua's vararg expression to implement a ''check_parameters'' command to count the number of parameters passed, merge them all into a single string and output it. This is also shows you how you can use table.concat to merge all the passed arguments. This is particularly useful when you want to read in a sentence of text passed from the user.
<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
-- Get the number of arguments in the arg table (arg table is the same as: {...})
local parameterCount = #arg
-- 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( arg, ", " )
-- Output this parameter list to the player's chatbox
outputChatBox ( "Parameters passed: " .. stringWithAllParameters, playerSource )
end
end
-- Attach the 'consoleCheckParameters' function to the "check_parameters" command
addCommandHandler ( "check_parameters", consoleCheckParameters )
</syntaxhighlight>
</section>

<section name="Server" class="server" show="hide">
'''Example 4:''' This example shows using a single function to handle multiple command handlers. This isn't advised for general usage, as it makes code harder to understand, but where multiple command handlers share some logic, it can be a useful way of reducing duplicated code. Generally, it would be preferable to put this shared logic in a separate function instead, as this gives you more control over the flow.

<syntaxhighlight lang="lua">
-- make the function
function moneyCmd(player, cmd, amount)
if getElementData(player, "canUseMoneyFunctions") then -- the shared logic
if cmd == "givemoney" then
amount = tonumber(amount)
if amount then
givePlayerMoney(player, amount)
else
outputChatBox("[usage] /givemoney [amount]", player)
end
else if cmd == "takemoney" then
amount = tonumber(amount)
if amount then
takePlayerMoney(player, amount)
else
outputChatBox("[usage] /takemoney [amount]", player)
end
end
else
outputChatBox("You aren't able to use this command", player)
end
end

addCommandHandler("givemoney", moneyCmd);
addCommandHandler("takemoney", moneyCmd);
</syntaxhighlight>
</section>
<section name="Server" class="server" show="false">
'''Example 5:''' This example shows you how to create a function inside a commandHandler. This example creates an object, in this case a dildo, and attaches it to the player. Notice that unlike the other examples, we dont add 'addCommandHandler' after the function has been created. We create the function inside the commandHandler. This is not something you have to do, but it can save some work and space in the end in some cases.

<syntaxhighlight lang="lua">addCommandHandler("give_me_a_willy",function(player) -- Notice our function stats here
local x,y,z = getElementPosition(player)
local myObject = createObject(321,x,y,z)
setElementCollisionsEnabled(myObject ,false)
attachElements(myObject ,player,0.03,0.2,-0.45,0,0,90)
end) -- Remember to end the function before closing the commandHandler.
</syntaxhighlight>
</section>
<section name="Client" class="client" show="true">
'''Example 1:''' This creates a GUI window and allows a player to change its alpha (transparency) value with a command. Note that, in a clientside script, the player using the command is not passed as a parameter to the handler function, since it is always the local player.

<syntaxhighlight lang="lua">--Create a window
myWindow = guiCreateWindow ( 0.30, 0.10, 0.5, 0.60, "GUI window title", true )

--Add a command handler to change the alpha of the GUI window. Usage example: 'alpha 0.15'
function changeAlpha ( commandName, alphaAmount )
-- All command parameters are strings, so we'll convert the value to a number first
alphaAmount = tonumber(alphaAmount)
guiSetAlpha ( myWindow, alphaAmount )
end
addCommandHandler ( "alpha", changeAlpha )
</syntaxhighlight>
</section>
<section name="Client" class="client" show="false">
'''Example 2:''' This creates a GUI window and allows a player to change its alpha (transparency) value with a command. Note that, in a clientside script, the player using the command is not passed as a parameter to the handler function, since it is always the local player.

<syntaxhighlight lang="lua">function escapeMe ( commandName, taskType )
local x, y, z = getElementPosition ( getLocalPlayer() ) --Get player's position
setElementPosition ( getLocalPlayer(), x+(math.random(-10,10)), y+(math.random(-10,10)), z+(math.random(1,15)) ) --Move a player randomly to a nearby location. X is current x + a number between -10, 10 and so on.
end
addCommandHandler ( "escape", escapeMe ) --When player types "/escape" in chatbox or "escape" in console
</syntaxhighlight>
</section>

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

AddCommandHandler

2011-11-30T17:16:39Z

Wafamde: /* Example */

__NOTOC__
{{Server client function}}
{{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. Use a name that describes your handler's purpose more specifically.}}
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.

For users, a command is in the format:

''commandName'' ''argument1'' ''argument2''

This can be triggered from the player's console or directly from the chat box by prefixing the message with a forward slash (''/''). For server side handlers, the server admin is also able to trigger these directly from the server's console in the same way as they are triggered from a player's console.

==Syntax==

<section name="Server" class="server" show="true">
<syntaxhighlight lang="lua">
bool addCommandHandler ( string commandName, function handlerFunction, [bool restricted = false, bool caseSensitive = true] )
</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 function that you want the command to trigger, which has to be defined before you add the handler. This function can take two parameters, playerSource and commandName, followed by as many parameters you expect after your command (see below). These are all optional.
===Optional Arguments===
{{OptionalArg}}
*'''restricted:''' Specify whether or not this command should be restricted by default. Use this on commands that should be inaccessible to everyone as default except special users specified in the ACL (Access Control List). This is to make sure admin commands such as ie. 'punish' won't be available to everyone if a server administrator forgets masking it in ACL. Make sure to add the command to your ACL under the proper group for it to be usefull (i.e <right name="command.killEveryone" access="true"></right>). This argument defaults to false if nothing is specified.
{{New feature|3|1.0|
*'''caseSensitive:''' Specifies if the command handler will ignore the case for this command name.
}}

</section>

<section name="Client" class="client" show="true">
<syntaxhighlight lang="lua">
bool addCommandHandler ( string commandName, function handlerFunction, [bool caseSensitive = true] )
</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 function that you want the command to trigger, which has to be defined before you add the handler. This function can take two parameters, playerSource and commandName, followed by as many parameters you expect after your command (see below). These are all optional.
===Optional Arguments===
{{OptionalArg}}
{{New feature|3|1.0|
*'''caseSensitive:''' Specifies if the command handler will ignore the case for this command name.
}}
</section>

====Handler function parameters====
These are the parameters for the handler function that is called when the command is used.
<section name="Server" class="server" show="true">
<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 4''' below.
</section>

<section name="Client" class="client" show="true">
<syntaxhighlight lang="lua"> string commandName, [string arg1, string arg2, ...] </syntaxhighlight>
* '''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 4''' below.
</section>

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

==Example==
<section name="Server" class="server" show="true">
'''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 )
-- 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 his chat box
outputChatBox ( "You got a red marker", playerSource )
end
end
-- Attach the 'consoleCreateMarker' function to the "createmarker" command
addCommandHandler ( "createmarker", consoleCreateMarker )
</syntaxhighlight>
</section>

<section name="Server" class="server" show="hide">
'''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 = getPedOccupiedVehicle ( 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
-- Attach the 'consoleSetVehicleColor' function to the "set_vehicle_color" command
addCommandHandler ( "set_vehicle_color", consoleSetVehicleColor )
</syntaxhighlight>
</section>

<section name="Server" class="server" show="hide">
'''Example 3:''' This example makes use of Lua's vararg expression to implement a ''check_parameters'' command to count the number of parameters passed, merge them all into a single string and output it. This is also shows you how you can use table.concat to merge all the passed arguments. This is particularly useful when you want to read in a sentence of text passed from the user.
<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
-- Get the number of arguments in the arg table (arg table is the same as: {...})
local parameterCount = #arg
-- 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( arg, ", " )
-- Output this parameter list to the player's chatbox
outputChatBox ( "Parameters passed: " .. stringWithAllParameters, playerSource )
end
end
-- Attach the 'consoleCheckParameters' function to the "check_parameters" command
addCommandHandler ( "check_parameters", consoleCheckParameters )
</syntaxhighlight>
</section>

<section name="Server" class="server" show="hide">
'''Example 4:''' This example shows using a single function to handle multiple command handlers. This isn't advised for general usage, as it makes code harder to understand, but where multiple command handlers share some logic, it can be a useful way of reducing duplicated code. Generally, it would be preferable to put this shared logic in a separate function instead, as this gives you more control over the flow.

<syntaxhighlight lang="lua">
-- make the function
function moneyCmd(player, cmd, amount)
if getElementData(player, "canUseMoneyFunctions") then -- the shared logic
if cmd == "givemoney" then
amount = tonumber(amount)
if amount then
givePlayerMoney(player, amount)
else
outputChatBox("[usage] /givemoney [amount]", player)
end
else if cmd == "takemoney" then
amount = tonumber(amount)
if amount then
takePlayerMoney(player, amount)
else
outputChatBox("[usage] /takemoney [amount]", player)
end
end
else
outputChatBox("You aren't able to use this command", player)
end
end

addCommandHandler("givemoney", moneyCmd);
addCommandHandler("takemoney", moneyCmd);
</syntaxhighlight>
</section>
<section name="Server" class="server" show="false">
'''Example 5:''' This example shows you how to create a function inside a commandHandler. This example creates an object, in this case a dildo, and attaches it to the player. Notice that unlike the other examples, we dont add 'addCommandHandler' after the function has been created. We create the function inside the commandHandler. This is not something you have to do, but it can save some work and space in the end in some cases.

<syntaxhighlight lang="lua">addCommandHandler("give_me_a_willy",function(player)
local x,y,z = getElementPosition(player)
local myObject = createObject(321,x,y,z)
setElementCollisionsEnabled(myObject ,false)
attachElements(myObject ,player,0.03,0.2,-0.45,0,0,90)
end)
</syntaxhighlight>
</section>
<section name="Client" class="client" show="true">
'''Example 1:''' This creates a GUI window and allows a player to change its alpha (transparency) value with a command. Note that, in a clientside script, the player using the command is not passed as a parameter to the handler function, since it is always the local player.

<syntaxhighlight lang="lua">--Create a window
myWindow = guiCreateWindow ( 0.30, 0.10, 0.5, 0.60, "GUI window title", true )

--Add a command handler to change the alpha of the GUI window. Usage example: 'alpha 0.15'
function changeAlpha ( commandName, alphaAmount )
-- All command parameters are strings, so we'll convert the value to a number first
alphaAmount = tonumber(alphaAmount)
guiSetAlpha ( myWindow, alphaAmount )
end
addCommandHandler ( "alpha", changeAlpha )
</syntaxhighlight>
</section>
<section name="Client" class="client" show="false">
'''Example 2:''' This creates a GUI window and allows a player to change its alpha (transparency) value with a command. Note that, in a clientside script, the player using the command is not passed as a parameter to the handler function, since it is always the local player.

<syntaxhighlight lang="lua">function escapeMe ( commandName, taskType )
local x, y, z = getElementPosition ( getLocalPlayer() ) --Get player's position
setElementPosition ( getLocalPlayer(), x+(math.random(-10,10)), y+(math.random(-10,10)), z+(math.random(1,15)) ) --Move a player randomly to a nearby location. X is current x + a number between -10, 10 and so on.
end
addCommandHandler ( "escape", escapeMe ) --When player types "/escape" in chatbox or "escape" in console
</syntaxhighlight>
</section>

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

AddCommandHandler

2011-11-30T17:15:32Z

Wafamde: /* Example */

__NOTOC__
{{Server client function}}
{{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. Use a name that describes your handler's purpose more specifically.}}
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.

For users, a command is in the format:

''commandName'' ''argument1'' ''argument2''

This can be triggered from the player's console or directly from the chat box by prefixing the message with a forward slash (''/''). For server side handlers, the server admin is also able to trigger these directly from the server's console in the same way as they are triggered from a player's console.

==Syntax==

<section name="Server" class="server" show="true">
<syntaxhighlight lang="lua">
bool addCommandHandler ( string commandName, function handlerFunction, [bool restricted = false, bool caseSensitive = true] )
</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 function that you want the command to trigger, which has to be defined before you add the handler. This function can take two parameters, playerSource and commandName, followed by as many parameters you expect after your command (see below). These are all optional.
===Optional Arguments===
{{OptionalArg}}
*'''restricted:''' Specify whether or not this command should be restricted by default. Use this on commands that should be inaccessible to everyone as default except special users specified in the ACL (Access Control List). This is to make sure admin commands such as ie. 'punish' won't be available to everyone if a server administrator forgets masking it in ACL. Make sure to add the command to your ACL under the proper group for it to be usefull (i.e <right name="command.killEveryone" access="true"></right>). This argument defaults to false if nothing is specified.
{{New feature|3|1.0|
*'''caseSensitive:''' Specifies if the command handler will ignore the case for this command name.
}}

</section>

<section name="Client" class="client" show="true">
<syntaxhighlight lang="lua">
bool addCommandHandler ( string commandName, function handlerFunction, [bool caseSensitive = true] )
</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 function that you want the command to trigger, which has to be defined before you add the handler. This function can take two parameters, playerSource and commandName, followed by as many parameters you expect after your command (see below). These are all optional.
===Optional Arguments===
{{OptionalArg}}
{{New feature|3|1.0|
*'''caseSensitive:''' Specifies if the command handler will ignore the case for this command name.
}}
</section>

====Handler function parameters====
These are the parameters for the handler function that is called when the command is used.
<section name="Server" class="server" show="true">
<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 4''' below.
</section>

<section name="Client" class="client" show="true">
<syntaxhighlight lang="lua"> string commandName, [string arg1, string arg2, ...] </syntaxhighlight>
* '''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 4''' below.
</section>

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

==Example==
<section name="Server" class="server" show="true">
'''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 )
-- 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 his chat box
outputChatBox ( "You got a red marker", playerSource )
end
end
-- Attach the 'consoleCreateMarker' function to the "createmarker" command
addCommandHandler ( "createmarker", consoleCreateMarker )
</syntaxhighlight>
</section>

<section name="Server" class="server" show="hide">
'''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 = getPedOccupiedVehicle ( 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
-- Attach the 'consoleSetVehicleColor' function to the "set_vehicle_color" command
addCommandHandler ( "set_vehicle_color", consoleSetVehicleColor )
</syntaxhighlight>
</section>

<section name="Server" class="server" show="hide">
'''Example 3:''' This example makes use of Lua's vararg expression to implement a ''check_parameters'' command to count the number of parameters passed, merge them all into a single string and output it. This is also shows you how you can use table.concat to merge all the passed arguments. This is particularly useful when you want to read in a sentence of text passed from the user.
<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
-- Get the number of arguments in the arg table (arg table is the same as: {...})
local parameterCount = #arg
-- 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( arg, ", " )
-- Output this parameter list to the player's chatbox
outputChatBox ( "Parameters passed: " .. stringWithAllParameters, playerSource )
end
end
-- Attach the 'consoleCheckParameters' function to the "check_parameters" command
addCommandHandler ( "check_parameters", consoleCheckParameters )
</syntaxhighlight>
</section>

<section name="Server" class="server" show="hide">
'''Example 4:''' This example shows using a single function to handle multiple command handlers. This isn't advised for general usage, as it makes code harder to understand, but where multiple command handlers share some logic, it can be a useful way of reducing duplicated code. Generally, it would be preferable to put this shared logic in a separate function instead, as this gives you more control over the flow.

<syntaxhighlight lang="lua">
-- make the function
function moneyCmd(player, cmd, amount)
if getElementData(player, "canUseMoneyFunctions") then -- the shared logic
if cmd == "givemoney" then
amount = tonumber(amount)
if amount then
givePlayerMoney(player, amount)
else
outputChatBox("[usage] /givemoney [amount]", player)
end
else if cmd == "takemoney" then
amount = tonumber(amount)
if amount then
takePlayerMoney(player, amount)
else
outputChatBox("[usage] /takemoney [amount]", player)
end
end
else
outputChatBox("You aren't able to use this command", player)
end
end

addCommandHandler("givemoney", moneyCmd);
addCommandHandler("takemoney", moneyCmd);
</syntaxhighlight>
</section>
<section name="Server" class="server" show="false">
'''Example 5:''' This example shows you how to create a function inside a commandHandler. This example creates an object, in this case a dildo, and attaches it to the player. Notice that unlike the other examples, we dont add 'addCommandHandler' after the function has been created. We create the function inside the commandHandler. This is not something you have to do, but it can save some work and space in the end in some cases.

<syntaxhighlight lang="lua">addCommandHandler("give_me_a_penis",function(player)
local x,y,z = getElementPosition(player)
local myObject = createObject(321,x,y,z)
setElementCollisionsEnabled(myObject ,false)
attachElements(myObject ,player,0.03,0.2,-0.45,0,0,90)
end)
</syntaxhighlight>
</section>
<section name="Client" class="client" show="true">
'''Example 1:''' This creates a GUI window and allows a player to change its alpha (transparency) value with a command. Note that, in a clientside script, the player using the command is not passed as a parameter to the handler function, since it is always the local player.

<syntaxhighlight lang="lua">--Create a window
myWindow = guiCreateWindow ( 0.30, 0.10, 0.5, 0.60, "GUI window title", true )

--Add a command handler to change the alpha of the GUI window. Usage example: 'alpha 0.15'
function changeAlpha ( commandName, alphaAmount )
-- All command parameters are strings, so we'll convert the value to a number first
alphaAmount = tonumber(alphaAmount)
guiSetAlpha ( myWindow, alphaAmount )
end
addCommandHandler ( "alpha", changeAlpha )
</syntaxhighlight>
</section>
<section name="Client" class="client" show="false">
'''Example 2:''' This creates a GUI window and allows a player to change its alpha (transparency) value with a command. Note that, in a clientside script, the player using the command is not passed as a parameter to the handler function, since it is always the local player.

<syntaxhighlight lang="lua">function escapeMe ( commandName, taskType )
local x, y, z = getElementPosition ( getLocalPlayer() ) --Get player's position
setElementPosition ( getLocalPlayer(), x+(math.random(-10,10)), y+(math.random(-10,10)), z+(math.random(1,15)) ) --Move a player randomly to a nearby location. X is current x + a number between -10, 10 and so on.
end
addCommandHandler ( "escape", escapeMe ) --When player types "/escape" in chatbox or "escape" in console
</syntaxhighlight>
</section>

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