Symbiotes are our first officially supported way for modding, allowing users to add extra functionality with access to game data in a sidebar window.The documentation resides at <a target="_blank" rel="noopener noreferrer nofollow" href="https://symbiote-docs.talespire.com/">https://symbiote-docs.talespire.com/</a>, if you want to see what people have already done with it, see our official mod repository: <a target="_blank" rel="noopener noreferrer nofollow" href="https://mod.io/g/talespire?tags-in=Symbiote">https://mod.io/g/talespire?tags-in=Symbiote</a>

Symbiote API

In several places there are limitations in the quantity/size of things within TaleSpire, here is a list of a few noteworthy ones:<ul>
<li>100 campaigns per user</li>
<li>300 boards per campaign</li>
<li>600 normal minis per board</li>
<li>100 unique minis per campaign</li>
<li>1 000 000 assets per board</li>
<li>2000 × 2000 × 1000 grid units board size</li>
<li>13000 meshes per 16×16×16 zone</li>
<li>30720 (30kB) bytes per slab string</li>
</ul>

Quantity Limitations

<h1>URL Anatomy</h1>All TaleSpire URLs start with <code>talespire://</code>. From there on, we have some number of path segments.We call the first path segment the "behavior identifier", this tells TaleSpire how to interpret the rest of the segments.<h2>Dice Links</h2>Example: <code>talespire://dice/d12</code> (behavior identifier: <code>dice</code>)This gets TaleSpire to bring the dice rolls specified in the URL into the “tray” ready to be rolledNote: Currently, we only support basic dice rolls with the "dice" behavior. In the future, we will support more complex dice rollsNext, let's take a more complex URL and break it down. We'll use this as our example: <code>talespire://dice/Eldritch%20Blast:1d10/4d6-1d4/4d10+2/3d20+1-d6+2</code>First we'll ignore the scheme and behavior identifier, which leaves us with these path segments: <code>Eldritch%20Blast:1d10/4d6-1d4/4d10+2/3d20+1-d6+2</code>Each path segment specifies a "dice group". The roll results of each dice group get summed separately. You can see an example result from the above roll here:A dice group is parsed, right-to-left, case insensitively, with the following regex:<code>(\+|\-|)\d*D\d+(\+\d+|\-\d+|)</code>The C# code to do this is:<pre><code>var diceGroup = Regex.Matches(pathSegment, @"(\+|\-|)(\d*)D(\d+)(\+\d+|\-\d+|)", RegexOptions.RightToLeft | RegexOptions.IgnoreCase);</code></pre>The extra brackets in the C# regex above were added so that the <code>Groups</code> field contains the most useful data already separated. Naturally, you will need to reverse the results to get them in the correct order.The regex is the most accurate specification, but here is a simpler (though maybe less precise) version with extra details:<pre><code>[optional name + ":"][optional operator][optional count]D[sides][optional modifier]</code></pre>where:<ul>
<li><code>name</code>: a name can be added to a dice group which will name the roll in the chat/dice history, as well as show the name of the roll in the result pop-up after rolling</li>
<li><code>operator</code>: currently, the only operators supported are + and -</li>
<li><code>count</code>: is the number of dice of that kind. Zero is not valid, but if it is not specified at all, then the count defaults to one.</li>
<li><code>D</code>: is the only uppercase in the regex to clearly distinguish it from the \ds. The regex is always case insensitive.</li>
<li><code>sides</code>: is the number of sides of the die. Currently we only support the standard TaleSpire dice. We will need to expand to support dice modding.</li>
<li><code>modifier</code>: here, you can specify an integer to add or subtract. It is always of the form +N or -N where N is a positive integer.</li>
</ul>Notes:<ul>
<li>Negation: As the operator is part of the group, a valid dice URL is <a target="_blank" rel="noopener noreferrer nofollow" href="talespire://dice/-d6">talespire://dice/-d6</a>. This results in a negated dice roll. Note that <a target="_blank" rel="noopener noreferrer nofollow" href="talespire://dice/d4-d6">talespire://dice/d4-d6</a> is supported but <a target="_blank" rel="noopener noreferrer nofollow" href="talespire://dice/d4--d6">talespire://dice/d4--d6</a> is not.</li>
<li>Right-to-left: The right-to-left matching is critical to get the correct result: Parsed left-to-right <a target="_blank" rel="noopener noreferrer nofollow" href="talespire://dice/d6-2d12-1">talespire://dice/d6-2d12-1</a> matches as d6-2 and d12-1, rather than what we want which is d6, -2d12-1. You can experiment with the right-to-left option by browsing <a target="_blank" rel="noopener noreferrer nofollow" href="https://www.regexplanet.com/share/index.html?share=yyyyd9vu5ar">here</a> and clicking the .Net button. Remember to select the "case insensitive" option on regexplanet before clicking the "Test" button.</li>
<li>Garbage is ignored: Due to lack of strictness in the specification, it is valid, although ugly, to have ignored text in the URL. For example: <a target="_blank" rel="noopener noreferrer nofollow" href="talespire://dice/horsed6horse-2d12-1horse">talespire://dice/horsed6horse-2d12-1horse</a> is parsed to d6 and -2d12-1. Arguably this should be made stricter.</li>
<li>Only first name is shown: Currently the result pop-up, as well as the chat history tab only show the name of the initial dice group, ignoring the others. It is also worth to note that the UI currently does not handle long names particularly well.</li>
</ul> <h2>Asset links</h2>Example: <code>talespire://asset/0b9f9061-a6e4-4126-829f-1deb43147f49</code> (behavior identifier: <code>asset</code>)The asset links are fairly straightforward: the path segment after the “asset” behavior identifier is simply the UUID of an asset. Once clicked and parsed by TaleSpire the asset of the corresponding UUID will be put into the hand ready to place.Possible assets are Tiles, Props and Minis.The asset UUIDs (as well as some other metadata) can be found in the index.json file inside TaleSpire’s install directory.<h2>Published-Board links</h2>Example: <code>talespire://published-board/TGVwaWRzdGFkdA==/c82b15b84b2fbebfb33929922c9f3fbe</code> (behavior identifier: <code>published-board</code>)These are links to board shares. As opposed to <a target="_blank" rel="noopener noreferrer nofollow" href="https://feedback.talespire.com/p/slab-format">slab strings</a> which contain all the necessary tile data within themselves, board shares are simply unique links to representations of a board stored on our servers. Clicking the link will cause TaleSpire to create a (shallow) copy of the board. Editing anything on the board as the one who shared it will not update the shared board state.The anatomy of the url is as follows:<pre><code>talespire://published-board/[encoded-name]/[published-board-id]</code></pre><ul>
<li>The encoded name is a utf8 string which has been base64 encoded, and then has had all forward-slashes replaced with underlines (<code>/</code> → <code>_</code>)</li>
<li>The published board id is a hex representation of a 16 byte ID. The ID refers to a published board on the server.</li>
</ul><h2>Go To Bookmark links</h2>Example: <code>talespire://goto/bookmark/89d1e76a49688d42b5ce62ae511415d6</code> (behavior identifier: <code>goto/bookmark</code> )Clicking the link causes TaleSpire to move the camera to the bookmark with the linked IDThe anatomy of the URL is as follows:<pre><code>talespire://goto/bookmark/[bookmark-id]</code></pre>The bookmark id is a hex representation of a 16 byte ID. The ID refers to a bookmark on the server.<h2>Stat Names links</h2>Example: <code>talespire://stat-names/AQAIBENvb2wEU3RhdAVOYW1lcwRUaGF0A0NhbgJCZQZDb3BpZWQDTm93</code> (behavior identifier: <code>stat-names</code>)This tells TaleSpire to update the currently open campaign’s stat name setup. The stat names are base64 encoded into the URL and can be extracted directly.The anatomy of the URL is as follows:<pre><code>talespire://stat-names/[stats-data]</code></pre>the stats-data is a base64 encoded string<pre><code>Processing the string:
- replace all underscores in string with forward-slashes (_ -&gt; /)
- Base64 decode the string</code></pre>The resulting binary data is laid out as follows:<pre><code>version :: u16 - This is currently 1
number-of-stats :: u8
names :: utf8-string[number-of-stats]

