Command Handler Functions

How to define a command handler function....

Syntax

var myHandler = function myHandler(command, player, message) {
	// your code here
 
	// return a string or array of strings
	return "Command was: "+command;
}

Parameters

Parameter

Type

Mandatory

Notes

Chat Ver

command

String

The command that was issued.

You can create a single handler function and use it as the handler for multiple chat commands, switching internally on the command name.

0.1

player

Number

The ID of the player that issued the command.

This is particularly useful if you want to start a chat conversation with that player in response to the command they just issued.

0.1

message

Array of String

An array containing each word in the player's message.

The string at message[0] will always be the command name (same as command parameter).

0.1

Return Values

Value	Type	Notes	Chat Ver
<string>	String	A single line chat message to send back to the player.	0.1
<array>	Array of String	A multi-line chat message to send back to the player.	0.1
`undefined`	Undefined	If your handler function returns nothing, no message will be sent back to the player.	0.1
<error>	Error	If an exception is thrown, the chat API will convert it in to a single line message and send back to the player.	0.1

Example

Single command, with different output based on second keyword

var helpHandler = function helpHandler(command, player, message) {
  // command == message[0] == "help"
  // message[1] == second keyword (eg. 'foo' if user sent '.help foo')
  switch (message[1]) {
    case "foo": return "some help for foo";
    case "bar": return "some help for bar";
    default   : return "Type '.help <whatever>' where <whatever> can be either 'foo' or 'bar'";
  }
}
 
registerChatCommand("help", helpHandler);
 
/* user can now send commands such as:
 
.help = Type '.help <whatever>' where <whatever> can be either 'foo' or 'bar'
.help foo = some help for foo
.help bar = some help for bar
*/

Single handler for multiple commands

var multiHandler = function multiHandler(command, player, message) {
  switch (command) {
    case "foo": return "your command: foo";
    case "bar": return "your command: bar";
    default   : return "your command: "+command+" (which I don't understand)";
  }
}
 
registerChatCommand("foo", multiHnadler); // .foo = your command: foo
registerChatCommand("bar", multiHandler); // .bar = your command: bar
registerChatCommand("moo", multiHandler); // .moo = your command: moo (which I don't understand)

Availability

Requires:

Warzone v3.2 or above
Util API v0.9 or above
Diag API v0.1 or above

Chat API

Topics:

Chat API Diagnostics — The Chat API provides the following diagnostic routines...
Conversation Descriptor Object — Each player is assigned a Conversation Descriptor Object that defines the current state of their chat conversation...
Conversation Mode — Quick start guide for making and using conversations...
- chat.isActive() — Determine conversation state for a specific player.
- chat.get() — Get the object associated with a multi-message conversation with a specific player.
- chat.stop() — Stop a conversation with a specific player.
- chat.extend() — Extend the "Time to Live" of the most recent conversation with a player.
- Conversation Handler Functions — How to define a conversation handler function....
- chat.start() — Start a multi-message conversation with a player.
Command Mode — Quick start guide for creating and using commands...
- Command Handler Functions — How to define a command handler function....
- chat.on() — Define a chat command and it's handler function.