This is a global built in package that provides information about and methods for handling the data for the
currently active identities and users. The package also provides handlers for user and identity activation and
state monitoring.

Interface

createLocalIdentity

function createLocalIdentity(
)

Creates a new entry into the local character list. The return value is a databasenode object containing the root node of the
new character's data.

Return values

(databasenode)

A databasenode object identifying the new character and containing the character's data

getActiveIdentities

function getActiveIdentities(
[username]
)

Get the list of active identity names for the current user (if client) or the specified user (if host).

Parameters

username (string) [optional]

The name of the user for which active identities is being queried (Required on host call).

Return values

(table)

An integer indexed table containing string values representing the identities in use by the user

An integer indexed table containing string values representing the identities in use

getCampaignName

function getCampaignName(
)

Returns the name of the currently active campaign.

Return values

(string)

The name of the active campaign

getCurrentIdentity

function getCurrentIdentity(
[username]
)

This function returns the identity identifier of the currently active identity. By default, the identity is queried for the active user.
If running as the host, the parameter may be specified to indicate a username of a connected client whose current identity selection will be
returned.

Parameters

username (string) [optional]

The username of the client whose current identity is being queried

Return values

(string)

The identity identifier of the currently active identity

getCurrentIdentityColors

function getCurrentIdentityColors(
)

This function returns the colors used for the current identity. The function returns the color used for the die base and the pointers painted
when this identity is active, and whether black or white text is used on the dice.

Return values

(string)

A string containing the color for the die base and pointers, in the format "RRGGBB" where the color components are
hexadecimal digits representing color channel values in the range 0 .. 255

(boolean)

A value of true will render dice text as black, a value of false will use white color

getIdentityColor

function getIdentityColor(
identity
)

This function returns the currently active color selection for the specified identity. The color will be given as a string value in
the format "AARRGGBB" where the components are hexadecimal digits representing the values (in the range 0 .. 255) for alpha (transparency),
red, green and blue color channels, respectively.

Parameters

identity (string)

The identifier of the identity whose color is being queried

Return values

(string)

The color for the queried identity in the form "AARRGGBB"

getIdentityLabel

function getIdentityLabel(
[identityname]
)

Fetch the string used as the label for the specified identity. If the identity name is not specified, the label for the current
identity will be retrieved.

Parameters

identityname (string) [optional]

The identity identifier for the identity whose label is being queried

Return values

(string)

The label of the identity, or nil if no identity is active or running as the host

getIdentityOwner

function getIdentityOwner(
identityname
)

Fetch the name of the user that owns the specified identity.

Parameters

identityname (string)

The name of the identity for which the owner is being queried

Return values

(string)

The name of the user who owns the identity, or nil if the identity is not owned by any user

getLocalIdentities

function getLocalIdentities(
)

Lists the currently available locally saved characters that can be used as identities in the running connected session, or in the
active local mode session.

If the application is running in local mode, and a cached campaign has been selected, this list also includes characters used in the
remote session. These characters' data cannot be modified. When connected to a running session, these identities are not included.

Each local mode character entry consists of a table with two or three values. The dbnode value contains a
databasenode object reference identifying the database node containing the information for the character. The session
value contains a string identifying the session the character is associated with, and is empty for characters that aren't used in remote
campaigns. The id value is the identifier of the identity, and is only present for characters used in remote campaigns.

Return values

(table)

An integer indexed table containing entries with information about locally available characters.

A string identifying the currently set portrait. This value should only be used to pass to other portrait elements using
functions such as portraitselectioncontrol.setFile

getOwnedIdentities

function getOwnedIdentities(
)

Get the list of identity names owned by this client.

Return values

(table)

An integer indexed table containing string values representing the identities in use

getPortraitDirectoryList

function getPortraitDirectoryList(
)

This function fetches a list of the directories in the portraits subfolder found in the current campaign directory. If a relative path is defined, then the relative path will be appended to the campaign portraits directory path before retrieveing directories. The contents of the returned list should not be used directly, but rather can be used to populate controls in a portrait selection window.

Return values

(table)

An integer indexed list of strings containing the directories found

getPortraitFileList

function getPortraitFileList(
)

This function fetches a list of the portrait files found in the locally installed portrait folder. The contents of the returned list
should not be used directly, but rather can be used to populate controls in a portrait selection window.

Return values

(table)

An integer indexed list of strings containing the filenames of the portrait images found

getRemoteIdentities

function getRemoteIdentities(
node, labelnode, resultcallback
)

Lists the identities available for the current user on the remote host. The list will include unowned identities and identities
owned by the user with the current username.

The identity list is populated using the session data base, and will include all the child nodes of the node identified by the
node parameter. The labelnode parameter will be used to fetch a child node of the identity node, and will contain the text used as
the label for the identity.

Parameters

node (string)

A global database identifier identifying the node in the session database from where the list of identities should be
retrieved

labelnode (string)

The name of a child node under the identity node containing the string value to use as a label for the identity

