Can Opener API Plugin

This unofficial TaleSpire plugin for accessing TS content at runtime via file based API.

Install

User R2ModMan or similar to download and install the plugin.

Usage

The Can Openeer API plugin reads content from its CustomData/API folder. It processes any files ending in API and responds using the same file name but with a extension of $$$.

The contents of the file contains one or more operations with one operation per line along with any parameters separated by a space. The following operators are available:

Find name

Set the active object to the GameObject of the provided name or sets the active object to one of the following objects LocalClient, CreaturePresenter, CreatureBoardAsset, or Messages (for Stat Messaging content).

Type name

Sets the active object to a type for use with static classes.

New name

Creates a new instance of the specific type (name) and sets the active object to it.

Instances name

Gets all unity objects of the give type (name) and set the active object to the array. Use the : operator to select a specific index in the array.

Components name

Gets all components of the give type (name) and set the active object to the array. Use the : operator to select a specific index in the array.

: index

Sets the active object to the indicated (index) element interpreting the current active object as an array of objects.

; key

Sets the active object to the indicated (index) key element interpreting the current active object as a dictionary of objects.

SET name

Stores the current active object under the give name. Typically used to easily switch between multiple objects.

GET name

Sets the active object to the object previously stored with the give name. Typically used to easily switch between multiple objects.

-> name

Sets the active object to the property or field indicated by the name. Typically used to traverse an object such moving from a GameObject to the game object's transform object.

? name ? cid key

Returns the active object's value of the specified (name) property or field. Only one result is supported. Successive results replace previous results.

When the active object is MESSAGES then the syntax changes to the cid as the first parameter and the Stat Messaging key as the second parameter.

= name value = cid key value

Sets the activeobject's specified (name) property or field to the indicated value. Includes a handler for Vector3 objects which are specified as 3 numbers separated by comma and no spaces (e.g. 3,6,8)

When the active object is MESSAGES then the syntax is changed to include the cid as the first parameters, the stat messaging key as the second parameter and the value as the third parameter.

| method | method parameters Invokes the specified method on the active object. Optionally with parameters.

{}

The opening and closing brace brackets is not an operator. It is used to insert the last result into thge parameters of other commands. The {} gets replaced by the last result when the operation that contains it is executed.

Examples:

FIND LOCALCLIENT
? SelectedCreatureId
FIND MESSAGES
? {} org.lordashes.plugins.states

FIND LOCALCLIENT
? SelectedCreatureId
FIND MESSAGES
= {} org.lordashes.plugins.states Ice

FIND LOCALCLIENT
? SelectedCreatureId
FIND CREATUREBOARDASSET {}
-> CreatureRoot
-> transform
? position

FIND LOCALCLIENT
? SelectedCreatureId
FIND CREATUREBOARDASSET {}
-> CreatureRoot
-> transform
= position 1.5,0.0,2,5

FIND LOCALCLIENT
? SelectedCreatureId
FIND CREATUREBOARDASSET {}
| RequestDelete

Change Log

1.0.0: Initial release

Why A File Interface?

Why a file interface? Why not a TCP/IP interface, Websocket interface or an REST API?

Threading in Unity/TS is difficult. If a communication server is not implemented correctly it can cause it to delay or even hang TS while it waits for a connection or communication. Communication timeouts and other similar factors can also introduce performance issues in TS. As a result, the plugin implements a file based API. The user can then add any type of front end (Websockets, TCP/IP messages, REST API) on top of that but that means any issues with the server will not be propagated into TS.

The implementation of the interface allows both read and write access to many of the Unity and/or Talespire objects and even communication to other other plugins via the Stat Messaging interface. The implementation is general and thus any additional objects which cannot be accessed via the provided functions can be added easily.