Revision as of 18:15, 3 December 2021

Page Updated:   2021-12-03

This API supports initiative for RPGs (initially only AD&D 2e) using the Turn Order and the Tracker window. The InitiativeMaster API provides functions dealing with all aspects of: managing how initiative is done; rolling for initiative; for “group” and “individual” initiative types providing Character action selection to determine the speed and number of attacks of weapons, the casting time of spells & the usage speed of magic items; supporting initiative for multiple attacks with one or multiple weapons per round; supporting and tracking actions that take multiple rounds; managing the resulting Turn Order; as well as performing the “End of Day” activity. It works very closely with the RoundMaster API to the extent that InitiativeMaster cannot work without RoundMaster (though the reverse is possible). InitiativeMaster also works closely with AttackMaster API and MagicMaster API and uses the data configured on the Character Sheet by these other APIs, although it can use manually completed Character Sheets once correctly configured.
This API is currently configured to only use the AD&D2e Character Sheet from Peter B. It uses the Roll Templates defined in that sheet extensively. It may be possible to use it with other character sheets if you follow the instructions in the Section on Character Sheet Data Fields and future development will focus on implementing more generic functionality.

Syntax

The InitiativeMaster API is called using !init.

!init --help

Commands to be sent to the InitiativeMaster API must be preceeded by two hyphens ‘--’ as above for the --help command. Parameters to these commands are separated by vertical bars ‘|’, for example:

!init --init [party-roll]|[foes-roll]

If optional parameters are not to be included, but subsequent parameters are needed, use two vertical bars together with nothing between them, e.g.

!--init  |[foes-roll]

Commands can be stacked in the call, for example:

!init --doCharList  ALL  --init 

When specifying the commands in this document, parameters enclosed in square brackets [like this] are optional: the square brackets are not included when calling the command with an optional parameter, they are just for description purposes in this document. Parameters that can be one of a small number of options have those options listed, separated by forward slash ‘/’, meaning at least one of those listed must be provided (unless the parameter is also specified in [] as optional): again, the slash ‘/’ is not part of the command. Parameters in UPPERCASE are literal, and must be spelt as shown (though their case is actually irrelevant).

Installation and Configuration

Copy the script's code, available from the menu on the right and stored at Roll20's API GitHub Repository. Paste the code into a new script in your campaign's API Script Editor. Save the new script and it will be available inside your campaign. It will install several new Character Sheets & Handouts: The handout InitiativeMaster Help provides a full manual of how to use InitiativeMaster. The handout RPGMaster CharSheet Setup provides information on setting up a character sheet for use with InitiativeMaster.

Script Use

After installing the script, refer the the handout InitiativeMaster Help for full information on use. Below is a copy of the contents of that handout.

Command Index

All commands are preceded by !init unless otherwise stated.

Manage Initiative type, rolls & party

--init [party-roll]|[foes-roll]
--type < STANDARD / GROUP / INDIVIDUAL >

Show group / individual Initiative menus

--menu [token-id]
--monmenu [token-id]

Show action-specific Initiative menus

--weapon [token-id]
--monster [token-id]
--complex [token-id]
--muspell [token-id]
--prspell [token-id]
--power [token-id]
--mibag [token-id]
--thief [token-id]
--other [token-id]

Maintain the Turn Order and Rounds

--maint
--check-tracker
--list-pcs  ALL / MAP / REPLACE / ADD

End of Day processing

--end-of-day [cost]

Other commands

--help
--debug ON/OFF

Configuring the Token and Character Sheet for use

Character Sheet data fields

Command Details

Manage Initiative type, rolls & party

Manage the Initiative process

--init [party-roll]|[foes-roll]

DM Only command. Takes an optional dice roll result for the Party, and an optional dice roll result for the foes.
This command displays a chat menu to specify:

• the type of initiative to do (standard, group or individual),
• the initiative rolls for the Party and the Foes (for standard and group initiative),
• who is in the Party,
• to check if everyone has selected their action for the next round (for group and individual initiative),
• and whether to show this menu automatically as each new round starts.

