Latest revision as of 16:10, 14 June 2023

Page Updated:   2023-06-14

Main Page: API:RPGMaster

[edit] Part of the RPGMaster Suite of APIs

This page explains how to configure Character Sheets for use with the RPGMaster Suite of APIs:

• Script:InitMaster -- Manages initiative rolls and priorities for Player Characters, NPCs and Creatures.
• Script:AttackMaster -- Provides functions to manage weapons, armour & shields, including taking weapons in hand and using them to attack. It uses standard AD&D 2e rules to the full extent
• Script:MagicMaster -- Provides functions to manage all types of magic, including Wizard & Priest spell use and effects; Character, NPC & Monster Powers; and discovery, looting, use and cursing of Magic Items.
• Script:CommandMaster -- 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:RoundMaster -- Extends the functionality of the t Turn Tracker capability. Based on the old TrackerJacker API, extended to support Effect Macros triggered when statuses are added, exist on, or are removed from tokens. Effect Macros are user programmable and can do anything Roll20 or added APIs can do.
• Script:RPGMaster Library -- Holds all RPG-version specific data, rulesets and processing for the RPGMaster series of APIs, but also provides Roll Templates, Character Sheet table management functions, database management functions and other useful functions that can be used by API authors and others (Roll Templates are usable from macros) that are applicable to unsupported RPGs.

[edit] Character Sheet and Token setup for use with RPGMaster APIs

[edit] Using APIs to do setup

The simplest way to configure a Character Sheet for use with the RPGMaster APIs is to use the functions of the APIs to set up the Character Sheet. If the CommandMaster API is installed, a number of features and commands are provided to help the DM/Game Creator in this process.

The most basic of these is to configure a blank Character Sheet.

• Use the [+Add] button on the Roll20 Journal to add a new blank Character Sheet, and Roll20 displays a form to give the sheet a name (or accept with the default provided by Roll20) and optionally an image.
• Select the [Save Changes] button on this form, and then close the blank Character Sheet.
• Drag the newly created Character Sheet onto the map area of the Roll20 UI.
• Switch to the Chat Window, and the Review & Set Race & Classes menu has appeared (scroll down to the bottom if need be).
• If this menu has not appeared, the menu can be opened on the DM's Token-Setup button.
• Make sure the token you have just placed on the map area is selected (often it is not).
• Selecting a Creature type from the Creature drop-down list will automatically setup the Character Sheet and Token to work with the APIs as that creature, setting all necessary fields and setting the Token as the default token for the Character Sheet. At this point the token can immediately be used in play as that creature.
• Selecting a Race and/or Class & level for the Character Sheet will not do as much - the basics will be set, but
  • the Character Attributes of Strength, Dexterity, Constitution, Intelligence, Wisdom and Charisma must be rolled for and added to the sheet manually
  • the Token is not linked or set up, as many fields still need to have values set
  • use the Token-Setup menu to add Character menu action buttons to the Character Sheet, which provide menu access for Players
  • the DM's Token-Setup menu can be used to complete setting other aspects of the character before play
  • if appropriate, once everything is set up manually make the token the default for the Character Sheet
• Use either the DM's Add-Items menu or the Character's Attk-Menu / Edit Weapons & Armour menu to add equipment including weapons & armour to Characters and even Creatures that can make use of them.
• Use the Character's Attk-Menu / Change Weapons menu to take weapons, shields, and other items in-hand, ready to use in attacks.
• Wizards and Priests can have spells added to their spell books on the DM's Token-Setup / Add to Spellbook menu. Then spells can be memorised from the spellbook using the Character's Spell-Menu / Memorise Spells menu.
• There are many other features of the APIs that can be used to enhance the Character / NPC being created with Powers, Magic Items and Proficiencies with weapons and Fighting Styles. Explore the other help handouts that come with the APIs for more information.

Alternatively, the Character Sheet can be set up manually from scratch, or existing Characters with Character Sheets can be adapted for use with the APIs. This option is explored in the rest of this document. However, adding information (other than Character Attributes) to the Character Sheet manually will never be as functionally rich as using the APIs for setting up the sheet, and in some cases will restrict the operation of the APIs to not work in the optimal way. Always use the API menus where possible.

[edit] Converting existing Character Sheets

