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
getAllActiveIdentities
function getAllActiveIdentities(
)
Get the list of identity names in use by all connected clients.
Return values
(table)
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 username of the user that owns the specified identity.
Parameters
identityname (string)
The identity identifier for the identity whose owner is being queried
Return values
(string)
The username of the owner of 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.
getLocalIdentityPortrait
function getLocalIdentityPortrait(
identityroot
)
This function fetches the portrait set for a local character. The character is identified by a databasenode reference obtained from
User.getLocalIdentities.
Parameters
identityroot (databasenode)
Return values
(string)
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(
[username]
)
Returns a list of all identities activated by the specified user. If no username is given, returns the identities
for the current user.
Parameters
username (string) [optional]
The user whose identity list is being queried
Return values
(table)
An integer indexed table containing string values representing the identities in use
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 currently held by the specified user. If no username is given,
checks whether the current user holds the given identity.
Parameters
identityname (string)
The identity whose status is being queried
username (string) [optional]
The username whose ownership is being queried
Return values
(boolean)
If true, the user owns the identity, otherwise false.
onIdentityActivation
handler
function onIdentityActivation(
username, identityname, activated
)
Registered functions on this handler are called when a user activates or deactivates an identity.
Parameters
username (string)
The username of the user triggering the event
identityname (string)
The identifier of the identity being activated or deactivated
activated (boolean)
A value of true if the identity is being activated, or false otherwise
onIdentityStateChange
handler
function onIdentityStateChange(
identityname, username, statename, state
)
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.
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
blacktext (boolean)
A value of true will render dice text as black, a value of false will use white color
setLocalIdentityPortrait
function setLocalIdentityPortrait(
identityroot
)
This function sets the portrait for a local character. The character is identified by a databasenode reference obtained from
User.getLocalIdentities or User.createLocalIdentity.
Parameters
identityroot (databasenode)
Return values
(string)
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.
Parameters
identity (string)
The identifier of the identity whose portrait is being changed
portraitfile (string)
The file identifying the portrait to use
