Beyond Link Pack

OBSOLETE: Please use Beyond Link Via Chrome instead unless use of a Chrome Extension is not possible (https://talespire.thunderstore.io/package/LordAshes/BeyondLinkViaChrome/)

This unofficial TaleSpire asset pack links your external source stats with corresponding Tale Spire mini. Comes with a sample configuration for D&D Beyond character sheets which currently copies current HD, max HD, AC, Shield AC, used HD, max HD.

Previously the "Beyond" in the BeyondLink plugin represented D&D Beyond but not, with the use of the Generic Data Parser, this plugin can support many different data sources and thus the Beyond now refers to (data) Beyond TS.

The Generic Data Parser allows reading and processing of a configruation file which tells the parsers how to extra the desired data from the given data source. As such, by writing a correct configuration file the Generic Data Parser can be used to extract data from most text based sources including JSON, XML, INI and other formats.

Change Log

1.1.0: Modified the processing of the source to use the Generic Data Parser allowing it to be used with other sources besides D&D Beyond. Sample D&D Beyond configuration provided. 1.0.0: Initial release

Install

Use R2ModMan or similar installer to install this asset pack.

Update the BeyondLink.gdp (Generic Data Parser) file to extra the desired data from the source. The included sample GDP file extracts data from D&D Beyond character sheets. Within the GDP file, the keyword {URL} will be replaced without the URL for the character being updated.

Update the BeyondLinks.json configuration with the desired character sources. Note that this configuration has changed from the previous version since it is no longer D&D Beyond specific. Instead of just containing the D&D Beyond Id, it now contains the whole URL of the data source.

The name in the configuration needs to match the TS mini name. The url is the url of the data source (character sheet) from which the data will be extracted.

The R2ModMan configuration for this plugin can be used to change the interval at which TaleSpire is syneced with the D&D Beyond character sheets. Default 10 seconds.

Usage

Everything happens automatically. When any of the supported properties are changed in data source, Tale Spire will be updated with the interval number of seconds.

The sample D&D Beyond configruation, the following data is extracted and updated...

The current HP and max HP is transferred to the Tale Spire asset HP. The current AC and the shield modified AC are transferred to Stat 1. Expressed as AC without shield of AC with shield. The used HD of and max HD is transferred to Stat 2. Expressed as used HD of max HD.

Operating Status

In the bottom right side of the screen the word "Link" is visile when this plugin is running. The color of this word indicates the success of syncing activity:

Blue = In-Between syncs. Green = Last sync was successful. Red = Last sync had at least one failure.

Centralized vs Distributed Configuration

There are two ways in which this plugin can be used: Centralized and Distributed.

Centralized: The GM configures all D&D Beyond characters in his/her BeyondLinks.json. All other players do not have the plugin active. Disadvantages: Larger stress on single device. Advantages: Other players don't needs to have this plugin at all, so other players could even be using an unmodded version of TaleSpire.

Distributed: Each player configures his/her BeyondLinks.json with their own characters. Disadvantage: Each player needs to have the plugin. Advantage: The processing is distributed between many devices so les powerful devices are needed.

Limitations

The D&D Beyond example uses the last armor listed on the character sheet regardless if it is being worn or not.
The D&D Beyond example does not recognize Unarmored AC bonus (like that obtained by Monk or Barbarian). As a work around you can add the corresponding armor (that would yield the same AC) to the character's inventory without wearing it.

Generic Data Parser

The generic data parser is a text file processor which can be used on a numbere of different text format files (such as JSON, XML and INI) to extract specific pieces of information. The generic data parser is "programmmed" using a configuration file which means it can easily be used to extra data from a different file format.

The generic data parser uses a concept of buffers. More straigth forward data extraction need only one buffer so the content is loaded into the buffer and then the various generic data parser instructions are used to go through the contents and extract the desired information. For more complex data extractions the generic data parser allows the use of multiple buffers so that the reminder of the buffer can be saved, processed and then restored. The generic data parser supports an unlimited number of buffers so that extraction can be nested.

Parameters for instructions are separated from the instruction and from each other using the pipe (|) character.

URL|content

This loads the buffer with the contents of the URL. This is typically used to get the content from which data will be parsed. For example:

URL|https://character-service.dndbeyond.com/character/v3/character/12345678

Result: Contents of the URL will be placed in the active buffer. If an buffer was active before this command it is automatically pushed (see Push).

Load|content

This loads the buffer with the contents of a local file. This is typically used to get the content from which data will be parsed. For example:

Load|c:/data/datafile.txt

Result: Contents of the file will be placed in the active buffer. If an buffer was active before this command it is automatically pushed (see Push).

Push

This instruction creates a new buffer with a copy of the current buffer. This allows the current buffer to be consumed with the ability to restore the saved copy of the buffer using the Pop instruction. Typically this instruction is used to isolate a portion of the buffer (with the ConsumeTo and ConsumeAfter) and process it without tripping searches outside the isolation range. Once the isolated section of the buffer is processed the Pop instruction can be used to restore the buffer to include content outside the isolation area.

Pop

Deletes the current buffer and restores the previously Pushed buffer. This typically allows an isolated section of the buffer and then restore the previusly saved buffer to continue processing outside the isolated area.

ConsumeTo|key

Removes content from the buffer until up to the first occurance of the given key word (including the keyword). Removed content is discarded. Typically this instruction is used to move through the content up to key points from where data will be extracted. For example:

ConsumeTo|Version:

ConsumeAfter|key

Removes all content from the buffer from (and including) the first occurance of the given key word. Removed content is discarded. Typically this instruction is used to isolate a section of the buffer for processing without tripping search results outside the isolated area. For example:

ConsumeTo|</Head>

ExtractRange|set|count

Removes a number of characters from the front of the buffer equal to the count parameter. The removed content is assigned to a variable with a name matching the set parameter. For example:

ExtractRange|phoneNumber|10

ExtractBetween|set|startKey|endKey|remove

Removes content from front of the buffer until (and including) the first occurance of startKey. Removes content from the front of the buffer until the first occurance of endKey. Removed content is stored in a variable with a name equal to the set parameter. This instruction is typically used to extract of data between two known points. The remove parameter is optional. When set, any characters in the remove parameter are stripped out of the removed content before assigning it to the variable. For example:

ExtractBetween|phone|"phone":|,|-

ExtractUtilClosed|set|startKey|endKey

Removes content from front of the buffer until (and including) the first occurance of startKey. Removes content from the front of the buffer until all occurancs of startKey are paied by occurance of endKey. This instruction differs from the ExtractBetween in that multiple startKey occurances require the same amount of endKey occurances before content removal stops. This is typically used with content that uses hierarchical structures like JSON or XML formats. By using ExtractUntilClosed allows extraction of the whole hierarchy or sub-hierarchy instead of stopping at the first endKey. For example:

ExtractUtilClosed|object|<item>|</item>

Computer|set|expression

Allows computing of expression and setting the result to a variable with name matching the set parameter. Expression use the same format as DataTable. Variables within the expression can be accessed by placing the name in brace brackets {}. The buffer can be accessed through the buffer variable. Lastly D&D stat mod determination can be obtained by placing the value in square brackets []. Lastly if the computation results in {NoChange} the result is not written to the variable. This allows conditional statements which don't change the current value if the condition is false. Below are some examples:

Compute|raceSTR|0 // Sets raceSTR variable to 0 Compute|raceSTR|IIF('{temp}'='-2 Strength',-2,'{NoChange}') // Conditionally sets raceSTR to -2

Replace|set|seek|new

Replaces all occurances of the seek parameter with the contents of the new parameter in the set variable. For example:

BranchOnSuccess|offset

Conditional branching based on the result of the last Consume or Computer instruction. If the keyword in the last Consume instruction was found or if the last Compute instruction did not result in a {NoChange} this instruction will cause the processing to jump within the instruction list by the amount indicated in the offset parameter. Negative numbers causes execution to jump back in the instruction list. Positive numbers causes execution to jump forward in the instruction list. Typically used to implement looping.

BranchOnFailure|offset

Conditional branching based on the result of the last Consume or Computer instruction. If the keyword in the last Consume instruction was not found or if the last Compute instruction resulted in a {NoChange} this instruction will cause the processing to jump within the instruction list by the amount indicated in the offset parameter. Negative numbers causes execution to jump back in the instruction list. Positive numbers causes execution to jump forward in the instruction list. Typically used to implement looping.

BranchOnLess|var|count|offset

BranchOnCount|var|count|offset

BranchOnMore|var|count|offset

Conditional branching based on the value of a variable. There are three versions: Less, Count or More which branching when the specified variable is less than, equal to or more than the specified count. If the condition is true then execution within the instruction list is adjusted by the value of offset. Typically used to implement count loops.

HP|source1|source2

This instruction sets the HP of the TaleSpire mini to the value of the variable indicated by the source1 and source2 parameters.

For example:

HP|currentHP|maxHP

Stat1|source1|source2

Stat2|source1|source2

Stat3|source1|source2

Stat4|source1|source2

Stat5|source1|source2

Stat6|source1|source2

Stat7|source1|source2

Stat8|source1|source2

This instruction sets the corresponding stat of the TaleSpire mini to the value of the variable indicated by the source1 and source2 parameters.