Character Vault
Any Concept / Any System
Compendium
Your System Come To Life
Roll20 for Android
Streamlined for your Tablet
Roll20 for iPad
Streamlined for your Tablet

Personal tools

Difference between revisions of "Script:InitMaster"

From Roll20 Wiki

Jump to: navigation, search
m
 
(13 intermediate revisions by 2 users not shown)
Line 1: Line 1:
 
{{revdate}}{{main|API:Script Index}}
 
{{revdate}}{{main|API:Script Index}}
 
{{script overview
 
{{script overview
|name=RoundMaster
+
|name=InitMaster
 
|author=[[Richard E]]
 
|author=[[Richard E]]
|version=1.037
+
|version=1.5.01
|lastmodified=2021-12-02
+
|lastmodified=2023-05-19
 
|code=InitMaster
 
|code=InitMaster
 
|dependencies={{api repository link|RoundMaster}}
 
|dependencies={{api repository link|RoundMaster}}
 +
{{api repository link|RPGMlibrary AD+D2e}}
 
|conflicts=None}}
 
|conflicts=None}}
 
'''InitiativeMaster''' supports initiative for RPGs (initially only AD&D 2e) using the Turn Order and the {{Turn Tracker}} window. It's a part of the '''[[RPGMaster]]'''-series of APIs.
 
'''InitiativeMaster''' supports initiative for RPGs (initially only AD&D 2e) using the Turn Order and the {{Turn Tracker}} window. It's a part of the '''[[RPGMaster]]'''-series of APIs.
Line 19: Line 20:
 
* performing the “End of Day” activity.
 
* performing the “End of Day” activity.
  
It works very closely with the [[Script:RoundMaster|RoundMaster]] API to the extent that InitiativeMaster cannot work without RoundMaster (though the reverse is possible).  InitiativeMaster also works closely with [[Script:AttackMaster]] and [[Script:MagicMaster]], and uses the data configured on the Character Sheet by these other APIs, although it can use manually completed Character Sheets once correctly configured.<br>
+
'''Note:''' This API ''requires'' that the [[Script:RoundMaster|RoundMaster]] API and a '''[[Script:RPGMaster Library|RPGMaster Library]]''' API is loaded, which provides RPG version-specific and Roll20 Character Sheet version-specific data, rulesets and processing (as well as other goodies!), to the extent that InitiativeMaster cannot work without them (though the reverse is possible).  InitiativeMaster also works closely with [[Script:AttackMaster|AttackMaster]] and [[Script:MagicMaster|MagicMaster]], 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 [[ADnD_2nd_Edition_Character_sheet|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 under [[#Configuring the Token and Character Sheet for use with the API]].
+
== Forum ==
 
+
[https://app.roll20.net/forum/post/11115777/script-rpgmaster-apis-for-ad-and-d-2e RPGMaster Forum]
Future development will focus on implementing more generic functionality.
+
== Configuring Character Sheets ==
 +
[[API:RPGMaster-CharacterSheets|RPGMaster Character Sheet setup]] - RPGMaster Character Sheet setup Wiki page
  
 
== Syntax ==
 
== Syntax ==
Line 42: Line 44:
 
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.
 
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=
+
==Using Character Sheet Ability/Action buttons==
All commands are preceded by !init unless otherwise stated.
+
<p>The most common approach for the Player to run these commands is to use Ability macros on their Character Sheets which are flagged to appear as Token Action Buttons: Ability macros & Token Action Buttons are standard Roll20 functionality, refer to the Roll20 Help Centre for information on creating and using these.</p>
==Manage Initiative type, rolls & party==
+
<p>In fact, the simplest configuration is to provide only Token Action Buttons for the menu commands: <b>--menu</b> and <b>--monmenu</b>.  From these, most other commands can be accessed.  If using the <b>CommandMaster API</b>, its character sheet setup functions can be used to add all the necessary and/or desired Ability Macros and Token Action Buttons to any Character Sheet.</p>
 +
 
 +
==How Initiative Master API works==
 +
{| role="presentation" class="wikitable mw-collapsible mw-collapsed"
 +
|
 +
|-
 +
|<p>The Initiative Master API ("InitMaster") provides commands that allow the DM to set and manage the type of initiative to be used in the campaign, and for Players to undertake initiative rolls.  The API uses data on the Character Sheet represented by a selected token to show menus of actions that can be taken: these commands are often added to the Character Sheet as Ability Macros that can be shown as Token Actions (see Roll20 Help Centre for how to achieve this, or the <b>CommandMaster API</b> documentation).  The API displays resulting Turn Order token names with action priorities in the Turn Order Tracker window (standard Roll20 functionality - see Roll20 documentation & Help Centre).</p>
 +
<p><b>Note:</b> Use the <b>--maint</b> command to display the Maintenance Menu and start the <b>RoundMaster API</b> using the <b>Start / Pause</b> button (at the top of the displayed menu) before using the Turn Order Tracker.  The top entry in the Turn Order Tracker window should change from showing a "Stopped" symbol, and change to a "Play".
 +
<p>The API must be used with both the <b>RoundMaster API</b> and the game-version-specific <b>RPGMaster Library</b>.  The RPGMaster Library sets all the right parameters for the RPGMaster APIs to work with different D&D game versions and different Roll20 D&D character sheets.  Ensure you have the right library loaded for the game version you are playing and the character sheet version you have loaded.</p>
 +
 
 +
<p style="font-size: 150%">Specifying a token</p>
 +
<p>Most of the InitiativeMaster API commands need to know the token_id of the token that represents the character, NPC or creature that is to be acted upon.  This ID can be specified in two possible ways:</p>
 +
<ol><li>explicitly in the command call using either a literal Roll20 token ID or using @{selected|token_id} or @{target|token_id} in the command string to read the token_id of a selected token on the map window,<br>or</li>
 +
<li>by having a token selected on the map window, not specifying the token_id in the command call, and allowing the API to discover the selected token_id.</li></ol>
 +
<p>In either case, if more than one token is selected at the time of the call then using either @{selected|token_id} to specify the token in the command call, or allowing the command to find a selected token, is likely (but not guaranteed) to take the first token that was selected.  To avoid ambiguity, it is generally recommended to make command calls with only one token selected on the map window.</p>
 +
 
 +
<p style="font-size: 150%">Types of Initiative System</p>
 +
<p>The API supports several methods for initiative: "standard", "group" and "individual", selectable by the DM in-game and changeable during game play, if desired.</p>
 +
<p>"Standard" initiative just requires a "Party" initiative dice roll and a "Foe" initiative dice roll to be entered, and the Turn Order entries are set appropriately.  For "Group" initiative, the same rolls are entered but, in addition, the action of each character / NPC / creature (each token) taking part specifies what actions they are going to perform that round and the speed of that action is added to the relevant group dice roll to create the Turn Order priority for that token.  For "Individual" initiative, each character / NPC / creature makes its own individual dice roll as well as specifying their action, with the individual dice roll and speed of action being combined to give the Turn Order priority.</p>
 +
<p>Alternatively, standard Roll20 functionality can be used to "right click" on a token and choose the option to add it to the Turn Order, and the <b>--maint</b> command can be used to set "Stop Melee" button, thus stopping the Turn Order from being cleared each round, and then the Initiative will just cycle round the party members.</p>
 +
 
 +
<p style="font-size: 150%">Monster Attack Initiatives</p>
 +
<p>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</p>
 +
<pre>[Attack name],damage dice roll,[speed],[dmg type] </pre>
 +
<p>for example <code>Claw,1d8,2,S</code> and <code>Club+1,2d4+1,5,B</code>.  These will result in possible initiative actions for that creature for <b>Claw</b> and <b>Club+1</b>.  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.</p>
 +
 
 +
<p style="font-size: 150%">Effect of Magic on Initiative</p>
 +
<p>The system can take into account various modifiers applied by spells and/or magic items (e.g. Haste and Slow spells), and the spell, power & magic item macros provided with the <b>MagicMaster API</b> use this functionality when used in conjunction with <b>RoundMaster</b> <i>Effects</i>.  <b>The Character Sheet Setup handout</b> states which Character Sheet fields to enter the modifiers into in order for them to be taken into account.</p>
 +
 
 +
<p style="font-size: 150%">Multi-attack Initiatives</p>
 +
<p>The system can also create multiple initiative turns for weapons that achieve multiple attacks per round, like bows and daggers, as well as by the class, level and proficiency of the character or any combination of the three as per the D&D game version rules (held in the specific version of the <i>RPGMaster Library</i> you have loaded), including 3 attacks per 2 rounds, or 5 per 2.  Also Fighter and Rogue classes using 2 weapons are catered for, even with those weapons possibly having multiple attacks themselves - the weapon specified by the character as the Primary will achieve its multiple attacks, whereas the secondary weapon will only get the number of attacks specified as per the rules for multiple attacks in the game version you are using.</p>
 +
 
 +
<p style="font-size: 150%">Multi-round Initiatives</p>
 +
<p>Multi-round initiatives are also supported e.g. for spells like Chant which takes 2 rounds.  Any Character Sheet entry that has a speed (<b>note:</b> action speed only, not action plus initiative roll) of longer than 10 segments (1/10ths of a round), when chosen by a player, will add an entry for that action not only in the current round but also in the following and subsequent rounds as appropriate.  Each new round, when they select to specify an initiative action (e.g. using <b>!init --menu</b>) the Player of that character (or the DM for a Foe) is asked if they want to continue with the action or has it been interrupted: if interrupted or stopped by choice the player can choose another action for that character, otherwise the "carried forward" action is added to the tracker. </p>
 +
<p><b>Note:</b> the Player (or DM) must still select to do initiative each round for this to happen.</p>
 +
 
 +
<p style="font-size: 150%">Changing an Initiative Action</p>
 +
<p>If using "Group" or "Individual" initiative and a Player has completed selecting an initiative action for a Character (or the DM for a Foe) and changes their mind about what they are doing before the DM starts the round, the Player can select the token and rerun the relevant command (use the relevant token action button) to do initiative again (presuming the DM's agreement).  The system will warn the Player that initiative has already been completed for the Character and present a new button to redo initiative if the Player wants to (this is so that accidental selection of the redo command is prevented) - all entries for the token name will be removed from the Turn Order and the relevant menus presented again to the Player.</p>
 +
<p>Selecting any particular action for initiative <i><u>does not</u> force that to be the action the Player takes on their turn</i>.  When that Character's turn comes up in the Turn Order, a message is displayed to all Players and the DM stating the action that was selected for initiative for that token (DM-controlled NPCs & creatures only display to the Players that it is their turn, not what they are doing, while the DM gets a full action message).  The Player can then take that action, or do something else entirely (presumably with the DM's agreement) for instance if circumstances have changed (e.g. the foe being attacked has died prior to an "Attack" action).</p>
 +
 
 +
<p style="font-size: 150%">In Summary</p>
 +
<p>InitMaster manages the whole of this process seamlessly, and in addition will support actions that result in more than one Turn Order entry (such as firing a bow that can make two shots per round), automatically taking into account character class to allow two-weapon attack actions, supporting initiative for "dancing" weapons (when used with the AttackMaster and MagicMaster APIs), and other complex aspects of initiative.</p>
 +
<p>The easiest way to set up Character Sheets for InitMaster operation is by using the rest of the APIs in the Master series:</p>
 +
<p><b>RPGMaster Library</b> for the game version you are playing is required for the operation of all RPGMaster APIs (except RoundMaster).  It holds the version-specific rules, parameters and databases for the game version.</p>
 +
<p><b>RoundMaster API</b> is required for the operation of InitMaster.  It manages all aspects of interaction with the Turn Order Tracker window in Roll20, and the management of token statuses and Effects.</p>
 +
<p><b>CommandMaster API</b> will add the relevant DM Macro Bar buttons, and Token Action Buttons to a Character Sheet for all commands needed for each of the APIs, including InitiativeMaster.</p>
 +
<p><b>MagicMaster API</b> will support entering the correct data on the sheet for all sorts of weapons, magic items, spells and powers, through looting chests & bodies, learning & memorising spells and being granted powers.  Initiative actions can then use these items with the correct action speed.</p>
 +
<p><b>AttackMaster API</b> will arm the character by taking weapons and/or shields "in hand".  Initiative actions can then be selected for attacks with these weapons using the correct speed modifiers.  AttackMaster will also support making attacks with all the relevant modifiers, changing the weapons in-hand, managing ammunition for ranged weapons, selecting the correct range for ranged weapons and applying the right modifiers, supporting magical weapons and artifacts, and also dealing with armour, armour classes & saves.</p>
 +
<p>Token setup for use with the Master series of APIs is simple (to almost non-existent) and explained in the Character Sheet Setup handout.</p>
 +
|}
 +
<br>
 +
 
 +
==Command Index==
 +
<p>All commands are preceded by !init unless otherwise stated.</p>
 +
===Manage Initiative type, rolls & party===
 
<pre>--init [party-roll]|[foes-roll]
 
<pre>--init [party-roll]|[foes-roll]
 
--type < STANDARD / GROUP / INDIVIDUAL ></pre>
 
--type < STANDARD / GROUP / INDIVIDUAL ></pre>
==Show group / individual Initiative menus==
+
===Show group / individual Initiative menus===
 
<pre>--menu [token-id]
 
<pre>--menu [token-id]
 
--monmenu [token-id]</pre>
 
--monmenu [token-id]</pre>
==Show action-specific Initiative menus==
+
===Show action-specific Initiative menus===
 
<pre>--weapon [token-id]
 
<pre>--weapon [token-id]
 
--monster [token-id]
 
--monster [token-id]
Line 60: Line 116:
 
--thief [token-id]
 
--thief [token-id]
 
--other [token-id]</pre>
 
--other [token-id]</pre>
==Maintain the Turn Order and Rounds==
+
===Maintain the Turn Order and Rounds===
 
<pre>--maint
 
<pre>--maint
 
--check-tracker
 
--check-tracker
 
--list-pcs  ALL / MAP / REPLACE / ADD</pre>
 
--list-pcs  ALL / MAP / REPLACE / ADD</pre>
==End of Day processing==
+
===End of Day processing===
<pre>--end-of-day [cost]</pre>
+
<pre>--end-of-day [Type]|[=][cost]</pre>
==Other commands==
+
===Other commands===
 
<pre>--help
 
<pre>--help
--hsq from|[command]
+
--handshake from | [cmd]
--handshake from|[command]
+
--hsq from | [cmd]
 +
--hsr from | [cmd] | [TRUE/FALSE]
 
--debug ON/OFF</pre>
 
--debug ON/OFF</pre>
==Configuring the Token and Character Sheet for use==
 
==Character Sheet data fields==
 
 
<br>
 
<br>
<br>
+
==Detail of Commands==
=Command Details=
+
===Manage Initiative type, rolls & party===
==Manage Initiative type, rolls & party==
+
====Manage the Initiative process====
===Manage the Initiative process===
+
 
<pre>--init [party-roll]|[foes-roll]</pre>
 
<pre>--init [party-roll]|[foes-roll]</pre>
DM Only command.  Takes an optional dice roll result for the Party, and an optional dice roll result for the foes.<br>
+
<p>DM Only command.  Takes an optional dice roll result for the Party, and an optional dice roll result for the foes.</p>
This command displays a chat menu to specify:<br>
+
<p>This command displays a chat menu to specify:</p>
<ul><li>the type of initiative to do (standard, group or individual),</li>
+
<ul>
<li>the initiative rolls for the Party and the Foes (for standard and group initiative),</li>
+
<li>the type of initiative to do (standard, group or individual),</li>
<li>who is in the Party,</li>
+
<li>the initiative rolls for the Party and the Foes (for standard and group initiative),</li>
<li>to check if everyone has selected their action for the next round (for group and individual initiative),</li>
+
<li>who is in the Party,</li>
<li>and whether to show this menu automatically as each new round starts.</li></ul>
+
<li>to check if everyone has selected their action for the next round (for group and individual initiative),</li>
The different types of AD&D2e Initiative process are explained in the DMG p55, and consist of “standard”, “group”, and “individual”:<br>
+
<li>and whether to show this menu automatically as each new round starts.</li></ul>
 +
<p>The different types of AD&D2e Initiative process are explained in the DMG p55, and consist of "standard", "group", and "individual":</p>
 
{| class="wikitable"
 
{| class="wikitable"
 
|+  
 
|+  
 
|-
 
|-
 
! scope="row"| Standard:
 
! scope="row"| Standard:
|| the Party and the Foes (DM) each roll 1d10, and all of whichever gets the lowest roll goes first.  The system supports taking the two rolls, and putting entries in the Turn Order for all defined Party members, and one entry for the Foes.
+
|| the Party and the Foes (GM) each roll 1d10, and all of whichever gets the lowest roll goes first.  The system supports taking the two rolls, and putting entries in the Turn Order for all defined Party members, and one entry for the Foes.
 
|-
 
|-
 
! scope="row"| Group:
 
! scope="row"| Group:
|| the Party and the Foes (DM) each roll 1d10, and then all Party members and all Foes choose what actions they will perform during the next round.  The speed/casting time of the Character’s / Foes selected action will then be added to the relevant roll to define the Character’s / Foes initiative(s) which are added to the Turn Order.
+
|| the Party and the Foes (GM) each roll 1d10, and then all Party members and all Foes choose what actions they will perform during the next round.  The speed/casting time of the Character’s / Foes selected action will then be added to the relevant roll to define the Character’s / Foes initiative(s) which are added to the Turn Order.
 
|-
 
|-
 
! scope="row"| Individual:
 
! scope="row"| Individual:
 
|| each individual Character & Foe chooses what action they will do each round, and the speed/casting time of that action is added to an individual system-rolled 1d10 for that Character / Foe resulting in each Character’s initiative(s) which are all added to the Turn Order.
 
|| each individual Character & Foe chooses what action they will do each round, and the speed/casting time of that action is added to an individual system-rolled 1d10 for that Character / Foe resulting in each Character’s initiative(s) which are all added to the Turn Order.
 
|}
 
|}
The type of initiative selected persists between game sessions.<br>
+
<p>The type of initiative selected persists between game sessions.</p>
Who is in the party can be defined by using API Buttons on the menu to do one of:<br>
+
<p>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.</p>
<ul><li>search all maps in the Campaign for tokens controlled by Players;</li>
+
<p>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.</p>
<li>search just the map the Players are on for tokens controlled by Players;</li>
+
<p>This menu can appear automatically as each completed round finishes if <b>RoundMaster API</b> 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 an API Button on the menu.</p>
<li>select a number of tokens on any map and add them to the list; or</li>
+
====Set the type of Initiative being used in the Campaign====
<li>replace the whole list with the selected tokens.</li></ul>
+
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.<br>
+
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.<br>
+
 
+
===Set the type of Initiative being used in the Campaign===
+
 
<pre>--type < STANDARD / GROUP / INDIVIDUAL ></pre>
 
<pre>--type < STANDARD / GROUP / INDIVIDUAL ></pre>
Takes a mandatory initiative type which must be one of those shown.<br>
+
<p>Takes a mandatory initiative type which must be one of those shown.</p>
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.<br>
+
<p>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.</p>
 
+
<br>
==Show Group / Individual initiative action selection menus==
+
===Show Group / Individual initiative action selection menus===
 
+
====Display a menu of possible actions for the selected Character / NPC====
===Display a menu of possible actions for the selected Character / NPC===
+
 
<pre>--menu [token-id]</pre>
 
<pre>--menu [token-id]</pre>
Takes an optional token ID.  If token ID is not supplied, the selected token is used.<br>
+
<p>Takes an optional token ID.</p>
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.<br>
+
<p>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 <b>RoundMaster API</b> - '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 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.</p>
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).<br>
+
<p>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 concurrent not sequential.</p>
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.<br>
+
<p>See the individual menu explanations for more detail on each type of action.</p>
See the individual menu explanations for more detail on each type of action.<br>
+
====Display a menu of possible actions for the selected creature====
 
+
===Display a menu of possible actions for the selected creature===
+
 
<pre>--monmenu [token-id]</pre>
 
<pre>--monmenu [token-id]</pre>
Takes an optional token ID.  If token ID is not supplied, the selected token is used.<br>
+
<p>Takes an optional token ID.</p>
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.
+
<p>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.</p>
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.<br>
+
<p>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 <b>--monster</b> command instead: see below.</p>
 
+
<br>
==Action specific Initiative menus==
+
===Action specific Initiative menus===
===Display initiative actions to attack with the weapons ‘in-hand’===
+
====Display initiative actions to attack with the weapons "in-hand"====
 
<pre>--weapon [token-id]</pre>
 
<pre>--weapon [token-id]</pre>
Takes an optional token ID.  If token ID is not supplied, the selected token is used.<br>
+
<p>Takes an optional token ID.</p>
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).<br>
+
<p>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 <i>RPGMaster CharSheet Setup</i> handout) or loaded using the <b>AttackMaster API</b> (see AttackMaster documentation).</p>
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.<br>
+
<p>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 <b>--power</b> and <b>--mibag</b> commands.  There are also buttons for "Other" actions, such as Moving, Changing Weapon (which takes a round), doing nothing, or Player-specified actions - see the <b>--other</b> command.</p>
 
+
====Display initiative actions for a simple creature to attack====
===Display initiative actions for a simple creature to attack===
+
 
<pre>--monster [token-id]</pre>
 
<pre>--monster [token-id]</pre>
Takes an optional token ID.  If token ID is not supplied, the selected token is used.<br>
+
<p>Takes an optional token ID.</p>
Displays a chat menu only listing innate monster attacks from the Monster tab of the AD&D2e Character Sheet.<br>
+
<p>Displays a chat menu only listing innate monster attacks from the Monster tab of the AD&D2e Character Sheet.</p>
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.<br>
+
<p>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 [&lt;Attack name&gt;,]&lt;damage dice roll&gt;[,&lt;speed&gt;][,&lt;attack type&gt;] for example <code>Claw,1d8,2,S</code> and <code>Club+1,2d4+1,5,B</code>.  These will result in possible initiative actions for that creature for <b>Claw</b> and <b>Club+1</b>.  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. The optional attack type of S(slashing), P(piercing), or B(bludgeoning), or any combination of these, will be used by the <b>AttackMaster API</b> when displaying the success or otherwise of a targeted attack.</p>
 
+
====Display initiative actions for a weapon-wielding creature to attack====
===Display initiative actions for a weapon-wielding creature to attack===
+
 
<pre>--complex [token-id]</pre>
 
<pre>--complex [token-id]</pre>
Takes an optional token ID.  If token ID is not supplied, the selected token is used.<br>
+
<p>Takes an optional token ID.</p>
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.<br>
+
<p>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 <b>AttackMaster API</b> 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.</p>
 
+
====Display initiative actions for Wizard spells====
===Display initiative actions for Wizard spells===
+
 
<pre>--muspell [token-id]</pre>
 
<pre>--muspell [token-id]</pre>
Takes an optional token ID.  If token ID is not supplied, the selected token is used.<br>
+
<p>Takes an optional token ID.</p>
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.<br>
+
<p>Displays a menu of Wizard spells that the Character / NPC has memorised (see the <b>MagicMaster API</b> documentation for memorising spells, or see <i>RPGMaster CharSheet Setup</i> handout 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.</p>
 
+
====Display initiative actions for Priest spells====
===Display initiative actions for Priest spells===
+
 
<pre>--prspell [token-id]</pre>
 
<pre>--prspell [token-id]</pre>
Takes an optional token ID.  If token ID is not supplied, the selected token is used.<br>
+
<p>Takes an optional token ID.</p>
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.<br>
+
<p>Displays a menu of Priest spells that the Character / NPC has memorised (see the <b>MagicMaster API</b> documentation for memorising spells, or see <i>RPGMaster CharSheet Setup</i> handout 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.<p>
 
+
====Display initiative actions for powers====
===Display initiative actions for powers===
+
 
<pre>--power [token-id]</pre>
 
<pre>--power [token-id]</pre>
Takes an optional token ID.  If token ID is not supplied, the selected token is used.<br>
+
<p>Takes an optional token ID.</p>
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.<br>
+
<p>Displays a menu of Powers that the Character / NPC has been granted (see the <b>MagicMaster API</b> documentation for managing powers, or see <i>RPGMaster CharSheet Setup</i> handout 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.</p>
 
+
====Display initiative actions for Magic Items====
===Display initiative actions for Magic Items===
+
 
<pre>--mibag [token-id]</pre>
 
<pre>--mibag [token-id]</pre>
Takes an optional token ID.  If token ID is not supplied, the selected token is used.<br>
+
<p>Takes an optional token ID.</p>
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.<br>
+
<p>Displays a menu of Magic Items and non-magical equipment that the Character / NPC / creature has on their person - that is in the Item table (by default, the Potions table on the AD&D2e character sheet): see the Character Sheet Setup handout, or the <b>MagicMaster API</b> documentation for information on Items.  Selecting an item for initiative uses the speed of action of that item to calculate the Turn Order priority.</p>
 
+
====Display initiative actions for Thieves====
===Display initiative actions for Thieves===
+
 
<pre>--thief [token-id]</pre>
 
<pre>--thief [token-id]</pre>
Takes an optional token ID.  If token ID is not supplied, the selected token is used.<br>
+
<p>Takes an optional token ID.</p>
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.<br>
+
<p>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.</p>
 
+
====Display other actions ====
===Display other actions===
+
 
<pre>--other [token-id]</pre>
 
<pre>--other [token-id]</pre>
Takes an optional token ID.  If token ID is not supplied, the selected token is used.<br>
+
<p>Takes an optional token ID.</p>
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).<br>
+
<p>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).</p>
 
+
<br>
==Maintain the Turn Order and Rounds==
+
===Maintain the Turn Order and Rounds===
===Display the DM’s round maintenance menu===
+
====Display the DM's round maintenance menu====
 
<pre>--maint</pre>
 
<pre>--maint</pre>
DM Only command.  Does not take any parameters.<br>
+
<p>DM Only command.  Does not take any parameters.</p>
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:<br>
+
<p>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:</p>
 
{| class="wikitable"
 
{| class="wikitable"
 
|+  
 
|+  
Line 235: Line 274:
 
|| !rounds --stop || After confirmation, performs a Full Stop and re-start of the RoundMaster API, dropping all internal tables of statuses & effects, token markers, timers etc.  Use with care!
 
|| !rounds --stop || After confirmation, performs a Full Stop and re-start of the RoundMaster API, dropping all internal tables of statuses & effects, token markers, timers etc.  Use with care!
 
|}
 
|}
===Display those characters that have not yet had initiative actions selected===
+
====Display those characters that have not yet had initiative actions selected====
 
<pre>--check-tracker</pre>
 
<pre>--check-tracker</pre>
DM Only command.  Does not take any parameters.<br>
+
<p>DM Only command.  Does not take any parameters.</p>
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.<br>
+
<p>Uses the Player Character name list created & maintained in the <b>--init</b> menu or with the <b>--list-pcs</b> 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.</p>
 
+
====Change the list of characters in the Party====
===Change the list of characters in the Party===
+
 
<pre>--list-pcs < ALL / MAP / REPLACE / ADD ></pre>
 
<pre>--list-pcs < ALL / MAP / REPLACE / ADD ></pre>
DM Only command.  Takes a specifier for the tokens to have in the Player Character list which must be one of those listed.<br>
+
<p>DM Only command.  Takes a specifier for the tokens to have in the Player Character list which must be one of those listed.</p>
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:<br>
+
<p>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 <b>--init</b> menu, and is used by <b>--check-tracker</b> and <b>--end-of-day</b> commands.  The list persists between sessions of game-play.  The following parameters have the following effects:</p>
 
{| class="wikitable"
 
{| class="wikitable"
 
|+  
 
|+  
Line 260: Line 298:
 
|}
 
|}
  
==End of Day processing==
+
===End of Day processing===
 
<pre>--end-of-day [ASK/ASKTOREST/OVERNIGHT/REST/SET/FOES]|[=][cost]</pre>
 
<pre>--end-of-day [ASK/ASKTOREST/OVERNIGHT/REST/SET/FOES]|[=][cost]</pre>
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 =.<br>
+
<p>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 '='.</p>
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).<br>
+
<p>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 <b>MagicMaster API</b> 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 <b>AttackMaster API</b> documentation about recovery of ammunition and its loss over a Long Rest).</p>
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).<br>
+
<p>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 <i>cost</i> 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).</p>
 
{| class="wikitable"
 
{| class="wikitable"
 
|+  
 
|+  
Line 298: Line 336:
 
|}
 
|}
  
==Other Commands==
+
===Other Commands===
===Display help on these commands===
+
====Display help on these commands====
 
<pre>--help</pre>
 
<pre>--help</pre>
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.<br>
+
<p>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.</p>
 
+
====Handshake with other APIs====
===Handshake with other APIs===
+
<pre>--hsq from|[command]<br>
<pre>!rounds --hsq from|[command]
+
--handshake from|[command]</pre>
!rounds --handshake from|[command]</pre>
+
<p>Either form performs a handshake with another API, whose call (without the '!') is specified as the <i>from</i> paramater in the command parameters.  The response from InitiativeMaster 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. </p>
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 API receiving the command calls the from API command responding with its own command to confirm that it is loaded and running: e.g. <br>
+
<p>Received: <i>!init --hsq magic</i><br>
'''Received:''' !init --hsq magic<br>
+
Response: <i>!magic --hsr init</i></p>
'''Response:''' !magic --hsr init<br>
+
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.</p>
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.<br>
+
<p>Optionally, a command query can be made to see if the command is supported by InitMaster if the command string parameter is added, where command is the InitMaster command (the '--' text without the '--').  This will respond with a true/false response: e.g.</p>
Optionally, if the command string parameter is added, a command query can be made to see if the command is supported by InitiativeMaster. ''command'' is the InitiativeMaster command (the --text without the --).  This will respond with a true/false response: e.g.<br>
+
<p>Received: <i>!init --handshake attk|monster</i><br>
'''Received:''' !init --handshake attk|monster<br>
+
Response: <i>!attk --hsr init|monster|true</i></p>
'''Response:''' !attk --hsr init|monster|true<br>
+
====Switch on or off Debug mode====
Which means AttackMaster has queried if InitiativeMaster has a command called --monster, and InitiativeMaster has responded in the affirmative.<br>
+
 
+
===Switch on or off Debug mode===
+
 
<pre>--debug (ON/OFF)</pre>
 
<pre>--debug (ON/OFF)</pre>
Takes one mandatory argument which should be ON or OFF.<br>
+
<p>Takes one mandatory argument which should be ON or OFF.</p>
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.<br>
+
<p>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.</p>
 
+
=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.<br>
+
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.<br>
+
The recommended Token Bar assignments for all APIs in the Master Series are:<br>
+
{| class="wikitable"
+
|+
+
|-
+
! scope="row"| Bar1 (Green Circle):
+
|| Armour Class (AC field) – only current value
+
|-
+
! scope="row"| Bar2 (Blue Circle):
+
|| Base Thac0 (thac0-base field) before adjustments – only current value
+
|-
+
! scope="row"| Bar3 (Red Circle):
+
|| Hit Points (HP field) – current & max
+
|}
+
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.<br>
+
These assignments can be changed in the APIs that use them, by changing the ''fields'' object near the top of the API script, but InitiativeMaster does not use these fields, so they are not mapped.<br>
+
 
+
==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 the next section for details.  This can be altered to get the API to work with other character sheets.<br>
+
The Initiative API, as with all the other RPGMaster series APIs use Roll20 Roll Templates extensively.  This is sometimes the only way to get Roll20 to roll 3D animated dice (using a Character Sheet ability macro triggered by a Player), as 3D animated dice do not work when commanded by an API via a sendchat() call, due to a reported bug. Of course, there is a default Roll Template provided by the Roll20 system, but it is a bit clunky and Roll Templates provided by Character Sheet coders are often better.  InitiativeMaster and other RPGMaster APIs use these Character Sheet-defined Roll Templates, by default from the AD&D 2e Character Sheet.  As with every other field, the Roll Templates used can be altered in the ''fields'' object.<br>
+
The coding of the API is designed to use the AD&D 2E system of initiative systems and calculations.  If you use another system, it might be that one of the "Standard", "Group", or "Individual" initiative rule systems implemented in the system will work for you.<br>
+
 
+
==Matching the API to a type of Character Sheet==
+
The API has an object definition called ''fields'', which contains items of the form<br>
+
''Internal_api_name: [sheet_field_name, field_attribute, optional_default_value, optional_set_with_worker_flag]''<br>
+
A typical example might be:<br>
+
<pre> Fighter_level:['level-class1','current'],
+
Or
+
MUSpellNo_memable:['spell-level-castable','current','',true],</pre>
+
In order to change the field that the API uses on the character sheet for a different one, you can change the ''sheet_field_name'' and/or ''field_attribute'' for the one you want to use.  <u>'''However, the ''Internal_api_name'' and the other values should not be changed'''</u> as otherwise the system will not work.<br>
+
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.<br>
+
''Internal_api_table: [sheet_repeating_table_name,starting_index]''<br>
+
An example is:<br>
+
<pre>MW_table:['repeating_weapons',0],</pre>
+
<u>'''The ''Internal_api_name'' must not be altered!'''</u> 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.<br>
+
Each character sheet must have repeating tables to hold weapons, ammo, spells 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, spells in the repeating_spells 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.<br>
+
 
+
==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 the section above).<br>
+
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.<br>
+
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.<br>
+
'''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.<br>
+
'''Note:''' classes of Fighter and Rogue (such as Paladins, 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.  They '''do not''' also need an entry under a spellcaster column.<br>
+
The following Classes are currently supported, and the class name must be entered into the class field.  If missing, the top row is assumed in each case:<br>
+
{| class="wikitable"
+
|+
+
|-
+
! Fighter classes !! Wizard Classes !! Priest Classes !! Rogue Classes !! Psion Classes
+
|-
+
| Warrior || Wizard || Priest || Rogue || Psion
+
|-
+
| Fighter || Mage || Cleric || Thief ||
+
|-
+
| Ranger || Abjurer || Druid || Bard ||
+
|-
+
| Paladin || Conjurer || Healer || Assassin ||
+
|-
+
| Beastmaster || Diviner || Priest of Life ||  ||
+
|-
+
| Barbarian || Enchanter || Priest of War || ||
+
|-
+
| Defender (Dwarven) || Illusionist || Priest of Light || ||
+
|-
+
| || Invoker || Priest of Knowledge || ||
+
|-
+
| || Necromancer || Shaman || ||
+
|-
+
| || Transmuter || || ||
+
|}
+
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.  If not entered, 0 (zero) is assumed (i.e. a commoner)<br>
+
 
+
==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.<br>
+
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).<br>
+
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.<br>
+
 
