Revision as of 19:07, 9 February 2022

Page Updated:   2022-02-09

Main Page: API:Script Index

CommandMaster API is part of the RPGMaster suite of APIs, which includes Script:RoundMaster, Script:InitMaster, Script:AttackMaster, Script:MagicMaster and CommandMaster.

It manages the initialisation of a Campaign to use the RPGMaster APIs, communication and command syntax updates between the APIs and, most importantly for the DM, easy menu-driven setup of Tokens and Character Sheets to work with the APIs.

Forum

RPGMaster Forum

How CommandMaster Works

The CommandMaster API coordinates other APIs in the RPGMaster API series and provides the DM with facilities to set the Campaign up to use them. It will initialise a Campaign in Roll20 to use the RPGMaster series APIs. APIs can register their commands with CommandMaster and, should they change in the future, CommandMaster will search all Character Sheets and databases for that command and offer the DM the option to automatically update any or all of those found to the new command structure of that API. Selected Tokens and their associated Character Sheets can be set up with the correct Token Action Buttons, with spell-users given spells in their spell book, fighters given weapon proficiencies, setting saving throws correctly, and linking token circles to standard Character Sheet fields.

Initialising a Campaign

Using the --initialise command will add a number of Player Macros for the DM that will run the most-used RPGMater DM commands, which can be flagged to appear in the Macro Bar at the bottom of the DM’s screen for ease of access.

Setting up tokens & character sheets

Selecting one or multiple tokens and running the --abilities command will allow token action buttons and RPGMaster API capabilities to be set up for all the represented Character Sheets at the same time, with variations as relevant to the data on the Character Sheets (e.g. Saving Throw table will be initialised with the right saving throws for the class, level, and race of character or monster).

Registering API commands

Any API command can be registered with CommandMaster using the --register command. This will allow the command registered to be added as a Token Action Button to Character Sheets by the abilities command, and to be optionally updated in all Character Sheets wherever used should the details of the registration change.

Editing Character Sheet abilities

Danger: this command is very powerful, and can ruin your campaign if mis-used! The --edit command can be used to change any string in Character Sheet ability macros to any other string, using ‘escaped’ characters to replace even the most complex strings. However, use with care!

How to use CommandMaster

Installation and Configuration

Copy the script's code, available either via the Roll20 One-Click Install system, or from the menu on the right and stored at Roll20's API GitHub Repository and 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 Handouts: The handout CommandMaster Help provides a full manual of how to use CommandMaster. The handout RPGMaster CharSheet Setup provides information on setting up a character sheet for use with CommandMaster and the rest of the RPGMaster API series.

Script Use

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

Syntax of CommandMaster calls

The CommandMaster API is called using !cmd.

!cmd --initialise

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

!cmd --register action|description|api-call|api-command|parameters

Commands can be stacked in the call, for example:

!cmd --initialise --abilities

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

Command Index

Commands

Campaign setup

--initialise
--abilities

Character Sheet configuration

--add-spells [POWERS/MUSPELLS/PRSPELLS] | [level]
--add-profs
--set-prof  [NOT-PROF/PROFICIENT/SPECIALIST/MASTERY] | weapon | weapon-type
--set-all-prof

Command and Ability maintenance

--register action|description|api-call|api-command|parameters
--edit old-string | new-string

Other commands

--help
--debug [ON/OFF]

Campaign setup

Initialise for RPGMaster APIs

--initialise

This command creates a number of Player Macros which can be found under the Player Macro tab in the Chat window (the tab that looks like three bulleted lines, next to the cog). These macros hold a number of DM commands that are useful in setting up and running a campaign. It is recommended that the “Show in Bar” flags for these macros are set, and the “Show Macro Bar” flag is set (the macro bar is standard Roll20 functionality - see Roll20 Help Centre for more information).

The buttons added are:

• Maint-menu: Runs the !init --maint command
• Token-setup: Runs the !cmd --abilities command
• Add-items: Runs the !magic --gm-edit-mi command
• End-of-Day: Runs the !init --end-of-day command
• Initiative-menu: Runs the !init --init command

The DM can drag Macro Bar buttons around on-screen to re-order them, or even right-click them to change their name and colour of the button. Feel free to do this to make the Macro Bar as usable for you as you desire.

Setup Tokens & Character Sheets

--abilities

Displays a menu with which one or more selected tokens and the Character Sheets they represent can be set up with the correct Token Action Buttons and data specific to the RPGMaster APIs, to work with the APIs in the best way. The menu provides buttons to add any command registered with CommandMaster (see --register command) as a Token Action Button, add spells to spell books, add granted powers, add or change weapon proficiencies and proficiency levels for each weapon, set the correct saving throws based on race, class & level of character / NPC / creature, and optionally clear or set the Token ‘circles’ to represent AC (bar 1), base Thac0 (bar 2) and HP (bar 3). Essentially, using this menu accesses the commands in section 2 without the DM having to run them individually.