utf8-string is laid out as follows:
byte-count :: u8
utf8-data :: u8[byte-count]

&gt; We use the following notation above
&gt; u8: 8bit unsigned integer (byte in c#)
&gt; u16: 16bit unsigned integer (ushort in c#</code></pre><h2>Creature-Blueprint links</h2>When you copy a creature, TaleSpire saves a blueprint of the creature to the system clipboard in the form of a creature-blueprint URL.The anatomy of the URL is as follows:<pre><code>talespire://creature-blueprint/[blueprint-data]</code></pre>the blueprint-data is a base64 encoded string<pre><code>Processing the string:
- replace all underscores in string with forward-slashes (_ -&gt; /)
- Base64 decode the string</code></pre>The resulting binary data is laid out as follows:<pre><code>
version :: u16 - This is currently 1
number-of-stats :: u8 - this number MUST be &lt;= 150
names :: utf8-string[number-of-stats] - 
number-of-morph-ids :: u8 - this number MUST be &lt;= 10
morph-ids :: uuid[number-of-morph-ids]
active-morph-index :: u8
morph-scales :: packed-morph-scales
RESERVED :: u16
RESERVED :: u16
RESERVED :: u16
RESERVED :: u16
RESERVED :: u16
RESERVED :: u16
RESERVED :: u16
RESERVED :: u16
RESERVED :: u8[3]
hp :: stat
stat-0 :: stat
stat-1 :: stat
stat-2 :: stat
stat-3 :: stat
stat-4 :: stat
stat-5 :: stat
stat-6 :: stat
stat-7 :: stat
torch-hide-fly-state :: torch-hide-fly-state
number-of-emote-slot-overrides :: u8 - this number MUST be &lt;= 16
slot-overrides :: slot-override[number-of-emote-slot-overrides]
number-of-active-emote-ids :: u8 - this number MUST be &lt;= 16
active-emote-ids :: uuid[number-of-active-emote-ids]

utf8-string is laid out as follows:
byte-count :: u8
utf8-data :: u8[byte-count]

packed-morph-scales is a u64 with data bit-packed into it.
It stores up to 10 scales, each taking 6 bits:
to get the nth scale you:
- shift out the 6 bits you are interested in
- divide the value by 4 to get the scale

stat is laid out as follows:
value :: f32
max :: f32

torch-hide-fly-state is a u8 with data bit-packed into it.
bit 0: torch enabled
bit 1: explicitly hidden
bit 2: flying enabled

slot-override is laid out as follows:
id :: uuid
index :: u16

e.g. ((packed-morph-scales &gt;&gt; (6 * n)) &amp; 0b111111) / 4f

&gt; We use the following notation above
&gt;
&gt; u8: 8bit unsigned integer (byte in c#)
&gt; u16: 16bit unsigned integer (ushort in c#)
&gt; u32: 32bit unsigned integer (uint in c#)
&gt; u64: 64bit unsigned integer (ulong in c#)
&gt; f32: 32bit ieee754 binary floating point number (float in c#)
&gt; uuid: 128bit id</code></pre><h1>TaleSpire URL Relay</h1><h2>Windows</h2>The URLs get passed onto TaleSpire by adding a registry key on install that tells windows what .exe to run when a talespire:// URL is launched. As we don't want lots of copies of TaleSpire starting we have TaleSpireUrlRelay.exe, which either<ul>
<li>launches TaleSpire and passes the URL as a command-line argument</li>
<li>use some form of <a target="_blank" rel="noopener noreferrer nofollow" href="https://en.wikipedia.org/wiki/Inter-process_communication">IPC</a> to send the URL to the running instance of TaleSpire</li>
</ul>Using the Links from typical browsers is as simple as clicking on it, and telling the browser to allow to open talespire:// links with the TaleSpireUrlRelay.exe (and for convenience possibly also allow to always do that without asking).Notes:<ul><li>TaleSpire must not be run as administrator for the TaleSpireUrlRelay to work (unless the Relay is also run as administrator)</li></ul><h2>Linux</h2>While Linux support isn’t official, TaleSpire does run pretty well using Steam Proton and we are looking into officially supporting Linux (via Proton) in the future. However, the registry keys for Windows obviously don’t work when installing on Linux, so to get the URL relay to work you have to tell your Linux system to forward the talespire:// scheme to the UrlRelay (and open said Relay using Wine).LividJava from the Discord Community has created a shell script to automatically create the needed desktop entry for getting TaleSpire URLs work - you can get the newest version of it from GitHub: <a target="_blank" rel="noopener noreferrer nofollow" href="https://github.com/LividJava/talespire-linux-uri">https://github.com/LividJava/talespire-linux-uri</a>Keep in mind that this is code written by community members so no guarantees for safety and correctness can be given! Check the script yourself, or follow the instructions for setting it up manually:For manual registration of the link forwarding you need to create a .desktop file at<code>~/.local/share/applications/xdg-talespire.desktop</code>:<pre><code>[Desktop Entry]
Type=Application
Name=TaleSpire
Exec=/bin/bash -c 'env WINEPREFIX="/home/$USER/.steam/steam/steamapps/compatdata/720620/pfx" WINEESYNC=1 "/home/$USER/.steam/steam/steamapps/common/Proton 6.13/dist/bin/wine64" "/home/$USER/.steam/steam/steamapps/common/TaleSpire/TaleSpireUrlRelay.exe" %u'
StartupNotify=false
MimeType=x-scheme-handler/talespire;</code></pre>And then add the mime type to xdg:<pre><code>xdg-mime default xdg-talespire.desktop x-scheme-handler/talespire</code></pre>Of note:<ul>
<li>The actual path to <code>wine64</code>will likely differ from system to system based on: Installed Proton version(s) and default library location. If the library location is left to default it may still vary between distributions.</li>
<li>The actual path for the <code>WINEPREFIX</code> (= Wine’s working directory) depends on the install location of TaleSpire (which “library folder” in Steam it’s installed to), in the example above shows the default location in <code>~/.steam/</code>. The same obviously also applies to the path to the <code>TaleSpireUrlRelay.exe</code>.</li>
<li>Some people needed to use <code>WINEFSYNC=1</code> instead of <code>WINEESYNC=1</code>.</li>
</ul>(Thanks Doskious and Adriannom on Discord for figuring this out!)PS: For the official Linux support this setup should be done automatically, this is just a manual workaround while support is still unofficial.

talespire:// URL Scheme

By opening the chat (default keybinding: Enter) and prepending a message with “!” you can create a dice roll through chat. They follow the same system as the <a target="_blank" rel="noopener noreferrer nofollow" href="https://feedback.talespire.com/kb/article/talespire-url-scheme">dice URLs</a> and as such contain the same features. For the full description of what is supported and how exactly, please refer to that article, but here’s a short run down of examples with what is possible:<ul>
<li><code>!1d20</code> Normal dice rolls</li>
<li><code>!Rapier:1d20+4</code> Named dice rolls, modifiers in dice rolls</li>
<li><code>!2d20-4+3d12</code> Several different dice types in one roll, modifiers</li>
<li><code>!1d20+2/1d20+2</code> Two separate dice groups (that are separately summed up) in one roll, modifiers</li>
</ul>The system is subject to the same base limitations as the internal dice rolls and the URLs:<ul>
<li>Per dice roll the maximum number of dice across all dice groups is 40.</li>
<li>Currently labels/names on several groups isn’t supported (only the first label specified shows)</li>
<li>Not all possible arrangements with basic arithmetic are properly supported, eg: <code>!7-d6</code>, which drops the 7 at the start</li>
<li>More features are definitely planned like being able to drop the lower or higher of two dice, … This is just the first iteration.</li>
</ul>

Chat Dice Rolls

The Slab format encodes tile and prop information to be able to copy and paste it between clients.<h1>Encoding / Decoding</h1>The slab format is a binary data format (as opposed to a text based one) containing information on version, used assets and asset positions. This binary data is first packed using <a target="_blank" rel="noopener noreferrer nofollow" href="https://en.wikipedia.org/wiki/Gzip">gzip</a> to decrease size and then for compatibility with network streams and easier sharing through text chat clients it is encoded using <a target="_blank" rel="noopener noreferrer nofollow" href="https://en.wikipedia.org/wiki/Base64">base64</a>. Programmatically creating slab strings naturally requires these steps to be applied in order.To decode an existing slab string (for example one copied from TaleSpire itself), these steps need to be done in reverse order, so first base64 decode and then gzip unpacking, which leaves the raw binary data ready to be parsed.<h1>Binary Format</h1>See <a target="_blank" rel="noopener noreferrer nofollow" href="https://github.com/Bouncyrock/DumbSlabStats">this repository</a> on GitHub for documentation on the slab format, as well as a small demonstration application for decoding and encoding the current version.Notes:<ul><li>The slab format is by no means finished and can change in the future to be better optimized and/or support more features. For example the slab format should also include the ability to copy and paste miniatures in the future, as this is not implemented yet it is expected that there will be an update to the format once that feature ships.</li></ul>

How can we help you?

Technical Documentation

Symbiote API

Quantity Limitations

talespire:// URL Scheme

Chat Dice Rolls

Slab Format