Symbiote API Plugin

This unofficial TaleSpire dependency plugin allows plugin to make use of the Symbiote API. Using the Symbiote API to interact with Talespire makes plugins more resistance to breaking on BR updates because the under-the-hood namespace, fields, properties or methods may change but the API is more likely to be preserved.

Video (Plugin To Symbiote): https://youtu.be/XS6aVpiaaaI Video (Symbiote To Plugin): https://youtu.be/LmhFQ2AYrpM

This plugin, like all others, is free but if you want to donate, use: http://LordAshes.ca/TalespireDonate/Donate.php

Change Log

1.2.0: Asset support for Symbiote triggered plugin functionality
1.1.0: Symviote API warning only shows when board is loaded (since Symbiote panel is not available in main menu)
1.1.0: Fixed bug with regular log entries being logged as exception
1.0.0: Initial release

Install

Use R2ModMan or similar installer to install this plugin.

This is a dependency plugin and thus is not used directly by the user. It is used by other plugins to implement various communication and data storage features.

Runtime Usage (IMPORTANT NOTE!)

Due to a bug in Talespire, the Symbiote that this plugin created must be activated each session even if the Symbiote says that it is already active. A warning message will continue to display periodically if this has not been done.

To re-activate the Symbiote, open the Symbiote Panel and click on the Symbiote API selection in the menu. This will open the Symbiote API symbiote and display a bunch of diagnostic information. Close the Symbiote API window and close the Symbiote panel.

It should be noted that users can still use other Symbiote after the Symbiote API is activated. The Symbiote API symbiote just need to be activated but does not need to be the currently opened Symbiote.

Once the corresponding Talespire bug is fixed, this will no longer be necessary and the warning message check will be remove from the plugin at that time.

Development Usage

Plugin To Symbiote

The Symbiote API plugin provides a number of function for interacting with the Symbiote API:

Initialized(callback)

The Initialized method is used to provide a callback which is triggered when the corresponding Symbiote has been initialized (re-activated by the user). Normally this callback is used to make a subscription if the plugin is to make use of Symbiote API subscription events.

Subscribe(subscription)

The Subscribe method is used to list the Symbiote API events that the plugin wishes to be notified about. These events correspond to the Symbiote API events listed in the Symbiote API documentation. Be advised that the list contains the list of events and not the event heading. For example, the user would subscribe to rollResults and not onRollResults. This is in contrast to Symbiote manifest files which subscrive to the category and not the specific event. The Subscribe method must be called after the corresponding Symbiote API is initialized and thus is usually combined with the Initialized method. For example:

SymbioteApiPlugin.Initialized(() => { SymbioteApiPlugin.Subscribe(new List<string>(){ "rollResults" }, rollResultCallback); });

The Subscribe method return a subscription guid which can be used to unsubscribe.

Unsubscribe(guid)

The Unsubscribe method is used to unsubscribe from Symbiote API subscription events. Use the guid generated by the Subscription method as the parameter to this method to unsubscribe the corresponding events. The method returns the number of subscriptions removed (typically 0 or 1).

Symbiote_API(js)

The Symbiote_API method is used to trigger Symbiote API code. More specifically it can be used to trigger any Javascript code which can include Symbiote API code. This method is intended to run short javascript code snippets usually one line or about couple lines of code. This function uses the talespire://symbiote URL protocol and thus the length of the code will be limited to a length less than what is allowable by the OS for a URL. For example:

Symbiote_Api("TS.chat.send('Hello World!','board');");

Symbiote To Plugin

The Symbiote API plugin comes with a file called extra.js which provides a bunch of helper functions that Symbiote can use. Among these helper functions are functions for triggering Asset Data Plugin functionality which can be used to trigger the function of other plugins that use Asset Data Plugin for turning on and off functionality. The intension of the extra.js file is for the contents to be included in the Symbiote's injection code, allowing the Symbiote to use the related helper functions.

com.bouncyrock.talespire.extra.sendSimpleDiceResult(rolls, gmOnly, quiet) provides a simplified function for posting dice reults. The content of rolls is an array of the roll object which has the proeprties of name, formula and results. Name is a string which dictates the name of the roll. Formula is a string depresenting the dice formula (e.g. 3D6+4). Results is an array of int with the dice results (without modifier applied).

com.bouncyrock.talespire.extra.getSimpleDiceResult(roll) converts a Talespire roll result into its simplified format. The result of the call is a object with the proeprties name, formula and results (see above).

com.bouncyrock.talespire.extra.sendPluginMessage(key, value) sends a Symbiote request to the Symbiote API plugin to send an Asset Data Plugin message. This works like the SendInfo() method of Asset Data (see AssetDataPlugin docs for more details) except that it is initiated from the Symbiote.

com.bouncyrock.talespire.extra.setPluginState(source, key, value, legacy) sends a Symbiote request to the Symbiote API plugin to set the specified asset's key to the specified value. This works like the SetInfo() method of Asset Data (see AssetDataPlugin docs for more details) except that it is initiated from the Symbiote.

com.bouncyrock.talespire.extra.clearPluginState(source, key, value, legacy) sends a Symbiote request to the Symbiote API plugin to clear the specified asset's key. This works like the ClearInfo() method of Asset Data (see AssetDataPlugin docs for more details) except that it is initiated from the Symbiote.

How It Works (Details For Those Who Are Interested But Not Required To Use It)

The plugin creates a dedicated Symbiote, called Symbiote API, if it does not already exist. The dedicated Symbiote subscribes to the entire set of Symbiote API subscription events allowing the provision of notification regarding Symbiote API subscription events. When the Symbiote is started, it sends its Symbiote Id to the Talespire Chat. The Symbiote API Plugin captures this id, before it is displayed, and stores it for future communication.

Normally, at this point, the plugin sends a subscription request to the corresponding Symbiote to indicate which subscription events the Symbiote should notify the plugin about. To do this, the plugin uses the Symbiote_API method (like any other code request) to trigger the predefined Subscribe event on the Symbiote. This causes the Symbiote to store the subscription list for comparison when a subscription event occurs.

When a plugin wants to execute Symbiote API code, the Symbiote_API method is used. This triggeres the TalespireUrlRelay with a specific URL which comprises of the Symbiote id prefix and the javascript code to be executed as the URL parameter message. Since the Symbiote subscribes to URL messages, it obtains the message (sent only to it due to the Symbiote id prefix) and validates the request to ensure it is an API request (this is done by checking for a API: prefix). If the request passes the validation, it is executed as javascript code (thus running the Symbiote API command or commands).

When a subscription event occurs, the Symbiote obtains notification of the event since it is subscribed to subscription events. It then compares the name of the event against the subscribed list and if the event name is present, it sends a Chat message prefixed by the keyword EVENT: to the corresponding player running the Symbiote. The Symbiote API intercepts this and sends it to the corresponding plugins that subscribed to the event.