+
==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.<br>
+
==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.<br>
+
<br>
+
=Character Sheet data fields =
+
As stated in the previous section, 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 =
 
= Changelog =
 +
{{changelog version|1.5.01|2023-05-19|* Removed CheckAC call from initiative submission in an attempt to speed up multi-user experience.
 +
* Fixed weapon menu display of creature attack descriptions.
 +
* Made initiative processing much more asynchronous to improve user response.}}
 +
{{changelog version|1.4.05|2023-03-02|* Add initiative selection for in-hand magical item attacks to the Attack and Magic Item initiative menus}}
 +
{{changelog version|1.4.01|2022-11-28|* Deal with fighting styles. Extended String prototype with dbName() method.}}
 +
{{changelog version|1.3.03|2022-10-31|* Fixed bug in Initiative Redo command}}
 +
{{changelog version|1.3.02|2022-10-21|* Gray out attack initiative buttons for weapons without charges}}
 +
{{changelog version|1.3.01|2022-10-10|* Fixed initiative for classes that have multi-class spell casting}}
 +
{{changelog version|1.3.00|2022-10-01|* Major release to extract all RPG version-specific data and rule processing to RPGMaster Library API}}
 +
{{changelog version|1.041|2022-01-23|* Corrected initiative modifier for haste & slow on 2nd and subsequent attacks in a round, and corrected a slight issue with Bow specialist initiative
 +
* Corrected illegal characters not rendered by One-Click install
 +
* Fixed issue with non-character tokens displaying errors on end-of-day}}
 +
{{changelog version|1.039|2022-01-16|* Added all Roll Template names to fields object
 +
* Fixed illegal characters in handout text
 +
* Found & fixed errors in command registration with CommandMaster API
 +
* Corrected initiative modifier for haste & slow on 2nd and subsequent attacks in a round
 +
* Corrected a slight issue with Bow specialist initiative}}
 
