Embedded Character Sheet Plugin

This unofficial TaleSpire plugin for adding an embedded read only character sheet into Talespire from which you can make rolls. Supports Talespire dice rolling and Chat Roll rolling. Uses concept of layouts to make character sheet configuration easier but the character data dictates the layout so the GM can mix layouts as needed.

Video: https://youtu.be/tzhLeRBiScU

While this plugin is similar in functionality to Character Sheet Plugin there are some major difference and thus this plugin does not replace the Character Sheet Plugin. Notable difference are:

1. Character Sheet Plugin can have multiple sheets open. Embedded Character Sheet can only have one sheet open.
2. Character Sheet Plugin is a form on top of Talespire while Embedded Character Sheet renders inside Talespire.
3. Embedded Character Sheet has better support for controlling the appearance of each sheet element.
4. Embedded Character Sheet has support for inserting content from other files so you can seperate content easier.
5. Embedded Character Sheet has support for sub-pages.
6. Embedded Character Sheet allows editing vales.

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

Change Log

1.8.6: Added documentation for the close on click configuration option. No plugin update.
1.8.6: Corrected documenation regarding embedded images. No plugin update.
1.8.5: Corrected modified consolidation functionality
1.8.4: Updated for compatibility with BR Seats update
1.8.1: Fixed issue with Roll RegEx
1.8.0: Updated for compatibility with BR Taleweaver update
1.8.0: Corrected dice roll RegEx
1.7.2: Bug fix for allowing additional rolls to be named
1.7.1: Fixed bug with pass through rolls
1.7.0: Added optional target propery
1.7.0: Added evaluation of name and target proeprty
1.6.7: Fix bug regarding sending results to chat if the roll content is not a roll format
1.6.5: Added support for division in rolls via & or ÷ character
1.6.5: Added evaluations of place holders when added to improve ability to nest rolls
1.6.3: Added warning about using Legacy "Type 0" elements. Please switch layouts to use "Type 1" elements instead.
1.6.3: Added option to toggle mouse position display
1.6.1: Bug fix for rolling manually added dice to dice tray
1.6.0: Updated for compatibility with latest BR Update
1.6.0: Added optional name property used in roll results
1.5.5: Added fast change functionality for numeric elements
1.5.4: Bug fix for regex matching to detect valid rolls
1.5.3: Bug fix for calculated modifier
1.5.2: Reworked regex to support D100 (e.g. 1D100+1D10+0)
1.5.2: Added support for multi dice type per roll (e.g. 3D8+2D6+0) 
1.5.1: Bug fixes for nested place holders
1.5.0: Added support of content resolving to texture reference (as opposed to just hard coded texture references)
1.4.0: Added support for editing values directly from the plugin
1.3.0: Added link functionality allowing swapping between different layout sub-pages
1.2.0: Addes pass-thru support (if roll does not contain a dice formula then it just passes the roll to chat)
1.1.0: Added support for loading embedded files in layout and data so that contents can be split along multiple files
1.0.1: Bug fix for cache issues
1.0.1: Make certain data types public to support Config Editor
1.0.0: Initial release

Install

Install using R2ModMan or similar.

Usage

1. Select a mini for which you want to see the character sheet and for which one is defined.
2. Press the keyboard shortcut for toggling the character sheet or select Character Sheet from the Info radial menu.
3. Depending on the configuration the chartacter sheet will close after making a roll or can be closed using the toggle character sheet keyboard shortcut.
4. Click on a element associated with a roll to make a roll.

Default Configruation: LCTRL + S

As always, Jon is the sample. Name a mini Jon and then activate the Embedded Character Sheet.

Charcter Sheet vs Heads Up Display

The Embedded Character Sheet plugin has a configuration, which can be changed using R2ModMan's Edit Config, which determines if the ECS layout closes after a selection is made. By default this setting is set to true and thus the character sheet will close after a roll is clicked on. However, in some case, such as when build a heads up display type interface, it may be desirable for the character sheet to stay open. In such a case this setting can be changed. Note: This change is a local change and requires all players to make the change.

Roll Method