The different types of AD&D2e Initiative process are explained in the DMG p55, and consist of “standard”, “group”, and “initiative”:

The type of initiative selected persists between game sessions.
Who is in the party can be defined by using API Buttons on the menu to do one of: search all maps in the Campaign for tokens controlled by Players; search just the map the Players are on for tokens controlled by Players; select a number of tokens on any map and add them to the list; or replace the whole list with the selected tokens. Another API button checks to see if the Turn Order contains entries for every token listed as being in the Party, i.e. that everybody has selected their actions for the next round.
This menu can appear automatically as each completed round finishes if RoundMaster API is managing the Turn Order and Rounds. This is useful for standard and group initiative, as the first thing that needs to happen is for the Party & Foe initiative dice rolls to be entered. It is less useful for this menu to appear for individual initiative, and it can be turned off with another API Button.

Set the type of Initiative being used in the Campaign

--type < STANDARD / GROUP / INDIVIDUAL >

Takes a mandatory initiative type which must be one of those shown.
This command sets the initiative type to the specified type without bringing up the complete --init menu. The type of initiative specified persists between game sessions.

Show Group / Individual initiative action selection menus

Display a menu of possible actions for the selected Character / NPC

--menu [token-id]

Takes an optional token ID.
This command displays a chat menu of buttons for types of action that the Character / NPC / creature can perform. Each of these buttons may take the Player to a more detailed list of specific action buttons. Selecting any of the buttons will add the speed/casting time and correct number of instances of the selected action to the group or individual initiative dice roll (1d10) and enter the result in the Turn Order using the RoundMaster API – ‘individual’-type initiative dice rolls are performed in the background by the API and there is currently no option for the Player to do the roll instead.
The system displays immediately and also records the action selected and the speed of that action along with any modifiers as a message to display when the Character’s / NPCs / creature’s turn comes around. For each type of action, once chosen, the “rate” is displayed as the number of attacks per round multiplied by any magical modifier (such as a Haste spell). The “speed” is displayed as the speed of the action in segments (1/10ths of a round), and the “modifier” is the bonus or penalty to the roll for other magical effects (such as a Slow spell).
For multiple actions per round, those subsequent to the first action with the same item have speeds in the Turn Order incremented from each other by the speed of the action: thus multiple attacks with a Longbow (2 per round, speed 8), after an initiative roll of 5 on a 1d10, will happen at priority 13 & 21. For attacks by a Fighter with two weapons, such as a Longsword (sp 5) in their left hand and a Short sword (sp 3) in their right hand, after an initiative roll of 5, the Short sword will get a Turn Order priority of 8 and the Longsword 10 – that is they are consecutive not sequential.
See the individual menu explanations for more detail on each type of action.

Display a menu of possible actions for the selected creature

--monmenu [token-id]

Takes an optional token ID.
This produces a slightly simpler form of the initiative action menu for creatures. Otherwise, all actions result in similar processing as per the normal action selection. If the creature is very simple (only uses the simple attack lines on the Monster tab of the AD&D2e Character Sheet), then it might be sensible to use the --monster command instead: see below.

Action specific Initiative menus

Display initiative actions to attack with the weapons ‘in-hand’

--weapon [token-id]

Takes an optional token ID.
Displays a chat menu listing all the weapons that the Character / NPC / creature has ‘in-hand’ (i.e. that are currently in the Weapon and Ranged tables), with additional options as appropriate to the Character Sheet. Rogue class characters will get a ‘Backstab’ option which will apply the Rogue backstab multiplier as appropriate. Fighter & Rogue classes will get an option to choose two weapons (if there are two one-handed weapons in-hand) which presents the option of selecting a Primary and a Secondary weapon to do initiative for. Weapons can be those typed into the Character Sheet weapons tables (see Section 7 below) or loaded using AttackMaster API (see AttackMaster documentation).
If the Character / NPC / creature has Powers or Magic Items they can use, buttons also appear on the menu to go to the menus to select these instead of doing a weapon initiative – see the --power and --mibag commands. There is also a button for ‘Other’ actions, such as Moving, Changing Weapon (which takes a round), doing nothing, or Player-specified actions – see the --other command.

