Latest revision as of 16:52, 11 June 2023

Page Updated:   2023-06-11

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.

[edit] Forum

RPGMaster Forum

[edit] AttackMaster Database Help

Weapon, Ammo & Armour Database - RPGMaster Weapons & Armour database Wiki page
Attack Templates Database - Attack macro definition database Wiki page

[edit] Configuring Character Sheets

RPGMaster Character Sheet setup - RPGMaster Character Sheet setup Wiki page

[edit] How AttackMaster Works

[edit] How To Use AttackMaster

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

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

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

[edit] Command Index

[edit] Command Index

[edit] Menus

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

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

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

[edit] Ammunition Management

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

[edit] Armour Class and Saving Throws

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

[edit] Other Commands

--help
--config [PROF/ALL-WEAPS/WEAP-CLASS/ALL-ARMOUR/MASTER-RANGE/SPECIALIST-RULES/SPELL-NUM] | [TRUE/FALSE]
--check-db [ db-name ]
--extract-db db-name
--handshake from | [cmd]
--hsq from | [cmd]
--hsr from | [cmd] | [TRUE/FALSE]
--debug [ ON / OFF ]

[edit] Command details

[edit] Menus

[edit] 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 Roll20 rolling a dice or the Player entering a dice roll result, or the Player selecting a target and getting the result of an attack (if allowed by the DM in setting the API options); 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.

[edit] 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; managing character classes and levels (if the CommandMaster API is loaded) 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.

[edit] Attacking Commands

[edit] Attack an opponent with a weapon

--attk-hit [token_id] | [message] | [monster weap1] | [monster weap2] | [monster weap3]
--attk-menu-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:

--attk-hit

displays a menu of current possible attacks with buttons the Player or GM can use to change the type of attack that will be done (Roll20 rolls, Player rolls, or Targeted attack, default Roll20 rolls) which is remembered for each Player and carried between campaign sessions.

--attk-menu-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

asks the Player 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 relative proportion of Hit Points for the targeted token at the time of the attack. Recommended only for the DM, as it reveals information about the target, but can be enabled for Players using the --config command.

The attack menu also has buttons that allow the Player or GM to change the default attack type made: Roll20 rolls, Player rolls, or a targeted attack. It also has a button to turn 3D dice on or off. This configuration is held by Player for each Campaign, and preserved between sessions of game play.

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:

[edit] 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. For example, 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 if using the AD&D 2e RPGMaster Library rule set.

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.

[edit] Weapon Management

[edit] 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, shield, or light source that they have in their items, or for spell casters any weaponised spell (a spell that requires an attack roll, either in Melee combat or at range) they have menorised. Subsequent attacks will then use the newly specified weapon(s) or weaponised spell(s). When selecting a ranged weapon that uses ammunition, the appropriate ammunition held in their on-person items is also loaded into the character's "quiver".

Selecting a hand (either Left or Right) will display any 1-handed items and spells that can be used for selection in a list. Selecting the Both Hands button will display all the 2-handed items (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.

A button is also shown to allow the Character to "lend" their hands to another Character: this will allow the receiving Character to use weapons and devices that require more than 2 hands, such as large siege engines and windlasses on ships. If the donating Character selects to take any new weapon in-hand, the "lent" hands will be removed from the receiving Character and any device needing more hands than are left will be dropped. Multiple Characters can lend hands to a receiving Character so that very large devices (such as a Battering Ram) can be used.

Buttons are also provided to set the rings worn on each hand. Rings affecting armour class and/or saves will only take effect in the system if worn.

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, shield, light source and spell definitions including certain key information in a specified format: see the [Weapon & Armour Database Help] or [Magic Database Help] for details.

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

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

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.

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