The roll method can be selected between Talespire dice (use Auto Roll plugin if you want them to be rolled automatically) or Chat Roll dice. To change this setting, go to the R2ModMan setting for this plugin, find the correspoding setting, change it and save it. Next time Talespire is run, the roll method will be changed according to the setting.

Editing

To edit values of a character sheet entry, click it with the middle mouse button. This will open a prompt asking for the new value (with the current value as the default). Only the last place holder in the roll can be edited this way. The results are written back to the character data file (and distributed to others).

Fast Change Editing

Placing the mouse over an element and using the Decrease or Increase keyboard buttons causes the value to decrease or increase my one. Repeating the process allows modification of values by more than one. This functionality employs a fast local change system where repretitive changes to the value (to decrease or increase it by multiple points) where the value updates locally only and is only distributed (and related values updated) when the user stops adjusting the value.

There are a number of requirements for this functionality to work:

1. The content of the element must be a placeholder and only a place holder (e.g. {HP})
2. The roll of the element must include that placeholder. For elements that aren't intended to roll copy the content.
3. The value of the placeholder must be a numeric value.
4. The element id of the element must match one or more of the patterns in the Fast Change Elements List configuration.

Fast Change Elements List Configuration

The Fast Change Elements List configuration is a string of one or more patterns separated by a comma. In order for an element to support the fast change property the element's id need to match one or more of the Fast Change Elements List patterns.

Since the element id is currently used only for this feature, the default setting for the list is FastChange and any element that meets the other conditions can be turned into a Fast Change element by giving it an id of FastChange in the layout. However, in the future the id may be used to uniquely identify element and thus it is better to use unique ids for element and then provide a while card pattern for the Fast Change Elements List.

\* = Any number of characters (including none) ? = Any one character

For example, elements could be name such as AttribSTR_FastChange, AttribDEX_FastChange, etc and the Fast Change Elements List pattern could be \*_FastChange

Jon Show Option

Once a layout and/or character data is loaded, it is cached to make re-opening the character sheet quicker and not require disk access. However, in some cases this is not desirable. For example, if the character has leveled up the character data can be updated outside of Talespire but with the cache, Talespire would not see the changes until the next time it runs.

To get around this, there is the Jon Snow option. Pressing the corresponding keyboard shortcut causes, like the famous quote from the series, the plugin to forget all its cached information and thus re-read any layout and/or character data when it is needed. So, for example, after updating the character sheet data (outside of Talespire), you can use this option to forget the cached version and thus, when the character sheet it opened, it will load the updated version.

Default Configruation: RCTRL + S

Configuration

Similar to Character Sheet Plugin the Embedded Character Sheet Plugin uses the concept of Layout and Character Data. While you can use Layout for the actual entries (and have a Layout for each character sheet) the usual concept is to make a layout with place holders for the actual data (which is common to all or most minis) and then place the actual data into a character data file.

Unlike Character Sheet Plugin which used only one layout at a time, Embedded Character Sheet can use many layouts at the same time so, for example, player minis can use a full character sheet layout while monsters can use a stat block layout.

In general that means you need 2 or 3 files but then adding additional characters requires only one file. The three files are:

1. Layout file (required - common to multiple minis)
2. Backgound image (optional - common to multiple minis)
3. Character data file (required - per mini)

The Place Holder Concept

The layouts and character data sheets use a concept of place holders. Instead of the layout providing values directly (which would mean it could not be re-used), the layout defines place holders which are then replaced with actual values when the layout is used by a specific character. This allows the layout to be used for multiple characters making it easy to update the layout file without having to edit all of the character files that use it.

There is no specific enforced format for a place holder but place holders should be unique so that they don't show up in regular text. For example, a place holder of wis is not a good place holder because if the layout wants to write out the world wisdom the first portion of it would match the place holder and thus get replaced. The typical convention is to use brace brackets around place holders. If the place holder is {wis} then it will not be found in the word wisdom and thus such a word will be possible to display.

The place holders can be nested to make calculations easier. For example a place holder of {Attack1} could resolve to 1D20+{BAB}+{STR} which then resolves to 1D20+7+4.

Layout File