Display initiative actions for a simple creature to attack

--monster [token-id]

Takes an optional token ID.
Displays a chat menu only listing innate monster attacks from the Monster tab of the AD&D2e Character Sheet.
Creatures using the Innate Monster Attack fields on the AD&D2e Character Sheet Monster tab benefit from an extended syntax for entries in these fields: each field can take [<Attack name>,]<damage dice roll>[,<speed>] for example Claw,1d8,2 and Sword+1,2d4+1,5. These will result in possible initiative actions for that creature for Claw and Sword+1. If Attack Name is omitted, the dice roll is displayed as the action name instead. If the speed is omitted, the Innate attack speed field value is used instead. The speed will then be used to calculate the Turn Order priority.

Display initiative actions for a weapon-wielding creature to attack

--complex [token-id]

Takes an optional token ID.
Displays a more complex monster attack menu, with both ‘Innate’ attacks from the Monster tab as well as weapon attacks from the Character tab weapons tables (the API does not use the recently introduced Weapon table for Monsters on the Monster tab so that the AttackMaster API only has to deal with one set of tables) – see 3.1 above for entering weapons and 3.2 for setting up monster attacks. If the creature has powers or magic items, it will also offer action menu buttons for those. The selected attack or weapon speed will then be used to calculate the Turn Order priority.

Display initiative actions for Wizard spells

--muspell [token-id]

Takes an optional token ID.
Displays a menu of Wizard spells that the Character / NPC has memorised (see the MagicMaster API documentation for memorising spells, or see Section 7 below for entering spells manually). Any spell that is still memorised can be selected for initiative, and the relevant casting time will be used to calculate the Turn Order priority.

Display initiative actions for Priest spells

--prspell [token-id] Takes an optional token ID.
Displays a menu of Priest spells that the Character / NPC has memorised (see the MagicMaster API documentation for memorising spells, or see Section 7 below for entering spells manually). Any spell that is still memorised can be selected for initiative, and the relevant casting time will be used to calculate the Turn Order priority.

Display initiative actions for powers

--power [token-id]

Takes an optional token ID.
Displays a menu of Powers that the Character / NPC has been granted (see the MagicMaster API documentation for managing powers, or see Section 7 below for entering powers manually). Any power that has not been consumed can be selected for initiative, and the relevant casting time will be used to calculate the Turn Order priority.

Display initiative actions for Magic Items

--mibag [token-id]

Takes an optional token ID.
Displays a menu of Magic Items and non-magical equipment that the Character / NPC / creature has on their person - that is in the Items table (by default, the Potions table on the AD&D2e character sheet): see Section 7.5 below and the MagicMaster API documentation for information on Items. Selecting an item for initiative uses the speed of action of that item to calculate the Turn Order priority.

Display initiative actions for Thieves

--thief [token-id]

Takes an optional token ID.
Displays a menu of Thievish actions (with current percentage proficiencies of each). Selecting one for initiative uses the speed of action of that item to calculate the Turn Order priority.

Display other actions

--other [token-id]

Takes an optional token ID.
Displays a menu of other (non-attacking) actions that the Character / NPC / creature can take, namely: Moving (speed 0 as it is an innate ability); Changing Weapon (also speed 0 but takes all round); Doing Nothing (obviously speed 0); and one that allows the Player to enter a description and specify a speed for that action (presumably with the agreement of the DM).

Maintain the Turn Order and Rounds

Display the DM’s round maintenance menu

--maint

DM Only command. Does not take any parameters.
Displays a chat menu of action API Buttons to control the Turn Order Tracker window using commands sent to the RoundMaster API. The key one is Start/Pause, which initialises RoundMaster and starts it managing the Turn Order, or pauses it so that stepping through the Turn Order does not trigger any RoundMaster actions (such as counting down token status timers or initiating Effects). The full list of functions is:

