Page Updated:   2022-10-17

Main Page: API:Script Index

AttackMaster API provides functions to manage weapons, armour & shields, including taking weapons in hand and using them to attack, for the AD&D 2E sheet. It's a part of the RPGMaster suite of APIs.

It uses the attack definitions defined in the Attacks-DB attack definition database (which the GM / Game Creator can add to or replace), taking into account: ranged weapon ammo management with ranges varying appropriately and range penalties/bonuses applied; Strength & Dexterity bonuses where appropriate; any magic bonuses to attacks that is in effect (if used with RoundMaster API effects); penalties & bonuses for non-proficiency, proficiency, specialisation & mastery; penalties for non-Rangers attacking with two weapons; use of 1-handed, 2-handed or many-handed weapons and restrictions on the number of weapons & shields that can be held at the same time; plus many other features. This API requires RPGMaster Library to work (make sure it is loaded alongside AttackMaster), and works best with the MagicMaster API and its databases which hold the data for automatic definition of weapons and armour. However, some attack commands will generally work with manual entry of weapons onto the character sheet. The CommandMaster API can be used by the GM to easily manage weapon proficiencies.

Specification for weapons, armour & shields are implemented as ability macros in specific database character sheets. This API comes with a wide selection of weapon and armour macros, held in the MI-DB-Weapons, -Ammo and -Armour databases that are created and updated automatically when the API is run. If the MagicMaster API is also loaded, it provides many more specifications for standard and magic items that are beneficial to melee actions and armour class. The GM can add to the provided items in the databases using standard Roll20 Character Sheet editing, as explained in the associated weapons, ammo & armour database Help Handout and Wiki page.

Contents 1 Forum 2 How AttackMaster Works 2.1 Specifying a token 2.2 Who can make AttackMaster API command calls 2.3 Weapons that can be used 2.4 Allocating weapons to a Character 2.5 Selecting weapons to attack with 2.6 Making attacks 2.7 Ammunition 2.8 Ranged weapon and ammunition ranges 2.9 Dancing weapons 2.10 Armour Class management 2.11 Saves 3 How To Use AttackMaster 3.1 Installation and Configuration 3.2 Script Use 3.3 Syntax 4 Command Index 4.1 Menus 4.2 Attacking commands 4.3 Weapon Management 4.4 Ammunition Management 4.5 Armour Class and Saving Throws 4.6 Other Commands 5 Command Details 5.1 Menus 5.1.1 Display a menu to do actions relating to attacks 5.1.2 Display a menu of other actions 5.2 Attacking Commands 5.2.1 Attack an opponent with a weapon 5.2.2 Use two weapons to attack 5.3 Weapon Management 5.3.1 Change weapons currently in hand 5.3.2 Manage a dancing weapon 5.3.3 Manage weapon statistics 5.3.4 Adding & removing weapons and ammunition 5.3.5 Blanking a weapon from attack tables 5.4 Ammunition Management 5.4.1 Ammunition recovery 5.4.2 Ammunition quantity amendment 5.5 Armour Class and Saving Throws 5.5.1 Edit Armour 5.5.2 Review Armour Class 5.5.3 Saving Throws 5.6 Other commands 5.6.1 Display help on these commands 5.6.2 Configure API behavior 5.6.3 Check database completeness & integrity 5.6.4 Extract database for Editing 5.6.5 Handshake with other APIs 5.6.6 Switch on or off Debug mode 6 Configuring the Token and Character Sheet for use with the API 7 Weapon, Ammo & Armour Databases 8 Changelog

Forum

RPGMaster Forum

How AttackMaster Works

Specifying a token

Most of the AttackMaster API commands need to know the token_id of the token that represents the character, NPC or creature that is to be acted upon. This ID can be specified in two possible ways:

1. explicitly in the command call using either a literal Roll20 token ID or using @{selected|token_id} or @{target|token_id} in the command string to read the token_id of a selected token on the map window,
   or
2. by having a token selected on the map window, not specifying the token_id in the command call, and allowing the API to discover the selected token_id.

In either case, if more than one token is selected at the time of the call then using either @{selected|token_id} to specify the token in the command call, or allowing the command to find a selected token, is likely (but not guaranteed) to take the first token that was selected. To avoid ambiguity, it is generally recommended to make command calls with only one token selected on the map window.

Who can make AttackMaster API command calls

The majority of API command calls can be made by both the GM and all Players. The typical means for command calls to be made is via Character Sheet Token Action Buttons (standard Roll20 functionality - see Roll20 Help Centre for information) which trigger Ability macros on the Character Sheet which simply make the API command call. The Character Sheets can be controlled by the GM or Players. The API knows if it is a GM or a Player that has triggered the call, and reacts accordingly.