All tokens selected when menu items are used will be set up the same way: exceptions to this are using the Set Saves button (sets saves for each selected token/character sheet correctly for the specifications of that sheet), and the Set All Profs button (sets weapon proficiencies to proficient based on the weapons in each individual token/character sheet’s item bag). Different tokens can be selected and set up differently without having to refresh the menu.

Character Sheet configuration

The commands in this section can be accessed using the --abilities command menu. The individual commands below are used less frequently.

Add spells to spell book

--add-spells [POWERS/MUSPELLS/PRSPELLS] | [level]

Displays a menu allowing spells in the Spells Databases to be added to the Character Sheet(s) represented by the selected Token(s). If no spell type and/or spell level is specified, the initial menu shown is for Level 1 Wizard spells (MUSPELLS). Buttons are shown on the menu that allow navigation to other levels, spell types and powers.

Note: adding spells / powers to a sheet does not mean the Character can immediately use them. They must be memorised first. Use the commands in the MagicMaster API to memorise spells and powers.

Choose weapon proficiencies

--add-profs

Displays a menu from which to select proficiencies and level of proficiency for any weapons in the Weapon Databases. Also provides a button for making the Character proficient in all weapons carried (i.e. those currently in their Item table).

All current proficiencies are displayed, with the proficiency level of each, which can be changed or removed.

Note: this does more than just entering the weapon in the proficiency table. It adds the weapon group that the weapon belongs to as a field to the table (see weapon database help handouts for details), which is then used by the AttackMaster API to manage related weapon attacks and give the correct proficiency bonuses or penalties for the class and weapon used.

Add weapon proficiencies

--set-prof  [NOT-PROF/PROFICIENT/SPECIALIST/MASTERY] | weapon | weapon-type 

Sets a specific weapon proficiency to a named level. If the proficiency level is omitted, PROFICIENT is assumed. If the weapon already exists in the proficiencies table, the existing proficiency level is updated to that specified. Otherwise, the weapon (and its weapon group) are added to the table at the specified level.

Note: this does more than just entering the weapon in the proficiency table. It adds the weapon group that the weapon belongs to as a field to the table (see weapon database help handouts for details), which is then used by the AttackMaster API to manage related weapon attacks and give the correct proficiency bonuses or penalties for the class and weapon used.

Add proficiencies for all carried weapons

--set-all-prof

Adds all currently carried weapons (those in the Items table) to PROFICIENT, saving them and their weapon group to the weapon proficiency table. Those weapons found that are already in the table are reset to PROFICIENT (overwriting any existing different proficiency level). Any other proficiencies already in the table are not altered.

Note: this command always adds a weapon proficiency called innate. This proficiency is used for attacks with innate weapons, such as claws and bites, but also for spells that require a touch attack. Indeed, to make this even more specific, the weapons database distributed with the AttackMaster and MagicMaster APIs includes a weapon called Touch.

Tip: if using the MagicMaster API then running the !magic --gm-edit-mi command and adding weapons before running this command can speed up setting up character sheets.

Command and Ability maintenance

Register an API command

--register action|description|api-call|api-command|parameters

Register an API command with the CommandMaster API to achieve two outcomes: allow the command to be set up as a Token Action Button, and/or automatically maintain & update the syntax of the commands in Character Sheet ability macros and the RPGMaster API databases.

This is a powerful and potentially hazardous command. Registry of an API command is remembered by the system in the state variable, which is preserved throughout the life of the Campaign in Roll20. If a subsequent registration of the same action has different parameters, the system detects this and searches all Character Sheet ability macros for the old version of the command and replaces all of them with the new version of the command. It also changes the parameters, using a syntax including a range of character 'escapes' to substitute characters that Roll20 might otherwise interpret as commands itself. In detail, the --register command takes:

Commands cannot have a CR (carrage return/new line) in the middle of them, but CR can separate commands in multi-command sequences.

If the parameter string ends with $$, this will ensure that a complete command up to the next CR is to be replaced (including everything up to the CR even if not part of the command). If there is not a $$ on the end of the parameter string, then only the command and parameters that are matched are replaced (using a parameter count of each old and new parameter separated by ‘%%’) - the rest of the line (including any remaining parameters not so matched) will be left in place.

Here are some examples of registration commands:

--register Spells_menu|Open a menu with spell management functions|magic|~~spellmenu |`{selected|token_id}
--register Use_power|Use a Power|magic|~~cast-spell|POWER%%\at{selected|token_id}
--register Attack_hit|Do an attack where Roll20 rolls the dice|attk|~~attk-hit|`{selected|token_id}

