Custom Dice Pack Plugin

This unofficial TaleSpire plugin allows truely custom dice to be brought into Talespire. Includes both cosmetic custom dice and true custom dice allowing dice which don't roll numbers but symbols/keywords instead.

Video: https://www.youtube.com/watch?v=GpkJeDCAoWg

Change Log

2.0.2: Bug fix for multiple compatibility issues with proximity rolling
2.0.1: Bug fix preventing dice spawn in some cases
2.0.1: Added dice icons for demo dice
2.0.0: Added GUI for spawning custom dice in session
1.3.1: Added option to always use custom format for result for message and chat
1.3.0: Custom dice result message when a true custom die is rolled 
1.3.0: Identification of custom dice while in the tray (as opposed to a weird modifier)
1.2.0: Added support for custom numeric keywords (dice with values other than the side value) 
1.1.0: Added support for multiple keywords for true custom dice
1.0.1: Corrected demo save dice file. No plugin change.
1.0.0: Initial release

Install

Use R2ModMan or similar installer to install this plugin.

Usage

Note: Do NOT use this plugin with Save Dice Plugin. This plugin implements that code.

This is an initial release of the Custom Dice Pack Plugin which does not have all the bells and whistles that, hopefully, the plugin will eventually have. Once of the biggest limitation, current, is the lack of a GUI to select and bring out custom dice. As such, at the moment, custom dice are brought out by editing a simple configuration file.

Using Custom Dice Session Spawn

When Talespire is running, the Custom Dice Tray can be accessed using the keyboard shortcut. Default keyboard shortcut is:

F11 = Open Custom Dice Tray

Opening the Custom Dice Tray will open the initial menu which shows the different dice collections. All custom dice must be part of a collection or they will be placed in a Default dice collection. This is necessary because the menu space is limited and the user may want more than custom dice than is available through a single menu.

By default the menu is a slide out menu on the right hand side but the plugin provides a configuration to switch this to a center screen menu instead. In addition to the dice collections, an Close door icon can be used to close the custom dice tray.

To spawn a dice, select once of the dice collection. This will show all of the available dice in that collection. Click on a die to spawn it. Once the die is spawned it is recommend to click the mouse somewhere on the board because currently there is a quirk where the die gets stuck to the mouse pointer and will fly to whereever the mouse is first clicked.

The dice try remians open at the selected collection to allow multiple custom dice to be spawned. Currently dice are always spawned one by one. If you need to spawn a large volume of dice consider using the Auto Spawn feature detailed below.

To move back to the dice collection menu, use the Back button. To close the cutsom dice tray use the Close door button.

Custom dice spawned using this method are not automatically saves but they can be using the usual keyboard shortcut for saving the dice configruation.

Using Custom Dice Auto Spawn

All custom dice use a core die as the base. This dictates the number of sides that the custom dice will have. While there are different ways to do it, one of the easiest ways to use custom dice is to spawn regular dice and then make a small edit to the dice save file to turn them into custom dice. This process assumes you have already created the custom dice and now you just want to use them. If this is not the case, see the next section for creating custom dice.

1. Start Talespire
2. Pull dice out of the dice tray as usual
3. Save the dice configuration using the corresponding keyboard shortcut (default ``RCTRL``+``D``).
4. Exit Talepire

Now, in your Custom Dice Plack Plugin install folder you should see SaveDicePlugin JOSN filem corresponding to your campaign. Open this file in any text editor. This file will have a section for each die that was save. Each section will look similar to this:

    {
      "name": "numbered1D6(Clone)",
      "resource": "numbered1D6",
      "customization": "",
      "pos": {
        "x": -2.43248773,
        "y": 0.1478481,
        "z": 1.16910255
      },
      "rot": {
        "x": -0.6295764,
        "y": -0.6274181,
        "z": 0.321368575,
        "w": 0.3266534
      },
      "gmOnly": false
    },

To customize the die, enter the name of the custom die in the customization field. That is it! Now when you load the board (any board in the Campaign) the dice will be restored and any custom dice will be customized.

Creating Custom Dice

In order to use custom dice, we first need to create them. This is not a difficult process thanks to the files provdied with this plugin. To create custom dice, we edit the CustomDicePacks.json file found in CustomData/CustomDicePacks folder of the plugin install folder. The file can be edited with any text editor.

