Difference between revisions of "Script:InitMaster"
From Roll20 Wiki
Andreas J. (Talk | contribs) m |
|||
| Line 408: | Line 408: | ||
= Changelog = | = Changelog = | ||
| + | {{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}} | ||
Revision as of 07:21, 18 January 2022
 | Page Updated: 2022-01-18 |
Version: 1.037
Last Modified: 2021-12-02
Code: InitMaster
Dependencies: RoundMaster
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.
It works very closely with the RoundMaster API to the extent that InitiativeMaster cannot work without RoundMaster (though the reverse is possible). InitiativeMaster also works closely with 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.
This API is currently configured to only use the AD&D2e Character Sheet from Peter B. It uses the Roll Templates defined in that sheet extensively. It may be possible to use it with other character sheets if you follow the instructions under #Configuring the Token and Character Sheet for use with the API.
Future development will focus on implementing more generic functionality.
Syntax
The InitiativeMaster API is called using !init.
!init --help
Commands to be sent to the InitiativeMaster API must be preceeded by two hyphens ‘--’ as above for the --help command. Parameters to these commands are separated by vertical bars ‘|’, for example:
!init --init [party-roll]|[foes-roll]
If optional parameters are not to be included, but subsequent parameters are needed, use two vertical bars together with nothing between them, e.g.
!init --init |[foes-roll]
Commands can be stacked in the call, for example:
!init --doCharList ALL --init
When specifying the commands in this document, parameters enclosed in square brackets [like this] are optional: the square brackets are not included when calling the command with an optional parameter, they are just for description purposes in this document. Parameters that can be one of a small number of options have those options listed, separated by forward slash ‘/’, meaning at least one of those listed must be provided (unless the parameter is also specified in [] as optional): again, the slash ‘/’ is not part of the command. Parameters in UPPERCASE are literal, and must be spelt as shown (though their case is actually irrelevant).
Installation and Configuration
Copy the script's code, available from the menu on the right and stored at Roll20's API GitHub Repository. Paste the code into a new script in your campaign's API Script Editor. Save the new script and it will be available inside your campaign. It will install several new Character Sheets & Handouts: The handout InitiativeMaster Help provides a full manual of how to use InitiativeMaster. The handout RPGMaster CharSheet Setup provides information on setting up a character sheet for use with InitiativeMaster.
Script Use
After installing the script, refer the the handout InitiativeMaster Help for full information on use. Below is a copy of the contents of that handout.
Command Index
All commands are preceded by !init unless otherwise stated.
Manage Initiative type, rolls & party
--init [party-roll]|[foes-roll] --type < STANDARD / GROUP / INDIVIDUAL >
--menu [token-id] --monmenu [token-id]
--weapon [token-id] --monster [token-id] --complex [token-id] --muspell [token-id] --prspell [token-id] --power [token-id] --mibag [token-id] --thief [token-id] --other [token-id]
Maintain the Turn Order and Rounds
--maint --check-tracker --list-pcs ALL / MAP / REPLACE / ADD
End of Day processing
--end-of-day [cost]
Other commands
--help --hsq from|[command] --handshake from|[command] --debug ON/OFF
Configuring the Token and Character Sheet for use
Character Sheet data fields
Command Details
Manage Initiative type, rolls & party
Manage the Initiative process
--init [party-roll]|[foes-roll]
DM Only command. Takes an optional dice roll result for the Party, and an optional dice roll result for the foes.
This command displays a chat menu to specify:
- the type of initiative to do (standard, group or individual),
- the initiative rolls for the Party and the Foes (for standard and group initiative),
- who is in the Party,
- to check if everyone has selected their action for the next round (for group and individual initiative),
- and whether to show this menu automatically as each new round starts.
The different types of AD&D2e Initiative process are explained in the DMG p55, and consist of “standard”, “group”, and “individual”:
| 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. |
|---|---|
| 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. |
| 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 another API Button.
Set the type of Initiative being used in the Campaign
--type < STANDARD / GROUP / INDIVIDUAL >
Takes a mandatory initiative type which must be one of those shown.
This command sets the initiative type to the specified type without bringing up the complete --init menu. The type of initiative specified persists between game sessions.
--menu [token-id]
Takes an optional token ID. If token ID is not supplied, the selected token is used.
This command displays a chat menu of buttons for types of action that the Character / NPC / creature can perform. Each of these buttons may take the Player to a more detailed list of specific action buttons. Selecting any of the buttons will add the speed/casting time and correct number of instances of the selected action to the group or individual initiative dice roll (1d10) and enter the result in the Turn Order using the RoundMaster API – ‘individual’-type initiative dice rolls are performed in the background by the API and there is currently no option for the Player to do the roll instead.
The system displays immediately and also records the action selected and the speed of that action along with any modifiers as a message to display when the Character’s / NPCs / creature’s turn comes around. For each type of action, once chosen, the “rate” is displayed as the number of attacks per round multiplied by any magical modifier (such as a Haste spell). The “speed” is displayed as the speed of the action in segments (1/10ths of a round), and the “modifier” is the bonus or penalty to the roll for other magical effects (such as a Slow spell).
For multiple actions per round, those subsequent to the first action with the same item have speeds in the Turn Order incremented from each other by the speed of the action: thus multiple attacks with a Longbow (2 per round, speed 8), after an initiative roll of 5 on a 1d10, will happen at priority 13 & 21. For attacks by a Fighter with two weapons, such as a Longsword (sp 5) in their left hand and a Short sword (sp 3) in their right hand, after an initiative roll of 5, the Short sword will get a Turn Order priority of 8 and the Longsword 10 – that is they are consecutive not sequential.
See the individual menu explanations for more detail on each type of action.
--monmenu [token-id]
Takes an optional token ID. If token ID is not supplied, the selected token is used.
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.
Display initiative actions to attack with the weapons ‘in-hand’
--weapon [token-id]
Takes an optional token ID. If token ID is not supplied, the selected token is used.
Displays a chat menu listing all the weapons that the Character / NPC / creature has ‘in-hand’ (i.e. that are currently in the Weapon and Ranged tables), with additional options as appropriate to the Character Sheet. Rogue class characters will get a ‘Backstab’ option which will apply the Rogue backstab multiplier as appropriate. Fighter & Rogue classes will get an option to choose two weapons (if there are two one-handed weapons in-hand) which presents the option of selecting a Primary and a Secondary weapon to do initiative for. Weapons can be those typed into the Character Sheet weapons tables (see Section 7 below) or loaded using AttackMaster API (see AttackMaster documentation).
If the Character / NPC / creature has Powers or Magic Items they can use, buttons also appear on the menu to go to the menus to select these instead of doing a weapon initiative – see the --power and --mibag commands. There is also a button for ‘Other’ actions, such as Moving, Changing Weapon (which takes a round), doing nothing, or Player-specified actions – see the --other command.
Display initiative actions for a simple creature to attack
--monster [token-id]
Takes an optional token ID. If token ID is not supplied, the selected token is used.
Displays a chat menu only listing innate monster attacks from the Monster tab of the AD&D2e Character Sheet.
Creatures using the Innate Monster Attack fields on the AD&D2e Character Sheet Monster tab benefit from an extended syntax for entries in these fields: each field can take [<Attack name>,]<damage dice roll>[,<speed>] for example Claw,1d8,2 and Sword+1,2d4+1,5. These will result in possible initiative actions for that creature for Claw and Sword+1. If Attack Name is omitted, the dice roll is displayed as the action name instead. If the speed is omitted, the Innate attack speed field value is used instead. The speed will then be used to calculate the Turn Order priority.
Display initiative actions for a weapon-wielding creature to attack
--complex [token-id]
Takes an optional token ID. If token ID is not supplied, the selected token is used.
Displays a more complex monster attack menu, with both ‘Innate’ attacks from the Monster tab as well as weapon attacks from the Character tab weapons tables (the API does not use the recently introduced Weapon table for Monsters on the Monster tab so that the AttackMaster API only has to deal with one set of tables) – see 3.1 above for entering weapons and 3.2 for setting up monster attacks. If the creature has powers or magic items, it will also offer action menu buttons for those. The selected attack or weapon speed will then be used to calculate the Turn Order priority.
Display initiative actions for Wizard spells
--muspell [token-id]
Takes an optional token ID. If token ID is not supplied, the selected token is used.
Displays a menu of Wizard spells that the Character / NPC has memorised (see the MagicMaster API documentation for memorising spells, or see Section 7 below for entering spells manually). Any spell that is still memorised can be selected for initiative, and the relevant casting time will be used to calculate the Turn Order priority.
Display initiative actions for Priest spells
--prspell [token-id]
Takes an optional token ID. If token ID is not supplied, the selected token is used.
Displays a menu of Priest spells that the Character / NPC has memorised (see the MagicMaster API documentation for memorising spells, or see Section 7 below for entering spells manually). Any spell that is still memorised can be selected for initiative, and the relevant casting time will be used to calculate the Turn Order priority.
Display initiative actions for powers
--power [token-id]
Takes an optional token ID. If token ID is not supplied, the selected token is used.
Displays a menu of Powers that the Character / NPC has been granted (see the MagicMaster API documentation for managing powers, or see Section 7 below for entering powers manually). Any power that has not been consumed can be selected for initiative, and the relevant casting time will be used to calculate the Turn Order priority.
Display initiative actions for Magic Items
--mibag [token-id]
Takes an optional token ID. If token ID is not supplied, the selected token is used.
Displays a menu of Magic Items and non-magical equipment that the Character / NPC / creature has on their person - that is in the Items table (by default, the Potions table on the AD&D2e character sheet): see Section 7.5 below and the MagicMaster API documentation for information on Items. Selecting an item for initiative uses the speed of action of that item to calculate the Turn Order priority.
Display initiative actions for Thieves
--thief [token-id]
Takes an optional token ID. If token ID is not supplied, the selected token is used.
Displays a menu of Thievish actions (with current percentage proficiencies of each). Selecting one for initiative uses the speed of action of that item to calculate the Turn Order priority.
Display other actions
--other [token-id]
Takes an optional token ID. If token ID is not supplied, the selected token is used.
Displays a menu of other (non-attacking) actions that the Character / NPC / creature can take, namely: Moving (speed 0 as it is an innate ability); Changing Weapon (also speed 0 but takes all round); Doing Nothing (obviously speed 0); and one that allows the Player to enter a description and specify a speed for that action (presumably with the agreement of the DM).
Maintain the Turn Order and Rounds
--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! |
Display those characters that have not yet had initiative actions selected
--check-tracker
DM Only command. Does not take any parameters.
Uses the Player Character name list created & maintained in the –init menu or with the –list-pcs command, and checks that all of the Character’s named have completed initiative selection to the point where their token name is in the Turn Order at least once, and appears in the Tracker window. Names those that have not in a message to the DM, or states that initiative is complete.
Change the list of characters in the Party
--list-pcs < ALL / MAP / REPLACE / ADD >
DM Only command. Takes a specifier for the tokens to have in the Player Character list which must be one of those listed.
Updates the internally held list of Characters that are controlled by Players (and others that the DM can add at will). This list is displayed on the --init menu, and is used by --check-tracker and --end-of-day commands. The list persists between sessions of game-play. The following parameters have the following effects:
| 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. |
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 |
Other Commands
Display help on these commands
--help
This command does not take any arguments. It displays a very short version of this document, showing the mandatory and optional arguments, and a brief description of each command.
Handshake with other APIs
!rounds --hsq from|[command] !rounds --handshake from|[command]
Either form performs a handshake with another API, whose call (without the ‘!’) is specified as from in the command parameters (the response is always an –hsr command). The API receiving the command calls the from API command responding with its own command to confirm that it is loaded and running: e.g.
Received: !init --hsq magic
Response: !magic --hsr init
Which means the MagicMaster API has requested a handshake with InitiativeMaster to see if it is loaded, and InitiativeMaster has responded, proving it is running and taking commands.
Optionally, 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.
Received: !init --handshake attk|monster
Response: !attk --hsr init|monster|true
Which means AttackMaster has queried if InitiativeMaster has a command called --monster, and InitiativeMaster has responded in the affirmative.
Switch on or off Debug mode
--debug (ON/OFF)
Takes one mandatory argument which should be ON or OFF.
The command turns on a verbose diagnostic mode for the API which will trace what commands are being processed, including internal commands, what attributes are being set and changed, and more detail about any errors that are occurring. The command can be used by the DM or any Player – so the DM or a technical advisor can play as a Player and see the debugging messages.
Configuring the Token and Character Sheet for use with the API
Token configuration
The API can work with any Token configuration but requires tokens that are going to participate in initiative actions for ‘Group’ and ‘Individual’ initiative to represent a Character Sheet, so that actions relevant to the token can be selected.
A single Character Sheet can have multiple Tokens representing it, and each of these are able to do individual initiative using the actions made possible by the data on the Character Sheet jointly represented. However, if such multi-token Characters / NPCs / creatures are likely to encounter spells that will affect the Character Sheet (such as Haste and Slow) they must be split with each Token representing a separate Character Sheet, or else the one spell will affect all tokens associated with the Character Sheet, whether they were targeted or not! In fact, it is recommended that tokens and character sheets are 1-to-1 to keep things simple.
The recommended Token Bar assignments for all APIs in the Master Series are:
| Bar1 (Green Circle): | Armour Class (AC field) – only current value |
|---|---|
| Bar2 (Blue Circle): | Base Thac0 (thac0-base field) before adjustments – only current value |
| 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.
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.
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.
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.
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.
Matching the API to a type of Character Sheet
The API has an object definition called fields, which contains items of the form
Internal_api_name: [sheet_field_name, field_attribute, optional_default_value, optional_set_with_worker_flag]
A typical example might be:
Fighter_level:['level-class1','current'], Or MUSpellNo_memable:['spell-level-castable','current','',true],
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. However, the Internal_api_name and the other values should not be changed as otherwise the system will not work.
Table names are slightly different: always have an internal_api_name ending in ‘_table’ and their definition specifies the repeating table name and the index of the starting row of the table or -1 for a static field as the 1st row, with the 2nd row starting at repeating row number 0.
Internal_api_table: [sheet_repeating_table_name,starting_index]
An example is:
MW_table:['repeating_weapons',0],
The Internal_api_name must not be altered! Doing so will cause the system not to work. However, the sheet_repeating_table_name and starting_index can be altered to match any character sheet.
Each character sheet must have repeating tables to hold weapons, ammo, 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.
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).
The Character’s race is also important for calculating saves and ability to use certain items. The race should be set in the appropriate Character Sheet field. Currently, the races ‘dwarf’, ‘elf’, ‘gnome’, ‘halfelf’, ‘halfling’, ‘half-orc’, and ‘human’ are implemented (not case sensitive, and spaces, hyphens and underscores are ignored). If not specified, human is assumed. The race impacts saves, some magic items and armour, and bonuses on some attacks.
The system supports single-class and multi-class characters. Classes must be entered in the appropriate fields on the Character Sheet. Classes and levels affect spell casting ability, weapon multiple attack numbers per round, ability to do two-weapon attacks with or without penalty, and the ability to backstab and the related modifiers among other things. Class and level also determine valid armour, shields, some magic items and saves.
Note: on the Advanced D&D 2e Character Sheet, Fighter classes must be in the first class column, Wizard classes in the second column, Priest classes in the third, Rogues in the fourth, and Psions (or any others) in the fifth. It is important that these locations are adhered to.
Note: classes of Fighter and Rogue (such as 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.
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:
| 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)
Spells and Powers
The best (and easiest) way to give a Character or NPC spells and powers is to use the MagicMaster API. However, for the purposes of just doing initiative and selecting which spell to cast in the round, the spells and powers can be entered manually onto the character sheet. Spells are held in the relevant section of the Spells table, which by default is set to the character sheet spells table, repeating_spells. As with other fields, this can be changed in the fields object. Note that on the Advanced D&D 2e character sheet Wizard spells, Priest spells & Powers are all stored in various parts of this one very large table.
If you are just using the character sheet fields to type into, add spells (or powers) to the relevant “Spells Memorised” section (using the [+Add] buttons to add more as required) a complete row at a time (that is add columns before starting the next row). Enter the spell names into the “Spell Name” field, and “1” into each of the “current” & “maximum” “Cast Today” fields – the API suite counts down to zero on using a spell, so in order for a spell to appear as available (not greyed out) on the initiative menus, the “current” number left must be > 0. This makes spells consistent with other tables in the system (e.g. potion dose quantities also count down as they are consumed, etc).
Then, you need to set the “Spell Slots” values on each level of spell to be correct for the level of caster. Just enter numbers into each of the “Level”, “Misc.” and “Wisdom” (for Priests) fields, and/or tick “Specialist” for the Wizard levels as relevant. This will determine the maximum number of spells memorised each day, that will appear in the spells Initiative Menu. Do the same for Powers using the “Powers Available” field. As with other fields on the character sheet, each of these fields can be re-mapped by altering the fields object in the APIs.
Magic Items and Equipment
All magic items and standard equipment, including weapons, armour, lanterns etc, are held in the Items table, which by default is set to the potions table, repeating_potions, on the Character Sheet. As with other fields, this can be changed in the fields object. The best way to put items into this table is by using the MagicMaster API. However, it generally is possible to enter item names and quantities directly into the table and use them within the system. Only items that also exist in the supplied databases will actually work fully with the API (i.e. be recognised by the API as weapons, armour, ammo, etc). Initial weapon, ammunition and armour databases are provided with the AttackMaster API, and in addition to these Initial magic item, spell and power databases are provided with the MagicMaster API. Other items can be in the table and used for undertaking initiative actions but will not otherwise be effective. New databases and database items can be added using the specifications and instructions contained in the AttackMaster and MagicMaster API documentation.
Weapons and Ammo
For the InitiativeMaster API to support weapon attack actions melee weapons, damage, ranged weapons and ammo must be entered directly into the melee weapon, damage, ranged weapon and ammo tables on the Character Sheet. This is best done using the AttackMaster API, which will ensure all the right values are entered in the right fields, including taking into account the impact of weapon proficiencies, specialisation, mastery, character races and class/level. However, manual entry will generally work to the extent to allow weapon attack initiative actions to be selected. Weapon name, speed and number of attacks are the most important fields for initiative.
Character Sheet data fields
As stated in 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
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
