SharedDataClient 03/31/2024

Implements an actor based SharedData TLO for MacroQuest

The script will broadcast messages over the actor system at the configured frequency containing key/value pairs of all configured properties.
Properties include a key (the name the property will be exposed as in the character data) and an expression (a parsable line of macroscript like ${Me.PctHPs}).
Properties will only be included in messages when the value has changed.
Properties will be rebroadcast even if they haven't changed if a new character is seen.
Messages will still be published even if no properties have changed, just as a heartbeat mechanism.
Characters which stop broadcasting data will have their data marked as stale after the configured staleDataTimeout amount of time.
The script will check for stale character data and remove it after the configured cleanupInterval amount of time.
Per server/character configurations are stored in config/shareddata/ folder.

Includes support for defining custom data sources to output data other than what is available via existing MQ TLOs. See section on Custom Data Sources.

The script can be included into other scripts with require as well. See section on requiring SharedDataClient.

Caveat: Since its built on actor system, it currently only supports same PC characters.

What to use this script for?
I haven't thought that far ahead. Take advantage of the TLO from any Lua script where you want to send around fixed sets of TLO values between toons and access them via a TLO in your script.

Usage

Run with

Or run without showing UI on launch with

Available commands

Lua:

[/SIZE]
/sdc -- show help output
/sdc help -- show help output
/sdc reload -- reload settings for this character
/noparse /sdc add Key Expression -- add new property to be broadcast
/noparse /sdc addall Key Expression -- add new property to be broadcast for all characters
/sdc list -- list all properties
/sdc remove Key -- remove property from broadcasting
/sdc removeall Key -- remove property from broadcasting for all characters[/SIZE]
/sdc addsource filename -- add config/shareddata/customfilename.lua as a data source
/sdc addsourceall filename -- add config/shareddata/filename.lua as a data source for all characters
/sdc removesource filename -- remove config/shareddata/filename.lua from custom data sources
/sdc removesourceall filename -- remove config/shareddata/filename.lua from custom data sources for all characters
/sdc listsources -- list all custom data sources
[SIZE=15px]/sdc show -- open the UI
/sdc hide -- close the UI

TLO

Lua:

SharedData() -- print script version
SharedData.Names() -- return lua table of character names
SharedData.Characters() -- return lua table of all character data
SharedData.Characters('name1')() -- return lua table of name1 character data
SharedData.Frequency() -- get update frequency setting value
SharedData.CleanupInterval() -- get cleanupInterval setting value
SharedData.StaleDataTimeout() -- get staleDataTimeout setting value

Examples read TLO with Lua parse:

• Get list of character names which have data available:

Lua:

> /lua parse mq.TLO.SharedData.Names()[1]
Character1

[/SIZE]

• Get data for a single character in Lua table format

Lua:

[SIZE=15px]> /lua parse mq.TLO.SharedData.Characters('character1')().PctHPs
100

[/SIZE][/SIZE]

• Get data for all characters in Lua table format

Lua:

[SIZE=15px][SIZE=15px]> /lua parse mq.TLO.SharedData.Characters().Character1.PctHPs

Examples read TLO from a Lua script: [/SIZE][/SIZE][/SIZE]

Lua:

[/SIZE]
local names = mq.TLO.SharedData.Names()
for _,name in ipairs(names) do
    printf('PctHPs for %s: %s', name, mq.TLO.SharedData.Characters(name)().PctHPs)
end
local characterData = mq.TLO.SharedData.Characters('Character1')()
for k,v in pairs(characterData) do
    printf('%s: %s', k, v)
end
local allCharacters = mq.TLO.SharedData.Characters()
for name,data in pairs(allCharacters) do
    printf('PctHPs for %s: %s', name, data.PctHPs)
end

Adding Properties
Add key,value pairs of data to be shared using UI or commands.

Lua:

/noparse /sdc add PctEndurance ${Me.PctEndurance}

Lua:

/sdc remove PctEndurance

Lua:

/sdc list

Other Settings

• frequency - Delay, in milliseconds, for the main loop.
• cleanupInterval - How often to scan, in milliseconds, character data table for stale data. Default: 15000
• staleDataTimeout - How long to wait, in milliseconds, for updates from a character before considering that characters data to be stale. Default: 60000

Custom Data Sources​

Properties are limited to returning what is available via MacroScript such as ${Me.PctHPs}. Custom data sources provide a way to implement your own Lua functions to expose customized character data.

1. Create a new file under config/shareddata such as custom.Lua.
2. Return a table of key/value pairs from custom.Lua.
3. Add custom.Lua via the UI Custom Sources tab or with /sdc addsource custom.Lua.

The key/value pairs returned by your custom.Lua can return complex data such as Lua tables. For example, below code outputs a key BlockedBuffs whose value is a Lua table of blocked buff IDs.


This can then be accessed through the TLO like:


Requiring SharedDataClient in other Lua scripts
To make use of SharedDataClient from another Lua script, follow below example:


A path to a custom data source file (like above) should be provided when requiring SharedDataClient from another script. When run in this mode, the client won't publish any other values except those defined in the provided custom data source file. The UI, CLI and TLO will also be disabled, so that just the script which includes the client can access its relevant data through client.data.