Weapons that can be used

Any weapon in the Weapons tables on the Character Sheet can be used for attacks. However, the very best approach is to use the functions in this and other RPGMaster APIs (especially MagicMaster) to manage weapon choice. Weapon definitions are held in weapon databases. All standard weapons from the AD&D 2e Players Handbook are included, as well as many magic variations.

Allocating weapons to a Character

Weapons and ammunition are held in the Items table, which holds data on all items that the Character / NPC / creature has on their person - see the RPGMaster Character Sheet & Token Setup handout & Wiki page regarding where the Item table is on the Character Sheet and the data that is held in it. The added weapon should have a listing in the Weapons database to be fully functional.

The easiest way to enter the correct data into the Items table is to use the !attk --menu menu and select to edit weapons and armour, or use the !attk --edit-weapons command to bring up the edit weapons menu, or use the MagicMaster API, which supports finding and looting weapons e.g. from a chest or a dead body, or just the DM or Player choosing weapons from a menu. If a Ranged Weapon that uses ammunition is added, a quantity of the respective ammunition (or multiple types of ammunition) must also be added to the Items table.

Multiple weapons of many different types can be added, including those with magical properties. The system will take all the weapon statistics into account using the information in the associated databases.

Selecting weapons to attack with

Each Character / NPC / creature has a defined number of hands (which can be different from 2), and AttackMaster provides a menu to take any weapon(s) that are in the Items table in hand. Doing so enters all the correct information from the weapons database into the Weapons, Damage and Ranged Weapons tables, and the correct ammunition type(s) held in the Items table into the Ammo table.

Making attacks

Several different attack approaches are supported by the API.

