Interface Plugin

This unofficial TaleSpire add a remote websocket interface to manipulate Talespire from an external application. This can be a web browser extension (typically to integrate content from other VTTs such as Dnd Beyond, Roll20, Foundary), it can be a Talespire Symbiote (typically to perform some task that is not normally available via the Symbiote API), or it could be a standalone application running outside of Talespire.

Lord Ashes' Talespire Plugins are always available for free. Lord Ashes does not have a Patreon but if you really want to make a donation to the chocolate fund to keep the work going, you can do so using the Donate link above.

https://lordashes.ca/TalespireDonate/Donate.php

Change Log

1.0.0: Initial release

Install

Use R2ModMan or similar installer to install this plugin.

This plugin is needed by any player whose Talespire is going to be affected by the remote source.

Usage

This plugin is a dependency plugin which remote sources (such as Browser Extensions, Symbiotes or Standalone Applications) can use to manipulate Talespire from an external source (i.e. outside of Talespire).

Players making use of such remote sources do not need to do anything with this plugin to make it work. However, they will likely have to do stuff at the source but that has nothing to do with the plugin. See the source documentation for how to use the source browser extension, Symbiote or application.

Making Remote Command Requests

The Interface Plugin impelments a Websocket interface through which remote sources can make requests into Talespire. Webscokets are easy to implement in Javascript (i.e. Browser Extensions or Symbiotes) and most languages have libraries for implementing Webscokets if you are writing a standalone application or script.

A sample Javascript file is provided which can be run by double clicking it. This will open it in a browser without needing to host it. This sample code is intended to show an example of how the interface is used and a potential Javascript solution to make command requests.

Unlike the Symbiote API which is well documented but somewhat limited in what it can do, the Interface Plugin is very geenric allowing you to access most of Talespires methods and objects. However, this also means there is no detailed documentation for all it can do because it is a generic implementation that just provides access into the Talespire code. This means you will likely need to use a software like dnSpy to figure out what method you want to call and with what parameters.

Request Message

Requests are made my sending a Request message over the websocket and optionally listening for a response. The Request message has the following format:

{
	"command": "INVOKE", 
	"source": "Bouncyrock.TaleSpire.Runtime+ChatManager", 
	"method": "SendChatMessageToBoard", 
	"paramJson": [ "Hello Everyone!", "NGuid", null, "false" ]
}

Not all requests use all of these parameters. It should also be noted that in the Javascript example, there is one additional parameter called "delay". This is not used by the Interface Plugin itself, it is only used by the Javascript client to determine the timing of messages.

The command parameter is requires and it determines what kinds of an operation is being done. Possible options are "FIND", "READ", "REF", "WRITE", "INVOKE" and "REMOVE". The source parameter is used to determine on who or what the operation is happening. The method parameter is used as a further selection depending on the command. The paramsJson parameter is a list of parameters typically Json encoded unless simple specific to the command.

FIND

The find command is used to locate a specific asset, gameobject, instance, type, or component. The results of the find are stored under a given name to be used with future commands. For example, if you want to set the Hp of a asset, you first find the asset and store that under a speciifed name and then you can use that name in the Invoke command to perform the actual Hp set.

For a find command, the source parameter is identification of the item to be found. What type of identification is used is determined by the method parameter which not only determine the type of object to be found but also what identity is used.

When method is "ASSET" then the find command will return the CreatureBoardAsset which has the name matching the source parameter. When method is "CID" then the find command will return the CreatureBoardAsset which has the creature id matching the source parameter. When method is "GAMEOBJECT" then the find command will return the GameObject which has a name matching the source parameter. When method is "TYPE" then the find command will return the object of the type specified in the source parameter. When method is "INSTANCE" then the find command will return an instance of the object whose type matches the type specified in the source parameter. When method is "COMPONENT" is not yet fully implemented.

Each of these will store the results under the name given by the first element in the paramJson parameter.

e.g.

{	
	"command": "FIND", 
	"source": "Xander", 
	"method": "ASSET", 
	"paramJson": [ "Asset" ]
}

Result: Typically identification of the found item or a error message saying the find was unsuccessful/

READ AND REF

