RulesetBuilderPlugin

Ruleset Builder Plugin

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.

Change Log

1.4.0: Rewrite engine to not use co-routines for faster processing
1.4.0: Added numerous action blocks
1.3.0: Added rolling with adv/dis and GUI toolbar to select the current roll mode
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

Installing With R2ModMan

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.

Currently the Rulset Builder does not come with any sample Ruleset. For a demonstration of the capabilities of this plugin download the Ruleset Builder 5E Ruleset pack.

Usage

There are 3 different users of this plugin: 1) End uses (GM and players), 2) Ruleset builders, and 3) Action block builders.

Below is a brief description of each of the types of users.

End Users (GM/Players)

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".

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.

Rulset Builders

The plugin comes with no ruleset sequences but the Ruleset Builder 5E Ruleset pack can be downloaed which shows the file formats needed to make action block seqeunces and action seqeunces. However, this plugin is designed to allow users to fairly easily make their own rulesets - either modifictions to the provided 5E ruleset or rulesets for different game systems. 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 may seem overwhelming with a lot of information available 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:

Action Blocks

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

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

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:

{
	"ActionSequences": 
	[
		{ "MenuName": "Axe", "MenuIconName": "Axe", "MenuGroup": "Melee Attacks", "Parameters": 
			{ 
				"Block01.Name": "Attack",			"Block01.Parameters": {"Attack": "+5", "ShortRange": "5", "LongRange": "5", "Effect": "STR contest to disarm"}, 
				"Block02.Name": "Damage",			"Block02.Parameters": {"CriticalRange": "20", "Damage": "1D6+4", "DamageType": "Slashing"},
				"Block03.Name": "Damage",			"Block03.Parameters": {"CriticalRange": "20", "Damage": "1D4", "DamageType": "Poison"}, 
				"Block04.Name": "DamageReport",		"Block04.Parameters": {} 
			}
		},
		...
	],
	"Team": "PC",
	"Vulnerabilities": "Fire",
	"Resistances": "Cold",
	"Reductions": "Poison03",
	"Immunities": "Psychic"
}

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 Sequences 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 "Attack", followed by "Damage", followed by "Damage", followed by "DamageReport" Action Sequences and passes to that sequence the parameters for each Action Sequence. 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

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.

Action Block Builders

When rulesets cannot be implemented with the existing Action Blocks it may be necessary to generate additional action blocks. This process is briefly described in the ActionBlocks.MD document included in the this plugin pack. This document also has a complete list of currently available Action Blocks and their parameters.

Below is a description of the Storage Concept which it used thoughout all Action Blocks. This common storage concept is key to understanding Action Blocks not only to used them to make rulesets but also to build them.

Storage Concept

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.".