{{changelog version|1.037|2021-12-05|* First version for public release}}
 
{{changelog version|1.037|2021-12-05|* First version for public release}}
 
{{changelog version|1.012|2021-01-29|* First gaming release to test group of players}}
 
{{changelog version|1.012|2021-01-29|* First gaming release to test group of players}}
Line 414: Line 379:
 
[[Category:AD&D 2E]]
 
[[Category:AD&D 2E]]
 
[[Category:Combat/Initiative]]
 
[[Category:Combat/Initiative]]
 +
[[Category:API:RPGMaster]]

Latest revision as of 17:02, 12 June 2023

Main Page: API:Script Index

API ScriptAuthor: Richard E
Version: 1.5.01
Last Modified: 2023-05-19
Code: InitMaster
Dependencies: RoundMaster RPGMlibrary AD+D2e
Conflicts: None

InitiativeMaster supports initiative for RPGs (initially only AD&D 2e) using the Turn Order and the t Turn Tracker window. It's a part of the RPGMaster-series of APIs.

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
  • performing the “End of Day” activity.

Note: This API requires that the RoundMaster API and a RPGMaster Library API is loaded, which provides RPG version-specific and Roll20 Character Sheet version-specific data, rulesets and processing (as well as other goodies!), to the extent that InitiativeMaster cannot work without them (though the reverse is possible). InitiativeMaster also works closely with AttackMaster and MagicMaster, and uses the data configured on the Character Sheet by these other APIs, although it can use manually completed Character Sheets once correctly configured.