Display those characters that have not yet had initiative actions selected

--check-tracker

DM Only command. Does not take any parameters.
Uses the Player Character name list created & maintained in the –init menu or with the –list-pcs command, and checks that all of the Character’s named have completed initiative selection to the point where their token name is in the Turn Order at least once, and appears in the Tracker window. Names those that have not in a message to the DM, or states that initiative is complete.

Change the list of characters in the Party

--list-pcs < ALL / MAP / REPLACE / ADD >

DM Only command. Takes a specifier for the tokens to have in the Player Character list which must be one of those listed.
Updates the internally held list of Characters that are controlled by Players (and others that the DM can add at will). This list is displayed on the --init menu, and is used by --check-tracker and --end-of-day commands. The list persists between sessions of game-play. The following parameters have the following effects:

End of Day processing

--end-of-day [ASK/ASKTOREST/OVERNIGHT/REST/SET/FOES]|[=][cost]

DM Only command. Takes an optional type of rest (which, if provided, must be one of those shown – defaults to ASK) and an optional cost parameter, optionally preceded by an ‘=’ character. If cost is not provided, it defaults to that previously set with SET and/or ‘=’.
This command performs the ‘End-of-Day’ processing for the campaign. This consists of enabling Long Rests for all Characters / NPCs / creatures to regain their spells and powers, and for recharging Magic Items to regain their charges (see MagicMaster API documentation for information on Long Rests). It also removes spent ammunition from quivers that has not been recovered, as it is assumed to be lost, broken or taken by other creatures during the period of the night (see AttackMaster API documentation about recovery of ammunition and its loss over a Long Rest).
Each day can cost or earn the members of the Party money, perhaps depending on where they stay overnight, whether they eat just camp rations or lavish meals, use an Inn and drink too much, or earn money doing a job. The optional cost parameter can be set to a positive cost to the party which will be deducted from every member, or a negative quantity which will be earned (a negative cost).

Other Commands

Display help on these commands

--help

This command does not take any arguments. It displays a very short version of this document, showing the mandatory and optional arguments, and a brief description of each command.

Handshake with other APIs

!rounds –hsq from|[command]
!rounds –handshake from|[command]

Either form performs a handshake with another API, whose call (without the ‘!’) is specified as from in the command parameters (the response is always an –hsr command). The command calls the from API command responding with its own command to confirm that RoundMaster is loaded and running: e.g.
Received: !init –hsq magic
Response: !magic –hsr init
Which means the MagicMaster API has requested a handshake with InitiativeMaster to see if it is loaded, and InitiativeMaster has responded, proving it is running and taking commands.
Optionally, a command query can be made to see if the command is supported by RoundMaster if the command string parameter is added, where command is the RoundMaster command (the ‘--’ text without the ‘--‘). This will respond with a true/false response: e.g.
Received: !init –handshake attk|monster
Response: !attk –hsr init|monster|true
Which means AttackMaster has queried if InitiativeMaster has a command called --monster, and InitiativeMaster has responded in the affirmative.

Switch on or off Debug mode

--debug (ON/OFF)

Takes one mandatory argument which should be ON or OFF.
The command turns on a verbose diagnostic mode for the API which will trace what commands are being processed, including internal commands, what attributes are being set and changed, and more detail about any errors that are occurring. The command can be used by the DM or any Player – so the DM or a technical advisor can play as a Player and see the debugging messages.

Configuring the Token and Character Sheet for use with the API

Token configuration

The API can work with any Token configuration but requires tokens that are going to participate in initiative actions for ‘Group’ and ‘Individual’ initiative to represent a Character Sheet, so that actions relevant to the token can be selected.
A single Character Sheet can have multiple Tokens representing it, and each of these are able to do individual initiative using the actions made possible by the data on the Character Sheet jointly represented. However, if such multi-token Characters / NPCs / creatures are likely to encounter spells that will affect the Character Sheet (such as Haste and Slow) they must be split with each Token representing a separate Character Sheet, or else the one spell will affect all tokens associated with the Character Sheet, whether they were targeted or not! In fact, it is recommended that tokens and character sheets are 1-to-1 to keep things simple.
The recommended Token Bar assignments for all APIs in the Master Series are:

It is recommended to use these assignments, and they are the bar assignments set by the CommandMaster API if its facilities are used to set up the tokens. All tokens must be set the same way, whatever way you eventually choose.
These assignments can be changed in each API, by changing the fields object near the top of the API script (note: no underscore, and ‘bar#’ and ‘value’ or ‘max’ are separate entries in an array of 2 elements). All APIs must use the same field definitions:

Alter the bar numbers appropriately or, if you are not wanting one or more of these assigned: leave the two elements of the array as [‘’,’’]. The system will generally work fine with reassignment or no assignment, but not always. Specifically, some effects in the Effects-DB, which implement spell effects on Character Sheets and Tokens, may not set the right values if no assignment of one or more of HP, AC & Thac0 are made to the Token.

Use with various game system character sheets

The API issued is initially set up to work with the AD&D 2E character sheet (as this is what the author mostly plays). However, it can be set up for any character sheet. In each API script, right at the top, is an object definition called ‘fields’: see 7.2 for details. This can be altered to get the API to work with other character sheets. The coding of the API is designed to use the AD&D 2E system of initiative systems and calculations. If you use another system (e.g. the D&D 5e system) the API coding will need to change. This might be a future enhancement.

Matching the API to a type of Character Sheet

The API has an object definition called ‘fields’, which contains items of the form
Internal_api_name: [sheet_field_name, field_attribute, optional_default_value, optional_set_with_worker_flag]
A typical example might be:

	Fighter_level:['level-class1','current'],
	Or
	MUSpellNo_memable:['spell-level-castable','current','',true],

Table names are slightly different: always have an internal_api_name ending in ‘_table’ and their definition specifies the repeating table name and the index of the starting row of the table or -1 for a static field as the 1st row, with the 2nd row starting at repeating row number 0.
Internal_api_table: [sheet_repeating_table_name,starting_index]
An example is:

MW_table:['repeating_weapons',0],

The internal_api_name must not be altered! Doing so will cause the system not to work. However, the sheet_repeating_table_name and starting_index can be altered to match any character sheet.
Each character sheet must have repeating tables to hold weapons, ammo and magic items. By default, melee weapons ‘in hand’ are held in sections of the repeating_weapons table, melee weapon damage in the repeating_weapons-damage table, ranged weapons in the repeating_weapons2 table, ammo in the repeating_ammo table, and magic items are held in the repeating_potions table. Other repeating tables are also used, some of which are intended to be hidden and not visible in the Character Sheet. The table management system provided by the API creates, expands and writes to repeating attributes automatically, and the DM & Players do not need to worry about altering or updating any of these tables on the Character Sheet.

Character Attributes, Races, Classes and Levels

Character Attributes of Strength, Dexterity, Constitution, Intelligence, Wisdom and Charisma are not directly important to the Initiative Master API, but the resulting bonuses and penalties are. All Attributes and resulting modifiers should be entered into the Character Sheet in the appropriate places (that is in the Character Sheet fields identified in the ‘fields’ API object as noted in section 7.2 above).
The Character’s race is also important for calculating saves and ability to use certain items. The race should be set in the appropriate Character Sheet field. Currently, the races ‘dwarf’, ‘elf’, ‘gnome’, ‘halfelf’, ‘halfling’, ‘half-orc’, and ‘human’ are implemented (not case sensitive, and spaces, hyphens and underscores are ignored). If not specified, human is assumed. The race impacts saves, some magic items and armour, and bonuses on some attacks.
The system supports single-class and multi-class characters. Classes must be entered in the appropriate fields on the Character Sheet. Classes and levels affect spell casting ability, weapon multiple attack numbers per round, ability to do two-weapon attacks with or without penalty, and the ability to backstab and the related modifiers among other things. Class and level also determine valid armour, shields, some magic items and saves.
Note: on the Advanced D&D 2e Character Sheet, Fighter classes must be in the first class column, Wizard classes in the second column, Priest classes in the third, Rogues in the fourth, and Psions (or any others) in the fifth. It is important that these locations are adhered to.
Note: classes of Fighter and Rogue (such as Rangers and Bards) that can use clerical &/or wizard spells will automatically be allowed to cast spells once they reach the appropriate level by AD&D 2e rules, but not before.
The following Classes are currently supported:

The level for each class must be entered in the corresponding field. Multiple classes and levels can be entered, and will be dealt with accordingly. Generally, the most beneficial outcome for any combination will be used.

Spells and Powers

The best (and easiest) way to give a Character or NPC spells and powers is to use the MagicMaster API. However, for the purposes of just doing initiative and selecting which spell to cast in the round, the spells and powers can be entered manually onto the character sheet. Spells are held in the relevant section of the Spells table, which by default is set to the character sheet spells table, repeating_spells. As with other fields, this can be changed in the ‘fields’ object. Note that on the Advanced D&D 2e character sheet Wizard spells, Priest spells & Powers are all stored in various parts of this one very large table.
If you are just using the character sheet fields to type into, add spells (or powers) to the relevant “Spells Memorised” section (using the [+Add] buttons to add more as required) a complete row at a time (that is add columns before starting the next row). Enter the spell names into the “Spell Name” field, and “1” into each of the “current” & “maximum” “Cast Today” fields – the API suite counts down to zero on using a spell, so in order for a spell to appear as available (not greyed out) on the initiative menus, the “current” number left must be > 0. This makes spells consistent with other tables in the system (e.g. potion dose quantities also count down as they are consumed, etc).
Then, you need to set the “Spell Slots” values on each level of spell to be correct for the level of caster. Just enter numbers into each of the “Level”, “Misc.” and “Wisdom” (for Priests) fields, and/or tick “Specialist” for the Wizard levels as relevant. This will determine the maximum number of spells memorised each day, that will appear in the spells Initiative Menu. Do the same for Powers using the “Powers Available” field. As with other fields on the character sheet, each of these fields can be re-mapped by altering the ‘fields’ object in the APIs.

Magic Items and Equipment

All magic items and standard equipment, including weapons, armour, lanterns etc, are held in the Items table, which by default is set to the potions table, repeating_potions, on the Character Sheet. As with other fields, this can be changed in the ‘fields’ object. The best way to put items into this table is by using the MagicMaster API. However, it generally is possible to enter item names and quantities directly into the table and use them within the system. Only items that also exist in the supplied databases will actually work fully with the API (i.e. be recognised by the API as weapons, armour, ammo, etc). Initial weapon, ammunition and armour databases are provided with the AttackMaster API, and in addition to these Initial magic item, spell and power databases are provided with the MagicMaster API. Other items can be in the table and used for undertaking initiative actions but will not otherwise be effective. New databases and database items can be added using the specifications and instructions contained in the AttackMaster and MagicMaster API documentation.

Weapons and Ammo

For the InitiativeMaster API to support weapon attack actions melee weapons, damage, ranged weapons and ammo must be entered directly into the melee weapon, damage, ranged weapon and ammo tables on the Character Sheet. This is best done using the AttackMaster API, which will ensure all the right values are entered in the right fields, including taking into account the impact of weapon proficiencies, specialisation, mastery, character races and class/level. However, manual entry will generally work to the extent to allow weapon attack initiative actions to be selected. Weapon name, speed and number of attacks are the most important fields for initiative.

Character Sheet data fields

As stated in section 7, the Character Sheet field mapping to the API script can be altered using the definition of the fields object. You can find the complete mapping for all APIs in the RPGMaster series, with an explanation of each, in a separate document.

Changelog

v1.037 (2021-12-24)

• First version for public release