The layout file defines where things are displayed on the character sheet using a JSON file. The name of the layout file needs to be as follows: EmbeddedCharacterSheet.Layout.Name.csl where Name can be any unique identification for that particular layout. For example: EmbeddedCharacterSheet.Layout.StatBlock.csl

The contents are as follows:

{
  "background": "Sample_3.5E.png",
  "position": {
    "x": 10,
    "y": 40
  },
  "size": {
    "w": 293,
    "h": 512
  },
  "elements": [
    {
      "type": 0,
      "position": {
        "x": 52,
        "y": 88
      },
      "size": {
        "w": 230,
        "h": 10
      },
      "style": "fontSize=12|fontStyle=1|normal.textColor=220,220,200",
      "content": "{CharName}",
      "roll": ""
    },
    {
      "type": 0,
      "position": {
        "x": 52,
        "y": 116
      },
      "size": {
        "w": 70,
        "h": 10
      },
      "style": "fontSize=10|fontStyle=2|normal.textColor=128,64,32",
      "name": "Concentration",
	  "target": "{ConPass}",
      "content": "{ConMod}",
      "roll": "1D20+{ConMod}"
    },
    {
      "type": 0,
      "position": {
        "x": 52,
        "y": 116
      },
      "size": {
        "w": 70,
        "h": 10
      },
      "style": "fontSize=10|fontStyle=2|normal.textColor=128,64,32",
	  "name": "Luck",
      "content": "{LuckDie}",
      "roll": "1D{LuckDie}"
    }
  ]
}

Where background is the name of the background image. Empty string (default) is no background image is desired. Where position is the top left corner of the character sheet. Where size is the width and height of the character sheet. Where elements is an array of GuiElements that define all of the visual elements of the character sheet (besides the background).

A GuiElement has the following properties...

The type determines the type of element (0=label, 1=button, 2=link). Currently both 0 and 1 render the same, for 2 see below. The position determines the position of the element on the character sheet (with respect to the character sheet not screen). The size determines the width and height of the element on the character sheet. The name determines what name is used in the roll (defaults to content if not set). The target determines what target value is added to the roll name (defaults to not used if not set). The content determines what is displayed. If the content is surrounded by # characters, it is treated as a texture file name and displays the corresponding image. Otherwise it is treated as text with all placed holders replaced. The roll determines what is rolled when the element is clicked. If it is an empty string (default) then nothing happens when the element is clicked. Otherwise the content, after replacing all place holders, is sent to the corresponding rolling method. It is important that the roll resolve to something in the form #D#+# or #D#-#. This is especially true when using the Talespire dice rolling method. The Chat Roll method may support other formats in addition to the ones listed but sticking to the formats indicated means the roll will be compatible with both rolling methods. The roll parameter does support multiple rolls by using a slash to separate rolls. For example: 1D20+7/2D6+3 Roll supports multiple dice types but each with only a single modifier except for the last listed die type. For example, 1D100+3+1D10+3+7 is legal since the multiple modifiers are at the end but 1D20+7+3+1D4 is not. The last would need to be rewritten as 1D20+7+1D4+3 or 1D20+1D4+7+3. The style determins the apperance of the element and is used to override the (configurable) defaults. It is a pipe delimited string of GuiStyle proeprties (see Unity documentation for all GuiStyle properties). The most common use of this is to change the color, size and style of the element text. When using this method to change color, three formats are accepted: color name, RGB and ARGB. For color name just eneter the color name like "red". For RBG and ARGB list each of the components (as a byte) separated by commas.

Note: Rolls can resolve to a #D# specification with any number of numeric bonuses and/or penalties. The total modifier is calculated before passing the roll to the rolling method. For example, 1D20+3+2-5 is a valid roll specification. Note: The above shows 2 GuiElements but the actual layout will have many more elements. Note: In rolls / is used for roll separation and thus cannot be used for division. Use & or ÷ (ALT+246) instead.

The following rules are used to construct the named roll:

1. If name and target is not set, roll is talespire://dice/content:roll
2. If name is set but target is not set, roll is talespire://dice/name:roll
3. If name is not set but target is set, roll is talespire://dice/content (target):roll
4. If name is and target are set, roll is talespire://dice/name (target):roll