Edit ability macros

--edit existing-string | new-string

Danger: use this command with extreme care! It can destroy your Campaign! It is recommended that you make a backup copy of your Campaign before using this command. --register is more controlled, as it has been tested with the RPGMaster command strings, and any future releases that change the API commands will be fully tested before release for their effect on Campaigns, with accompanying release notes. Using the --edit function directly can have unintended consequences!

Replaces an existing ‘escaped’ string with a new replacement string in all ability macros on all Character Sheets including the API character sheet databases. These strings both use the same escape sequence replacements as for the --register command (see section 3.1) as in fact --register and --edit use the same functionality.

Examples of its use are to change API command calls, or Character Sheet field name access in macros should the field names change.

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.

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.

Character Sheet and Token setup for use with RPGMaster APIs

Token configuration

The API can work with any Token configuration but requires tokens that are going to participate in API actions to represent a Character Sheet, so that actions relevant to the token and the character it represents can be selected.

A single Character Sheet can have multiple Tokens representing it, and each of these are able to do individual actions made possible by the data on the Character Sheet jointly represented. However, if such multi-token Characters / NPCs / creatures are likely to encounter spells that will affect the Character Sheet (such as Haste and Slow) they must be split with each Token representing a separate Character Sheet, or else the one spell will affect all tokens associated with the Character Sheet, whether they were targeted or not! In fact, it is recommended that tokens and character sheets are 1-to-1 to keep things simple.

The recommended Token Bar assignments for all APIs in the Master Series are:

It is recommended to use these assignments, and they are the bar assignments set by the CommandMaster API if its facilities are used to set up the tokens. All tokens must be set the same way, whatever way you eventually choose.

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 the AttackMaster API code, right at the top, is an object definition called 'fields': see section 3 for details. This can be altered to get the API to work with other character sheets.

The coding of the API is designed to use the AD&D 2E system of attack calculations, armour class values and saving throw management. If you use another system (e.g. the D&D 5e system) the API coding will need to change. This might be a future enhancement.

Matching the API to a type of Character Sheet

The API has an object definition called 'fields', which contains items of the form

Internal_api_name: [sheet_field_name, field_attribute, optional_default_value, optional_set_with_worker_flag]

A typical example might be:

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

The internal_api_name must not be altered! Doing so will cause the system not to work. However, the sheet_field_name and field_attribute can be altered to match any character sheet.

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 1^st row.

Internal_api_table: [sheet_repeating_table_name,starting_index]

An example is:

MW_table:['repeating_weapons',0],

The internal_api_table must not be altered! Doing so will cause the system not to work. However, the sheet_repeating_table_name and starting_index can be altered to match any character sheet.

Each character sheet must have repeating tables to hold weapons, ammo and magic items, as well as other data. By default, melee weapons 'in hand' are held in sections of the repeating_weapons table, melee weapon damage in the repeating_weapons-damage table, ranged weapons in the repeating_weapons2 table, ammo in the repeating_ammo table, and magic items are held in the repeating_potions table. The table management system provided by the API 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 generally not directly important to the RPGMaster Series APIs, but the resulting bonuses and penalties are. All Attributes and resulting modifiers should be entered into the Character Sheet in the appropriate places (that is in the Character Sheet fields identified in the 'fields' API object as noted in section 2 above).

The Character's race is also important for calculating saves and ability to use certain items. The race should be set in the appropriate Character Sheet field. Currently, the races 'dwarf', 'elf', 'gnome', 'halfelf', 'halfling', 'half-orc' and 'human' are implemented (not case sensitive, and spaces, hyphens and underscores are ignored). If not specified, human is assumed. The race impacts saves, some magic items and armour, and bonuses on some attacks.

The system supports single-class and multi-class characters. Classes must be entered in the appropriate fields on the Character Sheet. Classes and levels affect spell casting ability, 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 weapons, armour, shields, some magic items and saves.

Important Note: on the Advanced D&D 2e Character Sheet, Fighter classes must be in the first class column, Wizard classes in the second column, Priest classes in the third, Rogues in the fourth, and Psions (or any others) in the fifth. It is important that these locations are adhered to.

Note: classes of Fighter and Rogue (such as Rangers and Bards) that can use clerical &/or wizard spells will automatically be allowed to cast spells once they reach the appropriate level by AD&D 2e rules, but not before. They do not need to have levels set in the corresponding spell-caster columns - the casting ability & level is worked out by the system

The following Classes are currently supported:

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

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 commands --edit-mi or the GM-only command --gm-edit-mi. Alternatively, the AttackMaster --edit-weapons command can be used to load weapons, ammunition and armour into the Items table. It is generally possible to enter item names and quantities directly into the table and use them within the system, but 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). Other items can be in the table but will not otherwise be effective.

