Light Plugin

This unofficial TaleSpire plugin is for adding custom light sources to your TaleSpire game. The custom light options are accessible from the mini radial menu under an new Light menu. Menu includes a None option to extinguish the current light. The plugin comes with a few sample lights but the plugin is easy to configure with your own light options and will automaticlaly enumerate those options in the radial menu.

Provides access to ambient, point and spotlight which can be placed at an offset to the mini and their intensity, range, color and angle (for spot light) can be set.

Added light causes object to cast shadows. Added light produced hard light limits.

Change Log

2.7.0: Updated for compatibility with BR Taleweaver update
2.6.0: Migarated to Asset Data Plugin (instead of Stat Messaging)
2.6.0: Updated for compatibility with BR Slab Browser update
2.5.1: Removed unused dependencies. No plugin change.
2.5.0: Modified LightSpecs structure to better support LightEditor Plugin
2.5.0: Removed Light Editor (moved to its own Light Editor Plugin)
2.4.1: Bugfix with repeated Extinguish (None) option
2.4.0: Runtime editor for editing lights
2.4.0: Use LightSpecs.json over LightTypes.json when both are present
2.3.0: Supports runtime limited configuration reload
2.2.0: Region independent version
2.0.0: Fix for BR HF Integration update
1.7.3: Updated light is added to radial menu if not already present
1.7.2: Added SaveConfig method to dump lights configuration to KVP file
1.7.1: Bug fix: Exposed method and lights property are made static
1.7.0: Added UpdateLight() method to change light properties locally
1.7.0: Exposed lights dictionary for easier configuration file manipulation
1.6.3: Fixed bug with access to Radial UI menu when no hierarchy is defined
1.6.2: Fixed bug which prvented GUI Menu functionality
1.6.1: Fixed bug that did not allow use of KVP file without JSON
1.6.0: Modified for direct light object access
1.6.0: Modified configuration file format
1.6.0: Includes automatic conversion of legacy configuration to new format
1.5.0: Added support for hierarchical light menus using GUI Menu Plugin
1.4.1: Bug fix for issue which prevented lights from being removed
1.4.0: Added optional properties intensityMin and deltaMax for two flickering light options
1.3.0: Added hiddenBase option
1.2.0: Added GM only light option (via onlyGM property)
1.2.0: Light menu does not show options for mini that the player does not own
1.2.0: Changed sight light distribution so that it can be triggered by player or GM
1.1.0: Added sight light option (light only visible by mini owner and GM)
1.1.0: Removal of light now removes Stats Messaging key (as opposed to making it blank)
1.0.0: Initial release

Install

Install using R2ModMan.

Usage

The plugin can be used out-of-the-box as soon as it is installed with the sample lights but typically the GM will want to configure his/her own light settings appropriate for the game.

Right click the mini to open the radial menu. Select the (new) Light menu. The sub-menu will enumarate all of conmfigured lights and includes a None option to turn off the light. Select one of the options to turn on the corresponding light. If a light is already on, the light will switch to the selected type. If no light is currently on, the selected light will be turned on. Select the None sub-menu option to turn off the light.

If using the Legacy configuration, plugin will convert it automatically to the newer JOSN format. Please note that the KVP format is no longer supported.

Limited Configuring Reload

While Talespire is running with this plugin, it is possible to do a limited configuration reload. This is idea for a GM who is setting up different lights and needs to make adjusttments to the lights configuration. Using this feature, reloads the lights configuration with the following limitations:

1. The new configuration is not automatically re-applied to all minis. If you want to use the new configuration on any particular minis, you will need to turn its light of and back on again to reapply the new configuration.

2. Lights cannot be added, only modified. If new lights are added to the configuration they will not show up in the menu until Talespire is restarted. If lights are removed from the configuration they will still appear in the lights menu and will cause errors when selected.

To trigger a configuration reload, use the corresponding keyboard key (RCTFL+L by default).

Runtime Lights Editor

1. Select a mini which has a light attached
2. Press the Config Editor shortcut (default RCTRL+K)
3. Change values in GUI Config Editor
4. Press Save
5. The updated values are saved to the LightSpecs.json file and existing lights are updated

This function uses LightSpecs.json configuration file (not the legacy LightTypes.json)

Configuring Lights

The plugin uses one of two different JSON configurations. Both configurations have the same information but legacy version has more of a flat configuration whereas the new configuration used a more structured JSON format.

Legacy "LightTypes.json":

[
  {
	"name":"Torch",
	"lightType":2,
	"iconName":"torch.png",
    "onlyGM": false,
    "menuNode": "",
    "menuLink": ""
	"intensity":0.03,
	"color":"255,255,128",
	"range":2.0,
	"pos":"0,0.75,0",
	"rot":"90,0,0",
	"spotAngle":15.0,
	"flicker": true,
	"intensityMin": 0.025,
	"deltaMax": 0.05
  },
	...
]

Updated "LightSpecs.json":

[
  {
    "name": "Ball(10')",
    "specs": [
      "type=2",
      "color=200,200,200",
      "range=3",
      "spotAngle=10",
      "shadows=2"
    ],
    "position": [ 0.0, 1.5, 0.0 ],
    "rotation": [ 90.0, 0.0, 0.0 ],
    "behaviour": {
      "flicker": false,
      "intensityMin": 0.0,
      "intensityMax": 0.05,
      "deltaMax": 0.0,
      "sight": false,
      "hiddenBase": false
    },
    "menu": {
      "iconName": "ball.png",
      "onlyGM": false,
      "menuNode": "",
      "menuLink": ""
    }
  },
  ...
]