It is possible to use existing character sheets for favourite characters and creatures, and use the facilities of the CommandMaster API to convert them for optimal use with the RPGMaster APIs. Use the Token-Setup / Convert Spells and / Convert Items buttons, or the !cmd --conv-spells and !cmd --conv-items commands on the token representing the character. These functions move data to the optimal locations for use with the APIs, and attempt to match spells and items with those stored in the RPGMaster databases. Those spells and items that cannot be matched are displayed to the GM as selectable buttons, alongside buttons to display lists of database entries to cater for manual matching. Spells and items that have no automatic or manual match can be left in the tables but will not function with the RPGMaster APIs to their fullest extent. Of course, the GM can use the information and instructions provided in the RPGMaster Database Help handouts to add these spells & items to the databases.

Warning: Converting the Character for use with the RPGMaster APIs may alter how they work if copied to other campaigns that don't use the RPGMaster suite. Make copies of the Character Sheets before converting them to use elsewhere if necessary!

Note: After conversion, no weapons or magic items will be "in-hand", no rings will be on fingers, and no spells or powers will be memorised. The other functions of the Token-Setup menu must still be used to add Action Buttons and also to check the converted data held for Race, Class, Level, Saves, Proficiencies, Fighting Styles, etc. Use the Token-Setup / Manage Token Bars function to check the Token bar setup. Once Action Buttons have been added to the Token, use the menus provided by them to take weapons in-hand, put rings (if any) on fingers, and memorise spells & powers.

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

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 default bar assignments set by the CommandMaster API if its facilities are used to set up the tokens: the CommandMaster functions can be used to change the defaults to whatever you require. However the bars are set (using CommandMaster or manually), the APIs will always search for the most appropriate fields to use from the token and character sheet - only if the APIs can't find valid values will they revert to using the default fields on the token. It is recommended that all tokens are set the same way, whatever way you eventually choose.

[edit] Use with various game system character sheets

The latest version of the RPGMaster series APIs use various game and character sheet-specific versions the RPGMaster Library to implement the relevant rules, parameters and databases specific to a game-version and/or Roll20 character sheet version. Loading the correct RPGMaster Library will configure all the RPGMaster APIs to work with that game rule set and character sheet. However: at the time of writing, only the AD&D 2E game version, and Advanced D&D 2E Character Sheet by Peter B. are supported.

[edit] Matching the API to a type of Character Sheet

As with other game and character sheet specific configuration, selecting the correct RPGMaster Library will configure the RPGMaster APIs for the character sheet in use. If a character sheet does not have the fields specified in the Library, the RPGMaster APIs will create them - it can, in fact, work with a totally blank character sheet definition and it will create all of the fields it requires from scratch: it just won't look very pretty or be very usable as a character sheet! However, you can alter the Library to work with any character sheet as follows (though the game rules and databases will remain those coded in that version of the Library).

The Library 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 (if it does not, or they are not the ones specified in the fields object, the APIs will create them). 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. If the Character Sheet does not have tables to display any specific table, the APIs will create the table and attach it to the sheet and will be able to use it, but the Players and DM will not see the content except through the API menus and dialogues.

[edit] 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', as well as many of their sub-races, 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, as well as granting some racial powers.

The system supports single-class and multi-class characters. Classes must be entered in the appropriate fields on the Character Sheet - if using the CommandMaster API, the --abilities or --class-menu commands can be used to set the classes and levels of characters and NPCs. 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: the appropriate fields must be used for relevant classes - this varies by character sheet. E.g. 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. If manually adding classes, 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 the specific game version 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 Class-DB database holds definitions of the classes and class rules distributed with the system. If the MagicMaster API is loaded, use the !magic --extract-db Class-DB command to extract the database to a character sheet to examine and update the class rules. Examples of Classes currently supported are:

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.

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

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

[edit] 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 entered manually, if a weapon or its related weapon group does not appear in the list, it will be assumed to be not proficient. However, if CommandMaster is used to set proficiencies, just having proficiency in a weapon will mean automatic related weapon proficiency in any related weapon.

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

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.

[edit] Powers

Powers are defined in the Powers database - see Database handouts - though it is possible to use Wizard or Priest spells as powers. 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). If you want to add Wizard or Priest spells as powers that can be used one or more times a day, or at will, the CommandMaster token setup spellbook function allows spells to be added to the powers spellbook. Otherwise, just add the name of the spell with a prefix of "MU-" or "PR-" manually to the powers spellbook e.g. to add a Wizard Light spell as a power, add it to the powers spellbook as "MU-Light". Spells added in this way can be memorised as powers in exactly the same way as other powers.