Contents

[edit] Forum

RPGMaster Forum

[edit] Configuring Character Sheets

RPGMaster Character Sheet setup - RPGMaster Character Sheet setup Wiki page

[edit] 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 --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).

[edit] 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.

[edit] 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.

[edit] Using Character Sheet Ability/Action buttons

The most common approach for the Player to run these commands is to use Ability macros on their Character Sheets which are flagged to appear as Token Action Buttons: Ability macros & Token Action Buttons are standard Roll20 functionality, refer to the Roll20 Help Centre for information on creating and using these.

In fact, the simplest configuration is to provide only Token Action Buttons for the menu commands: --menu and --monmenu. From these, most other commands can be accessed. If using the CommandMaster API, its character sheet setup functions can be used to add all the necessary and/or desired Ability Macros and Token Action Buttons to any Character Sheet.

[edit] How Initiative Master API works

The Initiative Master API ("InitMaster") provides commands that allow the DM to set and manage the type of initiative to be used in the campaign, and for Players to undertake initiative rolls. The API uses data on the Character Sheet represented by a selected token to show menus of actions that can be taken: these commands are often added to the Character Sheet as Ability Macros that can be shown as Token Actions (see Roll20 Help Centre for how to achieve this, or the CommandMaster API documentation). The API displays resulting Turn Order token names with action priorities in the Turn Order Tracker window (standard Roll20 functionality - see Roll20 documentation & Help Centre).

