Content Comparison

...

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.

...

addEventHandler

...

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

getActiveUsers

function getActiveUsers()

Get the list of users names for all connected clients.

Return values

(table)
An integer indexed table containing string values representing the connected users

function addEventHandler( event, callback )

Add a general event handler callback function.

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.

• [onIdentityActivation] parameters = (sCharID, sUserName, bValue)

  • This event is fired when a Character record identity is activated/deactivated by a player client

• [onIdentityStateChange] parameters = (sCharID, sUserName, sStateKey, vStateValue)

  • This event is fired when a Character record identity state is changed

    • [color] = Color value in ARGB hexadecimal format

    • [current] = character ID is set as current character (true) or removed as current (false).

• [onLogin] parameters = (sUserName, bValue)

  • This event is fired when a player logs in or logs out of a session.

• [onUserStateChange] parameters = (sUserName, sStateKey)

  • This event is fired when a player state is changed

    • [idle] = player idle state triggers

    • [typing] = player is typing

    • [active] = player is not idle nor typing

Parameters

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

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

createLocalIdentity

function getAllActiveIdentitiescreateLocalIdentity()

Get the list of identity names in use by all connected clientsCreates 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

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

...

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

getActiveIdentities

function getCampaignNamegetActiveIdentities([username])

Returns Get the name of the currently active campaign.

Return values

(string)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 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

...

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

getActiveUsers

function getActiveUsers()

Get the list of users names for all connected clients.

Return values

(table)
An integer indexed table containing string values representing the connected users

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 getCurrentIdentityColorsgetCampaignName()

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 diceReturns the name of the currently active campaign.

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

...

The name of the active campaign

getCurrentIdentity

function getIdentityColorgetCurrentIdentity(identity[username])

This function returns the identity identifier of the currently active color selection identity. By default, the identity is queried 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

identityactive 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 identifier username of the client whose current identity whose color is being queried

Return values

(string)
The color for the queried identity in the form "AARRGGBB"

...

identity identifier of the currently active identity

getCurrentIdentityColors

function getIdentityLabelgetCurrentIdentityColors([identityname])

Fetch This function returns the string colors used as the label for the specified current 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 queriedThe 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)
The label of the identity, or nil if no identity is active or running as the host

...

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 getIdentityOwnergetIdentityColor(identitynameidentity)

Fetch the name of the user that owns This function returns the currently active color selection for 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

...

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 getLocalIdentitiesgetIdentityLabel([identityname])

Lists the currently available locally saved characters that can be Fetch the string 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.

...

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 getLocalIdentityPortraitgetIdentityOwner(identityrootidentityname)

This function fetches the portrait set for a local character. The character is identified by a databasenode reference obtained from User.getLocalIdentitiesFetch the name of the user that owns the specified identity.

Parameters

identityrootidentityname   (databasenodestring)   
The name of the identity for which the owner is being queried

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()

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 retrieving 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

...

)
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.

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 getPortraitFileListgetOwnedIdentities()

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 windowGet the list of identity names owned by this client.

Return values

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

...

table containing string values representing the identities in use

getPortraitDirectoryList

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 chat name. If you need the network user name, then use Session.UserName instead. This is a legacy function from FG Classic used to support legacy functionality.

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.

Warning

This function will only work if running as a host.

Parameters

username   (string)   
The user name to kick

...

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 retrieving 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 onIdentityActivationgetRemoteIdentities(identitynamenode, usernamelabelnode, activatedresultcallback)

Registered functions on this handler are called when a user activates or deactivates an identity.

Parameters

identityname   (string)   
The identifier of the identity being activated or deactivated

username   (string)   
The username of the user triggering the event

activated   (boolean)   
A value of true if the identity is being activated, or false otherwise

onIdentityStateChange

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.

...

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 chat name. If you need the network user name, then use Session.UserName instead. This is a legacy function from FG Classic used to support legacy functionality.

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.

isOwnedIdentity

function onLoginisOwnedIdentity(usernameidentityname, activated)

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

...

[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 of the connecting/disconnecting clientactivated   whose ownership is being queried. Only used when calling from the host machine.

Return values

(boolean)   
This value is If true if , the user is logging on, or false if the user is logging off

...

owns the identity, otherwise false.

kick

function onUserStateChange(username, statename, state)

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

...

 kick(username)

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

Warning

This function will only work if running as a host.

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 releaseuser name to kick

releaseIdentity

function releaseIdentity(identityname)

Release the specified identity, deactivating it from current use.

Parameters

identityname   (string)   
The name of the identity to release

removeEventHandler

function removeEventHandler( event, callback )

Remove a general event handler callback function.

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

Parameters

event   (string)   
The event to be captured (see addEventHandler API)

callback   (function)
The event handling function to be removed

requestIdentity

function requestIdentity(identity_id, second, third, import_node, resultcallback)

...

resultcallback   (function)
A function that will be called when the request is complete. The function will receive two 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.

ringBell

function ringBell(username)

...

username   (string)   
Optional. The user name of the client where the bell is to be rung.

setCurrentIdentity

function setCurrentIdentity(identityname)

...

identityname   (string)   
The identity identifier of the identity to activate

setCurrentIdentityColors

function setCurrentIdentityColors(color, blacktext)

...

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

setLocalIdentityPortrait

function setLocalIdentityPortrait(identityroot)

...

(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)

...