Beyond Link Via Chrome Plugin

This unofficial TaleSpire plugin for transferring data from D&D Beyond to Talespire in near real time. While the Beyond Link Plugin uses a General Data Parser for allowing data from different sources, it does not parse D&D Beyond Data well because the JSON data has a list of features that are part of the character but not the stat totals. This means the parser needs to perform calculations to obtain the totals. The Beyond Link Via Chrome Plugin changes that. It uses a Chrome Extension to get at the final results on the character sheet as opposed to calculating the totals. While written specifically for D&D Beyond character sheets the logic of the Chrome Extension can be modified to support other sources. This plugin, updates current HP, max HP, AC, used HD, total HD, inititive and speed.

The design uses a 3 component solution: the Chrome Extension, the Beyond Link Server and the actual TaleSpire BeyondLinkViaChrome plugin. The Beyond Link Server is mostly transparent to the user. It is started by the plugin and closes itself automatically if TaleSpire is stopped. However, this 3 component implementation means that the TaleSpire plugin portion is never waiting for data. The data exchange is done between the Chrome Extension and the Beyond Link Server. Since the Beyond Link Server runs outside of TaleSpire (stand alone), if the communication fails or is slow it will not have any direct impact (i.e. block) on TaleSpire GUI (beyond general device resources). The Beyond Link Server makes any data changes available to the plugin via local files which means any failures to update statistics will just make the plugin use the old value and pick up the new value on the next pass.

The Beyond Link Server also searched through installed and active plugins for any plugins which contain LinkData handlers. These handlers are used to teach Beyond Link Server how to make specific files needed by these other plugins so that these plugins can use the gathered information. Examples of plugins, that provide a LinkData handler so that they can be used with the Beyond Link data, are Dice Selection plugin and Rule Set 5E plugin. However, if other plugins want to use the Beyond Link data they can add their own LinkData handler and Beyond Link Server will be able to serve them.

Change Log

2.3.0: Updated for compatibility with BR Slab Browser update
2.3.0: Removed dependency on Stat Messaging which was only used to parse the asset name 
2.3.0: Added template for creating DataLink projects
2.2.0: Better logging to the BeyondLink Server console
2.1.0: Bug fix for Dnd Beyond page change
2.1.0: Bug fix for Beyond Link server start
2.0.0: Bug fix for BR HF Integration update
1.4.1: Corrected corrupted upload
1.4.0: Updated Beyond Link Server with LinkData handlers mechanism to allow Beyond Link Server to produce
	   many different files, with the beyond link data, for various plugins.
1.4.0: Updated Chrome Extension extraction logic to fix bugs and make it more robust.
1.4.0: No changes to the actual plugin DLL file (which remains at version 1.3.0)
1.3.0: Added port to server and R2ModMan configruation to allow using a different port.
       Added Initiative and Move to the default configuration. 
1.2.0: Modified extraction script to avoid javascript crash if character sheet it is not on the attacks
       page. Will not be able to read attacks rolls but will not cause crash.
1.1.0: Added refresh rate selection. Ensure that Chrome refresh rate is same.
1.1.0: Added ability to assign extracted file values to stats.
1.0.0: Initial release

Install

1. Use R2ModMan or similar installer to install this plugin.
2. Open Chrome to the address chrome://extensions/
3. Ensure Developer Mode is on
4. Use the Load Unpackaged option to load the Chrome Extension from the BeyondLinkChromeExtension folder of the installed plugin

Note: The Chrome Extension has, intentionally, not been packaged so that the user can see and potentially edit what the extension does.

Customization

The R2ModMan configruation for the plugin has settings for the stat names (single string separated by commas) and settings for which files are used to populate each of the stats. Each setting is a string of two files names - the current value and the max value. The files are generated by the Beyond Link Server based on the Chrome extracted data. Any data that is not determined to be a DSM roll is converted into a file (using the same hierarchy name as in the JSON file extracted by Chrome) and be used by this setting to assign it to one of the 8 stats. If a value, such as AC, does not have a current vs max, just use the same file twice since each setting must specify a file for the current and max value. Only numeric data can be stored in stats. Leave slots blank in order to not use them.

Usage

There are two mode of using this plugin: Basic and Advanced.

Basic Mode involves using this to update the current HP, max HP, AC, used HD and total HD, initiative and Speed on minis.

Advanced Mode involves also using the plugin, in conjunction with the Dice Selection Plugin, to make rolls.

Basic Mode