Note: Use the --maint command to display the Maintenance Menu and start the RoundMaster API using the Start / Pause button (at the top of the displayed menu) before using the Turn Order Tracker. The top entry in the Turn Order Tracker window should change from showing a "Stopped" symbol, and change to a "Play". <p>The API must be used with both the RoundMaster API and the game-version-specific RPGMaster Library. The RPGMaster Library sets all the right parameters for the RPGMaster APIs to work with different D&D game versions and different Roll20 D&D character sheets. Ensure you have the right library loaded for the game version you are playing and the character sheet version you have loaded.

Specifying a token

Most of the InitiativeMaster API commands need to know the token_id of the token that represents the character, NPC or creature that is to be acted upon. This ID can be specified in two possible ways:

  1. explicitly in the command call using either a literal Roll20 token ID or using @{selected|token_id} or @{target|token_id} in the command string to read the token_id of a selected token on the map window,
    or
  2. by having a token selected on the map window, not specifying the token_id in the command call, and allowing the API to discover the selected token_id.

In either case, if more than one token is selected at the time of the call then using either @{selected|token_id} to specify the token in the command call, or allowing the command to find a selected token, is likely (but not guaranteed) to take the first token that was selected. To avoid ambiguity, it is generally recommended to make command calls with only one token selected on the map window.