There are two types of custom dice that can be made: cosmetic and true custom dice. Cosmetic custom dice, as the name implies, function just like core dice but they look different. It should be noted that the dice faces are part of the customization and thus you can have a cosmetic die with symbols on it which rolls regular numbers (e.g. a Klingon die or a Traditional Chinese die). However, the key with osmetic custom dice is that they still roll the regular dice numbers appropriate for the dice base being used (e.g. 1 to 4 for a D4 base, 1 to 6 for a D6 base and so on). True custom dice, on the other hand, don't roll numbers. They roll keywords. Each side of the dice is associated with a keyword and that keyword is the result when that side is rolled. The dice can use any number of keywords up to each side using a unique keyword to many sides re-using a keyword. When multiple such dice are rolled, the count of the kaywords is tallied.

Cosmetic Custom Dice

In the CustomDicePacks.json make an entry such as the following for each cosmetic custom die that you want to create. It is important to note that creating a custom dice is not making an instance of it. If you want 5 copies of the same custom die, it is created only once in the CustomDicePacks.json but is referenced multiple times in the save dice file (see above).

	"lava-d4":
	{
		"dicePack":"basedice",
		"diceBase":"d4",
		"diceCollection":"Lava",
		"diceTexture":"D4_Lava.png",
		"diceModifier": 0,
		"sides":
		{
		},
		"images":
		{
			"collection": "LavaCollection.png",
			"icon": "LavaD4.png",
		}
	},

The above definition creates a custom die called lava-d4. The shape of the die is taken from the basedice pack and uses the d4 shape. The die is then textures with the texture D4_Red.png. This die is part of the "Lava" dice collection. The dice total uses +0 modifier. The sides list is left empty and images list can either be left empty in which case it will us ethe default icons or can have a collection and icon entry indicating the name of the texture that should be used for the collection and die in the custom dice tray. Leaving the sides list empty is what determines the die to be a cosmetic custom die. Leaving the sides empty, tell the plugin to use the default sides for the base die type (in this case D4).

The basedice file (actually called basedice.cdp) had models (shapes) for all of the base dice (D4, D6, D8, D10, D12 and D20). As such, normally the dicePack can always point to basedice. However, some users may want to customize the shape of the dice. In such a case, they can create an asset bundle with the D4, D6, D8, D10, D12 and D20 prefabs and use that instead. While asset bundles don't usually have an extension, an "cdp" (custom data pack) extension needs to be added for the plugin to recognize the purpose of the file and to avoid CALP from registering the file as an asset. It should be noted that the dice still roll based on the shape of the base die so making, for example, a D30 shape will not work. However, the user could, for example, make the faces of the die bumpy. This would not affect the roll (since the shape is cosmetic only) but could make some interesting dice looks.

The diceBase should always be d4, d6, d8, d10, d12 or d20 unless you are using a custom dice pack. However, even in a custom dice pack it is recommended to use these names to make it obvious which base die is being used for the roll.

As we can see, making a custom dice is really easy but there is a catch, we still need to make the texture file with the custom look. Luckily the plugin provide a bunch of template files, one for each die type, for making your own textures. These templates indicate which part of the texture image corresponds to each roll value. It is importnat not to mix these up. Otherwise the rolled die side and the rolled value will not match up.

Once you have finished making the texture, place it in a File Access Plugin legal location and you are ready to add copies of the custom dice to your save dice file (see section above).

True Custom Dice

True dice allows the specification of other values for each dice side other than the traditional side nummbers. It should be noted that at the moment custom sides are treated a keywords and not numbers so creating a custom die with different numbers will treat such numbers as keywords and tally them instead of totaling them. Normally true custom dice are used to create dice which do not use numbers. For example, the Dragon Dice game uses dice with various amounts of attack, defense and magic symbols. Multiple such dice are rolled and the count of each is tallied.

Creating true custom dice is very similar to creating cosmetic custom dice except that there are a few additional properties to configure. A sample, true custom die configuration, in the CustomDicePacks.json might look like:

	"rps-d6":
	{
		"dicePack":"basedice",
		"diceBase":"d6",
		"diceCollection":"RPS",
		"diceTexture":"D6_RPS.png",
		"sides":
		{
			"1":"Paper",
			"2":"Scissors",
			"3":"Paper",
			"4":"Scissors",
			"5":"Rock",
			"6":"Rock"
		},
		"images":
		{
			"collection": "RPS_Collection.png",
			"icon": "RPS_D4.png",
			"Paper":"Paper.png",
			"Scissors":"Scissors.png",
			"Rock":"Rock.png"
		}
	},