Roll20 rolls:	the system makes an attack dice roll and modifies it using the data on the Character Sheet, then displays the results to the Player. Hovering the mouse over the displayed values of AC (armour class) hit and the Adjustments will display information explaining the values. Buttons are displayed to make Damage rolls which can be used if the attack was deemed successful (the target's AC was the same or worse than the AC hit).
Player rolls:	the system prompts for the Player to roll a dice and enter the result, and then modifies the roll entered using the data on the Character Sheet and displays the result to the Player. As above, hovering the mouse over the displayed results will explain how the amounts were calculated. Buttons to make Damage rolls are also displayed, which will also prompt the user to make a dice roll (showing the dice that should be rolled).
Targeted attack:	A targeted attack prompts the player to select the target. The system then rolls the Attack dice and the Damage dice and displays all possible results, and also displays the AC and HP of the target for quick analysis.

Ammunition

The system handles both Ranged weapons that take ammunition, such as bows and slings, and also “self-ammoed” Ranged weapons like daggers, that can be thrown at a target. The quantity of ammunition or self-ammoed weapons is managed by the system: as they are used in attacks, the quantity in the Character's Item table decreases. A menu can be called to recover ammunition, in agreement with the DM - the same menu can be used to add or remove quantities of ammunition for other reasons (such as being purchased). Some types of ammo always breaks and can't be recovered (for example glass arrows) - this is charged ammo.

Ranged weapon and ammunition ranges

Each type of ammunition has a range with the weapon used to fire it. These ranges can be different for different types of weapon - thus a longbow can fire an flight arrow further than a short bow, and a sheaf arrow has different ranges than the flight arrow with each. The ranges that can be achieved by the weapon and ammunition combination are displayed when they are used in an attack, and the Player is asked to select which range to use, which then applies the correct range modifier to the attack roll.

Dancing weapons

The system can support any weapon becoming a dancing weapon, with qualities that can be the same as or different from a Sword of Dancing. In the system a dancing weapon does not have to be held in hand in order for it to be available for attacks and, if using the InitiativeMaster API, the weapon is also automatically added to the Turn Order Tracker for its attacks to be performed in battle sequence. All of this can be achieved automatically if used with the RoundMaster API, with durations of 'warm up' and 'dancing' dealt with, as well as magical properties changing as the rounds progress - that function requires some editing of the Effects database to adapt for a particular weapon.

Armour Class management

The system continually checks the Armour Class of each Character / NPC / creature by examining the information on the Character Sheet and the items in the Item table. Armour and Shields can be placed in the Items table which will be discovered, and the specifications from the Armour database used to calculate the appropriate AC under various conditions and display them to the Player. The process the system made to achieve the calculated AC will be shown.

Many magic items have AC qualities, such as Bracers of Defence and Rings of Protection, and if the MagicMaster API is used these are also taken into account - invalid combinations will also be prevented, such as Rings of Protection with magical armour. If allocated to a Token Circle, the calculated AC is compared to the displayed Token AC and any difference highlighted - this may be due to magical effects currently in place, for instance - the highlight allows the Player to review why this might be.

Saves

The corollary to attacks is saves. The system provides a menu to access, review, update and make saving throws and the appropriate modifiers.

The initial menu presented shows the saving throw table from the Character Sheet (always the one from the Character tab rather than the Monster Tab - monster saving throws should be copied to both). Each type of save has a button to make the saving throw: the system will perform the roll and display the result with an indication of success or failure. The menu also shows buttons to add a situational adjustment (as per the AD&D 2e PHB) and to modify the saving throw table.

The easiest way to set the correct saving throws for each type of save, based on class, level & race, is to use the CommandMaster API Character Sheet setup commands.

How To Use AttackMaster

Installation and Configuration

The best way to install AttackMaster API is to use the Roll20 ["One-Click Install" menu], which will automatically keep the code an databases updated to the latest versions. Alternatively, copy the script's code, available from the menu on the right and stored at Roll20's API GitHub Repository. Paste the code into a new script in your campaign's API Script Editor. Save the new script and it will be available inside your campaign. It will install several new Character Sheets & Handouts: The handout AttackMaster Help provides a full manual of how to use AttackMaster. The handout RPGMaster CharSheet Setup provides information on setting up a character sheet for use with AttackMaster. The handout Weapon & Armour Database Help provides information on the databases that come with the API, and how to add to and change them.

Script Use

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

Syntax

The AttackMaster API is called using !attk.

!attk --help

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

!attk --attk-hit token_id | [message] | [monster weap1] | [monster weap2] | [monster weap3]

If optional parameters are not to be included, but subsequent parameters are needed, use two vertical bars together with nothing between them, e.g.

!attk --checkac token_id || [SADJ / PADJ / BADJ]

Commands can be stacked in the call, for example:

!attk --checkac token_id | [ SILENT ] | [SADJ / PADJ / BADJ] –weapon token_id

When specifying the commands in this document, parameters enclosed in square brackets [like this] are optional: the square brackets are not included when calling the command with an optional parameter, they are just for description purposes in this document. Parameters that can be one of a small number of options have those options listed, separated by forward slash ‘/’, meaning at least one of those listed must be provided (unless the parameter is also specified in [] as optional): again, the slash ‘/’ is not part of the command. Parameters in UPPERCASE are literal, and must be spelt as shown (though their case is actually irrelevant).

Command Index

Menus

--menu [token_id]
--other-menu [token_id]

Attacking commands

--attk-hit [token_id] | [message] | [monster weap1] | [monster weap2] | [monster weap3]
--attk-roll [token_id] | [message] | [monster weap1] | [monster weap2] | [monster weap3]
--attk-target [token_id] | [message] | [monster weap1] | [monster weap2] | [monster weap3]
--twoswords [token_id]|[prime-weapon]

Weapon Management

--weapon [token_id]
--dance [token_id] | weapon  | [ STOP ]
--mod-weapon [token_id] | weapon | MELEE / RANGED / DMG / AMMO | adjustments
--quiet-modweap [token_id] | weapon | MELEE / RANGED / DMG / AMMO | adjustments
--edit-weapons [token_id]
--blank-weapon [token_id] | weapon | [ SILENT ]

Ammunition Management

--ammo [token_id]
--setammo [token_id] | ammo_name | [ [+/-]cur_qty / = ] | [ [+/-]max_qty / = ] | [ SILENT ]

Armour Class and Saving Throws

--edit-armour [token_id]
--checkac [token_id] | [ SILENT ] | [SADJ / PADJ / BADJ]
--save [token_id] | [situation-mod]

Other Commands

--help
--check-db [ db-name ]
--extract-db db-name
--handshake from | [cmd]
--hsq from | [cmd]
--hsr from | [cmd] | [TRUE/FALSE]
--debug [ ON / OFF ]

Command Details

Menus

Display a menu to do actions relating to attacks

--menu [token_id]

Takes an optional token ID – if not specified uses selected token

Displays a Chat menu with buttons for: Attacking, with either Roll20 rolling a dice, or the Player entering a dice roll result; changing what is in the Character’s (or NPC’s) hands; to recover spent ammo; and to check the current Armour Class for the Character under various circumstances. If the GM uses the menu, an additional button for a Targeted Hit appears, which allows the GM to select both the attacker and the target and get full specs on the hit and damage done, and the AC & current hit Points of the target.

Display a menu of other actions

--other-menu [token_id]

Takes an optional token ID – if not specified uses selected token

Displays a Chat menu with buttons for: saving throws and saving throw management; and managing light sources for the character’s token (if Dynamic Lighting is being used) (requires MagicMaster API to work). If the GM uses the menu, two further options appear: mark the token selected as Dead (which also marks the body as an inanimate object that can be looted); and the ability to adjust damage for the selected token for any arbitrary reason, which can also be noted.

Attacking Commands

Attack an opponent with a weapon

--attk-hit [token_id] | [message] | [monster weap1] | [monster weap2] | [monster weap3]
--attk-roll [token_id] | [message] | [monster weap1] | [monster weap2] | [monster weap3]
--attk-target [token_id] | [message] | [monster weap1] | [monster weap2] | [monster weap3]

Each takes an optional token ID (if not specified uses selected token), an optional formatted message to include with the attack damage, and up to three optional names for each of the monster attacks that are displayed on the attack menu.

Each of these three commands present a menu of currently possible attacks, using the weapons and ammo in-hand or, for monsters using the Monster tab on the AD&D 2e Character Sheet, up to 3 types of monster attacks. Ranged weapon attacks will prompt the Player to specify which range to fire at. Selecting one of the possible attacks has different outcomes based on the command used:

The optional message is displayed as part of the display of the damage done on a successful hit. If a monster, the message can be three concatenated messages separated by ‘$$’. The message can include API Buttons if needed. The following characters must be replaced (escaped) using these replacements:

--attk-hit	prompts Roll20 to make an attack roll, using 3D dice if they are enabled, displays the AC hit with supporting information on how this was calculated and displays buttons to roll for damage if the attack is successful.
--attk-roll	displays an entry field to allow the Player to enter the value of their own dice roll (for those that prefer to roll their own dice) though the default entry will also roll the dice for the player. Subsequently, the process is the same as --attk-hit.
--attk-target	is only available to the GM. It asks the GM to select a target token for the attack. It then displays the AC the attack roll will hit and the AC of the selected target. It also automatically rolls damage for Small/Medium and Large targets, and displays the current Hit Points for the targeted token.

Character	Parameter separator	?	[	]	<	>	@	-	|	:	&	{	}
Substitute	%%	^	<<	>>			`	~	¦		&amp;	&#123;	&#125;
Alternative (no ; )	\vbar	\ques	\lbrak	\rbrak	\lt	\gt	\at	\dash	\vbar	\clon	\amp	\lbrc	\rbrc

Use two weapons to attack

--twoswords [token_id]|[prime-weapon]

Takes an optional token ID (if not specified uses selected token) and an optional weapon name.

This command sets the system up to apply the correct penalties / bonuses when using two weapons to attack. Under AD&D 2e rules, only types of Fighter & Rogue can use 2 weapons at a time to attack in a round, and only Rangers do so without penalty. Using this command with the name of a prime-weapon specified will mark that weapon as the Primary which will get the smaller penalty of the two and will also be allowed multiple attacks per round (if using InitiativeMaster API). Use of any other weapon during the current or subsequent rounds will incur a larger penalty and be restricted to one attack per round regardless of type of weapon, level & proficiency. Penalties are adjusted by the Dexterity Reaction Adjustment. See AD&D 2e PHB p96 for full explanation of rules applied.

Calling this command without a prime-weapon specified will terminate two-weapon mode and no penalties will be applied for the current and subsequent rounds.

Weapon Management

Change weapons currently in hand

--weapon [token_id]

Takes an optional token ID – if not specified uses selected token.

This command displays a chat menu displaying what is currently in the Character’s (or NPC or creature’s) hands, and allowing the Player to change what is held to any weapon or shield that they have in their backpack. Subsequent attacks will then use the newly specified weapon(s). Selecting a ranged weapon that uses ammunition, the appropriate ammunition held in their backpack is also loaded into the character’s “quiver”.

Selecting a hand (either Left or Right) will display any 1-handed weapons that can be used for selection in a list. Selecting the Both Hands button will display all the 2-handed weapons (including bows) that can be used for selection in a list. Some weapons can be used either 1-handed or 2-handed, and the appropriate stats will be given based on the selection made.

If being used by the GM, the menu also has an option to change the number of hands the creature has, which will then allow the creature to hold (and attack with) more than two items, or to hold items that require more than two hands.

Note: this function is dependent on the weapon and shield definitions including certain key information in a specified format: see the Weapon, Ammo & Armour Handout and Wiki page.

Manage a dancing weapon

--dance [token_id] | weapon  | [ STOP ]

Takes an optional token ID (if not specified uses selected token), a mandatory weapon name, and an optional STOP command.

This command marks the named weapon as “dancing” which means it will no longer occupy a hand, but will still appear in the list of possible attacks when an attack is made. When started, the --weapon command is automatically run so that an additional weapon can be taken in the freed-up hand.

Appending the “STOP” command will un-mark the weapon as dancing. The Player will have to take the no-longer dancing weapon back in hand, if they so desire, using the --weapon command.

Note: the most effective use of the --dance command is when combined with the RoundMaster effect management system, to count down rounds of use, automatically call the --dance command at the appropriate time, and stop the dancing automatically after the appropriate duration.

Manage weapon statistics

--mod-weapon [token_id] | weapon | MELEE / RANGED / DMG / AMMO | adjustments
--quiet-modweap [token_id] | weapon | MELEE / RANGED / DMG / AMMO | adjustments

Each command takes an optional token ID (if not specified uses selected token), a mandatory weapon name, and a mandatory data type.

These commands allow the specifications of any weapon currently in-hand to be adjusted programmatically. E.g. the magical plus on to-hit and damage can be adjusted round by round (as for a Sword of Dancing). The type of data to be adjusted must be identified using the data type parameter: MELEE & RANGED alter To-Hit data, and DMG & AMMO alter Damage.

The weapon parameter can name a specific weapon name, a type of weapon (e.g. bow, long-blade, club etc), a changed weapon name (previously changed by this command), or even ‘all’ for all currently held weapons. All data of the specified data type for all weapons that match the weapon parameter may then be altered, using the comma-separated adjustments parameter. Each adjustment is of the format

field_id:[=][+/-]value

where the field_ids are:

w:	weapon name	t:	weapon type	st:	weapon super-type
sb:	strength bonus	db:	dexterity bonus	+:	magical plus
n:	number of attacks per round	pl:	proficiency level	pd:	dancing proficiency level
ch:	critical hit roll	cm:	critical miss roll	sz:	size
r:	range (can be #/#/#)	ty:	damage type	sp:	speed in segments
sm:	damage vs small & medium	l:	damage vs large

Numeric values can be preceeded by + or -, which will adjust rather than replace the current value. To set a value as negative, precede the minus by an equals thus =-value. For attributes that are relevant to multiple data types, only the specified data type will be adjusted. Multiple attributes can be adjusted using one command call by concatenating comma-delimited adjustments. E.g.

--mod-weap @{selected|token_id}|Sword-of-Dancing|MELEE|sb:0,+:+1,sp:-1

If the weapon is not found, the GM receives an error message, but no other issues occur.

Adding & removing weapons and ammunition

--edit-weapons [token_id]

Takes an optional token ID – if not specified uses selected token.

The very best way for the Character, NPC or creature to acquire weapons (or any other items including magic items) is to use the MagicMaster API and its commands and databases. However, AttackMaster provides a small subset of those facilities to allow the DM and/or Players to add weapons, ammo & armour to their Character Sheet item bags. Once added, these items can be taken ‘in-hand’ by the Character (using the --weapon command) and then used to attack.

The advantage of doing this over just typing the item names into the Character Sheet tables is that the items are assured to exist in the weapon, ammo & armour databases that come with the API and so all other aspects of the API will work properly.

This command and --edit-armour are identical, and call the same menu.

Blanking a weapon from attack tables

--blank-weapon [token_id] | weapon | [ SILENT ]

Takes an optional token ID (if not specified uses selected token), the mandatory name of a weapon, and an optional "SILENT" command.

This command will programmatically remove the named weapon, and any associated ammunition for ranged weapons, from all attack tables on the character sheet, and from the system in-hand table and quiver, on the Character Sheet associated with the specified or selected token. This is especially useful for "weaponised" spells that need to be immediately removed once cast and attacked with.

Ammunition Management

Ammunition recovery

--ammo [token_id]

Takes an optional token ID – if not specified uses selected token.

This command displays a chat menu of ammunition that the Character has on their person (not just the ammo that they have in their quiver or in-hand) including any ammunition that has run-out but might still be recoverable. The Player can ask the DM if they can retrieve any ammunition of the types displayed that they have recently used and, once the DM responds with the amount recovered, click on the type of ammunition in the list and enter the amount recovered. Both the amount on their person, and any amount in their quiver or in-hand are updated.

Note: enter the amount recovered not the new total. The amount entered will be added to the current amount held, and then this new value set as the new maximum. A negative amount can also be entered, which will be removed from the current quantity and will also set the new maximum.

Note: after a Long Rest (see MagicMaster API) all ammunition maximum totals are set to current quantities at that time. It is assumed that during the period of a long rest, some creature will have found any loose ammo, or it will otherwise have been broken or lost.

Note: ammunition that has the item-type of ‘charged’ will appear on the menu with a grey box which cannot be selected, indicating that the ammo cannot be recovered – such ammunition always breaks on contact: e.g. glass arrows.

Ammunition quantity amendment

--setammo [token_id] | ammo_name | [ [+/-]cur_qty / = ] | [ [+/-]max_qty / = ] | [ SILENT ]

Takes an optional token ID (if not specified uses selected token), the unique name of the ammunition, an optional value for the current quantity, optionally preceded by +/- or replaced by an =, an optional value for the maximum quantity with the same +/- & = possibilities, and an optional parameter of “Silent” (case insensitive).

This command allows programmatic or macro alteration of the quantity of a type of ammo:

• The current quantity and/or the maximum held (i.e. the amount to which ammunition can be recovered up to – see section 4.1 Ammunition Recovery, above) can be set to absolute values just by entering numbers for the parameters.
• Either parameter can be preceded by a + or -, in which case the parameter will modify the corresponding current value, rather than replacing it.
• Either parameter can be an = by itself. In this instance, the corresponding value is set to the other corresponding value (after any modification) i.e. putting = for cur_qty sets the current quantity held to be the maximum possible, or putting = for max_qty sets the maximum possible to be the current quantity. Putting = for both does nothing.
• No value can go below 0, and the current quantity will be constrained at or below the maximum quantity.

So, for example, this command will set the maximum quantity to 10 and set the current quantity to be equal to it:

!attk –setammo @{selected|token_id}|Flight-Arrow+1|=|10|silent

If the “Silent” parameter is not specified, then the Ammunition Recovery chat menu will display with the amended values once complete, and a message is displayed with the changes that occurred.

Note: if more than one ammo item of the same name is listed in the backpack table (see the Character Sheet & Token Setup Handout & Wiki page), only the first item found will be amended. If no item of that name is found, nothing happens and no menus or messages are displayed.

Armour Class and Saving Throws

Edit Armour

--edit-armour [token_id]
--edit-armor [token_id]

Takes an optional token ID – if not specified uses selected token.

The very best way for the Character, NPC or creature to acquire armour (or any other items including magic items) is to use the MagicMaster API and its commands and databases. However, AttackMaster provides a small subset of those facilities to allow the DM and/or Players to add weapons, ammo & armour to their Character Sheet item bags. Once added, these items can be taken ‘in-hand’ by the Character (using the --weapon command), and improve the Armour Class of the Character appropriately.

The advantage of doing this over just typing the item names into the Character Sheet tables is that the items are assured to exist in the weapon, ammo & armour databases that come with the API and so all other aspects of the API will work properly.

This command is identical to the --edit-weapons command and uses the same menu.

Review Armour Class

--checkac [token_id] | [ SILENT ] | [SADJ / PADJ / BADJ]

Takes an optional token ID (if not specified uses selected token), an optional “Silent” command, and an optional damage type which can be “SADJ”, “PADJ” or “BADJ” (the “Silent” and damage type parameters are not case sensitive).

This command analyses the the items in the Character’s backpack table using the information in the various item databases supplied / created by the API(s), and taking into account the current Dexterity bonuses calculates the current Armour Class of the Character. It then displays a chat message with its results and an explanation of how it came to them. If the optional damage type is provided, the calculation takes this into account.

The system can use the information in the databases to take into account magical armour plusses, combined effects of armour that can work together (like Armour and Shields), exclude combinations that are not allowed (like Rings of Protection with magical armour), and the armour types allowed for various character classes and races including specialist variations (as defined in the Class-DB character class database).

The system automatically updates this information any time the Character changes what is in their hands (e.g. if they pick up or put down a shield) using the --weapon command. If using the InitMaster API, the command is also run every time the character does an Initiative roll. If using the MagicMaster API, the command is also run any time items are looted from a chest or NPC, or stored away or given to another character.

The system remembers on the Character Sheet what its calculations are each time. If the most recent calculation results in a change in Armour Class for the character, the character’s token AC (if displayed) will be modified by the difference between the old and new values. This modified value will be shown on the Armour Class Review message in the chat window if it is different from the calculated value.

Note: the token displayed AC is only modified by the difference between the previous and current calculations. This allows magical and other effects (such as those managed by the RoundMaster API) to alter the token displayed AC and not be overwritten by a change in calculated AC, but still take into account the change. The token AC can be manually updated at any time without impact on this functionality, to overcome any errors.

Note: if the token is configured following the Master Series API standard (see CommandMaster API documentation), the token bar for the displayed AC is normally hidden. if the calculated AC and token displayed AC are different (see above) then the AC token bar appears, representing the difference between the two. This acts as a visual reminder to the DM and Player that the token is the subject of some effect on AC – it also helps to identify if there is a difference in error, so that this can be manually rectified (by manually altering the token displayed AC). Once the two are again the same and the –check-ac command run, the token AC bar will again be hidden.

Saving Throws

--save [token_id] | [ situation-mod ]
--save [token_id] | [ situation-mod ] | save-type | saving-throw

Takes an optional token ID (if not specified uses selected token), and different forms of the command take an optional situational modifier to the saving throw, a type of save (which can be one of ‘paralysis’, ‘poison’, ‘death’, ‘rod’, ‘staff’, ‘wand’, ‘petrification’, ‘polymorph’, ‘breath’, or ‘spell’, not sensitive to case), and the base, unmodified saving throw achieved on a dice.

This command can either display a menu from which to display and manage the saving throw table, and make saving throws or, in its second form, to make a saving throw and check the result against the saving throw table.

The first form shows all the possible saves that can be made, the saving throw that needs to be achieved to make the save, and any modifiers that apply to this particular character. There are buttons to have the API calculate the currently valid saving throw table by examining Race, Class, Level, and Magic Items, or to manually modify the saving throw table and the modifiers, and/or to apply a “situational modifier” to immediate saving throws (the “situational modifier” only applies to current rolls and is not remembered). Also, each type of saving throw can actually be made by clicking the buttons provided. Doing so effectively runs the second form of the command.

The situational modifier can optionally be passed in as a value with the command call if so desired, instead of selecting via the button on the menu.

Running the second form of the command (or selecting to make a saving throw from the first form’s menu) will execute the saving throw (as a dice roll if this is specified instead of a straight value) of the specified type, using the data in the character’s saving throw table to assess success or failure, displaying the outcome and the calculation behind it in the chat window.

Other commands

Display help on these commands

--help

This command does not take any arguments. It displays a very short version of this document, showing the mandatory and optional arguments, and a brief description of each command.

Configure API behavior

--config [DM-TARGET/PROF/ALL-WEAPS/WEAP-CLASS/ALL-ARMOUR/MASTER-RANGE/SPECIALIST-RULES/SPELL-NUM] | [TRUE/FALSE]

Takes two optional arguments, the first a switchable flag name, and the second TRUE or FALSE.

Allows configuration of several API behaviors. If no arguments given, displays menu for DM to select configuration. Parameters have the following effects:

Flag	True	False
DM-TARGET	The default attack type for the DM is targeted	The default attack type for the DM is To Hit
PROF	Strictly apply non-proficient weapon penalties as per PHB	Use the non-proficient weapon penalty displayed on the Character Sheet
ALL-WEAPS	Allow any character of any class to use and become proficient in any weapon.	Restrict the use of weapons by class to some degree set by WEAP-CLASS
WEAP-CLASS	Weapons not allowed to a class get a penalty of -100	Weapons not allowed to a class get double non-proficient penalty
ALL-ARMOUR	All armour types allowed for all classes	Armour not allowed to a class not included in AC calculations
MASTER-RANGE	Ranged weapon Mastery gives double damage at Point Blank range	Ranged weapon Mastery not allowed, as per PHB
SPECIALIST-RULES	Only Specialist Wizards specified in the PHB get an extra spell per spell level	Any non-Standard Wizard gets an extra spell per spell level
SPELL-NUM	Spellcaster spells per level restricted to PHB rules	Spellcaster spells per level alterable using Misc Spells button
ALL-SPELLS	All spells are available to memorise for all Spellcasters	Spellcaster spells are restricted to those available to their Class

Check database completeness & integrity

--check-db [ db-name ]

Takes an optional database name or part of a database name: if a partial name, checks all character sheets with the provided text in their name that also have ‘-db’ as part of their name. If omitted, checks all character sheets with ‘-db’ in the name. Not case sensitive. Can only be used by the GM.

This command finds all databases that match the name or partial name provided (not case sensitive), and checks them for completeness and integrity. The command does not alter any ability macros, but ensures that the casting time (‘ct-‘) attributes are correctly created, that the item lists are sorted and complete, and that any item-specific power & spell specifications are correctly built and saved.

This command is very useful to run after creating/adding new items as ability macros to the databases. It does not check if the ability macro definition itself is valid, but if it is then it ensures all other aspects of the database consistently reflect the new ability(s).

Extract database for Editing

--extract-db [db-name]

Takes an optional database name or part of a database name: if a partial name, checks all character sheets with the provided text in their name that also have '-db' as part of their name. If omitted, checks all character sheets with '-db' in the name. Not case sensitive. Can only be used by the GM.

Extracts a named database or all provided databases from the loaded RPGMaster Library, and builds the database in a Character Sheet format: see the Database specific help handouts for further details of this format. This allows editing of the standard items in the databases, adding additional items to the databases, or for items to be copied into the GM's own databases. Unlike with previous versions of the Master Series APIs, these extracted databases will not be overwritten by the system. However: using extracted databases will slow the system down - the use of the internal API databases held in memory is much faster. The best use for these extracts is to examine how various items have been programmed so that the GM can create variations of the standard items in their own databases by copying and making small alterations to the definitions, and then the extracted databases can be deleted.

Important: Once a Character Sheet database is changed or deleted, run the --check-db command against any database (especially a changed one) to prompt the APIs to re-index the objects in all databases.

Handshake with other APIs

–hsq from|[command]
–handshake from|[command]

Either form performs a handshake with another API, whose call (without the ‘!’) is specified as from in the command parameters (the response is always an –hsr command). The command calls the from API command responding with its own command to confirm that the API is loaded and running: e.g.

Received: !attk --hsq init
Response: !init --hsr attk

Optionally, a command query can be made to see if the command is supported by the API if the command string parameter is added, where command is the command to be queried (the ‘--’ text without the ‘--‘). This will respond with a true/false response: e.g.

Received: !attk --handshake init|menu
Response: !init --hsr attk|menu|true

or

Received: !attk --handshake magic|notAcommand
Response: !magic --hsr attk|notAcommand|false

Switch on or off Debug mode

--debug (ON/OFF)

Takes one mandatory argument which should be ON or OFF.

The command turns on a verbose diagnostic mode for the API which will trace what commands are being processed, including internal commands, what attributes are being set and changed, and more detail about any errors that are occurring. The command can be used by the DM or any Player – so the DM or a technical advisor can play as a Player and see the debugging messages.

Configuring the Token and Character Sheet for use with the API

At the time of writing this Wiki, the RPGMaster APIs, including AttackMaster, are initially configured and distributed to support the Advanced Dungeons & Dragons 2nd Edition RPG and matching Advanced 2nd Edition Character Sheet on Roll20. The Character Sheets and tokens that represent them are best set up for game play by using the facilities provided by the APIs, and especially those menus and commands provided by the CommandMaster API. However, if desired, it is possible to set up Character Sheets and tokens manually (especially if not using all the APIs): instructions on how to achieve this are provided in the RPGMaster Character Sheet and Token setup Handout and Wiki page.

The APIs are currently capable of being adjusted to support any RPG and Character Sheet by adjusting the mappings and database entries supplied as default, but at present this is a significant task. The RPGMaster Character Sheet and Token Setup handout & Wiki, and the individual database help handouts and wiki pages provide information on how to do this. A future development currently planned (but with no date for release) is to reprogram the APIs to include a RPG-defining Library API, one for each supported game system, that will include the RPG rules for the RPGMaster APIs and adjust the API behaviours to work for the RPG the Library is for.

Weapon, Ammo & Armour Databases

As with other items that can be acquired and used by Characters, NPCs and Creatures in the RPGMaster suite, the definitions for Weapons, Ammunition and Armour for use by the AttackMaster API are held in Character Sheet databases. See the Weapon, Ammo & Armour Database Help handout and Wiki page for information on these databases.

Changelog

v1.3.00 (2022-10-01)

• Major release to extract all RPG version-specific data and rule processing to RPGMaster Library API

v2.046 (2022-03-28)

• Added Class database with PHB Character Class definitions.
• Added Attacks database with standard attack calculation definitions.
• Added full support for damage types (S, P & B) for both weapons and armour.
• Added support for non-standard fractional numbers of weapon attacks per round.
• Updated saving throw table calculations to automatically add in appropriate Magic Item bonuses.
• Made several long running processes asynchronous to eliminate "infinite loop" detection errors.
• Fixed handling of manual character sheet table entries.

v1.042 (2022-02-18)

• Fixed restricted weapon proficiency calculations.
• Fixed prioritisation of user-defined database entries

v1.040 (2022-02-02)

• Added --config command and menu for DM to alter some API behavior.
• Multiple weapon changes and additions

v1.039 (2022-01-23)

• Fixed Spear definition for self-ammo-ed ranged weapon & added powerful-longsword
• Fixed illegal characters not rendered by One-Click install
• Added Bow mastery to do double damage at PB range (removed from specialist)

v1.038 (2022-01-09)

• Improved Indexing & Performance
• Changed data tags to reflect newest standard
• Fixed bug relating to AC0 when calculating AC
• Added magically summoned weapons (e.g. Mordenkainen's Sword) for new spells

v1.037 (2021-12-14)

• First version for public release