Items can be added to the databases. See the Database Handouts for more information on the databases.

Weapons and Ammo

For the APIs to work fully the melee weapons, damage, ranged weapons and ammo must be selected using the AttackMaster --weapon command to take the weapon 'in hand'. This will display a menu to take weapons and shields from the Items table and take them in hand, ready to use. This automatically fills all the correct fields for the weapons and ammo to make attacks, including many fields that are not displayed. Entering weapon data directly into the melee weapon, damage, ranged weapon and ammo tables will generally work, but will be overwritten if the --weapon command is used. Also, some API functions may not work as well or at all.

For the InitiativeMaster API to support weapon attack actions weapon name, speed and number of attacks are the most important fields. For the AttackMaster API to support attack rolls, proficiency calculations, ranged attacks, strength and dexterity bonuses, and other aspects of functionality, fill in as many fields as are visible on the character sheet. When entering data manually, ensure that the row a melee or ranged weapon is in matches the row damage or ammo is entered in the respective tables (there is no need to do this if using AttackMaster functions to take weapons in-hand, as the relevant lines are otherwise linked).

Weapon Proficiencies

Weapon Proficiencies must be set on the Character Sheet. This is best done by using the CommandMaster API character sheet management functions, but can be done manually. Both specific weapons and related weapon groups can be entered in the table, and when a Player changes the character's weapons in-hand the table of proficiencies will be consulted to set the correct bonuses and penalties. Weapon specialisation and mastery (otherwise known as double specialisation) are supported by the CommandMaster functions, but can also be set by ticking/selecting the relevant fields on the Character Sheet weapon proficiencies table. If a weapon or its related weapon group does not appear in the list, it will be assumed to be not proficient.

Spell books and memorisable spells

The best (and easiest) way to give a Character or NPC spells and powers is to use CommandMaster API to add spells and powers to the Character's spellbooks, and MagicMaster API to memorise and cast spells and use powers. However, for the purposes of just doing initiative and selecting which spell to cast in the next 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.

Spells can only be cast if they have macros defined in the spell databases (see Spell Database Handout). If the CommandMaster API is loaded, the DM can use the tools provided there to manage Character, NPC & creature spell books and granted powers from the provided spell & power databases.

The spells a spell caster can memorise (what they have in their spell books, or what their god has granted to them) is held as a list of spell names separated by vertical bars '|' in the character sheet attribute defined in fields.Spellbook (on the AD&D2E character sheet 'spellmem') of each level of spell. On the AD&D2E sheet, the spell books are the large Spell Book text fields at the bottom of each spell level tab. The spell names used must be identical (though not case sensitive) to the spell ability macro names in the spell databases (hence the hyphens in the names). So, for example, a 1^st level Wizard might have the following in their large Wizard Level 1 spell book field:

Armour|Burning-Hands|Charm-Person|Comprehend-Languages|Detect-Magic|Feather-fall|Grease|Identify|Light|Magic-Missile|Read-Magic|Sleep

Only these spells will be listed as ones they can memorise at level 1. When they learn new spells and put them in their spell book, this string can be added to just by typing into it. When they reach 3^rd level and can have 2^nd level spells, the following string might be put in the spell book on the Level 2 Wizard spells tab:

Alter-Self|Invisibility|Melfs-Acid-Arrow|Mirror-Image|Ray-of-Enfeeblement

Again, as they learn more spells and put them in their spell book, just edit the text to add the spells.

Once these spell books are defined, the DM or Player can use the MagicMaster -mem-spell command (or an action button and associated ability macro on the Character Sheet) to memorise the correct number of these spells in any combination and store those on the Character Sheet.

Powers

Powers can only be used if they are defined in the Powers database - see Database handouts. If the CommandMaster API is also loaded, the DM can use the tools provided there to manage Character, NPC & creature spellbooks and granted powers.

Powers work in an almost identical way to Wizard & Priest spells, except that there is only 1 level of powers. Powers that the character has are added to the spell book on the Powers tab in the same way as spells, and then memorised using the --mem-spell command (which also works for powers with the right parameters).

Changelog

v1.024 (2022-02-02)

• Added flag to weapon proficiency table to remove ranged weapon restrictions on Mastery
• Linked to AttackMaster "masterRange" flag to allow or disallow setting of Ranged Weapon Mastery level of proficiency
• Added buttons to Abilities menu to set if a PC or DM token

v1.022 (2022-01-23)

• Fixed illegal characters not rendered by One-Click install

v1.021 (2022-01-16)

• Fixed bug of handling undefined API command registrations
• Fixed overrun on PR spell book setup

v1.020 (2022-01-09)

• First version for public release