resultcallback (function)

A callback function that will be called for each matching result delivered by the host. The function will receive two string value
parameters representing the identity identifier and the label for the identity, respectively.

getRulesetName

function getRulesetName(
)

Returns the name of the currently active ruleset.

Return values

(string)

The name of the active ruleset

getUsername

function getUsername(
)

Returns the local user's network username.

Return values

(string)

The username string

isHost

function isHost(
)

Check if the currently running application instance is acting as a session host.

Return values

(boolean)

Returns true if running as the host and false if running as a client.
Always returns false in local mode.

isLocal

function isLocal(
)

Check if the currently running application instance is running in local mode.

Return values

(boolean)

Returns true if running in local mode and false otherwise

isOwnedIdentity

function isOwnedIdentity(
identityname, [username]
)

This function can be used to check if an identity is owned by the current user (on the client) or held by a specific user (on the host).

Parameters

identityname (string)

The identity whose status is being queried

username (string) [optional]

The username whose ownership is being queried. Only used when calling from the host machine.

Return values

(boolean)

If true, the user owns the identity, otherwise false.

kick

function kick(
username
)

Kicks the specified user from the session, and release all their identities.

Registered functions on this handler are called when the state of an activated identity changes.

If the value of the statename parameter is "current", the event indicates that the user has changed his currently active identity. The event is
triggered once for each of the users activated identities, the state parameter being true for the newly activated
identity and false otherwise.

If the value of the statename parameter is "label", the event indicates that the specified identity's label string has been changed. In this case,
the state parameter is a string containing the value of the new label string.

If the value of the statename parameter is "color", the identity's color has changed. The state parameter should be ignored, and the
getIdentityColor function used to update the color setting's display.

Parameters

identityname (string)

The identifier of the identity that is the target of the operation triggering the event

username (string)

The username of the user triggering the event

statename (string)

A string representing the identity state flag whose value is changing. See above for details.

state (any)

The new value for the user state flag. See above for details.

onLogin

handler
function onLogin(
username, activated
)

Registered functions on this handler are called whenever a user logs in to or out of the running session.

Parameters

username (string)

The username of the connecting/disconnecting client

activated (boolean)

This value is true if the user is logging on, or false if the user is logging off

onUserStateChange

handler
function onUserStateChange(
username, statename, state
)

Registered functions on this handler are called when the state of a connected user changes.

Currently, this event notifies the user interface of changes in the user's input activity. The possible values for the statename paramter are "active", "typing" and "idle".
For these events, the state variable is always true.

Parameters

username (string)

The username of the client triggering the event

statename (string)

A string representing the user state flag whose value is changing. See above for details.

state (boolean)

The new value for the user state flag. See above for details.

releaseIdentity

function releaseIdentity(
identityname
)

Release the specified identity, deactivating it from current use.

Parameters

identityname (string)

The name of the identity to release

requestIdentity

function requestIdentity(
name, local, resultcallback
)

Send a request to activate the given identity to the host. The request may fail if the identity is already in use or
owned by another user.

Parameters

name (string)

The identity identifier of the identity requested

local (boolean)

This value should be true if the identity being activated is a local character.

resultcallback (function)

A function that will be called when the request is complete. The function will receive three parameters. The first
parameter is a boolean value indicating whether the request was successful (true) or not (false).
The second parameter is a string containing the identifier of the requested identity. The third parameter is a boolean value
containing the value given as the local parameter to the requestIdentity call.

ringBell

function ringBell(
username
)

Rings a bell on the client computer, specified by user name parameter. If no parameter is supplied, then the bell will be rung on all clients.

Parameters

username (string)

Optional. The user name of the client where the bell is to be rung.

setCurrentIdentity

function setCurrentIdentity(
identityname
)

This function changes the active identity for the current client. If the identity is used by another client or not owned by
the current user, the function will fail.

Parameters

identityname (string)

The identity identifier of the identity to activate

setCurrentIdentityColors

function setCurrentIdentityColors(
color, blacktext
)

This function sets the colors used for the current identity. The function sets the color used for the die base and the pointers painted
when this identity is active, and determines whether to use black or white text on the dice.

Parameters

color (string)

A string containing the color for the die base and pointers, in the format "RRGGBB" where the color components are
hexadecimal digits representing color channel values in the range 0 .. 255. If alpha is zero or not defined, FF is assumed.

blacktext (boolean)

A value of true will render dice text as black, a value of false will use white color

A string identifying the currently set portrait. This value should only be used to pass to other portrait elements using
functions such as portraitselectioncontrol.setFile

setPortrait

function setPortrait(
identity, portraitfile
)

This function changes the portrait of the specified identity to the one represented by the given portrait file. If used in local mode (i.e. Manage Characters), then only a databasenode may be used for the first parameter.

Parameters

identity (string (or databasenode))

The node name (not full path) of the character identity whose portrait is being changed, or a databasenode object representing the target identity.