The read and ref commands perform similar functionality. They read a field or property of a object and return the value. In the case of the read command, the value is returned but not stored. In the case of the ref command, the results are read and then stored under the given name. This command is usually used for two purposes: to read values and to traverse objects.

For read and ref commands, the source parameter is the object to be searched. In most cases this is the name of a stored object that was either set with the find or ref command. For read and red commands, the method is the proeprty or field name that is to be read. The first element of the paramJson parameter is used to determine the storage name for ref commands.

e.g.

{	
	"command": "FIND", 
	"source": "Xander", 
	"method": "ASSET", 
	"paramJson": [ "Asset" ],
},
{	
	"command": "REF", 
	"source": "Asset", 
	"method": "CreatureId", 
	"paramJson": [ "Cid" ],
},
{	
	"command": "REF", 
	"source": "Cid", 
	"method": "Value", 
	"paramJson": [ "NGuid" ],
}

The above example, uses the find command to find the asset called Xander storing it under the name "Asset". It then uses the ref command to read the CreatureId property/field of the object store under the name Asset and call that results Cid. Lastly it uses the red command to read the Value property/field of the object stored under the name Cid and stores the result under the name NGuid.

Result: The read value as a string, json string, null, or error message if the read failed.

WRITE

The write command is used to set a value. In a lot of cases Talespire provides methods to set values in which case the appropriate Invoke should be used instead but when such methods are not available, the write command can be used to write values to properties or fields.

For write commands, the source parameter is the object to be written to. In most cases this is the name of a stored object that was either set with the find or ref command. For write commands, the method is the proeprty or field name that is to be written. The values to be written is taken from the first element of the paramJson parameter.

e.g.

{	
	"command": "WRITE", 
	"source": "Asset", 
	"method": "_hover", 
	"paramJson": [ false ],
}

The above example writes the _hover property/field of the assets stored under the name Asset to false. This assumes that Asset has been set previously to a CreatureBoardAsset for whom the _hover property/field is to be changed.

Result: The modified value is read from the source and the current values is returned. This should normally be the set value unless the write operation failed.

INVOKE

The invoke command is used to trigger Talespire methods. Most of the time this is the command that will actually make something happen in Talespire. While write may also do that, methods are more common in Talespire to control things.

For invoke commands, the source parameter is the object on which the method will be invoked. For non-static methods this will be a stored object that was previously stored with a find or ref command. For static methods this will be the full name of the static object. The method parameter contains the method to be triggered. The paramJson parameter contains an array of parameters that are to be suppied to the method. The interface automatically determines the required data types for the parameters and tries to convert the provided json strings into those data types.

e.g.

{	
	"command": "INVOKE", 
	"source": "Bouncyrock.TaleSpire.Runtime+CreatureManager", 
	"method": "SetCreatureStatByIndex", 
	"paramJson": [ "Cid", "{\"Value\": 20.0, \"Max\": 60.0}", "0" ]
}

The above example uses the CreatureManager's SetCreatureStatByIndex to write new stats to the first Creature Stats slot. The above message assumes the value of Cid has been set previously to the creature whose stats are to be changed.

REMOVE

The remove command is used to remove stored references. This should always be done at the end of the remote source's requests to ensure that the Interface Plugin is not running with a lot of unused references.

For these commands, the source parameter contains the storage name which is to be removed.

e.g.

{	
	"command": "REMOVE",
	"source": "NGuid"
}

Result: Confirmation of the removal.


#### Static vs Non-Static

To use static objects, the source value can have the name of the static object. To use non-static objects, the find or ref command needs to
be used to first store the desired object and then it can be referenced in the source parameter by name.

#### 3rd Party References

When using static references to types that are not party of the core Interface plugin, the assembly name needs to be provided, followed by a
plus sign, followed the type name. For example: ``Bouncyrock.TaleSpire.Runtime+CreatureManager``. This tells the interface where the type
can be found.

#### Cleanup

While browsers, Symbiotes, applications and scripts may not persist (i.e. may make requests and then end), the Interface Plugin persists.
That means any object references set up by the remote sources remain in existance even after the remote source is no longer making requests.
That means if the same script is run again later, it may fail because objects with those names already exist. As a result, the remove commands
should always be used, at the end of each request session, to remove any stored references.