Character Data

The character data file defines the values of the various place holders in the layout file. This allows one layout file to be used for multiple characters without needing to copy the whole layout contents into each character sheet. This means that when an update is needed, the layout file can be updated and the change will be automatically applied to all characters that use the layout instead of having to update each character sheet for each character. The filename of the character data need to be as follows: EmbeddedCharacterSheet.Data.MiniName.csd where MiniName is the name assigned to the mini whose character sheet is being looked up. For example: EmbeddedCharacterSheet.Data.Jon.csd

The contents of the character data file is as follows:

{
  "layout": "5E",
  "stats": {
	"{CharName}": "James Bond",
	"{CharRace}": "Human",
	"{CharClass}": "Spy",
    "{STR}": "2",
    "{DEX}": "4",
    "{CON}": "2",
    "{INT}": "3",
    "{WIS}": "2",
    "{CHA}": "4",
  }
}

Where layout indicates the layout that the data is plugged into. This property is required. Where stats is a list of place holder names and their values.

It is important to understand that layout file and character data files are completely game independent. That means that the stat values in the character data file is comepletely up to the user. The only stipulation is that the character sheet file must contain a a value for each place holder used in the referenced layout. So if the layout has a place holder for {PicklesPerDay} the character data file that uses that layout needs to define that place holder value even if just as a empty string. As such the above stats are an example which suggest a D&D style game but this plugin can equally be used for any dice rolling game system.

Texture References

If the contents of an element is in the format #x# then the content is treated as a texture name with the file x. For example, #BackButton.png# would render the element as a texture whose content is obtained from the file BackButton.png.

Layout Links

Elements of type 2 are layout links. These allow the character sheet to use sub-pages. When these elements are clicked instead of the roll property being used to determine the roll, it instead determines the suffix applied to the layout. An empty roll means to use the main layout page (as ECS did prior to this feature). A non empty value adds the value to the layout name. For example, a type 2 element with a roll value of .Equip clicked when the main layout was 5E would result in a layout name of 5E.Equip.

Each subpage layout is created the exact same way as the main layout except the file name includes the suffix as part of the regular file name for layout. Thus there will be one file for main layout and a file for each sub-page.

The user has full control of these link elements since they are elements like any other. This means it is up to the user if the main page and all sub-pages will have the same nav bar (in which case see the embedded files section below to simplify such a configuration) or if the sub-pages will just have links back to the main page, or some other combination.

Embedded Files

Both the layout file or the character file now supports insertion of content from other files. To do this, enter the following syntax:

{#filename#}

This will take the contents of filename and insert it into the file at the location where the reference is placed. For example, the layout file could now be:

{
  "background": "Sample_3.5E.png",
  "position": {
    "x": 10,
    "y": 40
  },
  "size": {
    "w": 293,
    "h": 512
  },
  "elements": [
{#EmbeddedCharacterSheet.Layout.35E.CharSection.txt#}  
{#EmbeddedCharacterSheet.Layout.35E.Abilities.txt#}  
{#EmbeddedCharacterSheet.Layout.35E.Attacks.txt#}  
  ]
}

This embedded file format has two automatic replacements available:

{NAME} = The mini name. Typically used with the character data file so that the embedded files can be character specific. Such as:

{#EmbeddedCharacterSheet.Data.{NAME}.CharSection.txt#}

{LAYOUT} = The layout. Typically not needed since the layout is layout specific and thus the value can be hard coded.

This functionality is a straight search and replace and thus the location of the embedded file reference is important. For example, in the above sample, moving the embedded file references outside of the "elements" section would not work because the content of the files needs to be inserted into the elements section.

Character Vs Group Data

Most of the documentation refers to a character sheet for a mini or character implying a one to one relationship. However, this is not necessarily true. As implied above by the file naming requirement, the plugin connects the selected mini to a character sheet by the mini name. As such, you can have a group of enemies, for exmample, goblins use the same character sheet by naming them all the same name, such as goblin. Then you can make a character sheet for goblin and no matter which goblin you select the same character sheet will be displayed. If you need to distinguish between them (and you can't by name because of this plugin), you can use GM Notes to place text above the minis.