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.

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

Change Log

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

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');");

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.