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. Set only if the message contains an icon drawn at the beginning of the message, containing the icon resource
name for the desired icon
-
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. Set only if you want a dice results to be hidden from clients. This parameter is only used if dice is defined, even if it is empty. Also, this parameter is only valid on the host.
-
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.
Interface
addChatMessage
function addChatMessage(
messagedata
)
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. See the
Comm package for details.
clearChat
function clearChat(
)
This function will clear the chat window.
deliverChatMessage
function deliverChatMessage(
messagedata, [recipients]
)
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.
(string (or table)) [optional]
A string (or integer indexed table of strings) containing the user name(s) of the desired recipient(s)
deliverOOBMessage
function deliverOOBMessage(
tabledata, [recipients]
)
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)
onReceiveOOBMessage
handler
function onReceiveOOBMessage(
tabledata
)
Any registered callback handlers will be called when an OOB message is received, and the custom LUA table object containing the message will be passed as an input parameter.
Parameters
tabledata (table)
A LUA table object.
registerSlashHandler
function registerSlashHandler(
command, callback
)
This function registers a handler function that will be called if the specified slash command is requested.
Parameters
command (string)
The slash command to implement.
callback (function)
The LUA function that will be called when the specified slash command is requested.
setChatMood
function setChatMood(
message
)
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
function throwDice(
dragtype, dice, modifier, description, [customdata]
)
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.
(table)
An integer indexed list of die types to add to the roll, similar in function to
dragdata.setDieList.
(number)
description (string)
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).
vote
function vote(
message
)
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.
