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.

[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: 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 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 ? 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	^	<<	>>			`	~	¦		&	{	}
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

Roll20 Wiki

Navigation

Personal tools

Toolbox

Difference between revisions of "Script:InitMaster"

From Roll20 Wiki

Latest revision as of 17:02, 12 June 2023

Contents

[edit] Forum

[edit] Configuring Character Sheets

[edit] Syntax

[edit] Installation and Configuration

[edit] Script Use

[edit] Using Character Sheet Ability/Action buttons

[edit] How Initiative Master API works

[edit] Command Index

[edit] Manage Initiative type, rolls & party

[edit] Show group / individual Initiative menus

[edit] Show action-specific Initiative menus

[edit] Maintain the Turn Order and Rounds

[edit] End of Day processing

[edit] Other commands

[edit] Detail of Commands

[edit] Manage Initiative type, rolls & party

[edit] Manage the Initiative process

[edit] Set the type of Initiative being used in the Campaign

[edit] Show Group / Individual initiative action selection menus

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

[edit] Display a menu of possible actions for the selected creature

[edit] Action specific Initiative menus

[edit] Display initiative actions to attack with the weapons "in-hand"

[edit] Display initiative actions for a simple creature to attack

[edit] Display initiative actions for a weapon-wielding creature to attack

[edit] Display initiative actions for Wizard spells

[edit] Display initiative actions for Priest spells

[edit] Display initiative actions for powers

[edit] Display initiative actions for Magic Items

[edit] Display initiative actions for Thieves

[edit] Display other actions

[edit] Maintain the Turn Order and Rounds

[edit] Display the DM's round maintenance menu

[edit] Display those characters that have not yet had initiative actions selected

[edit] Change the list of characters in the Party

[edit] End of Day processing

[edit] Other Commands

[edit] Display help on these commands

[edit] Handshake with other APIs

[edit] Switch on or off Debug mode

[edit] Changelog