.menu.iconName=ball.png

The iconName property determines the name of the icon file to be used for the light.

.menu.menuNode=

The menuNode property is optional and determines which menu the light shows up if sub-menus are being used. If all iconNode properties are empty then all lights will show up in a single radial menu. If menuNode is set then the light when show only when that particular menu is being displayed (see below).

.menu.menuLink=

The menuLink property is optional and determines what menu is shown if the corresponding menu item is selected. This property is only used when using multipe menus (i.e. menuNode is set).

.menu.onlyGM=false

The onlyGM property is used to determine if players can see the corresponding light option or if it the light menu item is only visible to the GM. Please note this applied to the menu item and not the light itself. You can either make the link to the menu onlyGM in which case only the GM will be able to access that menu or you can set individual menu items as onlyGM in which case only those items will not be visible to players.

.behaviour.sight=false

The sight property is used to determine if the light is only visible to the GM and the mini owner (true) or if it is visisble to all players (false). Typically used to implement various visions like darkvision.

.behaviour.hiddenBase=false

The hiddenBase property is typically used with onlyGM lights to produce environment lighting like fire pits, lanters, chandeliers and other effects without showing the mini to which the light is attached. Saves the GM the step of having to hide the mini and also erases the name of the mini so that the name does not show up in the GM view (and clutter the screen in cases where there are a lot of lights).

.behaviour.flicker=false

The flicker property determines if the light is steady or if it flickes. There are two possible flicker effects. When set to true a light can use either flicker effect or both. When the values of intensityMin and intensityMax are different and flicker is true, the intensity of the light will shift to random values between the min and max intensity. When deltaMax is not 0 then light will also shift in the x and y direction, randomly, up to the deltaMax distance.

.behaviour.intensityMin=0 .behaviour.intensityMax=0.05

These properties are used to set the mininum and maximum intensity for a flickering light. When flicker is false, intensityMax will be used for the light intensity.

.behaviour.deltaMax=0

This property determines how much the light can shift, randomly, from its specified centre when flicker is true. Not used when flicker is false.

.position=[0,1.5,0]

This property determines the position of the light with respect to the mini to which it is attached.

.rotation=[90,0,0]

This property determines the rotation of the light with respect to the mini to which it is attached. The default value of 90,0,0 is a light that is pointing straight down.

.specs=["type=2", "color=200,200,200", "range=3", "spotAngle=10", "shadows=2"];

The specs property is an list of Unity Light properties and their values. Any Unity Light property whose value can be JSON serialzied and JOSN deserialized can be added into the specs list with its JSON value. The above settings are the settings that were accessible in the previous version of the plugin with shadow being an additional property (previously hard coded to 2). It should be noted that while the value of specs is a JSON value, it is a array of strings, and not object properties, with each key value pair being a string in the array.

The type property determine the type of light. 0=Spotlight, Directional=1, Point=2, Rectangle=3, and Disc=4. Rectangle and Disc may not be fully supported at this time. Spotlight creates a cone from the position point in the direction of the rotation with the angle of the cone defined by spotAngle. Directional creates a lightbeam from the position in the direction of the rotation. Point creates light in all direction from the position point.

The color property determines the color of the light in R,G,B format. Each R, G and B value ranges from 0 to 255. The R, G and B values are separated by commas.

The range property indicates the maximum range of the light.

The spotAngle property determines the angle of the cone of the spot light.

The shadows determines the type of shadows produced. 0=None, 1=Hard, and 2=Soft.

As indicated above the new plugin interpreter allows any property of the Light object to be specified as long as the value can be JSON serialized and JSON deserialized. Additional key value pairs can be added as string entries to the array to set additional properties. See Unity Light object for more details on what additional properties can be set.

Configuring Light Menus

There are two optional settings which can be used with light configuration to place them in hierarchical menus (menus with sub-menus) instead of the flat (one level) Radial UI menus. These properties are: menuNode and menuLink.

menuNode is used to indicate which menus the light belongs to. Each unique menuNode name is a different menu. Items (lights) that should appear in the same menu have the same menuNode. The main menuNode is always called Root. When the user clicks on the Light icon in the mini radial menu, it will cause the Root menu to be opened. The Root menu can contain a combination of light selections and menuLinks (which allow access to other menus).

menuLink is used to indicate the menuNode name of the menu that is to be navigated to when this selection is chosen. For a menuLink entry only the name, iconName, onlyGM, menuNode and menuLink settings are significant. All of the light settings are irrelevant for a entry with a menuLink since these entries are used to make navigation buttons as opposed to light selections.

By editing the R2ModMan configuration for the plugin, you can change the text color of link entries, text color of selection entries and if the menu is a centre menu (menu appears in the middle of the screen) or a side menu (menu slides out of the right side of the screen).

Configuring Update Interval

The R2ModMan configuration for the plugin contains an value which determines how often the light flicker is updated. The higher the number the less frequently the light flicker is updated and thus the less flickering. The smaller the value the faster the flickering will change. Min 0.

Use As A Dependecny Plugin

To trigger the Light effects from another plugin write the appropriate values to Stat Messaging using the light plugin guid as the key and the Cid of the creature to which the light is attached.

Limitations

1. Each mini supports only one light at a time. But you can always add a mini with a second effect and even use Grab/Drop plugin to grag it around automatically.

2. When a mini is not owned, the top level Light menu still shows but has no sub-options.

3. Config Editor has no Cancel option at the moment