Types of Initiative System

The API supports several methods for initiative: "standard", "group" and "individual", selectable by the DM in-game and changeable during game play, if desired.

"Standard" initiative just requires a "Party" initiative dice roll and a "Foe" initiative dice roll to be entered, and the Turn Order entries are set appropriately. For "Group" initiative, the same rolls are entered but, in addition, the action of each character / NPC / creature (each token) taking part specifies what actions they are going to perform that round and the speed of that action is added to the relevant group dice roll to create the Turn Order priority for that token. For "Individual" initiative, each character / NPC / creature makes its own individual dice roll as well as specifying their action, with the individual dice roll and speed of action being combined to give the Turn Order priority.

Alternatively, standard Roll20 functionality can be used to "right click" on a token and choose the option to add it to the Turn Order, and the --maint command can be used to set "Stop Melee" button, thus stopping the Turn Order from being cleared each round, and then the Initiative will just cycle round the party members.

Monster Attack Initiatives

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],[dmg type] 

for example Claw,1d8,2,S and Club+1,2d4+1,5,B. These will result in possible initiative actions for that creature for Claw and Club+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.

Effect of Magic on Initiative

The system can take into account various modifiers applied by spells and/or magic items (e.g. Haste and Slow spells), and the spell, power & magic item macros provided with the MagicMaster API use this functionality when used in conjunction with RoundMaster Effects. The Character Sheet Setup handout states which Character Sheet fields to enter the modifiers into in order for them to be taken into account.