The above example is a Rock Paper Scissors D6 with each being represented twice on the die. The fields common to the cosmetic custom die all work the same, so in the above eample it is a custom die called rps-d6, it uses the d6 shape in basedice and uses the D6_RPS.png for the texture. However, we can see that now we have entries in the sides and images properties. This is what makes the custom die and true custom die. In the sides property, we need one entry for each side, numbered sequentially starting at one (so 1 to 6 for a D6). The values of these entries is the keyword that is the result when that side of the die is rolled. In this case, when we roll as 1 we get "Paper". When we roll a 2 we get "Scissors". And so on. The images section is not being used as of yet but its intention is that each keyword is associated with a icon which will eventually be used in the Chat result. As such, for each keyword in sides, we have a mapping of that keyword to a texture file name in the images section.

Each side in the sides section can have one or more keywords associated with it. If more than one keyword is desired, separate the keywords by commas. For such entries, if the side is rolled it will give all the associated keywords. Thus by repeating the same keyword it is possible to provide the same keyword multiple tiles for a single side roll or different keywords can be used to provide one of each of the different keywords. For example:

"1":"Attack,Defense",
"2":"Attack,Attack",
"3":"Defense,Defense",
"4":"Magic",

The custom dice sides can also have a numeric value. In such a case they are treated as if the side rolled that value. This allows making dice with numeric values but not corresponding to the side number. For example, a die that has -2, -1, 0, 0, +2 and +2. The below die score a square of the side rolled:

"1":"2",
"2":"4",
"3":"8",
"4":"16",

Proximity Roller Integration

This plugin requires the Proximity Roller in order to be able to support tally rolls. However, the Proximity Roller plugin functionality is triggered by the user (i.e. the user actively needs to hold LSHIFT in order to trigger the functionality) and thus you can use this plugin without using the Proximity Roller function. Having said that, many games that use symbols typically roll multiple such dice and tally the results. In such a case, Proximity Roller is ideal because it allows multiple dice to be rolled and the result tallied.

Rolling Regular Dice

Regular dice should not be affected by this plugin or the presence of Proximity Roller except that the Chat Result will be delayed by a bit due to Proximity Roller's watchful eye. This includes cosmetic custom dice which, as noted before, still function like regular core dice in all respects except their appearance.

Rolling Custom Dice

When true custom dice are rolled the keywords for each die rolled is tallied and the results show the count for any keyword that was rolled at least once. Any keyword not rolled is not included in the tally.

Mixing Regular And True Custom Dice

When a roll includes both regular dice and true custom dice, something a little different occurs. The true custom dice keywords are tallied a always but an additional keyword of total is included and this keyword has the total of all of the regular dice. At the moment, this total does not show all of the dice values that contributed to it.

Save Dice Plugin

Recently the Save Dice Plugin was released. However, this plugin needs such close ties to the Save Dice Plugin that in the end, instead of making it a dependency, the Save Dice Plugin was incorporated directly into this plugin code. As such, the Save Data Plugin will be made obsolete and used can use this plugin instead. Even without any custom dice, this plugin will perform the same functionality as the Save Dice plugin.

Demo

Since the custom dice need to be added using the Save Dice configuration file and the name of that configuration file will depend on the campaign id, it is not possible to provide a configuration file out of the box. However, a save dice file is provided whose content can be copied into your own save dice file. To make use of this option, do the following:

1. Open Talespire
2. Add at least one die
3. Press the save dice function (default ``LCTRL``+``D``)
4. Exit Talespire
5. Open the save dice file that was created
6. Replace the contents with the contents of the save dice file that came with the plugin
7. Restart Talespire

The default custom die configuration, has the following possible custom dice:

lava-d4-1 (D4-1)
lava-d4-2 (D4+1)
lava-d6
lava-d8
lava-d10
lava-d12
lava-d20
rps-d6
dd-d6-combo1

Limitations

This is an initial release of the Custom Dice Pack plugin which does not have many bells and whistles that will hopefully be implemented in the future. Below is a list of some of the most obvious limitations:

1. When a custom die is spawned, it sticks to the mouse pointer and will move to the location of the next mouse
   pointer click. As such it is recommended to click once on the board after spawning a custom die. 
2. The dice result that shows on screen looks odd especially with true custom dice.
3. You can have a limit of around 2768 custom dice.
4. You can not have modifiers < -30000. 

The last two limitations are a result of how the plugin is implemented. To pass around the custom nature of a die (for true custom dice), the plugin uses the modifier proeprty of the die. Thus modifiers of -30000 to -32768 are used to indicate the type of custom die. It should be noted that this, once gain, refers to the number of distict custom dice. For example, 50 custom dice all using the same dice sides would be 50 copies of 1 custom die (and thus would use only 1 of the 2768 custom dice slots).