Comm

This is a global built in package that provides interfaces to program communications.

Message Data Structure

Chat message objects are passed as LUA table structures (described below). The fields in this table are:

• text: String. The text content of the message

• sender: String. The string identifying the sender of the message

• mood: String. Set only if a mood is specified, containing the contents of the mood string

• font: String. Set only if the message uses a font different from the default setting, containing the font resource name

• icon: String or table of strings. Set only if the message contains one or more icon resource names to be drawn at the beginning of the message.

• shortcuts: Table of shortcut tables. Each shortcut table contains description, class and recordname string fields. Set only if the message should display one or more shortcut links to be drawn after the icons and before the text of the message.

• secret: Boolean. Specifies whether this message is secret. (Only valid on host)

• type: String. The type of the message, as defined by the ruleset. (if any)

• mode: String. Set only if you want to specify a chat mode. (chat, system, ooc, emote, ...) The frames and fonts associated with each mode can be customized in the XML.

• dice: Table. Set only if you want dice results to be shown in the message. This parameter should be a table of die result objects. Each die result object is an array with a "type" and a "result" field. The "type" field is a string matching the die type defined in the XML ("d4", "d6", ...) and controls the die icon shown in the chat message. The "result" field is a number representing the die result to display on the die icon.

• diemodifier: Number. Set only if you want a numerical modifier to be shown with dice results. This parameter is only used if dice is defined, even if it is empty.

• dicesecret: Boolean. Same as secret field, kept for backward compatibility.

• dicedisplay: Number. Set only if you want a dice summary to be shown with dice results. Valid dice summary values are 0 = none, 1 = total, 2 = negative, 3 = double, and 4 = half. This parameter is only used if dice is defined, even if it is empty.

addChatMessage

Add a new entry to the chat window. The message is not delivered to other users, and chatwindow.onReceiveMessage event is not fired.

Parameters

messagedata   (table)   
A table containing information about the message.

addKeyedEventHandler

Add a keyed event handler callback function. If the key provided in the registration matches the key for the event, then the callback function will be called. If the empty key is provided in the registration (““), then the callback function will be called for all events of that type, regardless of key.

The handler function should have the following signature: [function name]([parameters]). The parameters will vary depending on the event the function is attached to, as follows.

• [onDiceLanded] parameters = (dragdata)

  • This event is fired then a dice roll has completed. The key will be the dragdata.getType() value.

• [onDiceLaunched] parameters = (dragdata)

  • This event is fired then a dice roll has been initiated. The key will be the dragdata.getType() value.

• [onReceiveMessage] parameters = (messagedata)

  • This event is fired when a chat message is received. The key will be the messagedata.type variable.

• [onReceiveOOBMessage] parameters = (tabledata)

  • This event is fired when an OOB message is received. The key will be the “type” value of the OOB message.

Parameters

event   (string)   
The event to be captured (see function details)

key   (string)
The key to be used to determine whether to trigger event callback function.

callback   (function)   
The function to be called when the event triggers

clearChat

This function will clear the chat window.

deliverChatMessage

Add a new entry to the chat window, and also delivers to others.

If client, then the message will always be distributed to all connected clients (regardless of recipients parameter).

If host, then the message will be distributed to the users specified in the recipients parameter, or to all clients if recipients not specified.

Parameters

messagedata   (table)   
A table containing information about the message. See the Comm package for details.

recipients   (string (or table))   [optional]
A string (or integer indexed table of strings) containing the user name(s) of the desired recipient(s)

deliverOOBMessage

Deliver a custom LUA table object to all connected clients.

If client, then the OOB message will always be distributed to all connected clients (regardless of recipients parameter).

If host, then the OOB message will be distributed to the users specified in the recipients parameter, or to all clients if recipients not specified.

Parameters

tabledata   (table)   
A LUA table object.

recipients   (string (or table))   [optional]
A string (or integer indexed table of strings) containing the user name(s) of the desired recipient(s)

registerSlashHandler

This function registers a handler function that will be called if the specified slash command is requested.

The handler function should have the following signature: [function name](sCommands, sParams).

* The first parameter will be the slash command entered, in case the same callback function is used for multiple commands.

* The second parameter will be the parameters passed to the slash command, exactly as typed by the user.

Parameters

command   (string)   
The slash command to implement.

callback   (function)   
The LUA function that will be called when the specified slash command is requested.

helptext (string or table)

The string to append to the command in the default help output to indicate usage. If a table is used, it is assumed to be a numerically-indexed table of strings, and multiple entries will be added to the default help output.

removeKeyedEventHandler

Remove a keyed event handler callback function.

Parameters should be the same as the event handler registration performed by addKeyedEventHandler API.

Parameters

event   (string)   
The event to be removed (see addKeyedEventHandler API)

key   (string)
The key to be removed

callback   (function)
The event handling function to be removed

setChatMood

This function is set the chat mood text for all speech (if host) or for the active identity (if client).

Parameters

message   (string)   
The text message to display as mood text.

throwDice

This function is used to trigger a roll of the dice without direct UI actions. Technically, the roll is performed by creating a dragdata object and triggering the action of the dice.

Parameters

dragtype   (string)   
The type used for the dragdata object. A value of "dice" performs a normal die roll.

dice   (table)   
An integer indexed list of die types to add to the roll, similar in function to dragdata.dicelist.

modifier   (number)   
The modifier applied to the roll (see dragdata.setNumberData).

description   (string)   
The description string applied to the roll (see dragdata.setDescription).

customdata   (any)   [optional]
A custom value useful for e.g. storing special information about the roll required when the results are displayed (see dragdata.setCustomData).

throwDice

An alternate version of the function used to trigger a roll of the dice without direct UI actions. Technically, the roll is performed by creating a dragdata object and triggering the action of the dice.

Parameters

data   (table)   
See the dragdata object for a description of the table (same as dragdata.setData)

vote

This function is used to initiate a voting block in the chat window.

Parameters

message   (string)   
The text message to display with the voting box.