Multi-attack Initiatives

The system can also create multiple initiative turns for weapons that achieve multiple attacks per round, like bows and daggers, as well as by the class, level and proficiency of the character or any combination of the three as per the D&D game version rules (held in the specific version of the RPGMaster Library you have loaded), including 3 attacks per 2 rounds, or 5 per 2. Also Fighter and Rogue classes using 2 weapons are catered for, even with those weapons possibly having multiple attacks themselves - the weapon specified by the character as the Primary will achieve its multiple attacks, whereas the secondary weapon will only get the number of attacks specified as per the rules for multiple attacks in the game version you are using.

Multi-round Initiatives

Multi-round initiatives are also supported e.g. for spells like Chant which takes 2 rounds. Any Character Sheet entry that has a speed (note: action speed only, not action plus initiative roll) of longer than 10 segments (1/10ths of a round), when chosen by a player, will add an entry for that action not only in the current round but also in the following and subsequent rounds as appropriate. Each new round, when they select to specify an initiative action (e.g. using !init --menu) the Player of that character (or the DM for a Foe) is asked if they want to continue with the action or has it been interrupted: if interrupted or stopped by choice the player can choose another action for that character, otherwise the "carried forward" action is added to the tracker.

Note: the Player (or DM) must still select to do initiative each round for this to happen.

Changing an Initiative Action

If using "Group" or "Individual" initiative and a Player has completed selecting an initiative action for a Character (or the DM for a Foe) and changes their mind about what they are doing before the DM starts the round, the Player can select the token and rerun the relevant command (use the relevant token action button) to do initiative again (presuming the DM's agreement). The system will warn the Player that initiative has already been completed for the Character and present a new button to redo initiative if the Player wants to (this is so that accidental selection of the redo command is prevented) - all entries for the token name will be removed from the Turn Order and the relevant menus presented again to the Player.

Selecting any particular action for initiative does not force that to be the action the Player takes on their turn. When that Character's turn comes up in the Turn Order, a message is displayed to all Players and the DM stating the action that was selected for initiative for that token (DM-controlled NPCs & creatures only display to the Players that it is their turn, not what they are doing, while the DM gets a full action message). The Player can then take that action, or do something else entirely (presumably with the DM's agreement) for instance if circumstances have changed (e.g. the foe being attacked has died prior to an "Attack" action).

In Summary

InitMaster manages the whole of this process seamlessly, and in addition will support actions that result in more than one Turn Order entry (such as firing a bow that can make two shots per round), automatically taking into account character class to allow two-weapon attack actions, supporting initiative for "dancing" weapons (when used with the AttackMaster and MagicMaster APIs), and other complex aspects of initiative.

The easiest way to set up Character Sheets for InitMaster operation is by using the rest of the APIs in the Master series:

RPGMaster Library for the game version you are playing is required for the operation of all RPGMaster APIs (except RoundMaster). It holds the version-specific rules, parameters and databases for the game version.

RoundMaster API is required for the operation of InitMaster. It manages all aspects of interaction with the Turn Order Tracker window in Roll20, and the management of token statuses and Effects.

CommandMaster API will add the relevant DM Macro Bar buttons, and Token Action Buttons to a Character Sheet for all commands needed for each of the APIs, including InitiativeMaster.

MagicMaster API will support entering the correct data on the sheet for all sorts of weapons, magic items, spells and powers, through looting chests & bodies, learning & memorising spells and being granted powers. Initiative actions can then use these items with the correct action speed.

AttackMaster API will arm the character by taking weapons and/or shields "in hand". Initiative actions can then be selected for attacks with these weapons using the correct speed modifiers. AttackMaster will also support making attacks with all the relevant modifiers, changing the weapons in-hand, managing ammunition for ranged weapons, selecting the correct range for ranged weapons and applying the right modifiers, supporting magical weapons and artifacts, and also dealing with armour, armour classes & saves.

Token setup for use with the Master series of APIs is simple (to almost non-existent) and explained in the Character Sheet Setup handout.


[edit] Command Index

All commands are preceded by !init unless otherwise stated.

[edit] Manage Initiative type, rolls & party

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

[edit] Show group / individual Initiative menus

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

[edit] 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]

[edit] Maintain the Turn Order and Rounds

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

[edit] End of Day processing

--end-of-day [Type]|[=][cost]

[edit] Other commands

--help
--handshake from | [cmd]
--hsq from | [cmd]
--hsr from | [cmd] | [TRUE/FALSE]
--debug ON/OFF


[edit] Detail of Commands

[edit] Manage Initiative type, rolls & party

[edit] 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 "individual":

Standard: the Party and the Foes (GM) each roll 1d10, and all of whichever gets the lowest roll goes first. The system supports taking the two rolls, and putting entries in the Turn Order for all defined Party members, and one entry for the Foes.
Group: the Party and the Foes (GM) each roll 1d10, and then all Party members and all Foes choose what actions they will perform during the next round. The speed/casting time of the Character’s / Foes selected action will then be added to the relevant roll to define the Character’s / Foes initiative(s) which are added to the Turn Order.
Individual: each individual Character & Foe chooses what action they will do each round, and the speed/casting time of that action is added to an individual system-rolled 1d10 for that Character / Foe resulting in each Character’s initiative(s) which are all added to the Turn Order.

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 an API Button on the menu.

[edit] 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.


[edit] Show Group / Individual initiative action selection menus

[edit] 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 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 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 concurrent not sequential.

See the individual menu explanations for more detail on each type of action.

[edit] 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.


[edit] Action specific Initiative menus

[edit] 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 RPGMaster CharSheet Setup handout) or loaded using the 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 are also buttons for "Other" actions, such as Moving, Changing Weapon (which takes a round), doing nothing, or Player-specified actions - see the --other command.

[edit] 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>][,<attack type>] for example Claw,1d8,2,S and Club+1,2d4+1,5,B. These will result in possible initiative actions for that creature for Claw and Club+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. The optional attack type of S(slashing), P(piercing), or B(bludgeoning), or any combination of these, will be used by the AttackMaster API when displaying the success or otherwise of a targeted attack.

[edit] 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.

[edit] 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 RPGMaster CharSheet Setup handout 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.

[edit] 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 RPGMaster CharSheet Setup handout 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.<p>

[edit] Display initiative actions for powers

--power [token-id]
<p>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 RPGMaster CharSheet Setup handout 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.

[edit] 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 Item table (by default, the Potions table on the AD&D2e character sheet): see the Character Sheet Setup handout, or 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.

[edit] 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.

[edit] 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).


[edit] Maintain the Turn Order and Rounds

[edit] 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:

