Overhead Notes Plugin

This unofficial TaleSpire plugin for adding text to minis and converted-props. Options are available for player visible text above the mini and GM only text beside the mini. A mini can have either or both.

This plugin replaces the GM Info Plugin and the States Plugin by using the streamlined architecture of GM Info Plugin 3.0.0 and combining it with the functionality of States Plugin also implemented using the streamlined architecture.

Change Log

1.4.0: Updated for compatibility with VR Taleweaver update
1.1.0: Added clear notes function
1.0.1: Improved auto height detection
1.0.1: Added option for manual height
1.0.1: Unified visibility and rotation updates
1.0.0: Initial release

Install

Install using R2ModMan or similar.

Usage

Add Player Note

Press the shortcut key to activate the Player Note dialog or select the Player Note from the right click radial context menu. Enter the desired note. Commas get translated to new lines. The text will appear above the mini. If any of the keywords in the text matches the (optional) colorization file, the replacements will be processed. This typiclaly allows keywords to be colorized.

To erase a Player Note, open the Player Note dialog (same as above) and then press the Clear button.

Player Notes are visible to all players (and the GM).

Default: LCTRL+N

Add GM Note

Press the shortcut key to activate the GM Note dialog or select the GM Note from the right click radial context menu. Enter the desired note. Commas get translated to new lines. The text will appear beside the mini. If any of the keywords in the text matches the (optional) colorization file, the replacements will be processed. This typiclaly allows keywords to be colorized.

To erase a GM Note, open the Player Note dialog (same as above) and then press the Clear button.

GM Notes are visible to the GM only. Any player currently in the GM role will see these notes.

Default: LALT+N

Clear All Notes

Pressing the shortcut to activate this functions clears both the player and GM notes on the selected mini. There is no undo so be careful with this feature.

Default: RSHIFT+N

Re-Apply Notes

Due to the way the streamline architecture handles board loads, this function should not be necessary. However, if the notes fail to show, you can try re-applying them with this function.

Default: RCTRL+N

Performance

On Startup

When a board loads, the assets are not immediately available. This means that when a board loads the plugin needs to try to figure out when all of the assets have properly loaded. This is basically a trial and error process. There are two configruations associated with this process. The issue is that if the plugin tries to hard, it will eat up all the CPU and TS will never actually be able to complete the board load (or it will take a very long time). If the plugin doesn't try hard enough then it will take a long time after the board load before all of the texts appear. The configurational parameters are:

Update Interval = The time that the plugin waits before trying to process texts. If it is unable to process at least one text then it will try again, to do the remained, after the same update interval. It will continue to try to process the board load texts at this interval until all have been processed. Setting this value too low means that the plugin is constantly trying and not leaving CPU to TS to actually process the board load. Setting this value too high means text will take a long time to load.

Update Throttle = This is the maximum number of text updates that the plugin performs per Update Interval. Setting this value high will process more text per udpate cycle but use more CPU. Setting this value too low will mean that it take a long time for text to be updated on board load.

On high performance devices, the Update Interval can be set low (e.g. 1 second) while the Update Throttle can be set high (e.g. 100).

On low performance devices, the Update Interval can be set high (e.g. 30 seconds) while the Update Throttle can be set low (e.g. 5).

On mid ranage performance, the user can play with the two settings to find a setting that works.

It should be noted that the board itself has a factor in this so you may need different settings for boards that have lots of minis with text as opposed to boards that have very few minis with text. So adjustment may be necessary based on the board for optimal performance.

The Duration After Which Unrendered TextBlock Are Ignored setting determines how long the plugin tried to apply TextBlock before giving up. This setting, in seconds, should be set large enough to allow a large board to fully load but not too high so that the plugin doesn't try for too long if there is an actual faulty asset.

During Play

The plugin only performs visual updates when necessary. While idle, the update loop does nothing but check for the keyboard triggers and for mouse movement.

When GM Info is added to an asset it is always fully refreshed.

When the GM/Player Mode changes, the visibility of all assets is updated.

When the mouse is dragged or when the keyboard is used, the rotation of assets is updated based on the update setting set in the configuration for the plugin. These settings are follows:

None = Text Blocks rotation (to face the screen) is not done. Selected = Text Blocks rotation (to face the screen) is done to the currently selected mini only. All = Text Blocks rotation (to face the screen) is done to all mini that have Text Blocks.

This setting can be further used to control performane. With on-demand updates only this plugin should run fairly smooth on most device but this configuration can be used to tweak performance. If you have a high performance device then set this option to "all". This will keep all Text Block rotated towards the screen at all times. If you have a medium performance device, try the "selected" option. This will lower the CPU requirement but at least keep the selected mini's Text Block facing the screen. If you have a low performance device then try the "none" setting. This will not rotate Text Block to face the screen but will use the least amount of CPU.

Appearance

Color

There are two settings for the color of the text blocks.

The Base Text Color setting indicates the color of the color of the text color font color. It is either a 6 or 8 digit Hex string in RGB or RGBA format.

The Background Highlight Color setting indicates the highlight color of the text. This is somewhat similar to background but is not a true background. It is implemented using the functionality which means the highlight is on top of the the regular text and thus affects both the background and font text color. The value must be an 8 digit hex string in RGBA format. The highlight must not be totally opaque or the text will not be visible. Use very low values for the opacity to start off with like 10 and adjust from there.

Please note that if the colorization file is used, the replacements (assuming they include color codes) override the base font color configured in the settings.

Text Position

There are two methods for determining the position of the Player Notes: Automatic (default) and Manual. In automatic mode, the plugin tried to determine the bounds of the mini to determine the upper most position of the mini and place the bottom of the text at that position. The plugin uses a number of different ways to determine the bounds of the mini to support differnet core and custom minis. However, in some cases it is not possible to properly determine the bounds of the mini and thus the text appears either inside the mini or a large distance above it. In such cases, it is possible to switch to manual mode where the position of the text is always at a fixed height above the mini. This makes the text position uniform but can look odd for minis that are small.

Automatic Mode Settings

Ensure that the Height Of The Tallest Medium Sized Mini Or 0 For Auto setting is set to 0 to use automatic mode.

The Auto TextBlock Height Offet setting can be used to somewhat adjust automatic determined text positions. If the automatic determined text position is two low or two high for all (or most) minis, this setting can be used to apply a fixed offset to all minis by the specified amount. Negative numbers lower the text. Positive numbers raise the text.

The Auto TextBlock Height Multiplier setting can be used to apply a multiplication factor to the automatic determined height instead. Values above 1 increase the automatic determine height while values between 0 and 1 decrease the automatic determine height.

These values can also be used to adjust the height for different screen resolutions.

Manual Mode Settings

Set the Height Of The Tallest Medium Sized Mini Or 0 For Auto setting to a value (such as 1.65) to place all text blocks at that height. If text blocks are applied while a asset is base radius 1, then scaling the asset should scale the text block with it.

Per Line Adjustment

The Text Offset Per Line setting determines how much the text is offset for each line in the text.

Known Bugs

1. Since the GM Notes are to the side, even though they rotate to face the screen, they can be hidden by the mini if the camera is rotated around the mini.
2. If the shortcut key for a feature does not seem to work, try switching to a different key combination.