Manual Review Required

Please finish this page using the corresponding Old Wiki article. Go to Contribution guidelines for more information.

---

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.

Note

You can't use "check", "list", "test" and "help" as a command name.

Important

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.

Syntax

bool addCommandHandler ( )

Returns

• bool: value

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

Code Examples

Example 1 Example 2 Example 3 Example 4

client

Example 1:This example warps the local player to a random nearby location (useful for when a player gets stuck somewhere).

function escapeMe ( commandName )
  local x, y, z = getElementPosition ( localPlayer ) --Get player's position
  setElementPosition ( localPlayer, 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

server

Example 1:This example defines a command handler for the commandcreatemarker. This will create a red marker at the position of the player player who uses it.

-- 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 his chat box
    outputChatBox ( "You got a red marker", playerSource )
  end
end
-- Attach the 'consoleCreateMarker' function to the "createmarker" command
addCommandHandler ( "createmarker", consoleCreateMarker )

server

Example 2:This example makes use of Lua's vararg expression to implement acheck_parameterscommand 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.

-- 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
    local arg = {...}
    -- 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 )

server

Example 3: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.

-- make the function
function moneyCmd(player, commandName, amount)
    if getElementData(player, "canUseMoneyFunctions") then -- the shared logic
        if commandName == "givemoney" then
            amount  = tonumber(amount)
            if amount then
                givePlayerMoney(player, amount)
            else
                outputChatBox("[usage] /givemoney [amount]", player)
            end
        else if commandName == "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);

See Also

Input Functions

• addCommandHandler
• bindKey
• executeCommandHandler
• getAnalogControlState
• getBoundKeys
• getCommandHandlers
• getCommandsBoundToKey
• getFunctionsBoundToKey
• getKeyBoundToCommand
• getKeyBoundToFunction
• getKeyState
• isCapsLockEnabled
• isControlEnabled
• isKeyBound
• removeCommandHandler
• setAnalogControlState
• toggleAllControls
• toggleControl
• unbindKey

Input Events

• onClientCharacter
• onClientClick
• onClientCursorMove
• onClientDoubleClick
• onClientGUIAccepted
• onClientGUIBlur
• onClientGUIChanged
• onClientGUIClick
• onClientGUIComboBoxAccepted
• onClientGUIDoubleClick
• onClientGUIFocus
• onClientGUIMouseDown
• onClientGUIMouseUp
• onClientGUIMove
• onClientGUIScroll
• onClientGUISize
• onClientGUITabSwitched
• onClientKey
• onClientMouseEnter
• onClientMouseLeave
• onClientMouseMove
• onClientMouseWheel
• onClientPaste

Reference

• Scripting Functions