Maintenance Menu Button Command Implemented Description
Start / Pause  !rounds --start Starts / Pauses RoundMaster functioning
Start Melee  !rounds --clearonround on
--clear
Causes the Turn Order to automatically clear at the end of each round (once all actions have completed) ready for Players to select actions for their Characters
Stop Melee  !rounds --clearonround off Stops the Turn Order from automatically clearing at the end of each round, so that the Turn Order is preserved. Can be useful when just wanting to cycle around a list of Characters selected in the !init –init menu command and running ‘Standard’ initiative.
Re-start  !rounds --sort Re-sorts the current Turn Order, effectively re-starting the round. Useful if the DM accidentally starts the next round by moving the Turn Order on before all Players have completed their initiative actions – allow new actions to be selected and then use Re-start
Set Round Number  !rounds --reset # Sets the current Round number to #. If # is larger than the current round, all token status counters will advance by the number of rounds difference, ending if they reach 0 with the consequential Effects triggered
Clear Turn Order  !rounds --clear Clears the Turn Order of all entries (except the round number)
Remove Tokens from Tracker  !rounds --removefromtracker Removes all the selected tokens from the Turn Order and the Tracker window. Multiple tokens can be selected and removed all at the same time.
Edit Selected Tokens  !rounds --edit Displays the status markers on all the selected tokens, and offers options to edit or delete them. The “spanner” icon edits the status, and the “bin” icon deletes it.
Move Token Status  !rounds --moveStatus For each of the selected tokens in turn, searches for tokens in the whole campaign with the same name and representing the same character sheet, and moves all existing statuses and markers from all the found tokens to the selected token (removing any duplicates). This supports Players moving from one Roll20 map to another and, indeed, roundMaster detects page changes and automatically runs this command for all tokens on the new page controlled by the Players who have moved to the new page.
Clean Selected Tokens  !rounds --clean Drops all status markers from the selected token, whether they have associated effects or time left, or are just manually applied markers. Useful when there might have been corruption, or everyone is just confused! The token statuses still exist, and associated markers will be correctly rebuilt at the start of the next round or the next trigger event (but not manually added ones).
Enable Long Rest for PCs  !init –end-of-day <cost> Run the normal initMaster end-of-day command
Enable Long Rest for selected tokens  !init –enable-rest Enable a long rest only for the characters / NPCs / creatures represented by the selected tokens. See the MagicMaster API documentation for information on Long Rests
Set Date Currently not implemented – future expansion
Set Campaign Currently not implemented – future expansion
Update Selected Tokens  !cmd --abilities Use the CommandMaster API function to setup and maintain Character ability action buttons, weapon proficiencies, spell books & granted powers, saving throws, token “bar & circle” assignment etc. See CommandMaster API documentation on the –abilities command.
Emergency Stop!  !rounds --stop After confirmation, performs a Full Stop and re-start of the RoundMaster API, dropping all internal tables of statuses & effects, token markers, timers etc. Use with care!

[edit] 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.

[edit] 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:

all: looks across all tokens in the campaign and creates a new list composed of those representing Character Sheets controlled by a Player (standard Roll20 Character Sheet functionality – refer to the Help Centre for information on setting Players to control Character Sheets and their tokens).
map: creates a new list that only has Characters represented by tokens on the current Player map that are controlled by Players. (See Roll20 Help Centre on how to select the current Player map).
replace: creates a new list including all the currently selected token(s) (whomever controls them), and no others.
add: adds the currently selected token(s) (whomever controls them) to the existing list leaving all the others unchanged.

[edit] 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).

ASK: If no rest type is supplied, or ASK is used, the DM is asked to confirm if they wish the cost to be deducted from/earned by all the Characters listed. If No is selected, nothing is deducted or earned. The system then sets flags to allow Players to perform a Rest command on their characters (see MagicMaster API).
ASKTOREST: Asks the DM to confirm the cost/earnings in the same way as ASK, but then automatically performs the MagicMaster API –rest command for each character in the party, and the Players do not need to do so.
OVERNIGHT: Applies the cost to the Party members and enables them to rest (they have to do the rest themselves). If cost (or the previously set default cost) is not a number (e.g. a Roll Query), asks if a charge is to be made.
REST: Does the same as OVERNIGHT, but automatically runs the MagicMaster API –rest command for all characters in the party, and the Players do not need to do so.
FOES: Does the same as OVERNIGHT, but for all NPCs and Monsters, allowing them to rest.
SET: If the rest type is SET and/or there is an ‘=’ before the cost, will not run the ‘End-of-Day’, but instead will set the standard cost for each night if no cost parameter is given when other commands are used. If the ‘=’ is followed by a Roll Query (see Roll20 Help Centre for information on Roll Queries), the Roll Query will be run each time the –end-of-day command is run without a cost parameter, allowing (for instance) the DM to select from a list of possible daily costs or earnings. However, remember to replace the ‘?’ at the start of the Roll Query with &#63; so that the Roll Query does not run when it is passed in to be set. Other characters can be substituted as follows:
Character  ? [ ] < > @ - |  : & { }
Substitute ^ << >> ` ~ ¦ &amp; &#123; &#125;
Alternative (no ; ) \ques \lbrak \rbrak \lt \gt \at \dash \vbar \clon \amp \lbrc \rbrc

[edit] Other Commands

[edit] 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.

[edit] Handshake with other APIs

--hsq from|[command]<br>
--handshake from|[command]

Either form performs a handshake with another API, whose call (without the '!') is specified as the from paramater in the command parameters. The response from InitiativeMaster 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.</p>

Optionally, a command query can be made to see if the command is supported by InitMaster if the command string parameter is added, where command is the InitMaster 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

[edit] 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.

[edit] Changelog

v1.5.01 (2023-05-19)

  • Removed CheckAC call from initiative submission in an attempt to speed up multi-user experience.
  • Fixed weapon menu display of creature attack descriptions.
  • Made initiative processing much more asynchronous to improve user response.


v1.4.05 (2023-03-02)

  • Add initiative selection for in-hand magical item attacks to the Attack and Magic Item initiative menus


v1.4.01 (2022-11-28)

  • Deal with fighting styles. Extended String prototype with dbName() method.


v1.3.03 (2022-10-31)

  • Fixed bug in Initiative Redo command


v1.3.02 (2022-10-21)

  • Gray out attack initiative buttons for weapons without charges


v1.3.01 (2022-10-10)

  • Fixed initiative for classes that have multi-class spell casting


v1.3.00 (2022-10-01)

  • Major release to extract all RPG version-specific data and rule processing to RPGMaster Library API


v1.041 (2022-01-23)

  • Corrected initiative modifier for haste & slow on 2nd and subsequent attacks in a round, and corrected a slight issue with Bow specialist initiative
  • Corrected illegal characters not rendered by One-Click install
  • Fixed issue with non-character tokens displaying errors on end-of-day


v1.039 (2022-01-16)

  • Added all Roll Template names to fields object
  • Fixed illegal characters in handout text
  • Found & fixed errors in command registration with CommandMaster API
  • Corrected initiative modifier for haste & slow on 2nd and subsequent attacks in a round
  • Corrected a slight issue with Bow specialist initiative


v1.037 (2021-12-05)

  • First version for public release


v1.012 (2021-01-29)

  • First gaming release to test group of players


v0.001 (2020-11-30)

  • Started development of InitiativeMaster