|
|
| (3 intermediate revisions by one user not shown) |
| Line 1: |
Line 1: |
| | {{revdate}} | | {{revdate}} |
| | {{main|API:Script Index}} | | {{main|API:Script Index}} |
| − | '''RPGMaster Suite API''' is the loader for the '''[[RPGMaster]]''' suite of APIs, which includes [[Script:RoundMaster]], [[Script:InitMaster]], [[Script:AttackMaster]], [[Script:MagicMaster]], [[Script:RPGMaster_Library]] and this loader. The '''RPGMaster Suite''' loader also supports the ''!cmd'' API commands which initialise the RPGMaster Mods and provide the GM with useful Character Sheet and Token tools. | + | '''RPGMaster Suite API''' is the loader for the '''[[RPGMaster]]''' suite of APIs, which includes [[Script:RoundMaster]], [[Script:InitMaster]], [[Script:AttackMaster]], [[Script:MagicMaster]], [[Script:CommandMaster]] [[Script:RPGMaster_Library]] and this loader. The '''RPGMaster Suite''' loader does not provide any additional functionality, other than loading the rest of the APIs. |
| | | | |
| | '''Note:''' This API ''requires'' that a '''[[Script:RPGMaster Library|RPGMaster Library]]''' API is loaded, which provides RPG version-specific and Roll20 Character Sheet version-specific data, rulesets and processing (as well as other goodies!). | | '''Note:''' This API ''requires'' that a '''[[Script:RPGMaster Library|RPGMaster Library]]''' API is loaded, which provides RPG version-specific and Roll20 Character Sheet version-specific data, rulesets and processing (as well as other goodies!). |
| | | | |
| − | '''Note:''' This API ''replaces'' '''CommandMaster API'''. The CommandMaster API is still supported and updates will be distributed via the One-Click auto-update system. However, the RPGMaster-Suite API provides all the same commands using the same ''!cmd'' syntax, and will conflict with CommandMaster if an attempt is made to load both.
| |
| − |
| |
| − | As well as loading the RPGMaster mods, '''RPGMaster Suite''' 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.
| |
| | {{script overview | | {{script overview |
| | |name=RPGMaster Suite | | |name=RPGMaster Suite |
| | |author=[[Richard E]] | | |author=[[Richard E]] |
| − | |version=2.1.0 | + | |version=2.1.1 |
| − | |lastmodified=6-6-2023 | + | |lastmodified=19-6-2023 |
| | |code=RPGMaster-Suite | | |code=RPGMaster-Suite |
| − | |dependencies={{api repository link|RoundMaster}}, {{api repository link|InitMaster}}, {{api repository link|AttackMaster}}, {{api repository link|MagicMaster}}, {{api repository link|RPGMlibrary AD+D2e}} | + | |dependencies={{api repository link|RoundMaster}}, {{api repository link|InitMaster}}, {{api repository link|AttackMaster}}, {{api repository link|MagicMaster}}, {{api repository link|CommandMaster}}, {{api repository link|RPGMlibrary AD+D2e}} |
| | |conflicts=None}} | | |conflicts=None}} |
| | | | |
| Line 21: |
Line 18: |
| | | | |
| | =How RPGMaster Suite Works= | | =How RPGMaster Suite Works= |
| − | <p>The RPGMaster-Suite 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 RPGMaster-Suite and, should they change in the future, RPGMaster-Suite 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.</p> | + | <p>The RPGMaster-Suite API is only a loader for the other APIs in the RPGMaster suite of APIs. It is paired with a script.json file which specifies the APIs that must be loaded to support working of the RPGMaster functions. It is the script.json that does the heavy lifting - the RPGMaster-Suite API only exists to be found in the Roll20 One Click library for those who search for RPGMaster in the library.</p> |
| − | ==Initialising a Campaign==
| + | |
| − | <p>Using the <b>--initialise</b> command will add a number of Player Macros for the GM that will run the most-used RPGMater GM commands, which can be flagged to appear in the Macro Bar at the bottom of the GM’s screen for ease of access.</p>
| + | |
| − | | + | |
| − | ==Setting up tokens & character sheets==
| + | |
| − | <p>Selecting one or multiple tokens and running the <b>--abilities</b> 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).</p>
| + | |
| − | ==Registering API commands==
| + | |
| − | <p>Any API command can be registered with RPGMaster-Suite using the <b>--register</b> 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.</p>
| + | |
| − | ==Editing Character Sheet abilities==
| + | |
| − | <p><b>Danger:</b> this command is very powerful, and can ruin your campaign if mis-used! The <b>--edit</b> 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!</p>
| + | |
| − | <br>
| + | |
| − | | + | |
| − | =How to use RPGMaster-Suite=
| + | |
| − | == Installation and Configuration ==
| + | |
| − | Copy the script's code, available either via the <i>Roll20 One-Click Install</i> system, or from the menu on the right and stored at Roll20's [https://github.com/Roll20/roll20-api-scripts API GitHub Repository] and paste the code into a new script in your campaign's [[API:Use_Guide#The_Script_Editor|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 RPGMaster-Suite. The handout '''RPGMaster CharSheet Setup''' provides information on setting up a character sheet for use with RPGMaster Suite 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 RPGMaster-Suite calls==
| + | |
| − | <p>The RPGMaster-Suite API is called using !cmd.</p>
| + | |
| − | <pre>!cmd --initialise</pre>
| + | |
| − | <p>Commands to be sent to the RPGMaster-Suite API must be preceded by two hyphens ‘--’ as above for the --initialise command. Parameters to these commands are separated by vertical bars ‘|’, for example:</p>
| + | |
| − | <pre>!cmd --register action|description|api-call|api-command|parameters</pre>
| + | |
| − | <p>Commands can be stacked in the call, for example:</p>
| + | |
| − | <pre>!cmd --initialise --abilities</pre>
| + | |
| − | <p>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).</p>
| + | |
| − | <br>
| + | |
| − | | + | |
| − | =Command Index=
| + | |
| − | ===1. Campaign setup===
| + | |
| − | <pre>--initialise
| + | |
| − | --abilities</pre>
| + | |
| − | | + | |
| − | ===2. Character Sheet configuration===
| + | |
| − | <pre>--conv-spells
| + | |
| − | --conv-items
| + | |
| − | --token-defaults
| + | |
| − | --check-chars
| + | |
| − | --class-menu [token_id]
| + | |
| − | --add-spells [POWERS/MUSPELLS/PRSPELLS] | [level]
| + | |
| − | --add-profs
| + | |
| − | --set-prof [NOT-PROF/PROFICIENT/SPECIALIST/MASTERY] | weapon | weapon-type
| + | |
| − | --set-all-prof</pre>
| + | |
| − | | + | |
| − | ===3. Command and Ability maintenance===
| + | |
| − | <pre>--register action|description|api-call|api-command|parameters
| + | |
| − | --edit old-string | new-string</pre>
| + | |
| − | | + | |
| − | ===4. Other commands===
| + | |
| − | <pre>--help
| + | |
| − | --debug [ON/OFF]</pre>
| + | |
| − | <br>
| + | |
| − | | + | |
| − | ==1. Campaign setup==
| + | |
| − | ===1.1 Initialise for RPGMaster APIs===
| + | |
| − | <pre>--initialise</pre>
| + | |
| − | <p>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).</p>
| + | |
| − | <p>The buttons added are:</p>
| + | |
| − | <ul>
| + | |
| − | <li><i>Maint-menu:</i> Runs the <b>!init --maint</b> command</li>
| + | |
| − | <li><i>Token-setup:</i> Runs the <b>!cmd --abilities</b> command</li>
| + | |
| − | <li><i>Add-items:</i> Runs the <b>!magic --gm-edit-mi</b> command</li>
| + | |
| − | <li><i>End-of-Day:</i> Runs the <b>!init --end-of-day</b> command</li>
| + | |
| − | <li><i>Initiative-menu:</i> Runs the <b>!init --init</b> command</li>
| + | |
| − | <li><i>Check-tracker:</i> Runs the <b>!init --check-tracker</b> command</li>
| + | |
| − | </ul>
| + | |
| − | <p>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.</p>
| + | |
| − | ===1.2 Setup Tokens & Character Sheets===
| + | |
| − | <pre>--abilities</pre>
| + | |
| − | <p>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 RPGMaster Suite (see <b>--register</b> command) as a Token Action Button, change control of the sheet and set the visibility of the token name to players (which also affects RoundMaster behaviour), set the Character Class and Level of the Character, 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.</p>
| + | |
| − | <p>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.</p><br>
| + | |
| − | | + | |
| − | ==2. Character Sheet configuration==
| + | |
| − | <p>The commands in this section can be accessed using the --abilities command menu. The individual commands below are used less frequently.</p>
| + | |
| − | ===2.1 Convert Character Sheet Spells===
| + | |
| − | <pre>--conv-spells</pre>
| + | |
| − | <p>Works on multiple selected tokens representing several Character Sheets.</p>
| + | |
| − | <p>For Character Sheets that have not been created using the commands provided by the <i>!cmd --abilities</i> menu, pre-existing from previous Roll20 campaigns using the Advanced D&D2e Character Sheet, this command does its best to convert all spells in tables on the Character Sheet to RPGMaster format and replace them with spells that exist in the RPGMaster spell databases. Those that the system can\'t automatically match are subsequently displayed in a menu, with additional buttons that list the spells that do exist in the databases that can be used to replace them by selecting both the spell to be replaced and the replacement spell.</p>
| + | |
| − | <p>It is possible that not all spells will be able to be replaced, if the Character Sheet reflects campaign experience where bespoke spells or spells from other handbooks have been available. In this case, the spells can be left unconverted, and the DM might add the spells to their own databases using the information provided in the <i>Magic Database Help</i> handout. Until the spells are added to the databases, they will not work, and cannot be memorised for spell use.</p>
| + | |
| − | <p>This command can be used on multiple selected tokens, as stated above. All the Character Sheets represented by the selected tokens will be converted, and the displayed list of spells to manually match represents the unmatched spells from all those Character Sheets. As the spells are manually matched, they will be replaced on all of the selected Character Sheets.</p>
| + | |
| − | ===2.2 Convert Character Sheet Equipment===
| + | |
| − | <pre>--conv-items</pre>
| + | |
| − | <p>Works on multiple selected tokens representing several Character Sheets.</p>
| + | |
| − | <p>As for the <i>--conv-spells</i> command, Character Sheets that have not been created using the commands provided by the <i>!cmd --abilities</i> menu, pre-existing from previous Roll20 campaigns using the Advanced D&D2e Character Sheet, this command does its best to convert all weapons, armour, other items of equipment and magical items such as potions, rings etc, in tables on the Character Sheet to RPGMaster format and replace them with weapons, armour and items that exist in the RPGMaster spell databases. Those that the system can\'t automatically match are subsequently displayed in a menu, with additional buttons that list the items that do exist in the databases that can be used to replace the unknown ones by selecting both the item to be replaced and the replacement item.</p>
| + | |
| − | <p>It is possible that not all weapons, armour, equipment and especially magic items will be able to be matched if the Character Sheet reflects campaign experience where bespoke magic items and equipment or equipment from other handbooks have been available. In this case, the items can be left unconverted, and the DM might add the items to their own databases using the information provided in the <i>Weapon & Armour Database Help</i> or <i>Magic Database Help</i> handouts. Until the items of equipment are added to the databases, if they are weapons they cannot be taken in-hand to fight with, armour will not be counted towards armour class calculations, and items that contribute to saving throws will not do so.</p>
| + | |
| − | <p>As with the <i>--conv-spells</i> command, this command can be used on multiple selected tokens. All the Character Sheets represented by the selected tokens will be converted, and the displayed list of items to manually match represents the unmatched items from all those Character Sheets. As the items are manually matched, they will be replaced on all of the selected Character Sheets.</p>
| + | |
| − | ===2.3 Set Default Token Bar mappings===
| + | |
| − | <pre>--token-defaults</pre>
| + | |
| − | <p>This command uses the selected token as a model to set the default token bar mappings that will be used in future by the RPGMaster APIs.</p>
| + | |
| − | <p>The standard defaults distributed with the APIs are for token bar1 to represent AC, bar2 to represent Thac0-base, and bar3 to represent HP. However, alternative mappings can be made. <b>It is highly recommended that HP, AC and Thac0-base are represented in some order</b> because these are the most common values to be affected by spells and circumstances, both in and out of combat situations.</p>
| + | |
| − | <p>If no token is selected, or the token selected to be the model does not have any bars linked to a character sheet, an error message will be displayed. If some but not all the bars are linked, then any bars not linked will be automatically matched to some of the recommended Character Sheet fields of AC, Thac0-base, and HP (in that order of priority).</p>
| + | |
| − | <p>Once this mapping is done, a menu will be displayed that can be used to map other tokens to the new defaults: either just the selected tokens, or all tokens in the campaign, or just those tokens that have bars currently linked to Character Sheets (i.e. excluding creature mobs with multiple tokens with unlinked bars representing a single character sheet). A button also exists to clear the bar links for all selected tokens to create creature mobs.</p>
| + | |
| − | ===2.4 Check control of Character Sheets===
| + | |
| − | <pre>--check-chars</pre>
| + | |
| − | <p>Displays a list of every Character Sheet with a defined Class, Level, or Monster Hit Dice categorised by <i>DM Controlled, Player Controlled PCs & NPCs, Player Controlled Creatures,</i> and <i>Controlled by Everyone.</i> Each name is shown as a button which, if selected, swaps control of that Character Sheet between DM control and the control of a selected Player (the Player, of course, must be one that has already accepted an invite to join the campaign). A button is also provided at the bottom of this menu to toggle the running of this check whenever the Campaign is loaded.</p>
| + | |
| − | ===2.5 Set Character Class, Race & Species===
| + | |
| − | <pre>--class-menu [token_id]</pre>
| + | |
| − | <p>Takes an optional ID for a token representing a character. If not specified, takes the currently selected token</p>
| + | |
| − | <p>Displays a menu from which the Race, Class and Level of a Character can be set, or a Creature species can be selected. Setting the Race, Class and Level of a Character (PC or NPC) enables all other capabilities to be used as appropriate for that character sheet in this and other APIs in the <b>RPGMaster API suite</b>, such as spell use, appropriate race & class powers, selection of allowed weapons, and the like. Selecting a Creature species <i>automatically</i> sets up the Character Sheet in an optimal way for the APIs to use it to represent the chosen creature, including saves, armour class, hit dice and rolling of hit points, as well as special attacks such as paralysation & level drain of high level undead, spell use by the likes of Orc Shamen, regeneration powers, and so on. However, it does not automatically give weapons, armour equipment, or magic items to Creatures - if appropriate this still needs to be done by the DM/Game Creator.</p>
| + | |
| − | <p>DMs/Game Creatores can add to or amend the Class, Race and Creature definitions. Refer to the appropriate database help handout distributed with the APIs and created as handouts in your campaign for more information.</p>
| + | |
| − | ===2.6 Add spells to spell book===
| + | |
| − | <pre>--add-spells [POWERS/MUSPELLS/PRSPELLS] | [level]</pre>
| + | |
| − | <p>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. For <i>Priests</i>, a button is also provided to add every spell allowed for the Priest\'s Class to their spellbooks at all levels (of course, they will only be able to memorise those that their experience level allows them to). For all Character Classes that have <i>Powers</i> (or Power-like capabilities, such as Priestly <i>Turn Undead</i> or Paladin <i>Lay on Hands</i>), there is a button on the <i>Powers</i> menu to add Powers that the character\'s Class can have.</p>
| + | |
| − | <p><b>Note:</b> adding spells / powers to a sheet does not mean the Character can immediately use them. They must be <i>memorised</i> first. Use the commands in the <b>MagicMaster API</b> to memorise spells and powers.</p>
| + | |
| − | ===2.7 Choose weapon proficiencies===
| + | |
| − | <pre>--add-profs</pre>
| + | |
| − | <p>Displays a menu from which to select proficiencies and level of proficiency for any weapons in the Weapon Databases for the Character Sheet(s) represented by the selected tokens. Also provides a button for making the Character proficient in all weapons carried (i.e. those currently in their Item table).</p>
| + | |
| − | <p>All current proficiencies are displayed, with the proficiency level of each, which can be changed or removed. It is also now possible to select proficiencies in <b>Fighting Styles</b> as introduced by <i>The Complete Fighter\'s Handbook</i>: these can be found under the <i>Choose Style</i> button, and can also be set as Proficient or Specialised. Selecting a Fighting Style proficiency grants benefits as defined in the Handbook, or as modified by the DM - see the <i>Styles Database Help</i> handout for more information.</p>
| + | |
| − | <p><b>Note:</b> this does more than just entering the weapon in the proficiency table. It adds the <i>weapon group</i> that the weapon belongs to as a field to the table (see weapon database help handouts for details), which is then used by the <b>AttackMaster API</b> to manage <i>related weapon</i> attacks and give the correct proficiency bonuses or penalties for the class and weapon used.</p>
| + | |
| − | ===2.8 Set weapon proficiencies===
| + | |
| − | <pre>--set-prof [NOT-PROF/PROFICIENT/SPECIALIST/MASTERY] | weapon | weapon-type </pre>
| + | |
| − | <p>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.</p>
| + | |
| − | <p><b>Note:</b> 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.</p>
| + | |
| − | ===2.9 Add proficiencies for all carried weapons===
| + | |
| − | <pre>--set-all-prof</pre>
| + | |
| − | <p>Adds all currently carried weapons (those in the Items table) to PROFICIENT, saving them and their <i>weapon group</i> 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.</p>
| + | |
| − | <p><b>Note:</b> this command always adds a weapon proficiency called <i>innate</i>. This proficiency is used for attacks with innate weapons, such as claws and bites, but also for spells that require a <i>touch attack</i>. Indeed, to make this even more specific, the weapons database distributed with the AttackMaster and MagicMaster APIs includes a weapon called <i>Touch</i>.</p>
| + | |
| − | <p><b>Tip:</b> if using the <b>MagicMaster API</b> then running the <b>!magic --gm-edit-mi</b> command and adding weapons before running this command can speed up setting up character sheets.</p><br>
| + | |
| − | | + | |
| − | ==3. Command and Ability maintenance==
| + | |
| − | ===3.1 Register an API command===
| + | |
| − | <pre>--register action|description|api-call|api-command|parameters</pre>
| + | |
| − | <p>Register an API command with the RPGMaster Suite 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.</p>
| + | |
| − | <p>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 <b>action</b> has different parameters, the system detects this and searches all Character Sheet ability macros for the <i>old version</i> of the command and replaces all of them with the new 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:</p>
| + | |
| − | <table>
| + | |
| − | <tr><th scope="row">action:</th><td>the unique name given to this command in the whole system. This can be any legal text name including A-Z, a-z, 1-9, -, _ only. Must start with an alpha. Case is ignored.</td></tr>
| + | |
| − | <tr><th scope="row">description:</th><td>a short description of the command, which is displayed in the menu that allows the command to be added as a Token Action Button.</td></tr>
| + | |
| − | <tr><th scope="row">api-call:</th><td>the API call <i>without</i> the !, e.g. cmd, or magic, etc</td></tr>
| + | |
| − | <tr><th scope="row">api-command:</th><td>the command to be passed to the specified API, with the hyphens replaced by ~~ or plusses replaced by **, e.g. ~~cast-spell or **menu.</td></tr>
| + | |
| − | <tr><th scope="row">parameters:</th><td>the parameters (or initial parameters) to be passed as part of this command to replace the matching existing command parameters. This string is \'escaped\' using the following character replacements:</td></tr>
| + | |
| − | </table>
| + | |
| − | <table>
| + | |
| − | <tr><th scope="row">Character</th><td>Parameter separator</td><td>?</td><td>[</td><td>]</td><td><</td><td>></td><td>@</td><td>-</td><td>|</td><td>:</td><td>&</td><td>{</td><td>}</td></tr>
| + | |
| − | <tr><th scope="row">Substitute</th><td>%%</td><td>^</td><td><<</td><td>>></td><td> </td><td> </td><td>`</td><td>~</td><td>&#124;</td><td> </td><td>&amp;</td><td>&#123;</td><td>&#125;</td></tr>
| + | |
| − | <tr><th scope="row">Alternative</th><td> \\vbar;</td><td>\\ques;</td><td>\\lbrak;</td><td>\\rbrak;</td><td>\\lt;</td><td>\\gt;</td><td>\\at;</td><td>\\dash;</td><td>\\vbar;</td><td>\\clon;</td><td>\\amp;</td><td>\\lbrc;</td><td>\\rbrc;</td></tr>
| + | |
| − | </table>
| + | |
| − | <p>Commands cannot have a CR (carrage return/new line) in the middle of them, but CR can separate commands in multi-command sequences.</p>
| + | |
| − | <p>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.</p>
| + | |
| − | <p>Here are some examples of registration commands:</p>
| + | |
| − | <pre>--register Spells_menu|Open a menu with spell management functions|magic|~~spellmenu |\`{selected|token_id}<br>
| + | |
| − | --register Use_power|Use a Power|magic|~~cast-spell|POWER%%\`{selected|token_id}<br>
| + | |
| − | --register Attack_hit|Do an attack where Roll20 rolls the dice|attk|~~attk-hit|\`{selected|token_id}</pre><br>
| + | |
| − | ===3.2 Edit ability macros===
| + | |
| − | <pre>--edit existing-string | new-string</pre>
| + | |
| − | <p style="background-color:yellow;"><b>Danger:</b> 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!</p>
| + | |
| − | <p>Replaces an existing \'escaped\' string with a new replacement string in all ability macros on all Character Sheets. These strings both use the same escape sequence replacements as for the <b>--register</b> command (see section 3.1) as in fact <b>--register</b> and <b>--edit</b> use the same functionality.</p>
| + | |
| − | <p>Examples of its use are to change API command calls, or Character Sheet field name access in macros should the field names change.</p>
| + | |
| − | <br>
| + | |
| − | ==4. Other Commands==
| + | |
| − | ===4.1 Display help on these commands===
| + | |
| − | <pre>--help</pre>
| + | |
| − | <p>This command does not take any arguments. It displays a very short version of this document, showing the mandatory and optional arguments, and a brief description of each command.</p>
| + | |
| − | ===4.2 Switch on or off Debug mode===
| + | |
| − | <pre>--debug (ON/OFF)</pre>
| + | |
| − | <p>Takes one mandatory argument which should be ON or OFF.</p>
| + | |
| − | <p>The command turns on a verbose diagnostic mode for the API which will trace what commands are being processed, including internal commands, what attributes are being set and changed, and more detail about any errors that are occurring. The command can be used by the DM or any Player - so the DM or a technical advisor can play as a Player and see the debugging messages.</p>
| + | |
| − | =Character Sheet and Token setup for use with RPGMaster APIs=
| + | |
| − | ==Token configuration==
| + | |
| − | <p>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. </p>
| + | |
| − | <p>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 <i>Haste</i> and <i>Slow</i>) 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, <b>it is recommended that tokens and character sheets are 1-to-1 to keep things simple.</b></p>
| + | |
| − | <p>The recommended Token Bar assignments for all APIs in the Master Series are:</p>
| + | |
| − | {| class="wikitable"
| + | |
| − | |+
| + | |
| − | |-
| + | |
| − | ! scope="row"| Bar1 (Green Circle):
| + | |
| − | || Armour Class (AC field) – only current value
| + | |
| − | |-
| + | |
| − | ! scope="row"| Bar2 (Blue Circle):
| + | |
| − | || Base Thac0 (thac0-base field) before adjustments – only current value
| + | |
| − | |-
| + | |
| − | ! scope="row"| Bar3 (Red Circle):
| + | |
| − | || Hit Points (HP field) – current & max
| + | |
| − | |}
| + | |
| − | <p>It is recommended to use these assignments, and they are the bar assignments set by the <b>RPGMaster Suite API</b> if its facilities are used to set up the tokens. All tokens must be set the same way, whatever way you eventually choose.</p>
| + | |
| − | <br>
| + | |
| − | ==Use with various game system character sheets==
| + | |
| − | <p>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.</p>
| + | |
| − | <p>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.</p>
| + | |
| − | ==Matching the API to a type of Character Sheet==
| + | |
| − | <p>The API has an object definition called 'fields', which contains items of the form </p>
| + | |
| − | <pre>Internal_api_name: [sheet_field_name, field_attribute, optional_default_value, optional_set_with_worker_flag]</pre>
| + | |
| − | <p>A typical example might be:</p>
| + | |
| − | <pre>Fighter_level:['level-class1','current'],
| + | |
| − | Or
| + | |
| − | MUSpellNo_memable:['spell-level-castable','current','',true],</pre>
| + | |
| − | <p>The <i>internal_api_name</i> <b><u>must not be altered!</u></b> Doing so will cause the system not to work. However, the <i>sheet_field_name</i> and <i>field_attribute</i> can be altered to match any character sheet.</p>
| + | |
| − | <p>Table names are slightly different: always have an <i>internal_api_name</i> 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<sup>st</sup> row.</p>
| + | |
| − | <p><i>Internal_api_table: [sheet_repeating_table_name,starting_index]</i></p>
| + | |
| − | <p>An example is:</p>
| + | |
| − | <pre>MW_table:['repeating_weapons',0],</pre>
| + | |
| − | <p>The <i>internal_api_table</i> <b><u>must not be altered!</u></b> Doing so will cause the system not to work. However, the <i>sheet_repeating_table_name</i> and <i>starting_index</i> can be altered to match any character sheet.</p>
| + | |
| − | <p>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. </p>
| + | |
| − | ==Character Attributes, Races, Classes and Levels==
| + | |
| − | <p>Character Attributes of <i>Strength, Dexterity, Constitution, Intelligence, Wisdom</i> and <i>Charisma</i> 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).</p>
| + | |
| − | <p>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 <i>'dwarf', 'elf', 'gnome', 'halfelf', 'halfling', 'half-orc'</i> and <i>'human'</i> are implemented (not case sensitive, and spaces, hyphens and underscores are ignored). If not specified, <i>human</i> is assumed. The race impacts saves, some magic items and armour, and bonuses on some attacks.</p>
| + | |
| − | <p>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.</p>
| + | |
| − | <p><b>Important Note:</b> 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.</p>
| + | |
| − | <p><b>Note:</b> 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 <b><u>do not</u></b> need to have levels set in the corresponding spell-caster columns - the casting ability & level is worked out by the system</p>
| + | |
| | | | |
| − | <p>The following Classes are currently supported:</p>
| + | ==How to use RPGMaster Suite== |
| − | {| class="wikitable"
| + | <p>To load the RPGMaster suite of APIs:</p> |
| − | |+
| + | <ol> |
| − | |-
| + | <li>Create a new Campaign or open the Campaign Details page</li> |
| − | ! Fighter classes !! Wizard Classes !! Priest Classes !! Rogue Classes !! Psion Classes
| + | <li>Open the <i>Settings</i> drop-down for the campaign you want to load the RPGMaster suite to.</li> |
| − | |-
| + | <li>Select the Mod / API Scripts entry in the drop-down.</li> |
| − | | Warrior || Wizard || Priest || Rogue || Psion
| + | <li>On the "Mods for <i>[your Campaign]</i>" page, select the "Roll20 Mod Library" drop-down.</li> |
| − | |-
| + | <li>Type "RPGMaster" into the search box and select the "RPGMaster Suite" when displayed.</li> |
| − | | Fighter || Mage || Cleric || Thief ||
| + | <li>Select the [Add Script] button below the text explaining what RPGMaster Suite does.</li> |
| − | |-
| + | <li>When Roll20 pops up a dialog asking if other scripts should be loaded, select the [Yes] button.</li> |
| − | | Ranger || Abjurer || Druid || Bard ||
| + | <li>Return to the Campaign Details page and use the [Launch Game] button.</li> |
| − | |-
| + | <li>Wait for the Campaign to fully load and the APIs to state they are ready.</li> |
| − | | Paladin || Conjurer || Healer || Assassin ||
| + | <li>Follow the link in the Chat Window message to the Release Notes and read them.</li> |
| − | |-
| + | <li>Enter the command <b>!cmd --initialise</b> and follow the instructions.</li> |
| − | | Beastmaster || Diviner || Priest of Life || ||
| + | </ol> |
| − | |-
| + | |
| − | | Barbarian || Enchanter || Priest of War || ||
| + | |
| − | |-
| + | |
| − | | Defender (Dwarven) || Illusionist || Priest of Light || ||
| + | |
| − | |-
| + | |
| − | | || Invoker || Priest of Knowledge || ||
| + | |
| − | |-
| + | |
| − | | || Necromancer || Shaman || ||
| + | |
| − | |-
| + | |
| − | | || Transmuter || || ||
| + | |
| − | |}
| + | |
| − | <p>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. </p>
| + | |
| − | ==Magic Items and Equipment== | + | |
| − | <p>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, <i>repeating_potions</i>, on the Character Sheet. As with other fields, this can be changed in the <i>'fields'</i> object. The best way to put items into this table is by using the <b>MagicMaster API</b> commands <b>--edit-mi</b> or the GM-only command <b>--gm-edit-mi</b>. Alternatively, the <b>AttackMaster --edit-weapons</b> 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.</p> | + | |
| − | <p>Items can be added to the databases. See the Database Handouts for more information on the databases.</p> | + | |
| − | ==Weapons and Ammo==
| + | |
| − | <p>For the APIs to work fully the melee weapons, damage, ranged weapons and ammo must be selected using the <b>AttackMaster --weapon</b> 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.</p> | + | |
| − | <p>For the <b>InitiativeMaster API</b> to support weapon attack actions weapon name, speed and number of attacks are the most important fields. For the <b>AttackMaster API</b> 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).</p> | + | |
| − | ==Weapon Proficiencies==
| + | |
| − | <p>Weapon Proficiencies must be set on the Character Sheet. This is best done by using the <b>RPGMaster Suite API</b> 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 RPGMaster Suite 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.</p> | + | |
| − | ==Spell books and memorisable spells==
| + | |
| − | <p>The best (and easiest) way to give a Character or NPC spells and powers is to use <b>RPGMaster Suite API</b> to add spells and powers to the Character's spellbooks, and <b>MagicMaster API</b> 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, <i>repeating_spells</i>. As with other fields, this can be changed in the <i>'fields'</i> 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.</p> | + | |
| − | <p>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) <b>a complete row at a time</b> (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 <i>counts down</i> 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).</p>
| + | |
| − | <p>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 <i>'fields'</i> object in the APIs.</p> | + | |
| − | <p>Spells can only be cast if they have macros defined in the spell databases (see Spell Database Handout). If the <b>RPGMaster Suite API</b> 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.</p> | + | |
| − | <p>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 <i>fields.Spellbook</i> (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<sup>st</sup> level Wizard might have the following in their large Wizard Level 1 spell book field:</p> | + | |
| − | <pre>Armour|Burning-Hands|Charm-Person|Comprehend-Languages|Detect-Magic|Feather-fall|Grease|Identify|Light|Magic-Missile|Read-Magic|Sleep</pre> | + | |
| − | <p>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<sup>rd</sup> level and can have 2<sup>nd</sup> level spells, the following string might be put in the spell book on the Level 2 Wizard spells tab:</p>
| + | |
| − | <pre>Alter-Self|Invisibility|Melfs-Acid-Arrow|Mirror-Image|Ray-of-Enfeeblement</pre>
| + | |
| − | <p>Again, as they learn more spells and put them in their spell book, just edit the text to add the spells.</p>
| + | |
| − | <p>Once these spell books are defined, the DM or Player can use the <b>MagicMaster -mem-spell</b> 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.</p> | + | |
| − | ==Powers==
| + | |
| − | <p>Powers can only be used if they are defined in the Powers database - see Database handouts. If the <b>RPGMaster Suite API</b> is also loaded, the DM can use the tools provided there to manage Character, NPC & creature spellbooks and granted powers.</p> | + | |
| − | <p>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 <b>--mem-spell</b> command (which also works for powers with the right parameters).</p> | + | |
| − | <br> | + | |
| | | | |
| | = Changelog = | | = Changelog = |
| − | {{changelog version|1.020|2022-01-09|* First version for public release}} | + | {{changelog version|2.1.1|2023-19-06|* Changed RPGMaster Suite to not replace CommandMaster}} |
| − | {{changelog version|1.021|2022-01-16|* Fixed bug of handling undefined API command registrations
| + | {{changelog version|2.1.0|2023-06-06|* Initial release of RPGMaster Suite.}} |
| − | * Fixed overrun on PR spell book setup}}
| + | |
| − | {{changelog version|1.022|2022-01-23|* Fixed illegal characters not rendered by One-Click install}}
| + | |
| − | {{changelog version|1.024|2022-02-02|* 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}}
| + | |
| − | {{changelog version|1.3.00|2022-10-01|* Major release to extract all RPG version-specific data and rule processing to RPGMaster Library API}}
| + | |
| − | {{changelog version|1.3.03|2022-10-29|* Add All Powers will add race powers from the race database.
| + | |
| − | * Add Race selection to Class menu.}}
| + | |
| − | {{changelog version|1.3.04|2022-11-17|*Added possible creature data attributes.
| + | |
| − | * Added weapon data update after race/class/level change to support things like attacks/round improvement}}
| + | |
| − | {{changelog version|1.4.01|2022-11-28|*Added support for the fighting Styles-DB.
| + | |
| − | * Added creature attribute dexdef dexterity bonus for ranged attacks.
| + | |
| − | * Added use of alpha indexed drop down for selection of creatures.
| + | |
| − | * Added suppression of power inheritance.
| + | |
| − | * Added function to check player, speakingas, token & character names for illegal characters.}}
| + | |
| − | {{changelog version|1.4.02|2022-12-13|* Added API button on token & character name checks to support immediate correction.
| + | |
| − | * Add ability to specify weapons and armour for creatures with probability of different sets.
| + | |
| − | * Split handling of PC Race specifications and Creature specifications, so that Races don't get set up with spurious creature specs.}}
| + | |
| − | {{changelog version|1.4.03|2023-01-16|* Added creature attkmsg & dmgmsg attributes to support messages to display with attack and damage rolls respectively.}}
| + | |
| − | {{changelog version|1.4.04|2023-01-24|* Added support for converting manually created character sheets to RPGMaster format.
| + | |
| − | * Added ability to configure the default token bars.
| + | |
| − | * Added functions to set token bars for all campaign tokens.
| + | |
| − | * Added separate Ammo list for Equipment conversion.
| + | |
| − | * Tidied up Token-Setup menu.}}
| + | |
| − | {{changelog version|1.4.05|2023-03-02|* Non-functional update release to maintain version sequence.}}
| + | |
| − | {{changelog version|1.4.06|2023-04-08|* Added support for when a magic item character sheet is first dragged to the player map, to set it to isdrawing true and link to the CS.}}
| + | |
| − | {{changelog version|1.4.07|2023-04-14|* Fixed bug stopping Token Setup, Add to Spellbook from working.}}
| + | |
| − | {{changelog version|1.5.01|2022-05-19|* Non-functional version number synchronisation release.}}
| + | |
| − | {{changelog version|1.5.02|2023-06-02|* First release as RPGMasterSuite.js, so that a search of the "One Click" library for "RPGMaster" will find this API and load the whole suite.}}
| + | |
| − | {{changelog version|2.1.0|2023-06-06|* Made many more functions asynchronous to multi-thread.}} | + | |
| | | | |
| | [[Category:AD&D 2E]] | | [[Category:AD&D 2E]] |
| | [[Category:API:RPGMaster]] | | [[Category:API:RPGMaster]] |
The RPGMaster-Suite API is only a loader for the other APIs in the RPGMaster suite of APIs. It is paired with a script.json file which specifies the APIs that must be loaded to support working of the RPGMaster functions. It is the script.json that does the heavy lifting - the RPGMaster-Suite API only exists to be found in the Roll20 One Click library for those who search for RPGMaster in the library.