1. Start TaleSpire
2. When the plugin starts a new window will appear. Do not close this window, just Alt-Tab (or otherwise) switch back to the TaleSpire screen.
3. Rename a mini to match the D&D Beyond name.
4. Open a D&D Beyond character, in the Chrome browser, that corresponds to the name used in step 3.
5. Click the Short Rest button to open the Hit Dice information. This is needed in order to obtain properly Hit Dice information.
6. Wait around 10 seconds and the mini's stats should synchronize. Updates occurs every 5 seconds or so.
7. When TaleSpire closes, the window that opened in step 2 will disappear within about 10 seconds.

Advanced Mode

The Beyond Link Via Chrome plugin automatically makes corresponding DSM files used by the Dice Selection plugin. These are also updated in near real time but the issue is that Dice Selection plugin only reads the configruation files on startup to avoid introducing performance hits. This means by the time the plugin synchronizes the D&D Beyond roll information, Dice Selection plugin has already read the old configuration and the updated rolls will not be used until next time.

There are two work-arounds to get your D&D Beyond rolls updated with Dice Selection plugin:

Restart Talespire

One way to update the rolls from D&D Beyond is to start Talespire using the instruction in the Basic Mode and then wait about 10 seconds for the data to update. This will also update the DSM files. Now restart Talespire. Please note that exiting to the main menu is not sufficient, you must close down TaleSpire. Restart Talespire and your rolls will be updated.

Typically this is the easiest way to update the rolls and since rolls don't typically need to be updated frequently (usually only when you level up or get new equipment), restarting is not a big deal.

Learn Mode

It is possible to run a component of the Beyond Link Via Chrome stand alone to get it to sync all the D&D Beyond rolls before starting TaleSpire. The steps for this are as follows:

1. Start the BeyondLinkServer (found in the plugin directory) with a parameter of Learn BeyondLinkServer *Post* Learn Where Port is the desired port number (default 9100).
2. Open a D&D Beyond character in the Chrome browser.
3. Click the Short Rest button to open the Hit Dice information. This is needed in order to obtain properly Hit Dice information.
4. Wait around 10 seconds and the character's information should be synced. You will see entries for all the found information identified in the BeyondLInkServer window. This process has created the related DSM files prior to TaleSpire being started so the Dice Selection plugin can get the latest roll information when it starts.
5. You can close the BeyondLinkServer window.
6. Start Talespire using the steps in the Basic Mode. Your rolls should be updated.

Note: You do not need to do this every time. You only need to do these steps when rolls change such as when you level up (and your proficient changes or you get an ASI) or when your equipment changes.

Limitations

1. The tab with the D&D Beyond character must remain open in Chrome in order to get updates.
2. The Short Rest dialog needs to be open in order to get correct Hit Dice information. If the Short Rest windows is closed, the Hit Dice informatation may be wrong.
3. The Beyond Link Server component which takes data from Chrome and turns it into uable files by the plugin is currently single client only. Since all the communication is done in bursts with the socket being closed in between this is acceptable for a few characters. With larger parties it is suggested to distribute the updating jobs between the players.
4. Some of the current information may not be optimized for multi classing characters.

Troubleshooting

If the link does not seem to work then look at the Beyond Link Server window. This not NOT the BepInEx console but, instead, is the window that starts automatically when TS is started (or was started manually). If there is or more entries being written to this file every 5 seconds or so, then the Chrome Extension is able to connect to the server and thus the problem is probably in your R2ModMan configuration (i.e. is a problem between the Beyond Link Server and the TS plugin). If the Beyond Link Server window is not getting any messages then the Chrome Extension is not able to connect to the server.

Looking At The Chrome Console

If Chrome does not seem to be able to connect to the Beyond Link Server, one can try looking at the Chrome console to see if it has any clues. Press F12 to open Developer Tools and then select the Console tab. Check to see if there are any error messages. The most common error message is a message saying Chrome is unable to connect to 127.0.0.1:9100. If this is the case, try switching ports.

Switching Ports

In order to switch ports, the port number need to be changed in 2 places (in the Chrome Extension and on the TS plugin). To do this:

1. Stop TS.
2. Stop the Chrome Extension.
3. Edit the Chrome Extension injection.js file. Near the bottom is the websocket send command which includes the port number (normally 9100). Change this to the desired port. Save.
4. Either remove and re-add the Chrome Extension or press the circular arrow button to reload the Chrome Extension.
5. Reload any D&D Beyond page that may be open (if any).
6. Edit the R2ModMan configuration for the Beyond Link via Chrome plugin. Change the port number to the same number set in step 3. Save.
7. Start TS.

Windows Permissions

If communication is still not established, try running the Beyond Link Server stand alone and As Administrator. This may cause a prompt to show up asking if you want to allow the communication. Allow the communication. The application should remember this setting so it is not necessary to do it each time.