WoW:Creating a slash command

Reference e
AddOns WoW API Widget API XML UI Event API WoW Lua Macro API CVars Battle.net HOWTOs Snippets UI tech Categories

→ HOWTOs

← HOWTOs

Slash commands allow the player to type commands into the chat window to interact with add-ons. This tutorial describes the necessary steps to add slash commands to your addon.

A fast example:

SLASH_TEST1 = "/test1"
SLASH_TEST2 = "/addontest1"
SlashCmdList["TEST"] = function(msg)
   print("Hello World!")
end 

This assigns a handler function to 'SlashCmdList["TEST"]', and creates 'SLASH_TEST1' and 'SLASH_TEST2' global variables, with the actual slash commands of '/test1' and '/addontest1'. WoW processes the 'SlashCmdList' and uses the key of "TEST" to find the global variable 'SLASH_TEST1', so those names must match and not conflict with another add-on or WoW UI slash key name.

WoW will then use the SlashCmdList 'TEST' key to find consecutive 'SLASH_TESTx' globals by iterating 'SLASH_TEST1', 'SLASH_TEST2', an so on until the next numbered global is not found. So the appended numbers must be consecutive and not have a gap. All of the 'SLASH_TESTx' slash commands will now execute the same handler.

When a user types a command starting with "/test1" or "/addontest1", WoW will run the Lua function assigned to SlashCmdList["TEST"], passing the command string without "/test1 " to the function as 'msg'.

Background

Slash command handlers are typically invoked by Blizzard's FrameXML code handling the player's chat input; therefore, an addon offering a slash command must register the command by placing certain values in a location where the chat input handling code looks for them.

An addon must create a function that would handle the slash command (possibly parsing the argument string passed to it), and place it into the SlashCmdList table. Additionally, an addon must declare which slash commands it wishes to bind to its handler function.

Strategy

1. Pick a unique identifier for the slash command: i.e. MYADDON

   A common convention is ADDONNAME if you only have one slash command, or ADDONNAME_COMMANDNAME if you have multiple (where ADDONNAME is the name of your addon).

2. Decide which slash commands you want to respond to: i.e. /myadd.

   You can select multiple alternatives for the same command -- allowing shorter or longer command names to be used in case of conflicts.

3. Assign your selected slash commands to SLASH_MYADDON1, SLASH_MYADDON2, etc global variables.
4. Write a slash command handler function (taking (msg, editbox) as arguments), and place assign it to SlashCmdList["MYADDON"].

Here is a simple example that can be placed anywhere in a Lua file:

-- 1. Pick HELLOWORLD as the unique identifier.
-- 2. Pick /hiw and /hellow as slash commands (/hi and /hello are actual emotes)
SLASH_HELLOWORLD1, SLASH_HELLOWORLD2 = '/hiw', '/hellow'; -- 3.
function SlashCmdList.HELLOWORLD(msg, editbox) -- 4.
 print("Hello, World!");
end

Parsing Arguments

If the user types '/yourcmd someargs' into chat, the function handling '/yourcmd' is passed 'someargs' as the first argument we have been naming 'msg', with the second argument as the chat edit box widget. Your handler function can then choose to act on that argument string. For simple slash commands, comparisons to pre-determined strings may be sufficient. Suppose we wanted to modify the "Hello, World!" example above to display a different string if the command was passed an argument, say "/hiw bye".

local function MyAddonCommands(msg, editbox)
  if msg == 'bye' then
    print('Goodbye, World!')
  else
    print("Hello, World!")
  end
end

SLASH_HELLOWORLD1, SLASH_HELLOWORLD2 = '/hiw', '/hellow'

SlashCmdList["HELLOWORLD"] = MyAddonCommands   -- add /hiw and /hellow to command list

Here is a more complex slash command example that is able to process arguments for commands that uses Lua Pattern matching to parse the arguments string:

local function MyAddonCommands(msg, editbox)
  -- pattern matching that skips leading whitespace and whitespace between cmd and args
  -- any whitespace at end of args is retained
  local _, _, cmd, args = string.find(msg, "%s?(%w+)%s?(.*)")
   
  if cmd == "add" and args ~= "" then
    print("adding " .. args)
    -- Handle adding of the contents of rest... to something.
  elseif cmd == "remove" and args ~= "" then
    print("removing " .. args)
    -- Handle removing of the contents of rest... to something.   
  else
    -- If not handled above, display some sort of help message
    print("Syntax: /hellow (add|remove) someIdentifier");
  end
end

SLASH_HELLOWORLD1, SLASH_HELLOWORLD2 = '/hiw', '/hellow'

SlashCmdList["HELLOWORLD"] = MyAddonCommands   -- add /hiw and /hellow to command list

Notes

• Default UI commands often have precedence over addon-created slash commands. There is no defined precedence order for addon-created commands, so conflicts caused by multiple addons attempting to use the same slash command will resolve non-deterministically.
  • If the unique command identifier (the key in SlashCmdList) conflicts between multiple addons, the addon that executes the assignment last will own the slash command.
• Command identifiers are generally all caps, with underscores if necessary. These can also contain lowercase characters.
  • The actual 'SLASH_<CommandId><Number>' values should be localizable if you plan on your addon being translated, but the command ID will remain the same.
• Be prudent about how many aliases you make for your command, and try and pick something that's unlikely to collide with someone else's (including Blizzard's!)
• There's a second parameter passed to the slash command handler functions that is rarely used. It is the chat frame edit box frame that the slash command originated from.

SLASH_BLAH1 = "/blah"
SlashCmdList["BLAH"] = function(msg, editBox)
    -- change the text on the editBox.
    editBox:Show()
    editBox:SetText("Blah blah blah!")
end

• If you want to set your slash command handler function to a method of an object, you will need to encapsulate the call to it inside a dummy function.

function SomeObject:SlashHandler(message, editbox)
  -- do stuff
end
SLASH_BLAH1 = "/blah"
SlashCmdList["BLAH"] = function(message, editbox) SomeObject:SlashHandler(message, editbox) end