Page Updated:   2022-04-02

Main Page: API:RPGMaster

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:

Bar1 (Green Circle):	Armour Class (AC field) - only current value
Bar2 (Blue Circle):	Base Thac0 (thac0-base field) before adjustments - only current value
Bar3 (Red Circle):	Hit Points (HP field) - current & max

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

The APIs always try to search the Token fields for appropriate Character Sheet linked fields, but will revert to the assignments above if they fail to match linked fields. These assignments can be changed in each API, by changing the fields object near the top of the API script (note: 'bar#' and 'value' or 'max' are separate entries in an array of 2 elements). All APIs must use the same field definitions:

fields.Token_AC:	defines the token field for the AC value (normally ['bar1','value'])
fields.Token_MaxAC:	defines the token field for the AC max (normally ['bar1','max'])
fields.Token_Thac0:	defines the token field for the Thac0 value (normally ['bar2','value'])
fields.Token_MaxThac0: defines the token field for the Thac0 max (normally ['bar2','max'])
fields.Token_HP:	defines the token field for the HP value (normally ['bar3','value'])
fields.Token_MaxHP:	defines the token field for the HP max (normally ['bar3','max'])

Alter the bar numbers appropriately or, if you are not wanting one or more of these assigned: leave the two elements of the array as [' ',' ']. The system will generally work fine with reassignment or no assignment, but not always. Specifically, some effects in the Effects-DB, which implement spell effects on Character Sheets and Tokens, may not set the right values if no assignment of one or more of HP, AC & Thac0 are made to the Token.

Use with various game system character sheets

The issued APIs are initially set up to work with the AD&D 2E character sheet (as this is what the author mostly plays). However, it will work with any character sheet, though the values used and altered by the APIs may not be visible or may appear in unexpected places. To work properly with your choice of Character Sheet, the mapping in the APIs must be altered. In each 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 APIs are designed to use attack calculations, armour class values and saving throw management defined in a number of databases, supplied in the APIs and created in the Campaign as a set of Character Sheets. If you use another system (e.g. the D&D 5e system), the calculations can be altered by replacing the provided calculations with your own. Refer to the documentation for each API and database, provided as handouts in the Campaign and as Roll20 Wiki pages, to discover how to do this. The Author may, over time, issue new sets of databases and mappings to other game systems and Character Sheets.

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 the previous section).

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, and the best way to do this is to use the functions provided by the CommandMaster API !cmd --abilities command or DM's [Token Setup] macro bar button, but they can be entered manually: using class names the same as those provided in the Class-DB class database will ensure the APIs use the correct class characteristics. 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.

At the time of writing this Wiki, the APIs support all the character classes specified in the AD&D 2e Player's Handbook (including specialist Wizards), plus some additional Priest classes specified in the Complete Priest's Handbook. The Author may add more over time, and Game Creators can always add their own using the help provided in the Class Database Help handout and Wiki.

Note: on the Advanced D&D 2e Character Sheet, the APIs are expecting Fighter classes to 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 these are not adhered to, the APIs will attempt to merge the definitions in the class database for the specified class with the class capabilities of the column the class name is entered in - thus a Fighter class entered in the Wizard column may get spell casting capabilities if the class definition in the Class-DB class database does not specify otherwise.

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 (this is specified in their Class-DB class database definitions). They do not need to have levels set in the corresponding spell-caster columns - the casting ability & level is applied appropriately by the system.

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 Magic Items Database Handouts and Wiki 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.

If entering the weapon and ammunition data manually, for the InitiativeMaster API to support weapon attack actions the 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 by fields not seen on the character sheet).

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