Conversation Handler Functions

How to define a conversation handler function....

Syntax

The basic syntax is identical to that of a Command Handler Function:

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

Parameters

Parameter	Type	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. Will always be converted to lowercase.	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). If you want the full message as a single string, you can get it from: `cdo.message`	0.1
cdo	Conversation Descriptor Object	The conversation object associated with the player.	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

When the user issues the "help" command, a conversation will be started. The conversation re-uses the same helpHandler function, which will provide more help if the user now types 'foo' or 'bar'...

Start conversation when user issues "help" command

var helpHandler = function helpHandler(command, player, message, cdo) {
  switch (command) {
	case "help": {
      // did user already state which help topic?
      if (message[1] == "foo") return helpHandler("foo", player, message);
      if (message[1] == "bar") return helpHandler("bar", player, message);
      // start conversation to find out what topic they want help with...
      chat.start(player, helpHandler); // activate conversation mode
      return [
        "What do you want help with?",
        "Reply '.foo' or '.bar', or '.stop' to abort."
      ];
    }
    case "foo" : {
      chat.stop(player); // chat returns to command mode
      return "some help for foo";
    }
    case "bar" : {
      chat.stop(player); // chat returns to command mode
      return "some help for bar";
    }
    case "stop": {
      chat.stop(player); // chat returns to command mode
      return;
    }
    default    : {
      chat.extend(player); // give user another 15 seconds to reply
      return [
        "What do you want help with?",
        "Reply '.foo' or '.bar', or '.stop' to abort."
      ];
    }
  }
}
 
chat.on("help", helpHandler);

Availability BETA

Requires:

Warzone v3.2 or above
Chat API

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.

EggPlant AI