The Ruleset Builder Plugin is an unofficial Talespire modding plugin that allows the user to use a modular, build block, solution to creating and using ruleset for different systems. As opposed to hard coding the rulsesets in the plugin, the plugin provides an bunch of action blocks which can be string together by the user to create rulesets for different systems and then the benefits can be be used by all players in the session.
1.2.0: Added CritDamage library of action blocks
1.2.0: Added ChatDiceResult to Notification action blocks library
1.2.0: Added Action Block Developer notes
1.1.0: Revised Melee Attack to use ChatGeneric to showcase how the header can be customized
1.1.0: Added ChatGeneric action block which gives direct control over the chat header
1.1.0: Change GetMiniSelection to use event based solution which does not select the clicked mini
1.0.0: Initial release
Install using R2ModMan or similar modding manager. The plugin packages comes with a bunch of action blocks (described below) but additional packs can be downloaded, as they are created, to add additional action blocks to build with.
There are 3 different users of this plugin: 1) End uses (GM and players), 2) Ruleset builders, and 3) Action block builders.
This document describes type 1 and type 2 users. For type 3 users (users wanting to create additional action blocks) additional information will be provided at a later date.
The Rulset Builder Plugin is versitile so there may be exceptions to this but generally there are two ways to interact with Rulsets being used. The most common way to start a ruleset sequence is to select a mini and then open the radial menu to see what sequences have been added. Typically Rulesets are grouped in groups so one will selected a group like "Melee Attack" and then an actual selection such as "Axe".
Please note that at this moment there is a limiltation where the mini needs to have been selected at least once for it to gain its corresponding Ruleset sequence options. This means if the board is loaded and then the user right clicks on a mini to open the radial menu, the Ruleset options will not be there. The mini needs to be selected first and then the radial menu opened. Once a mini has been selected at least once, the user can open the radial menu directly (so subsequent uses of the radial menu do not require selecting the mini first).
During ruleset sequences, some rulesets may require GUI interaction. These GUI elements may be always present or may only be present when needed. This depends on how the ruleset was built and not on this plugin.
Demo rules can be invoked by naming a character Jon.
The plugin comes with only a couple sample ruleset sequences. Not only does this means that these sample sequences may not be fully fleshed out but they also may not be correct for the desired game system. That is not a problem because the intention of this plugin is to provide the building blocks for users to create their own rulsets without needing to know how to program. Some very basic programming concepts may be useful but users will not be writing any code.
Initially this process will see overwhelming but there will be a lot of information but once you study the examples and/or write a few rules of your own, you will (hopefully) see that it is not so difficult.
There are 4 types of files used by Ruleset Builder Plugin but only 2 are of these files types are configured by the user:
There are the building blocks from which ruleset will be built. These blocks are what dictates what each rule sequence does when trying to execute a rule sequence. The plugin comes with a bunch of action blocks but additional action blocks can be added. Unless you are a developer, you wont be making these blocks but you will be using them.
Action sequences are a list of blocks which together form a rule. For example, the plugin comes with a sample Melee Attack and Skill Check action sequence. To create a new rule for your ruleset, you would create a new Action Sequence file. Action Sequence files are JSON files with the following format:
{
"name": "MeleeAttack",
"steps":
[
{"name": "Setup01", "block": "SystemNotification", "parameters": { "Message": "Select Victim Of Attack"} },
{"name": "Setup02", "block": "GetMiniSelection", "parameters": { } },
{"name": "Setup03", "block": "SetMiniSelection", "parameters": { "Storage": "Victim"} },
{"name": "Setup04", "block": "GetRange", "parameters": { "Storage": "Range"} },
{"name": "Setup05", "block": "BranchOnCondition", "parameters": { "Condition": "{Range}<1.3", "True": "Attack"} },
...
]
}
The Action Sequence has a name and then a list of steps. Each step has a name, a block and a parameters dictionary. The name of the step should be unique so that when using branching the correct step can be found. The block indicates which one the provided action block is being used (see list of action blocks below). The parameters is a dictionary of information being sent to the action block. The needed information is action block specific so you need to look at the action block documentation to see what information needs to be included.
When the Action Sequence (i.e. rule) is executed it will execute each action block in the list of steps in order (unless an action block such as one from the Branch collection is use to move to a different step).
File name format: {Edition}.{Name}.json for example: 5E.MeleeAttack.json
Characters indicated what Action Sequences are available for each specific character. The character Jon may have an Axe attack but June may have a firebolt attack instead. Character files look like:
[
{ "MenuName": "Axe", "MenuIconName": "Axe.png", "MenuGroup": "Melee Attacks", "Sequence": "MeleeAttack", "Parameters": { "Attack": "+5", "Damage": "1D6+4" } }
...
]
Character files are a list of Action Sequence Requests which indicated where they show up in the radial menu, what name is used in the radial menu, what icon is used in the radial menu, what Action Sequence the item uses and what parameetrs are sent to the Action Sequence. In the sample, above the item shows up in the "Melee Attacks" group in the radial menu and created an item called "Axe". The item uses the icon "Axe.png". When selected it runs the "MeleeAttack" Action Sequence and passes to that sequence the parameters of "Attack"="+5" and "Damage"="1D6+4". The parameters that need to be passed to an Action Sequence depends on the Action Sequence and thus can be different for different Action Sequences.
A character file has one entry per item that will appear in the radial menu. It should be noted that a character file may have multiple items that use the same Action Sequence. For example, a fighter that switches between different weapons can have multiple entries in the character files (one for each weapons) but they might all use the MeleeAttack Action Sequence.
File name format: {Edition}.{Name}.json for example: 5E.Jon.json
GUI Blocks are somewhat similar to Action Blocks but they are used to add addition GUI components. Unlike Action Blocks which are loaded when needed, GUI Blocks are always active if present although, depending on how they are writte, they can be turned on and off. Eventually there will be a configuration per edition to determine which GUI Blocks to use but for now, remove GUI Block that are not used.
To allows Action Sequences to use data from many sources but still make that data available to all Action Blocks without each Action Block having to support the different data source, the concept of a common Storage is used. Action Blocks get data from whatever source and they place it into the common Storage where all other Action Blocks can get at it. Similarly, Action Blocks can get data from the common storage and then write that data somewhere else. This concept means that some Action Blocks have a two step approach (i.e. get data from somewhere and then write data to the storage) while others combine the process into a single Action Block.
Once in storage, most Action Block can insert the contents of storage by using brace bracket placeholders.
For example, if the GetVictimStat was used to store the victim's AC under the storage key AC then the Action
Block ChatToAllAsGM could be used to display the AC in a message by using a message similar to:
The victim's AC is: {AC}
The brace brackets around the AC tells the plugin to look that value up in the storage and replace the it with
the stored value (thereby getting the value that was stored there earlier). There are two special place holders
and that is {Instigator.} and {Victim.} which refers to the CreatureBoardAsset for the instagtor (the mini
doing the Action Sequence) and the victim (the person who the Action Sequence is being done on if any). The
most common use of this is {Instigator.Name} and {Victim.Name}. This means that custom storage keys should not
start with "Instigator." or "Victim.".
The following is a brief description of each Action Block. For details on the parameters see the corresponding XML file for the package (the entry in square brackets) in which the Action Block resides. The XML is ugly but has notes for the parameters. Eventually proper documentation will be built but the XML files can be used for now to determine the parameters needed for any action block.
[Core]
Calculate: Stores the result of an expression in the specified key
Delay: Delays before processing next step. Not needed in most cases since most action support a delay parameter
Label: No action. Use with Branch action blocks to povide a step to beanch to
WaiForGUIContinue: Pauses sequence processing until something (typically a GUI button) resumes it
[5E.ReactionMenu]
Reaction Toolbar: Displays the current ruleset state on the screen (used for troubleshooting).
[Branch]
BranchAlways: Allows processing of a Action Sequence to jump to the indicated step (by name)
BranchOnCondition: Allows the processing of a Action Sequence to jump to the indicated step based on the results of a condition expression
[CharacterSequences]
GetMiniSelection: Allows user to click a mini to make a mini selection needed by the Action Sequence
SetMiniSelection: Writes the mini selection (from GetMiniSelection) to the victim (usual), storage (possible), or instigaror (hardly ever).
[CritData]
AddMaxDice: Adds the max value for each die to the existing total if a critial occurs. Supports crit range value (or 20 if not specified).
AddMeanDice: Adds the average value for each die to the existing total if a critial occurs. Supports crit range value (or 20 if not specified).
DoubleDice: Randomly generates an additional set of dice and adds them to the total if a critial occurs. Supports crit range value (or 20 if not specified).
DoubleDiceValue: Doubles the value of dice if a critial occurs. Supports crit range value (or 20 if not specified).
MakeDiceMax: Makes all the rolled dice max and recalculates the total if a critial occurs. Supports crit range value (or 20 if not specified).
[FileAccess]
LoadFromJson: Reads a JSON file, flattens the hierarchy and stores all the entries in the storage.
UnloadFromJson: Removes from storage all of the entries in the flattened version of the JSON file.
[Notification]
InstigatorSpeak: Generates text speech bubble from the instigator mini.
VictimSpeak: Generates text speech bubble from the victim's mini.
ChatGeneric: Writes a chat message with a custom header to the chat. Optional prefix supported for routing.
ChatToAllAsInstigator: Writes a chat message seen by all posing at the instigator.
ChatToAllAsVictim: Writes a chat message seen by all posing at the victim.
ChatToAllAsPlayer: Writes a chat message seen by all posing at the indicated player.
ChatToAllAsGM: Writes a chat message seen by all posing at the GM.
ChatToPlayerAsInstigator: Same as above but chat is only visible by specified player.
ChatToPlayerAsVictim: Same as above but chat is only visible by specified player.
ChatToPlayerAsPlayer: Same as above but chat is only visible by specified player.
ChatToPlayerAsGM: Same as above but chat is only visible by specified player.
ChatToGMAsInstigator: Same as above but chat is only visible by GM.
ChatToGMAsVictim: Same as above but chat is only visible by GM.
ChatToGMAsPlayer: Same as above but chat is only visible by GM.
ChatToGMAsGM: Same as above but chat is only visible by GM.
ChatDiceResults: Posts the specified dice results to the chat.
DiceResults: Posts the specifeid dice results to the player who rolled them (currently local only)
SystemNotification: Shows a system notification dialog at the top of the screen seen by all
[Range]
GetRange: Returns the reange between the instigator and the victim
[Roller]
RollDice: Rolls dice for the purpose of a attack, damage, save, or skill check
RollReactionDice: Rolls dice for the purpose of a modifier (used during reactions)
[Storage]
GetInstigatorStat: Gets the value of the specified stats from the instigator and stores it
GetVictimStat: Gets the value of the specified stats from the victim and stores it
SetInstigatorStat: Sets the instigator's stat to the given value
SetVictimStat: SetInstigatorStat: Sets the victim's stat to the given value