Character Vault
Any Concept / Any System
Compendium
Your System Come To Life
Roll20 for Android
Streamlined for your Tablet
Roll20 for iPad
Streamlined for your Tablet

Personal tools

Difference between revisions of "Script:AttackMaster"

From Roll20 Wiki

Jump to: navigation, search
 
(27 intermediate revisions by 2 users not shown)
Line 4: Line 4:
 
|name=AttackMaster
 
|name=AttackMaster
 
|author=[[Richard E]]
 
|author=[[Richard E]]
|version=1.039
+
|version=1.5.02
|lastmodified=2022-01-23
+
|lastmodified=2023-05-31
 
|code=AttackMaster
 
|code=AttackMaster
|dependencies=None
+
|dependencies=
 +
{{api repository link|RPGMlibrary AD+D2e}}
 
|conflicts=None}}
 
|conflicts=None}}
 
'''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.
 
'''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 standard AD&D 2e rules to the full extent, 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 [[Script: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 works best with the '''[[Script: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 <b>[[Script:CommandMaster]] API</b> can be used by the GM to easily manage weapon proficiencies.
+
It uses the attack definitions defined in the [[API:RPGMaster-AttacksDB|<b>Attacks-DB</b> 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 [[Script:RoundMaster|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'' '''[[Script:RPGMaster Library|RPGMaster Library]]''' to work (make sure it is loaded alongside AttackMaster), and works best with the '''[[Script:MagicMaster|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 <b>[[Script:CommandMaster|CommandMaster API]]</b> can be used by the GM to easily manage weapon proficiencies.
<p>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 two 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, following the instructions provided in section 8.</p>
+
<p>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 [[API:RPGMaster-WeaponsArmorDB|<b>MI-DB-Weapons, -Ammo and -Armour</b> 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 [[API:RPGMaster-WeaponsArmorDB|Help Handout and Wiki page.]]</p>
  
= Forum =
+
== Forum ==
[https://app.roll20.net/forum/post/10607093/script-rpgmaster-apis-for-ad-and-d-2e RPGMaster Forum]
+
[https://app.roll20.net/forum/post/11115777/script-rpgmaster-apis-for-ad-and-d-2e RPGMaster Forum]
 +
== AttackMaster Database Help ==
 +
[[API:RPGMaster-WeaponsArmorDB|Weapon, Ammo & Armour Database]] - RPGMaster Weapons & Armour database Wiki page<br>
 +
[[API:RPGMaster-AttacksDB|Attack Templates Database]] - Attack macro definition database Wiki page
 +
== Configuring Character Sheets ==
 +
[[API:RPGMaster-CharacterSheets|RPGMaster Character Sheet setup]] - RPGMaster Character Sheet setup Wiki page
  
 
=How AttackMaster Works=
 
=How AttackMaster Works=
==Specifying a token==
+
{| role="presentation" class="wikitable mw-collapsible mw-collapsed"
 +
|
 +
|-
 +
|<p style="font-size: 150%">Specifying a token</p>
 
<p>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:</p>
 
<p>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:</p>
 
<ol><li>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,<br>or</li>
 
<ol><li>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,<br>or</li>
 
<li>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.</li></ol>
 
<li>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.</li></ol>
 
<p>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.</p>
 
<p>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.</p>
==Who can make AttackMaster API command calls==
+
 
 +
<p style="font-size: 150%">Who can make AttackMaster API command calls</p>
 
<p>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.</p>
 
<p>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.</p>
==Weapons that can be used==
+
 
<p>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 <b>MagicMaster</b>) 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.</p>
+
<p style="font-size: 150%">Weapons that can be used</p>
==Allocating weapons to a Character==
+
<p>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 to manage weapon choice.  Weapon definitions are held in weapon databases: see Database-specific handouts for details.  All standard weapons are included, as well as many magic variations.</p>
<p>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 section 7 regarding where the Item table is on the Character Sheet and the data that is held in it.  The added weapon must have a listing in the Weapons database.</p>
+
 
<p>The easiest way to enter the correct data into the Items table is to use the <b>!attk --menu</b> menu and select to edit weapons and armour, or use the <b>!attk --edit-weapons</b> command to bring up the edit weapons menu,  or use the <b>MagicMaster API</b>, 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.</p>
+
<p style="font-size: 150%">Allocating weapons to a Character</p>
 +
<p>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 Character Sheet setup help handout regarding where the Item table is on the Character Sheet and the data that is held in it.  The added weapon must have a listing in the Weapons database.</p>
 +
<p>The easiest way to enter the correct data into the Items table is to use the <b>MagicMaster API</b>, 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.</p>
 
<p>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.</p>
 
<p>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.</p>
==Selecting weapons to attack with==
+
 
<p>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.</p>
+
<p style="font-size: 150%">Selecting weapons to attack with</p>
==Making attacks==
+
<p>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) 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.</p>
 +
 
 +
<p style="font-size: 150%">Making attacks</p>
 
<p>Several different attack approaches are supported by the API.</p>
 
<p>Several different attack approaches are supported by the API.</p>
<table><tr><th scope="row">Roll20 rolls:</th><td>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).</td></tr>
+
<table><tr><th scope="row">Roll20 rolls:</th><td>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).</d></tr>
 
<tr><th scope="row">Player rolls:</th><td>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).</td></tr>
 
<tr><th scope="row">Player rolls:</th><td>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).</td></tr>
<tr><th scope="row">Targeted attack:</th><td>DM only option. The DM can, if they choose, make a targeted attack, which prompts the DM 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.</td></tr></table>
+
<tr><th scope="row">Targeted attack:</th><td>Option under DM --config control. The DM can, if they choose, make targeted attacks available which 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 the HP status of the target for quick analysis.</td></tr></table>
==Ammunition==
+
 
<p>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 Characters 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.</p>
+
<p style="font-size: 150%">Ammunition</p>
==Ranged weapon and ammunition ranges==
+
<p>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 Characters 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.</p>
 +
 
 +
<p style="font-size: 150%">Ranged weapon and ammunition ranges</p>
 
<p>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.</p>
 
<p>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.</p>
==Dancing weapons==
+
 
<p>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 <b>InitiativeMaster API</b>, 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 <b>RoundMaster API</b>, 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 - see section 8 of the RoundMaster API documentation for details.</p>
+
<p style="font-size: 150%">Dancing weapons</p>
==Armour Class management==
+
<p>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 <b>InitiativeMaster API</b>, 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 <b>RoundMaster API</b>, 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 - see the RoundMaster API Effect Database documentation for details.</p>
 +
 
 +
<p style="font-size: 150%">Fighting Styles</p>
 +
<p><i>The Complete Fighter\'s Handbook</i> introduced the concept of Fighters being able to become proficient or a specialist in various styles of fighting, such as with two-handed melee weapons, a weapon and a shield, and such like. These are supported in the RPGMaster APIs via the <b>Styles-DB</b> database, and functions in the <b>CommandMaster API, InitiativeMaster API</b> as well as here in AttackMaster.  Each time weapons & shields in-hand are changed using the <i>Attack Menu / Change Weapons</i> menu, AttackMaster checks what is in-hand against any Fighting Styles the character is proficient or specialised in (as defined via the <b>CommandMaster</b> <i>Token-Setup / Set Proficiencies</i> menu). If any are applicable given what is currently in use, AttackMaster will apply the relevant fighting style benefits to the character and their use of their weapons and armour. The APIs are distributed with rules defined for the four styles defined in <i>The Complete Fighter\'s Handbook</i>, and DMs and game authors can add their own as desired. See the <b>Styles Database Help</b> handout for more information.</p>
 +
 
 +
<p style="font-size: 150%">Armour Class management</p>
 
<p>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.</p>
 
<p>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.</p>
 
<p>Many magic items have AC qualities, such as Bracers of Defence and Rings of Protection, and if the <b>MagicMaster API</b> 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.</p>
 
<p>Many magic items have AC qualities, such as Bracers of Defence and Rings of Protection, and if the <b>MagicMaster API</b> 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.</p>
==Saves==
+
 
<p>The corollary to attacks is saves.  The system provides a menu to access, review, update and make saving throws and the appropriate modifiers.</p>
+
<p style="font-size: 150%">Saves</p>
<p>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.</p>
+
<p>The corollary to attacks is saves.  The system provides two menus: one to access, review, update and make saving throws and the appropriate modifiers; and the other to make attribute checks, again with the appropriate modifiers.</p>
 +
<p>For each menu, the initial menu presented shows the saving throw and attribute tables 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 or attribute check 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, either automatically (taking into account race, class, level and magic items) or manually.</p>
 
<p>The easiest way to set the correct saving throws for each type of save, based on class, level & race, is to use the <b>CommandMaster API</b> Character Sheet setup commands.</p>
 
<p>The easiest way to set the correct saving throws for each type of save, based on class, level & race, is to use the <b>CommandMaster API</b> Character Sheet setup commands.</p>
 +
|}
 
<br>
 
<br>
  
 
=How To Use AttackMaster=
 
=How To Use AttackMaster=
 
== Installation and Configuration ==
 
== Installation and Configuration ==
Copy the script's code, available from the menu on the right and stored at Roll20's [https://github.com/Roll20/roll20-api-scripts API GitHub Repository]. Paste the code into a new script in your campaign's [[API:Use_Guide#The_Script_Editor|API Script Editor]]. Save the new script and it will be available inside your campaign.  It will install several new 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.
+
The best way to install AttackMaster API is to use the Roll20 [[https://wiki.roll20.net/API:Install_Menu|"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 [https://github.com/Roll20/roll20-api-scripts API GitHub Repository]. Paste the code into a new script in your campaign's [[API:Use_Guide#The_Script_Editor|API Script Editor]]. Save the new script and it will be available inside your campaign.  It will install several new Character Sheets & Handouts: The handout <i>AttackMaster Help</i> provides a full manual of how to use AttackMaster.  The handout <i>RPGMaster CharSheet Setup</i> provides information on setting up a character sheet for use with AttackMaster.  The handout <i>Weapon & Armour Database Help</i> provides information on the databases that come with the API, and how to add to and change them.
 +
 
 
== Script Use ==
 
== 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.
 
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.
Line 71: Line 95:
  
 
=Command Index=
 
=Command Index=
 +
==Command Index==
 
===Menus===
 
===Menus===
 
<pre>--menu [token_id]
 
<pre>--menu [token_id]
Line 84: Line 109:
 
--mod-weapon [token_id] | weapon | MELEE / RANGED / DMG / AMMO | adjustments
 
--mod-weapon [token_id] | weapon | MELEE / RANGED / DMG / AMMO | adjustments
 
--quiet-modweap [token_id] | weapon | MELEE / RANGED / DMG / AMMO | adjustments
 
--quiet-modweap [token_id] | weapon | MELEE / RANGED / DMG / AMMO | adjustments
--edit-weapons [token_id]</pre>
+
--edit-weapons [token_id]
 +
--blank-weapon [token_id] | weapon | [ SILENT ]</pre>
 
===Ammunition Management===
 
===Ammunition Management===
 
<pre>--ammo [token_id]
 
<pre>--ammo [token_id]
Line 91: Line 117:
 
<pre>--edit-armour [token_id]
 
<pre>--edit-armour [token_id]
 
--checkac [token_id] | [ SILENT ] | [SADJ / PADJ / BADJ]
 
--checkac [token_id] | [ SILENT ] | [SADJ / PADJ / BADJ]
--save [token_id] | [situation-mod]</pre>
+
--save [token_id] | [situation-mod]
 +
--attr-check [token_id] | [situation-mod] | [message] | [DCval]</pre>
 
===Other Commands===
 
===Other Commands===
 
<pre>--help
 
<pre>--help
 +
--config [PROF/ALL-WEAPS/WEAP-CLASS/ALL-ARMOUR/MASTER-RANGE/SPECIALIST-RULES/SPELL-NUM] | [TRUE/FALSE]
 
--check-db [ db-name ]
 
--check-db [ db-name ]
 +
--extract-db db-name
 
--handshake from | [cmd]
 
--handshake from | [cmd]
 
--hsq from | [cmd]
 
--hsq from | [cmd]
Line 100: Line 129:
 
--debug [ ON / OFF ]</pre>
 
--debug [ ON / OFF ]</pre>
 
<br>
 
<br>
=Command Details=
+
 
 +
==Command details==
 
==Menus==
 
==Menus==
 
===Display a menu to do actions relating to attacks===
 
===Display a menu to do actions relating to attacks===
 
<pre>--menu [token_id]</pre>
 
<pre>--menu [token_id]</pre>
<p>Takes an optional token ID if not specified uses selected token</p>
+
<p>Takes an optional token ID - if not specified uses selected token</p>
<p>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.</p>
+
<p>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.</p>
 
===Display a menu of other actions===
 
===Display a menu of other actions===
 
<pre>--other-menu [token_id]</pre>
 
<pre>--other-menu [token_id]</pre>
<p>Takes an optional token ID if not specified uses selected token</p>
+
<p>Takes an optional token ID - if not specified uses selected token</p>
<p>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 <b>MagicMaster API</b> 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.</p>
+
<p>Displays a Chat menu with buttons for: saving throws and saving throw management; managing character classes and levels (if the <b>CommandMaster API</b> is loaded) and managing light sources for the character's token (if Dynamic Lighting is being used) (requires <b>MagicMaster API</b> 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.</p>
 +
 
 
==Attacking Commands==
 
==Attacking Commands==
 
===Attack an opponent with a weapon===
 
===Attack an opponent with a weapon===
 
<pre>--attk-hit [token_id] | [message] | [monster weap1] | [monster weap2] | [monster weap3]
 
<pre>--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-roll [token_id] | [message] | [monster weap1] | [monster weap2] | [monster weap3]
 
--attk-target [token_id] | [message] | [monster weap1] | [monster weap2] | [monster weap3]</pre>
 
--attk-target [token_id] | [message] | [monster weap1] | [monster weap2] | [monster weap3]</pre>
 
<p>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.</p>
 
<p>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.</p>
 
<p>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:</p>
 
<p>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:</p>
 +
<dl><dt>--attk-hit<dd>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.
 +
<dt>--attk-menu-hit<dd>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.
 +
<dt>--attk-roll<dd>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.
 +
<dt>--attk-target<dd>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 <b>--config</b> command.</dl>
 +
<p>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.</p>
 +
<p>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:</p>
 
<table>
 
<table>
<tr><th scope="row">--attk-hit</th><td>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.</td></tr>
+
<tr><th scope="row">Character</th><td>?</td><td>[</td><td>]</td><td>@</td><td>-</td><td>|</td><td>:</td><td>&</td><td>{</td><td>}</td></tr>
<tr><th scope="row">--attk-roll</th><td>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.</td></tr>
+
<tr><th scope="row">Substitute</th><td>^</td><td>&lt;&lt;</td><td>&gt;&gt;</td><td>`</td><td>~</td><td>&amp;#124;</td><td> </td><td>&amp;amp;</td><td>&amp;#123;</td><td>&amp;#125;</td></tr>
<tr><th scope="row">--attk-target</th><td>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.</td></tr>
+
<tr><th scope="row">Alternative</th><td>\\ques;</td><td>\\lbrak;</td><td>\\rbrak;</td><td>\\at;</td><td>\\dash;</td><td>\\vbar;</td><td>\\clon;</td><td>\\amp;</td><td>\\lbrc;</td><td>\\rbrc;</td></tr>
<p>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:</p>
+
</table>
{| class="wikitable"
+
|+
+
|-
+
! scope="row" | Character
+
|| Parameter separator || ? || [ || ] || &lt; || &gt; || @ || - || &#124; || : || & || { || }
+
|-
+
! scope="row" | Substitute
+
|| %% || ^ || &lt;&lt; || &gt;&gt; || || || ` || ~ || ¦ ||  || &amp;amp; || &amp;#123; || &amp;#125;
+
|-
+
! scope="row" | Alternative<br>(no ; )
+
|| \vbar || \ques || \lbrak || \rbrak || \lt || \gt || \at || \dash || \vbar || \clon || \amp || \lbrc || \rbrc
+
|}
+
 
<br>
 
<br>
 
===Use two weapons to attack===
 
===Use two weapons to attack===
 
<pre>--twoswords [token_id]|[prime-weapon]</pre>
 
<pre>--twoswords [token_id]|[prime-weapon]</pre>
 
<p>Takes an optional token ID (if not specified uses selected token) and an optional weapon name.</p>
 
<p>Takes an optional token ID (if not specified uses selected token) and an optional weapon name.</p>
<p>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 <i>prime-weapon</i> 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 <b>InitiativeMaster API</b>).  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.</p>
+
<p>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 <i>prime-weapon</i> 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 <b>InitiativeMaster API</b>).  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.</p>
 
<p>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.</p>
 
<p>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.</p>
 
<br>
 
<br>
 +
 
==Weapon Management==
 
==Weapon Management==
 
===Change weapons currently in hand===
 
===Change weapons currently in hand===
 
<pre>--weapon [token_id]</pre>
 
<pre>--weapon [token_id]</pre>
<p>Takes an optional token ID if not specified uses selected token.</p>
+
<p>Takes an optional token ID - if not specified uses selected token.</p>
<p>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”.</p>
+
<p>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".</p>
<p>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.</p>
+
<p>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.</p>
 +
<p>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.</p>
 +
<p>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.</p>
 
<p>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.</p>
 
<p>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.</p>
<p><b>Note:</b> this function is dependent on the weapon and shield definitions including certain key information in a specified format: see section 8 below.</p>
+
<p><b>Note:</b> 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.</p>
 
===Manage a dancing weapon===
 
===Manage a dancing weapon===
 
<pre>--dance [token_id] | weapon  | [ STOP ]</pre>
 
<pre>--dance [token_id] | weapon  | [ STOP ]</pre>
 
<p>Takes an optional token ID (if not specified uses selected token), a mandatory weapon name, and an optional STOP command.</p>
 
<p>Takes an optional token ID (if not specified uses selected token), a mandatory weapon name, and an optional STOP command.</p>
<p>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.</p>
+
<p>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.</p>
<p>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.</p>
+
<p>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.</p>
 
<p><b>Note:</b> 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.</p>
 
<p><b>Note:</b> 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.</p>
 
===Manage weapon statistics===
 
===Manage weapon statistics===
Line 159: Line 188:
 
--quiet-modweap [token_id] | weapon | MELEE / RANGED / DMG / AMMO | adjustments</pre>
 
--quiet-modweap [token_id] | weapon | MELEE / RANGED / DMG / AMMO | adjustments</pre>
 
<p>Each command takes an optional token ID (if not specified uses selected token), a mandatory weapon name, and a mandatory data type.</p>
 
<p>Each command takes an optional token ID (if not specified uses selected token), a mandatory weapon name, and a mandatory data type.</p>
<p>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.</p>
+
<p>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.</p>
<p>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 <i><pre>field_id:[=][+/-]value</pre></i> where the field_ids are:</p>
+
<p>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 <i><pre>field_id:[=][+/-]value</pre></i> where the field_ids are:</p>
 
<table><tr><td>w:</td><td>weapon name</td><td>t:</td><td>weapon type</td><td>st:</td><td>weapon super-type</td></tr>
 
<table><tr><td>w:</td><td>weapon name</td><td>t:</td><td>weapon type</td><td>st:</td><td>weapon super-type</td></tr>
 
<tr><td>sb:</td><td>strength bonus</td><td>db:</td><td>dexterity bonus</td><td>+:</td><td>magical plus</td></tr>
 
<tr><td>sb:</td><td>strength bonus</td><td>db:</td><td>dexterity bonus</td><td>+:</td><td>magical plus</td></tr>
Line 173: Line 202:
 
===Adding & removing weapons and ammunition===
 
===Adding & removing weapons and ammunition===
 
<pre>--edit-weapons [token_id]</pre>
 
<pre>--edit-weapons [token_id]</pre>
<p>Takes an optional token ID if not specified uses selected token.</p>
+
<p>Takes an optional token ID - if not specified uses selected token.</p>
<p>The very best way for the Character, NPC or creature to acquire weapons (or any other items including magic items) is to use the <b>MagicMaster API</b> 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 <b>--weapon</b> command) and then used to attack.</p>
+
<p>The very best way for the Character, NPC or creature to acquire weapons (or any other items including magic items) is to use the <b>MagicMaster API</b> 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 <b>--weapon</b> command) and then used to attack.</p>
 
<p>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.</p>
 
<p>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.</p>
 
<p>This command and <b>--edit-armour</b> are identical, and call the same menu.</p>
 
<p>This command and <b>--edit-armour</b> are identical, and call the same menu.</p>
 +
===Blanking a weapon from attack tables===
 +
<pre>--blank-weapon [token_id] | weapon | [ SILENT ]</pre>
 +
<p>Takes an optional token ID (if not specified uses selected token), the mandatory name of a weapon, and an optional "SILENT" command.</p>
 +
<p>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.</p>
 
<br>
 
<br>
 +
 
==Ammunition Management==
 
==Ammunition Management==
 
===Ammunition recovery===
 
===Ammunition recovery===
 
<pre>--ammo [token_id]</pre>
 
<pre>--ammo [token_id]</pre>
<p>Takes an optional token ID if not specified uses selected token.</p>
+
<p>Takes an optional token ID - if not specified uses selected token.</p>
 
<p>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.</p>
 
<p>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.</p>
 
<p><b>Note:</b> enter the amount recovered <em>not</em> 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.</p>
 
<p><b>Note:</b> enter the amount recovered <em>not</em> 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.</p>
 
<p><b>Note:</b> after a Long Rest (see <b>MagicMaster API</b>) 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.</p>
 
<p><b>Note:</b> after a Long Rest (see <b>MagicMaster API</b>) 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.</p>
<p><b>Note:</b> ammunition that has the item-type of <i>‘charged’</i> 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.</p>
+
<p><b>Note:</b> ammunition that has the item-type of <i>'charged'</i> 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.</p>
 
===Ammunition quantity amendment===
 
===Ammunition quantity amendment===
 
<pre>--setammo [token_id] | ammo_name | [ [+/-]cur_qty / = ] | [ [+/-]max_qty / = ] | [ SILENT ]</pre>
 
<pre>--setammo [token_id] | ammo_name | [ [+/-]cur_qty / = ] | [ [+/-]max_qty / = ] | [ SILENT ]</pre>
<p>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).</p>
+
<p>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).</p>
 
<p>This command allows programmatic or macro alteration of the quantity of a type of ammo:</p>
 
<p>This command allows programmatic or macro alteration of the quantity of a type of ammo:</p>
<ul><li>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.</li>
+
<ul><li>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.</li>
 
<li>Either parameter can be preceded by a + or -, in which case the parameter will modify the corresponding current value, rather than replacing it.</li>
 
<li>Either parameter can be preceded by a + or -, in which case the parameter will modify the corresponding current value, rather than replacing it.</li>
 
<li>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.</li>
 
<li>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.</li>
 
<li>No value can go below 0, and the current quantity will be constrained at or below the maximum quantity.</li></ul>
 
<li>No value can go below 0, and the current quantity will be constrained at or below the maximum quantity.</li></ul>
 
<p>So, for example, this command will set the maximum quantity to 10 and set the current quantity to be equal to it:</p>
 
<p>So, for example, this command will set the maximum quantity to 10 and set the current quantity to be equal to it:</p>
<pre>!attk –setammo @{selected|token_id}|Flight-Arrow+1|=|10|silent</pre>
+
<pre>!attk -setammo @{selected|token_id}|Flight-Arrow+1|=|10|silent</pre>
<p>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.</p>
+
<p>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.</p>
<p><b>Note:</b> if more than one ammo item of the same name is listed in the backpack table (see section 7 on Character Sheet Setup), 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.</p>
+
<p><b>Note:</b> if more than one ammo item of the same name is listed in the items table (see [RPGMaster CharSheet Setup] handout), 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.</p>
 
<br>
 
<br>
 +
 
==Armour Class and Saving Throws==
 
==Armour Class and Saving Throws==
 
===Edit Armour===
 
===Edit Armour===
 
<pre>--edit-armour [token_id]
 
<pre>--edit-armour [token_id]
 
--edit-armor [token_id]</pre>
 
--edit-armor [token_id]</pre>
<p>Takes an optional token ID if not specified uses selected token.</p>
+
<p>Takes an optional token ID - if not specified uses selected token.</p>
<p>The very best way for the Character, NPC or creature to acquire armour (or any other items including magic items) is to use the <b>MagicMaster API</b> 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 <b>--weapon</b> command), and improve the Armour Class of the Character appropriately.</p>
+
<p>The very best way for the Character, NPC or creature to acquire armour (or any other items including magic items) is to use the <b>MagicMaster API</b> 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 <b>--weapon</b> command), and improve the Armour Class of the Character appropriately.</p>
<p>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 (see section 5.2 below).</p>
+
<p>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 (e.g. see section 5.2 below).</p>
 
<p>This command is identical to the <b>--edit-weapons</b> command and uses the same menu.</p>
 
<p>This command is identical to the <b>--edit-weapons</b> command and uses the same menu.</p>
 
===Review Armour Class===
 
===Review Armour Class===
 
<pre>--checkac [token_id] | [ SILENT ] | [SADJ / PADJ / BADJ]</pre>
 
<pre>--checkac [token_id] | [ SILENT ] | [SADJ / PADJ / BADJ]</pre>
<p>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).</p>
+
<p>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).</p>
<p>This command analyses the items in the Character’s backpack table (see section 7 on Character Sheet Setup) 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.</p>
+
<p>This command analyses the items in the Character's items table (see [RPGMaster CharSheet Setup] handout) 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.</p>
 
<p>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.</p>
 
<p>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.</p>
 
<p>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 <b>--weapon</b> 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.</p>
 
<p>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 <b>--weapon</b> 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.</p>
<p>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.</p>
+
<p>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.</p>
 
<p><b>Note:</b> 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.</p>
 
<p><b>Note:</b> 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.</p>
<p><b>Note:</b> 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 <b>–check-ac</b> command run, the token AC bar will again be hidden.</p>
+
<p><b>Note:</b> 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 <b>-check-ac</b> command run, the token AC bar will again be hidden.</p>
 
===Saving Throws===
 
===Saving Throws===
 
<pre>--save [token_id] | [ situation-mod ]
 
<pre>--save [token_id] | [ situation-mod ]
 
--save [token_id] | [ situation-mod ] | save-type | saving-throw</pre>
 
--save [token_id] | [ situation-mod ] | save-type | saving-throw</pre>
<p>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.</p>
+
<p>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.</p>
 
<p>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.</p>
 
<p>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.</p>
<p>The first form shows all the possible saves that can be made, the saving through that needs to be achieved to make the save, and any modifiers that apply to this particular character.  There are buttons to 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.</p>
+
<p>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 modify the saving throw table and the modifiers, to apply a "situational modifier" to immediate saving throws (the "situational modifier" only applies to current rolls and is not remembered), and/or to check the current saving throw table automatically (taking into account race, class, level, and magic items on their person).  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.</p>
 
<p>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.</p>
 
<p>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.</p>
<p>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.</p>
+
<p>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.</p>
 +
===Attribute Checks===
 +
<pre>--attr-check [token_id] | [situation-mod] | [message] | [DCval]</pre>
 +
<p>Takes an optional token ID (defaults to the selected token), an optional situational modifier, an optional message to display as the last action, and an optional "DC value".</p>
 +
<p>This command presents a menu which can be used to perform attribute checks for the character. The menu displays the character's attribute values and the currently applicable modifiers for attribute checks. Each line has a button which will run the Attribute Check roll and display success or failure. As for the Saving Throw table, buttons also exist to set a situational modifier and to check the modifiers against current magic items in use and magic in effect.</p>
 +
<p>A DC value parameter is provided to emulate attribute check modifiers for D&D 3e and later, though as these checks and modifiers work very differently this is not a direct equivalence. If a DC value is set as a parameter, 10 minus the DC value is added to all the modifiers.</p>
 
<br>
 
<br>
 +
 
==Other commands==
 
==Other commands==
 
===Display help on these commands===
 
===Display help on these commands===
Line 233: Line 274:
 
<p>Takes two optional arguments, the first a switchable flag name, and the second TRUE or FALSE.</p>
 
<p>Takes two optional arguments, the first a switchable flag name, and the second TRUE or FALSE.</p>
 
<p>Allows configuration of several API behaviors.  If no arguments given, displays menu for DM to select configuration.  Parameters have the following effects:</p>
 
<p>Allows configuration of several API behaviors.  If no arguments given, displays menu for DM to select configuration.  Parameters have the following effects:</p>
{| class="wikitable"
+
<table>
|+
+
<tr><th>Flag</th><th>True</th><th>False</th></tr>
|-
+
  <tr><th scope="row">FANCY-MENUS</th><td>Chat templates will use textured backgrounds</td><td>Chat templates will use plain backgrounds</td></tr>
! Flag !! True !! False
+
<tr><th scope="row">PROF</th><td>Strictly apply non-proficient weapon penalties as per PHB</td><td>Use the non-proficient weapon penalty displayed on the Character Sheet</td></tr>
|-
+
<tr><th scope="row">ALL-WEAPS</th><td>Allow any character of any class to use and become proficient in any weapon.</td><td>Restrict the use of weapons by class to some degree set by WEAP-CLASS</td></tr>
! scope="row" | PROF
+
<tr><th scope="row">WEAP-CLASS</th><td>Weapons not allowed to a class get a penalty of -100</td><td>Weapons not allowed to a class get double non-proficient penalty</td></tr>
|| Strictly apply non-proficient weapon penalties as per PHB || Use the non-proficient weapon penalty displayed on the Character Sheet
+
<tr><th scope="row">ALL-ARMOUR</th><td>All armour types allowed for all classes</td><td>Armour not allowed to a class not included in AC calculations</td></tr>
|-
+
<tr><th scope="row">MASTER-RANGE</th><td>Ranged weapon Mastery gives double damage at Point Blank range</td><td>Ranged weapon Mastery not allowed, as per PHB</td></tr>
! scope="row" | ALL-WEAPS
+
<tr><th scope="row">SPECIALIST-RULES</th><td>Only Specialist Wizards specified in the PHB get an extra spell per spell level</td><td>Any non-Standard Wizard gets an extra spell per spell level</td></tr>
|| 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
+
<tr><th scope="row">SPELL-NUM</th><td>Spellcaster spells per level restricted to PHB rules</td><td>Spellcaster spells per level alterable using Misc Spells button</td></tr>
|-
+
<tr><th scope="row">ALL-SPELLS</th><td>Spellcaster spell schools are unrestricted</td><td>Spellcaster spell schools are restricted by class rules</td></tr>
! scope="row" | WEAP-CLASS
+
</table>
|| Weapons not allowed to a class get a penalty of -100 || Weapons not allowed to a class get double non-proficient penalty
+
|-
+
! scope="row" | ALL-ARMOUR
+
|| All armour types allowed for all classes || Armour not allowed to a class not included in AC calculations
+
|-
+
! scope="row" | MASTER-RANGE
+
|| Ranged weapon Mastery gives double damage at Point Blank range || Ranged weapon Mastery not allowed, as per PHB
+
|-
+
! scope="row" | 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
+
|-
+
! scope="row" | SPELL-NUM
+
|| Spellcaster spells per level restricted to PHB rules || Spellcaster spells per level alterable using Misc Spells button
+
|}
+
 
===Check database completeness & integrity===
 
===Check database completeness & integrity===
 
<pre>--check-db [ db-name ]</pre>
 
<pre>--check-db [ db-name ]</pre>
<p>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.</p>
+
<p>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.</p>
<p>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.</p>
+
<p>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.</p>
<p>This command is very useful to run after creating/adding new items as ability macros to the databases (see section 8 below).  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).</p>
+
<p>This command is very useful to run after creating/adding new items as ability macros to the databases (see Database-specific handouts).  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).</p>
 +
===Extract database for Editing===
 +
<pre>--extract-db [db-name]</pre>
 +
<p>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.</p>
 +
<p>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. <b>However:</b> 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.</p>
 +
<p><b>Important:</b> Once a Character Sheet database is changed or deleted, run the <b>--check-db</b> command against any database (especially a changed one) to prompt the APIs to re-index the objects in all databases.</p>
 
===Handshake with other APIs===
 
===Handshake with other APIs===
<pre>–hsq from|[command]
+
<pre>-hsq from|[command]
–handshake from|[command]</pre>
+
-handshake from|[command]</pre>
<p>Either form performs a handshake with another API, whose call (without the !) is specified as <i>from</i> in the command parameters (the response is always an <b>–hsr</b> command).  The command calls the <i>from</i> API command responding with its own command to confirm that RoundMaster is loaded and running: e.g. </p>
+
<p>Either form performs a handshake with another API, whose call (without the '!') is specified as <i>from</i> in the command parameters (the response is always an <b>-hsr</b> command).  The command calls the <i>from</i> API command responding with its own command to confirm that RoundMaster is loaded and running: e.g. </p>
'''Received:''' <code>!attk –hsq init</code><br>
+
<dl><dt>Received:<dd><i>!attk -hsq init</i>
'''Response:''' <code>!init –hsr attk</code>
+
<dt>Response:<dd><i>!init -hsr attk</i></dl>
<p>Optionally, a command query can be made to see if the command is supported by RoundMaster if the <i>command</i> string parameter is added, where <i>command</i> is the RoundMaster command (the --text without the --).  This will respond with a <i>true/false</i> response: e.g.</p>
+
<p>Optionally, a command query can be made to see if the command is supported by RoundMaster if the <i>command</i> string parameter is added, where <i>command</i> is the RoundMaster command (the '--' text without the '--').  This will respond with a <i>true/false</i> response: e.g.</p>
'''Received:''' <code>!attk –handshake init|menu</code><br>
+
<dl><dt>Received:<dd><i>!attk -handshake init|menu</i>
'''Response:''' <code>!init –hsr attk|menu|true</code>
+
<dt>Response:<dd><i>!init -hsr attk|menu|true</i></dl>
 
===Switch on or off Debug mode===
 
===Switch on or off Debug mode===
 
<pre>--debug (ON/OFF)</pre>
 
<pre>--debug (ON/OFF)</pre>
 
<p>Takes one mandatory argument which should be ON or OFF.</p>
 
<p>Takes one mandatory argument which should be ON or OFF.</p>
<p>The command turns on a verbose diagnostic mode for the API which will trace what commands are being processed, including internal commands, what attributes are being set and changed, and more detail about any errors that are occurring.  The command can be used by the DM or any Player so the DM or a technical advisor can play as a Player and see the debugging messages.</p>
+
<p>The command turns on a verbose diagnostic mode for the API which will trace what commands are being processed, including internal commands, what attributes are being set and changed, and more detail about any errors that are occurring.  The command can be used by the DM or any Player - so the DM or a technical advisor can play as a Player and see the debugging messages.</p>
 
<br>
 
<br>
 +
 
=Configuring the Token and Character Sheet for use with the API=
 
=Configuring the Token and Character Sheet for use with the API=
==Token configuration==
+
<p>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 [[Script:CommandMaster#Setup_Tokens_.26_Character_Sheets|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 [[API:RPGMaster-CharacterSheets|RPGMaster Character Sheet and Token setup Handout and Wiki page]].</p>
The API can work with any Token configuration but requires tokens that are going to participate in attacks to represent a Character Sheet, so that actions relevant to the token can be selected.<br>
+
<p>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 [[API:RPGMaster#Related_Pages|database help handouts and wiki pages]] provide information on how to do thisA 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.</p>
A single Character Sheet can have multiple Tokens representing it, and each of these are able to do individual attacks using the 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.<br>
+
The recommended Token Bar assignments for all APIs in the Master Series are:<br>
+
{| class="wikitable"
+
|+
+
|-
+
! scope="row"| Bar1 (Green Circle):
+
|| Armour Class (AC field) – only current value
+
|-
+
! scope="row"| Bar2 (Blue Circle):
+
|| Base Thac0 (thac0-base field) before adjustments – only current value
+
|-
+
! scope="row"| Bar3 (Red Circle):
+
|| Hit Points (HP field) – current & max
+
|}
+
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 tokensAll tokens must be set the same way, whatever way you eventually choose.<br>
+
These assignments can be changed in the APIs that use them, by changing the ''fields'' object near the top of the API script.<br>
+
  
==Use with various game system character sheets==
 
The API issued is initially set up to work with the AD&D 2E character sheet (as this is what the author mostly plays).  However, it can be set up for any character sheet.  In each API script, right at the top, is an object definition called ''fields'': see the next section for details.  This can be altered to get the API to work with other character sheets.<br>
 
The AttackMaster API, as with all the other RPGMaster series APIs, use Roll20 Roll Templates extensively.  This is sometimes the only way to get Roll20 to roll 3D animated dice (using a Character Sheet ability macro triggered by a Player), as 3D animated dice do not work when commanded by an API via a sendchat() call, due to a reported bug. Of course, there is a default Roll Template provided by the Roll20 system, but it is a bit clunky and Roll Templates provided by Character Sheet coders are often better.  AttackMaster and other RPGMaster APIs use these Character Sheet-defined Roll Templates, by default from the AD&D 2e Character Sheet.  As with every other field, the Roll Templates used can be altered in the ''fields'' object.<br>
 
The coding of the API is designed to use the AD&D 2E system of attack systems and calculations.  If you use another system, future developments might support additional approaches.  Contact the author for information and to pass on ideas (see the link in the sidebar at the top).<br>
 
 
==Matching the API to a type of Character Sheet==
 
The API has an object definition called ''fields'', which contains items of the form<br>
 
''Internal_api_name: [sheet_field_name, field_attribute, optional_default_value, optional_set_with_worker_flag]''<br>
 
A typical example might be:<br>
 
<pre> Fighter_level:['level-class1','current'],
 
Or
 
MUSpellNo_memable:['spell-level-castable','current','',true],</pre>
 
In order to change the field that the API uses on the character sheet for a different one, you can change the ''sheet_field_name'' and/or ''field_attribute'' for the one you want to use.  <u>'''However, the ''Internal_api_name'' and the other values should not be changed'''</u> as otherwise the system will not work.<br>
 
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 1st row, with the 2nd row starting at repeating row number 0.<br>
 
''Internal_api_table: [sheet_repeating_table_name,starting_index]''<br>
 
An example is:<br>
 
<pre>MW_table:['repeating_weapons',0],</pre>
 
<u>'''The ''Internal_api_table'' must not be altered!'''</u> 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.<br>
 
Each character sheet must have repeating tables to hold weapons, ammo, spells and magic items.  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, spells in the repeating_spells table and magic items are held in the repeating_potions table.  Other repeating tables are also used, some of which are intended to be hidden and not visible in the Character Sheet.  The table management system provided by the API creates, 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.<br>
 
 
==Character Attributes, Races, Classes and Levels==
 
Character Attributes of Strength, Dexterity, Constitution, Intelligence, Wisdom and Charisma are not directly important to the AttackMaster API, 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 section above).<br>
 
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.<br>
 
The system supports single-class and multi-class characters.  Classes must be entered in the appropriate fields on the Character Sheet.  Classes and levels affect spell casting ability, weapon multiple attack numbers per round, 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 armour, shields, some magic items and saves.<br>
 
'''Note:''' on the Advanced D&D 2e Character Sheet, Fighter classes '''must''' be in the ''first'' class column, Wizard classes in the ''second'' column, Priest classes in the ''third'', Rogues in the ''fourth'', and Psions (or any others) in the ''fifth''.  It is important that these locations are adhered to.<br>
 
'''Note:''' classes of Fighter and Rogue (such as Paladins, Rangers and Bards) that can use clerical &/or wizard spells will automatically be allowed to cast spells once they reach the appropriate level by AD&D 2e rules, but not before.  They '''do not''' also need an entry under a spellcaster column.<br>
 
The following Classes are currently supported, and the class name must be entered into the class field.  If missing, the top row is assumed in each case:<br>
 
{| class="wikitable"
 
|+
 
|-
 
! Fighter classes !! Wizard Classes !! Priest Classes !! Rogue Classes !! Psion Classes
 
|-
 
| Warrior || Wizard || Priest || Rogue || Psion
 
|-
 
| Fighter || Mage || Cleric || Thief ||
 
|-
 
| Ranger || Abjurer || Druid || Bard ||
 
|-
 
| Paladin || Conjurer || Healer || Assassin ||
 
|-
 
| Beastmaster || Diviner || Priest of Life ||  ||
 
|-
 
| Barbarian || Enchanter || Priest of War || ||
 
|-
 
| Defender (Dwarven) || Illusionist || Priest of Light || ||
 
|-
 
| || Invoker || Priest of Knowledge || ||
 
|-
 
| || Necromancer || Shaman || ||
 
|-
 
| || Transmuter || || ||
 
|}
 
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.  If not entered, 0 (zero) is assumed (i.e. a commoner)<br>
 
 
==Spells and Powers==
 
The best (and easiest) way to give a Character or NPC spells and powers is to use the MagicMaster API.  However, for the purposes of just doing initiative and selecting which spell to cast in the 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.<br>
 
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 relevant 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).<br>
 
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 relevant spells  menus.  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.<br>
 
 
==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.  However, it generally is possible to enter item names and quantities directly into the table and use them within the system.  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).  Initial weapon, ammunition and armour databases are provided with the AttackMaster API, and in addition to these Initial magic item, spell and power databases are provided with the MagicMaster API.  Other items can be in the table and used for undertaking initiative actions but will not otherwise be effective.  New databases and database items can be added using the specifications and instructions contained in the AttackMaster and MagicMaster API documentation.<br>
 
 
==Weapons and Ammo==
 
For the AttackMaster API to support weapon attack actions melee weapons, damage, ranged weapons and ammo must be entered directly into the melee weapon, damage, ranged weapon and ammo tables on the Character Sheet.  This is best done using the AttackMaster commands ''--edit-weapons'' (to load from the database) and ''--weapon'' (to take weapons ''in-hand''), which will ensure all the right values are entered in the right fields, including taking into account the impact of weapon proficiencies, specialisation, mastery, character races and class/level.  However, manual entry will generally work to the extent to allow weapon attack actions to be selected.<br>
 
<br>
 
=Character Sheet data fields =
 
As stated in the previous section, the Character Sheet field mapping to the API script can be altered using the definition of the ''fields'' object.  You can find the complete mapping for all APIs in the RPGMaster series, with an explanation of each, in a separate document.<br>
 
<br>
 
 
=Weapon, Ammo & Armour Databases=
 
=Weapon, Ammo & Armour Databases=
==General Database information==
+
<p>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 [[API:RPGMaster-WeaponsArmorDB|Weapon, Ammo & Armour Database Help handout and Wiki page]] for information on these databases.</p>
<p>The RPGMaster APIs use a number of Character Sheets as databases to hold Ability Macros defining weapons, ammo, and items of armour and their specifications.  The API is distributed with many weapon, ammo and armour definitions and it also checks for, creates and updates these Character Sheet databases on start-up.  DMs can add their own weapons, ammo and armour to additional databases, but the databases provided are totally rewritten when new updates are released so the DM must add their own database sheets.  If the <i>provided</i> databases are accidentally deleted, they will be automatically recreated the next time the Campaign is opened. Additional databases should be named as follows:</p>
+
<table><tr><td>Weapons:</td><td>additional databases: ''MI-DB-Weapons-[added name]'' where ''[added name]'' can be replaced with anything you want.</td></tr>
+
<tr><td>Ammo:</td><td>additional databases: ''MI-DB-Ammo-[added name]'' where ''[added name]'' can be replaced with anything you want.</td></tr>
+
<tr><td>Armour:</td><td>additional databases: ''MI-DB-Armour-[added name]'' where ''[added name]'' can be replaced with anything you want.</td></tr></table>
+
<p><b>However:</b> the system will ignore any database with a name that includes a version number of the form “v#.#” where # can be any number or group of numbers e.g. MI-DB v2.13 will be ignored.  This is so that the DM can version control their databases, with only the current one (without a version number) being live.</p>
+
<p>There can be as many additional databases as you want.  Other Master series APIs come with additional databases, some of which overlap - this does not cause a problem as version control and merging unique macros is managed by the APIs.</p>
+
<p><b>Important Note:</b> all Character Sheet databases <b><u><i>must</i></u></b> have their <i>‘ControlledBy’</i> value (found under the [Edit] button at the top right of each sheet) set to <i>‘All Players’</i>.  This must be for all databases, both those provided (set by the API) and any user-defined ones.  Otherwise, Players will not be able to run the macros contained in them.</p>
+
<p>Each database has a similar structure, with:</p>
+
<ul><li>Ability Macros named as the weapon, ammo or armour specified, and used to describe and provide specifications for using the commands with the AttackMaster API;</li>
+
<li>Custom Attributes with the attribute name “ct-ability-macro-name”, one per Ability Macro, which defines the speed and type for each item;</li>
+
<li>An entry in a list on the character sheet in the spell book of the relevant Character Sheet tab (various spell books for different items – see entry below);</li>
+
<li>Optionally, some entries come also with attributes that define Powers and Spells delivered by or stored on the item.</li></ul>
+
<p><b>Note:</b> a DM only needs to program the Ability Macro using the formats shown in the next section, and then run the <b>!attk --check-db</b> or <b>!magic --check-db</b> command, which will correctly parse the ability macro and set the rest of the database entries as needed.</p>
+
<p>Ability Macros can be whatever the DM wants and can be as simple or as complex as desired. Roll Templates are very useful when defining ability macros.  When a Player or an NPC or Monster views the specifications of a weapon, ammunition or piece of armour, the APIs run the relevant Ability Macro from the databases as if it had been run by the Player from the chat window.  All Roll20 functions for macros are available.</p>
+
==Weapon & Ammunition Databases==
+
<p>Weapon databases are all character sheets that have names that start with MI-DB-Weapon (though in fact, weapons can be in any database starting with MI-DB- if desired), and can have anything put at the end, though those with version numbers of the form v#.# as part of the name will be ignored.  Ammunition databases are similar, with the root database MI-DB-Ammo.</p>
+
<p>As previously stated, each weapon definition has 3 parts in the database (see Section 1): an Ability Macro with a name that is unique and matches the weapon, an Attribute with the name of the Ability Macro preceded by “ct-“, and a listing in the database character sheet of the ability macro name separated by ‘|’ along with other weapons. The quickest way to understand these entries is to examine existing entries.  Do go to the root databases and take a look (but be careful not to alter anything unless you know what you’re doing!)</p>
+
<p><b>Note:</b> The DM creating new weapons does not need to worry about anything other than the Ability Macro in the database, as running the <b>AttackMaster</b> or <b>MagicMaster –check-db MI-DB-Weapons</b> command will update all other aspects of the database appropriately for all databases that have a name starting with or including <i>‘MI-DB-Weapons’</i>, as long as the <i>Specs</i> and <i>Data</i> fields are correctly defined. Use the parameter <i>'MI-DB-Ammo'</i> to check and update the ammunition databases.  Running the command <b>–check-db</b> with no parameters will check and update all databases.</p>
+
<p>Ability macros can be added to a database just by using the [+Add] button at the top of the Abilities column in the Attributes and Abilities tab of the Database Character Sheet, and then using the edit “pencil” icon on the new entry to open it for editing.  Ability macros are standard Roll20 functionality and not dependent on the API.  Refer to the Roll20 Help Centre for more information.</p>
+
<p>Here are some examples:</p>
+
===Longsword===
+
<p style="display: inline-block; background-color: lightgrey; border: 1px solid black; padding: 4px; color: black;">/w "@{selected|character_name}" <nowiki>&{template:2Edefault} {{name=Longsword}} {{subtitle=Sword}} {{Speed=[[5]]}} {{Size=Medium}} {{Weapon=1-handed melee long-blade}} </nowiki><span style="color:green">Specs=[Longsword,Melee,1H,Long-blade]</span><nowiki> {{To-hit=+0 + Str bonus}} </nowiki><span style="color:blue">ToHitData=[w:Longsword, sb:1, +:0, n:1, ch:20, cm:1, sz:M, ty:S, r:5, sp:5]</span><nowiki> {{Attacks=1 per round + level & specialisation, Slashing}} {{Damage=+0, vs SM:1d8, L:1d12, + Str bonus}} </nowiki><span style="color:yellow">DmgData=[w:Longsword, sb:1, +:0, SM:1d8, L:1d12]</span><nowiki> {{desc=This is a normal sword. The blade is sharp and keen, but nothing special.}}</nowiki></p>
+
<p>The ability specification for this Longsword uses a Roll20 Roll Template, in this case defined by the Advanced D&D 2e Character Sheet by Peter B (see the documentation for the Character Sheet on Roll20 for specifications of this Roll Template), but any Roll Template you desire can be used.  The entries in the Roll Template itself can be anything you desire, giving as much or as little information as you want.  However, the important elements for the APIs are those highlighted.  Each of these elements are inserted <i>between</i> the elements of the Roll Template, meaning they will not be seen by the player when the macro is run.  Generally spaces, hyphens and underscores in the data elements are ignored, and case is not significant.  Each element is described below:</p>
+
<pre>Specs = [Type, Class, Handedness, Weapon Group]</pre>
+
<p>The Specs section describes what weapon type and proficiency groups this weapon belongs to.  These fields must be in this order.  This format is identical for all database items, whether in these databases or others used by the Master series of APIs.</p>
+
<table><tr><td><b>Type</b></td><td>is the type of the weapon, often the same as the ability macro name without magical plusses.</td></tr>
+
<tr><td><b>Class</b></td><td>is one of Melee, Ranged, or Ammo.</td></tr>
+
<tr><td><b>Handedness</b></td><td>is #H, where # is the number of hands needed to wield the weapon.</td></tr>
+
<tr><td><b>Weapon Group</b></td><td>is the group of related weapons that the weapon belongs to.</td></tr></table>
+
<pre>ToHitData = [w:Longsword, sb:1, +:0, n:1, ch:20, cm:1, sz:M, ty:S, r:5, sp:5]</pre>
+
<p>The ToHitData section specifies the data relating to an attack with the weapon.  These fields can be in any order.</p>
+
<table><tr><td><b>w:</b></td><td>&lt;text&gt; the name to display for attacks with this weapon</td></tr>
+
<tr><td><b>sb:</b></td><td><0/1> strength bonus flag - specifies if the strength bonus is applicable to the To-Hit roll</td></tr>
+
<tr><td><b>+:</b></td><td><[+/-]#> the magical attack bonus/penalty - an integer of any size</td></tr>
+
<tr><td><b>n:</b></td><td><#[/#]> the basic number of attacks per round: the API will modify to account for specialisation and level</td></tr>
+
<tr><td><b>ch:</b></td><td><1-20> the roll for a Critical Hit, shown in the API with a green border to the attack AC achieved</td></tr>
+
<tr><td><b>cm:</b></td><td><1-20> the roll for a Critical Miss, shown in the API with a red border to the attack AC achieved</td></tr>
+
<tr><td><b>sz:</b></td><td><T/S/M/L/H/G> the size of the weapon</td></tr>
+
<tr><td><b>ty:</b></td><td><SPB> the type of damage done by the weapon - Slashing, Piercing and/or Bludgeoning</td></tr>
+
<tr><td><b>sp:</b></td><td><#> the speed of the weapon in segments</td></tr>
+
<tr><td><b>r:</b></td><td><[+/-/=]# [/#/#/#] > the range or range modifier of the weapon.  Ranged weapons use PB / S / M / L</td></tr></table>
+
<p>The number of attacks per round, <b>n:</b>, can be an integer or a fraction such as 3/2 meaning 3 attacks every 2 rounds.  If using the InitMaster API the Tracker will have the correct number of entries for the Character relating to the number of attacks in the current round.</p>
+
<p>The range for the weapon, <b>r:</b>, can be a single integer (representing the range of a melee weapon or simple ranged weapon) or a range modifier, starting with +, -, or =.  The range modifier will amend the range of the ammo for a ranged weapon - ranged weapons vary their range with the ammo used.  The weapon can use that range or modify it.  Ranged weapon range modifiers can be of the form [[+/-]#/][+/-]#/[+/-]#/[+/-]# which will add or subtract a different modifier for each range ([Point Blank] / Short / Medium / Long – Point Blank range is optional)</p>
+
<pre>DmgData = [w:Longsword, sb:1, +:0, SM:1d8, L:1d12]</pre>
+
<p>The DmgData section specifies the data relating to the damage done by the weapon, and relates to melee weapons only (not ranged weapons).  These fields can be in any order.</p>
+
<table><tr><td><b>w:</b></td><td>&lt;text&gt; the name to display for damage calculations for this weapon</td></tr>
+
<tr><td><b>sb:</b></td><td><0/1> strength bonus flag - specifies if the strength bonus is applicable to the Damage roll</td></tr>
+
<tr><td><b>+:</b></td><td><[+/-]#> the magical damage bonus/penalty - an integer of any size</td></tr>
+
<tr><td><b>sm:</b></td><td><dice roll spec> the base dice roll vs. small/medium creatures excluding any magical bonus</td></tr>
+
<tr><td><b>l:</b></td><td><dice roll spec> the base dice roll vs. large/huge creatures excluding any magical bonus</td></tr></table>
+
<br>
+
===Bastardsword+1===
+
<p style="display: inline-block; background-color: lightgrey; border: 1px solid black; padding: 4px; color: black;"><nowiki>/w "@{selected|character_name}" &{template:2Edefault} {{name=Bastard Sword+1}} {{subtitle=Magic Sword}} {{Speed=[[5]]}} {{Size=Medium}} {{Weapon=1 or 2-handed melee long blade}} </nowiki><span style="color:green">Specs=[Bastard-Sword,Melee,1H,Long-blade], [Bastard-Sword,Melee,2H,Long-blade]</span><nowiki> {{To-hit=+1 + Str Bonus}} </nowiki><span style="color:blue">ToHitData=[w:Bastard Sword+1, sb:1, +:1, n:1, ch:20, cm:1, sz:M, ty:S, r:5, sp:6,rc:uncharged],[w:Bastard Sword 2H+1, sb:1, +:1, n:1, ch:20, cm:1, sz:M, ty:S, r:5, sp:8,,rc:uncharged]</span><nowiki> {{Attacks=1 per round + specialisation & level, Slashing}} {{Damage=+1, 1-handed SM:1d8 L:1d12, 2-handed SM:2d4 L:2d8}} </nowiki><span style="color:yellow">DmgData=[w:Bastard Sword+1,sb:1,+:1,SM:1d8,L:1d12],[w:Bastard Sword 2H+1,sb:1,+:1,SM:2d4,L:2d8]</span><nowiki> {{desc=This is a normal magical sword. The blade is sharp and keen, and is a +[[1]] magical weapon at all times.}}</nowiki></p>
+
<p>The Bastardsword can be used either single handed or two handed with different to-hit and damage outcomes.  This can be represented in the macro as shown here, with multiple specification sections.  When using the <b>AttackMaster API !attk --weapon</b> command to take the Bastardsword in hand, choosing 1 hand (either left or right) will use the 1-handed specifications, and choosing to take it in Both Hands will use the 2-handed specifications.</p>
+
<p>All the field definitions are the same as for the Longsword example above, but there are (in this case) two sets of data for each section, the first set for 1-handed, the second set for 2-handed (as defined by the <b>handedness</b> entry in the <b>Specs</b> section data sets.</p>
+
<br>
+
===Longbow===
+
<p style="display: inline-block; background-color: lightgrey; border: 1px solid black; padding: 4px; color: black;"><nowiki>/w "@{selected|character_name}" &{template:2Edefault} {{name=Longbow}} {{subtitle=Bow}} {{Speed=[[8]]}} {{Size=Medium}} {{Weapon=Ranged 2-handed Bow}} </nowiki><span style="color:green">Specs=[Longbow,Ranged,2H,Bow]</span><nowiki> {{To-hit=+0 + Dex Bonus}} </nowiki><span style="color:blue">ToHitData=[w:Longbow,sb:0,db:1,+:0,n:2,ch:20,cm:1,sz:L,ty:P,sp:8]</span><nowiki> {{Attacks=Piercing, 2 per round}} {{desc=This is a normal longbow. The wood is polished, the string taut, but nothing special.}}</nowiki></p>
+
<p>A ranged weapon like a Longbow uses the same data section definitions as melee weapons except for the following additions and differences.</p>
+
<pre>ToHitData=[w:Longbow,sb:0,db:1,+:0,n:2,ch:20,cm:1,sz:L,ty:P,sp:8]</pre>
+
<p>The To-Hit section has an extra option:</p>
+
<table><tr><td><b>db:</b></td><td><0/1> dexterity bonus flag - specifies if the dexterity bonus is applicable to the To-Hit roll.</td></tr>
+
<tr><td><b>r:</b></td><td>the range data is not provided because this weapon does not modify the range of its ammo, but could be provided if required.</td></tr></table>
+
<p>There is no DmgData section, as damage is defined by the ammo.</p>
+
<br>
+
===Flight-Arrow+2 (Ammunition Database)===
+
<p style="display: inline-block; background-color: lightgrey; border: 1px solid black; padding: 4px; color: black;"><nowiki>/w "@{selected|character_name}" &{template:2Edefault} {{name=Flight Arrow+2}} {{subtitle=Magic Weapon}} {{Speed=As per bow}} {{Size=Small}} </nowiki><span style="color:green">Specs=[Flight-Arrow,Ammo,1H,Arrow],[Flight-Arrow,Ammo,1H,Arrow]</span><nowiki> {{</nowiki>Ammo=+2,<br>
+
<b>**Warbow**</b> vs. SM:1d8, L:1d8,<br>
+
<b>**Other Bows**</b> vs. SM:1d6, L:1d6, Piercing<nowiki>}} </nowiki><span style="color:purple">AmmoData=[w:Flight Arrow+2, st:Bow, sb:1, +:2, SM:1d6, L:1d6],[w:Warbow Flight Arrow+2, t:warbow, sb:1, +:2, SM:1d8,L:1d8]</span><nowiki> {{</nowiki>Range=PB:30, others vary by bow<br>
+
<b>**Shortbow:**</b><br>
+
S:50, M:100, L150,<br>
+
<b>**Longbow:**</b><br>
+
S:60, M:120, L:210,<br>
+
<b>**Warbow:**</b><br>
+
S90, M:160, L:250,<br>
+
<b>**Composite Sbow:**</b><br>
+
S:50, M:100, L:180,<br>
+
<b>**Composite Lbow:**</b><br>
+
S:70, M:140, L:210<nowiki>}} </nowiki><span style="color:cyan">RangeData=[t:longbow, +:2, r:3/6/12/21],[t:shortbow, +:2, r:3/5/10/15],[t:warbow, +:2, r:3/9/16/25],[t:compositelongbow, +:2, r:3/7/14/21],[t:compositeshortbow, +:2, r:3/5/10/18]</span><nowiki> {{desc=A magical Flight Arrow of very fine quality}}</nowiki></p>
+
<p>Ammo has a different specification, as the To-Hit data sections are obviously part of the ranged weapon data.  Instead it provides data on which weapons this can be ammo for, and what ranges it has for each.  To determine this, it uses the weapon type and group-type set in the weapon <b>Specs</b> section.</p>
+
<pre>AmmoData=[w:Flight Arrow+2, st:Bow, sb:1, +:2, SM:1d6, L:1d6],[w:Warbow Flight Arrow+2, t:warbow, sb:1, +:2, SM:1d8,L:1d8]</pre>
+
<p>The AmmoData section has mostly the same as the DmgData sections (order of fields is immaterial and spaces, hyphens and underscores ignored in type and supertype names), but repeated data sets relate to the data for different types of weapon, and in addition:</p>
+
<table><tr><td><b>t:</b></td><td><weapon-type> the specific type of ranged weapon this data matches - takes priority over <b>st:</b>.  An example is ''Longbow''</td></tr>
+
<tr><td><b>st:</b></td><td><group-type> the group-type of ranged weapon this data can be used for.  An example is <i>Bow</i>, which means all bows</td></tr></table>
+
<pre>RangeData=[t:longbow, +:2, r:3/6/12/21],[t:shortbow, +:2, r:3/5/10/15],[t:warbow, +:2, r:3/9/16/25], [t:compositelongbow, +:2, r:3/7/14/21],[t:compositeshortbow, +:2, r:3/5/10/18],[st:bow, +:2, r:3/5/10/15]</pre>
+
<p>The RangeData section has one or more data sets relating to weapons that result in different ranges. The range specifications can have 3 or 4 parts: if 4, the first is for Point Blank range which is only relevant for specialists; the remaining 3 are always short, medium & long ranges.</p>
+
===Self-ammoed weapons e.g. Warhammer===
+
<p style="display: inline-block; background-color: lightgrey; border: 1px solid black; padding: 4px; color: black;"><nowiki>/w "@{selected|character_name}" &{template:2Edefault} {{name=Warhammer}} {{subtitle=Hammer/Club}} {{Speed=[[4]]}} {{Size=Medium}} {{Weapon=1-handed melee or thrown club}} </nowiki><span style="color:green">Specs=[Warhammer,Melee,1H,Club],[Warhammer,Ranged,1H,Club]</span><nowiki> {{To-hit=+0 + Str & Dex bonus}} </nowiki><span style="color:blue">ToHitData=[w:Warhammer, sb:1, +:0, n:1, ch:20, cm:1, sz:M, ty:B, r:5, sp:4],[ w:Warhammer, sb:1, db:1,  +:0, n:1, ch:20, cm:1, sz:M, ty:B, sp:4]</span><nowiki> {{Attacks=1 per round + level & specialisation, Bludgeoning}} {{Damage=+0, vs SM:1d4+1, L:1d4, + Str bonus}} </nowiki><span style="color:yellow">DmgData=[ w:Warhammer, sb:1, +:0, SM:1+1d4, L:1d4][]</span><nowiki> {{Ammo=+0, vs SM:1d4+1, L:1d4, + Str bonus}} </nowiki><span style="color:purple">AmmoData=[w:Warhammer,t:Warhammer,st:Throwing-club,sb:1,+:0,SM:1+1d4,L:1d4]</span><nowiki> {{Range=S:10, M:20, L:30}} </nowiki><span style="color:cyan">RangeData=[t:Warhammer,+:0,r:1/2/3]</span><nowiki> {{desc=This is a normal warhammer. The blade is sharp and keen, but nothing special.}}</nowiki></p>
+
<p>A melee weapon that can also be thrown, and is its own ammunition, is termed a “self-ammoed” weapon.  Its definition combines the data elements of both melee weapons, ranged weapons and ammunition.</p>
+
<pre>Specs=[Warhammer,Melee,1H,Club],[Warhammer,Ranged,1H,Club]</pre>
+
<p>Has two data sets, one as a melee weapon and one as a ranged weapon.</p>
+
<pre>ToHitData=[w:Warhammer, sb:1, +:0, n:1, ch:20, cm:1, sz:M, ty:B, r:5, sp:4],[ w:Warhammer, sb:1, db:1,  +:0, n:1, ch:20, cm:1, sz:M, ty:B, sp:4]</pre>
+
<p>Also has two sets of data, each of which relates to the corresponding Specs set.</p>
+
<pre>DmgData=[ w:Warhammer, sb:1, +:0, SM:1+1d4, L:1d4],[]</pre>
+
<p>Does have two data sets, but the one corresponding to the ranged data is empty, as this data is in the Ammo data set.</p>
+
<pre>AmmoData=[w:Warhammer,t:Warhammer,st:Throwing-club,sb:1,+:0,SM:1+1d4,L:1d4]</pre>
+
<p>There is only 1 Ammo data set, as it only relates to the one weapon, itself.</p>
+
<pre>RangeData=[t:Warhammer,+:0,r:1/2/3]</pre>
+
<p>And only 1 Range data set, as it only relates to itself.</p>
+
<br>
+
===Artifact sword===
+
<p style="display: inline-block; background-color: lightgrey; border: 1px solid black; padding: 4px; color: black;"><nowiki>/w "@{selected|character_name}" &{template:2Edefault} {{name=Jim the Sun Blade<br>
+
Intelligent, Neutral}} {{subtitle=Magic Sword}} {{Speed=[[3]]}} </nowiki><span style="color:orange">WeapData=[w:Jim the Sun Blade,ns:5][cl:PW,w:Jims-Locate-Object,sp:100,lv:6,pd:1],[cl:PW,w:Jims-Find-Traps,sp:5,lv:6,pd:2],[cl:PW,w:Jims-Levitation,sp:2,lv:1,pd:3],[cl:PW,w:Jims-Sunlight,sp:3,lv:6,pd:1],[cl:PW,w:Jims-Fear,sp:4,lv:6,pd:2]</span><nowiki> {{Size=Special (feels like a Shortsword)}} {{Weapon=1 or 2 handed melee Long or Short blade}} </nowiki><span style="color:green">Specs=[Bastard-sword|Short-sword,Melee,1H,Long-blade|Short-blade],[Bastard-sword|Short-sword,Melee,1H,Long-blade|Short-blade],[Bastard-sword,Melee,2H,Long-blade],[Bastard-sword,Melee,2H,Long-blade]</span><nowiki> {{To-hit=+2, +4 vs Evil + Str Bonus}} </nowiki><span style="color:blue">ToHitData=[w:Jim +2,sb:1,+:2,n:1,ch:20,cm:1,sz:M,ty:S,r:5,sp:3],[w:Jim vs Evil+4,sb:1,+:4,n:1,ch:20,cm:1,sz:M,ty:S,r:5,sp:3],[w:Jim 2H +2,sb:1,+:2,n:1,ch:20,cm:1,sz:M,ty:S,r:5,sp:3],[w:Jim 2H vs Evil+4,sb:1,+:4,n:1,ch:20,cm:1,sz:M,ty:S,r:5,sp:3]</span><nowiki> {{Attacks=1 per round}} {{Damage=+2, +4 vs Evil, + 1-handed SM:1d8 L:1d12, 2-handed SM:2d4 L:2d8}} </nowiki><span style="color:yellow">DmgData=[w:Jim+2,sb:1,+:2,SM:1d8,L:1d12],[w:Jim vs Evil+4,sb:1,+:4,SM:2d4,L:2d8],[w:Jim 2H +2,sb:1,+:2,SM:1d8,L:1d12],[w:Jim 2H vs Evil+4,sb:1,+:4,SM:2d4,L:2d8]</span><nowiki> {{</nowiki>desc=An intelligent weapon: A Sun Blade called Jim (DMs Guide Page 185). It is Neutral. It needs its owner to be proficient with either a Short or Bastard Sword or promise to get such proficiency as soon as possible. It cannot be used by someone who is not proficient. It requires its owner to be Neutral on at least one of its axis, and may not be Evil. NG LN CN and of cause true N are all ok. Abilities:<br>
+
<b>**1:**</b> It is +2 normally, or +4 against evil creatures, and does Bastard sword damage.<br>
+
<b>**2:**</b> It feels and react as if it is a short sword and uses short sword striking time.<br>
+
<b>**3:**</b> [Locate Object](<span style="color:red">!magic --mi-power @{selected|token_id}|Jims-Locate-Object|Jim-the-Sun-Blade|6</span>) at [[6]]th Level in 120’ radius (1x day).<br>
+
<b>**4:**</b> [Detect traps](<span style="color:red">!magic --mi-power @{selected|token_id}|Jims-Find-Traps|Jim-the-Sun-Blade|6</span>) of large size in 10’ radius (2xday).<br>
+
<b>**5:**</b> [Levitation](<span style="color:red">!magic --mi-power @{selected|token_id}|Jims-Levitation|Jim-the-Sun-Blade|1</span>) 3x a day for 1 turn (cast at 1st Level).<br>
+
<b>**6:**</b> [Sunlight](<span style="color:red">!magic --mi-power @{selected|token_id}|Jims-Sunlight|Jim-the-Sun-Blade|6</span>) Once a day, upon command, the blade can be swung vigorously above the head, and it will shed a bright yellow radiance that is like full daylight. The radiance begins shining in a 10-foot radius around the sword-wielder, spreading outward at 5 feet per round for 10 rounds thereafter, creating a globe of light with a 60-foot radius. When the swinging stops, the radiance fades to a dim glow that persists for another turn before disappearing entirely.<br>
+
<b>**7:**</b> It has a special purpose namely Defeat Evil. <br>
+
<b>**8:**</b> On hitting an Evil being it causes [Fear](<span style="color:red">!magic --mi-power @{selected|token_id}|Jims-Fear|Jim-the-Sun-Blade|6</span>) for 1d4 rounds (unless saving throw is made). It can do this **twice a day** when the wielder desires.<br>
+
<b>**9:**</b> It speaks Common and its name is Jim. It will talk to the party.<br>
+
<b>**10:**</b> It has an ego of 16 and is from Yorkshire. <br>
+
<b>**11:**</b> It will insist on having a Neutral wielder. (See Intelligent weapons on page 187 in DMG).<br>
+
<b>**12:**</b> If picked by a player, it will be keen to become the players main weapon.<br>
+
<b>**13:**</b> If picked up by a player who is not Neutral it will do them 16 points of damage<nowiki>}}</nowiki></p>
+
<p>An artefact such as an intelligent sword with powers introduces data sets that specify the powers that the artefact has and how often they can be used.  These match the API Buttons with calls to the <b>MagicMaster API</b> to enact the powers.</p>
+
<p style="display: inline-block; background-color: lightgrey; border: 1px solid black; padding: 4px; color: dimgrey; font-weight: extra-light;">WeapData=[w:Jim the Sun Blade,ns:5][cl:PW,w:Jims-Locate-Object,sp:100,lv:6,pd:1],[cl:PW,w:Jims-Find-Traps,sp:5,lv:6,pd:2],[cl:PW,w:Jims-Levitation,sp:2,lv:1,pd:3],[cl:PW,w:Jims-Sunlight,sp:3,lv:6,pd:1],[cl:PW,w:Jims-Fear,sp:4,lv:6,pd:2]</p>
+
<p>The WeapData data sets can be used to define the powers that an artefact has (or stored spells - see MagicMaster API for more information on spell storing)</p>
+
<p>1<sup>st</sup> data set:</p>
+
<table><tr><td><b>w:</b></td><td>&lt;text&gt;  The name of the weapon (not currently used)</td></tr>
+
<tr><td><b>ns:</b></td><td><#>  The number of spells or powers for which the specifications follow</td></tr></table>
+
<p>Subsequent data sets:</p>
+
<table><tr><td><b>cl:</b></td><td>< MU / PR / PW >  The type of data: MU=Wizard, PR=Priest, PW=Power</td></tr>
+
<tr><td><b>w:</b></td><td>&lt;text&gt;  Name of the spell or power: must be the same as the corresponding database definition</td></tr>
+
<tr><td><b>sp:</b></td><td><#>  Speed of the spell/power casting in segments (1/10ths of a round)</td></tr>
+
<tr><td><b>lv:</b></td><td><#>  The level at which the artefact will cast the spell/power (if omitted will use character’s level)</td></tr>
+
<tr><td><b>pd:</b></td><td><-1 / #>  Number per day, or -1 for “use at will”  </td></tr></table>
+
<br>
+
==Armour Databases==
+
<p>Armour databases are all character sheets that have names that start with MI-DB-Armour (as with weapons, this can be in any database starting with MI-DB- if desired), and can have anything put at the end, though those with version numbers of the form v#.# as part of the name will be ignored.</p>
+
<p>As previously stated and as per the weapon and ammunition databases, each armour definition has 3 parts in the database (see Section 1): the Ability Macro, the ct- attribute, and the listing (and occasionally attributes for powers and spells).  The quickest way to understand these entries is to examine existing entries.  Do go to the root databases and take a look (but be careful not to alter anything unless you know what you’re doing!)</p>
+
<p><b>Note:</b>The DM creating new armour entries does not need to worry about anything other than the Ability Macro in the database, as running the <b>!attk --check-db MI-DB-Armour</b> or <b>!magic --check-db MI-DB-Armour</b> command will update all other aspects of the database appropriately for all databases that have a name starting with or including ‘MI-DB-Armour’, as long as the Specs and Data fields are correctly defined.  Running the command <b>–check-db</b> with no parameters will check and update all databases.</p>
+
<p>Here are some examples:</p>
+
===Chain Mail===
+
<p style="display: inline-block; background-color: lightgrey; border: 1px solid black; padding: 4px; color: black;"><nowiki>/w "@{selected|character_name}" &{template:2Edefault}{{name=Chain Mail}}{{subtitle=Armour}}{{Armour=Chain Mail}} </nowiki><span style="color:green">Specs=[Chain Mail,Armour,0H,Mail]</span><nowiki>{{AC=[[5]] vs all attacks}} </nowiki><span style="color:blue">ACData=[a:Chain Mail,st:Mail,+:0,ac:5,sz:L,wt:40]</span><nowiki>{{Speed=[[0]]}}{{Size=Large}}{{Immunity=None}}{{Saves=No effect}}{{desc=This armor is made of interlocking metal rings. It is always worn with a layer of quilted fabric padding underneath to prevent painful chafing and to cushion the impact of blows. Several layers of mail are normally hung over vital areas. The links yield easily to blows, absorbing some of the shock. Most of the weight of this armor is carried on the shoulders and it is uncomfortable to wear for long periods of time.}}</nowiki></p>
+
<p>The ability specification for this suit of Chain Mail uses a Roll20 Roll Template, in this case defined by the Advanced D&D 2e Character Sheet by Peter B.  The entries in the Roll Template itself can be anything you desire, giving as much or as little information as you want.  However, the important elements for the AttackMaster API are those highlighted.  Each of these elements are inserted between the elements of the Roll Template, meaning they will not be seen by the player when the macro is run.  Generally spaces, hyphens and underscores in the data elements are ignored, and case is not significant.  Each element is described below:</p>
+
<pre>Specs=[Chain Mail,Armour,0H,Mail]</pre>
+
<p>The Specs section of the specification has exactly the same format as for weapons and ammunition (and indeed all database items).  See section 9 for the definition of the fields.</p>
+
<p><b>Note:</b>The armour Type (the 1<sup>st</sup> parameter) and Group-Type (the 4<sup>th</sup> parameter) are used to determine if the character is of a class that can use the armour.  Currently implemented types are listed in Section 9.</p>
+
<p><b>Note:</b> Armour that fits on the body generally does not take any hands to hold, and so the third field, <i>Handedness</i>, is set to “0H”.</p>
+
<pre>ACData=[a:Chain Mail,st:Mail,+:0,ac:5,sz:L,wt:40]</pre>
+
<p>The Armour Class Data (ACData) section holds data specific to the armour.  As with other data sections, fields can be in any order, and spaces, hyphens, underscores and case are ignored.</p>
+
<table><tr><td><b>a:</b></td><td>< text > the name of the armour to be displayed.  Often the same as the Ability.</td></tr>
+
<tr><td><b>st:</b></td><td>< group-type > the supertype of the armour, often the same as the fourth parameter of the Specs section.</td></tr>
+
<tr><td><b>+:</b></td><td><[+/-]#> the magical bonus or penalty of the armour (defaults to 0 if not supplied).</td></tr>
+
<tr><td><b>ac:</b></td><td><[-]#> the base armour class (excluding magical bonuses) for this type of armour.</td></tr>
+
<tr><td><b>sz:</b></td><td><[T/S/M/L/H]> The size of the item (not necessarily indicating its fit).</td></tr>
+
<tr><td><b>wt:</b></td><td><#> The weight of the item in lbs (could be considered kg - or any measure - if everything is the same).</td></tr></table>
+
<p>Other possible fields are:</p>
+
<table><tr><td><b>t:</b></td><td>< armour-type > The specific armour type, often the same as the first parameter of the Specs section.</td></tr>
+
<tr><td><b>db:</b></td><td><[-/+]#> The dexterity bonus or penalty that wearing the armour bestowes.</td></tr>
+
<tr><td><b>+m:</b></td><td><[-/+]#> The adjustment that the armour gives vs. missiles and ammunition of ranged weapons.</td></tr>
+
<tr><td><b>+s:</b></td><td><[-/+]#> The magical adjustment specifically against slashing damage.</td></tr>
+
<tr><td><b>+p:</b></td><td><[-/+]#> The magical adjustment specifically against piercing damage.</td></tr>
+
<tr><td><b>+b:</b></td><td><[-/+]#> The magical adjustment specifically against bludgeoning damage.</td></tr>
+
<tr><td><b>rc:</b></td><td><recharging/curse type> Armour can be “cursed”, but generally does not have charges. Default is “uncharged”.  See MagicMaster API documentation for more information on charges and curses.</td></tr></table>
+
<br>
+
===Shield+2===
+
<p style="display: inline-block; background-color: lightgrey; border: 1px solid black; padding: 4px; color: black;"><nowiki>/w "@{selected|character_name}" &{template:2Edefault}{{name=Shield+2}}{{subtitle=Shield}}{{Shield=1-handed +2 Medium Shield made of wood & metal}}</nowiki><span style="color:green">Specs=[Medium Shield,Shield,1H,Shield]</span><nowiki>{{AC=+[[2]] against all attacks from the front}}</nowiki><span style="color:blue">ACData=[a:Medium Shield+2, st:Shield, +:2,sz:M, wt:10]</span><nowiki> {{Speed=[[0]]}} {{Size=M}} {{Immunity=None}} {{Saves=No effect}} {{</nowiki>desc=All shields improve a character's Armor Class by 1 or more against a specified number of attacks. A shield is useful only to protect the front and flanks of the user. Attacks from the rear or rear flanks cannot be blocked by a shield (exception: a shield slung across the back does help defend against rear attacks). The reference to the size of the shield is relative to the size of the character. Thus, a human's small shield would have all the effects of a medium shield when used by a gnome.<br>
+
*The medium shield* is carried on the forearm and gripped with the hand. Its weight prevents the character from using his shield hand for other purposes. With a medium shield, a character can protect against any frontal or flank attacks.<nowiki>}}</nowiki></p>
+
<p>As can be seen here, the specification for a Shield is almost identical in structure to that of any other armour, the major difference being in the Specs section type field.</p>
+
<p><b>Note:</b> The <b>ac:</b> field in the data section for a shield is always assumed to be “+1”, meaning a shield adds 1 to the base AC before magical adjustments are taken into account.  However, it can be specified as a different value, if desired.</p>
+
<p><b>Note:</b> All shields except a <i>Buckler</i> must be taken in hand using the <b>!attk --weapon</b> command before the Armour Class system of the AttackMaster API adds it to the AC for the character.  A <i>buckler</i> is a special type of very small shield that is strapped to the arm and can counter only 1 blow per melee round, but allows both (all) hands to be free.  In fact, any shield can have this functionality if desired, by setting the handedness field of the Specs section to be “0H”, meaning it take no hands to hold it.</p>
+
<br>
+
===Armour-of-Vulnerability+-3===
+
<p style="display: inline-block; background-color: lightgrey; border: 1px solid black; padding: 4px; color: black;"><nowiki>/w "@{selected|character_name}" &{template:2Edefault}{{name=Field Plate Armour of Vulnerability+/-3}}{{subtitle=Cursed Armour}}{{Armour=+/-3 selectively magical Field Plate}}</nowiki><span style="color:green">Specs=[Armour-of-Vulnerability|Armour-of-Resistance,Armour,0H,Plate]</span><nowiki>{{AC=[[2]][[0-3]] better AC against Slashing damage +[[3]] worse AC against any other type}}</nowiki><span style="color:blue">ACData=[a:Armour-of-Vulnerability+-3,st:Mail,+S:3,+P:-3,+B:-3,ac:2,sz:L,wt:60,sp:0,rc:cursed]</span><nowiki>{{Speed=0}}{{Size=Large}}{{Immunity=None}}{{Saves=No effect}}{{</nowiki>desc=<b><i>Curse.</i></b> This armor is cursed, a fact that is revealed only when an identify spell is cast on the armor or you attune to it. Attuning to the armor curses you until you are targeted by the remove curse spell or similar magic; removing the armor fails to end the curse. While cursed, you have vulnerability to two of the three damage types associated with the armor (not the one to which it grants resistance).}}{{desc1=This armour provides resistance to Slashing damage only, but vulnerability to Piercing and Bludgeoning damage.<br>
+
This armor is a combination of chain or brigandine with metal plates (cuirass, epaulettes, elbow guards, gauntlets, tasets, and greaves) covering vital areas. The weight is distributed over the whole body and the whole thing is held together by buckles and straps. This is the most common form of heavy armor.<br>
+
For each +1 bonus to armor, regardless of the type of armor, the wearer\'s Armor Class moves downward (toward AC 2 . . . to 1 . . . to 0, -1, -2, and so on). Note, however, that Armor Class can never be improved beyond -10<nowiki>}}</nowiki></p>
+
<p>This is a slightly more complex type of armour.  It is a cursed item, and generally appears initially as <i>Armour-of-Resistance+3</i>, hence the <b>Specs</b> first parameter of armour type having two possible values, separated by ‘|’.</p>
+
<p>The use of the damage type specific magical adjustment fields can be seen in the data section, along with the use of the <b>rc:</b> field tag with the value <i>‘cursed’</i>.  See section 9 for a complete list of <b>rc:</b> field values.</p>
+
<br>
+
==Specs & Data field values==
+
<p>Below are lists of the current possible values for the item database Ability macro sections.</p>
+
===Specs sections===
+
<pre>Specs=[Type, Item-Class, Handedness, Group-Type]</pre>
+
====Weapon Types====
+
<p>There is an infinite list of weapon types: generally the type is the weapon name without any reference to magical plusses, so the Type of a Longsword+2 is Longsword.  This Type is used to check for Proficiency.</p>
+
====Weapon Item-Classes====
+
{| class="wikitable"
+
|+
+
|-
+
! scope="row"| Melee
+
|| Melee weapon which strikes while in hand
+
|-
+
! scope="row"| Ranged
+
|| Weapon that causes damage when thrown or with ammunition
+
|-
+
! scope="row"| Ammo
+
|| Ammunition for a ranged weapon of a specific Type or Group-Type
+
|}
+
<br>
+
====Weapon Handedness====
+
{| class="wikitable"
+
|+
+
|-
+
! scope="row"| 0H
+
|| A weapon that does not take a hand (e.g. spike on helm)
+
|-
+
! scope="row"| 1H
+
|| A weapon that is 1-handed, such as a short sword
+
|-
+
! scope="row"| 2H
+
|| A weapon that takes 2 hands to wield, such as a longbow
+
|-
+
! scope="row"| 3H
+
|| A weapon that takes 3 hands…
+
|-
+
! scope="row"| 4H
+
|| Etc (e.g. a siege weapon that needs 2 people to operate it)
+
|-
+
! scope="row"| …
+
|| …
+
|}
+
<br>
+
====Weapon Group-Types====
+
<p>Weapon Group-Types determine related weapons for weapon proficiency, and whether it can be used by a Character of a specific class.  The APIs use the definitions in the AD&D2e Fighter’s Handbook section on ‘Tight Groups’, extended to cover certain additional weapons and weapon types.  Those implemented so far for the Weapon databases are:</p>
+
{| class="wikitable"
+
|+
+
|-
+
| Arrow || Club || Great-Blade || Long-Blade || Short-Blade || Whip
+
|-
+
| Axe || Crossbow || Hook || Medium-Blade || Sling ||
+
|-
+
| Blowgun || Dart || Horeshoes || Pick || Spear ||
+
|-
+
| Bow || Fencing-Blade || Innate || Polearm || Staff ||
+
|-
+
| Bullet || Flail || Lance || Quarrel || Throwing-Blade ||
+
|}
+
<p>Types and Group-Types that can be used by various Character Classes are:</p>
+
{| class="wikitable"
+
|+
+
|-
+
! scope="row"| Warrior
+
|| Any
+
|-
+
! scope="row"| Fighter
+
|| Any
+
|-
+
! scope="row"| Ranger
+
|| Any
+
|-
+
! scope="row"| Paladin
+
|| Any
+
|-
+
! scope="row"| Beastmaster
+
|| Any
+
|-
+
! scope="row"| Barbarian
+
|| Any
+
|-
+
! scope="row"| Defender
+
|| axe, club, flail, long-blade, fencing-blade, medium-blade, short-blade, polearm
+
|-
+
! scope="row"| Wizard (all types)
+
|| dagger, staff, dart, knife, sling
+
|-
+
! scope="row"| Priest / Cleric
+
|| club, mace, hammer, staff
+
|-
+
! scope="row"| Druid
+
|| club, sickle, dart, spear, dagger, scimitar, sling, staff
+
|-
+
! scope="row"| Healer
+
|| club, quarterstaff, mancatcher, sling
+
|-
+
! scope="row"| Priest of Life
+
|| club, quarterstaff, mancatcher, sling
+
|-
+
! scope="row"| Priest of War
+
|| Any
+
|-
+
! scope="row"| Priest of Light
+
|| dart, javelin, spear
+
|-
+
! scope="row"| Priest of Knowledge
+
|| sling, quarterstaff
+
|-
+
! scope="row"| Shaman
+
|| long-blade, medium-blade, short-blade, blowgun, club, staff, shortbow, horsebow, hand-xbow
+
|-
+
! scope="row"| Rogue / Thief
+
|| club, short-blade, dart, hand-xbow, lasso, shortbow, sling, broadsword, longsword, staff
+
|-
+
! scope="row"| Bard
+
|| Any
+
|-
+
! scope="row"| Assassin
+
|| Any
+
|}
+
<br>
+
====Armour Types====
+
<p>There is an infinite list of armour types: generally the type is the armour name without any reference to magical plusses, so the Type of Plate-Mail+2 is Plate-Mail.  This Type is used to check for Proficiency.</p>
+
<br>
+
====Armour Item-Classes====
+
{| class="wikitable"
+
|+
+
|-
+
! scope="row"| Armour
+
|| Any type of armour that does not need to be held to work
+
|-
+
! scope="row"| Shield
+
|| A barrier that is held in hand(s) and defends against one or more attacks from the front
+
|}
+
<br>
+
====Armour Handedness====
+
{| class="wikitable"
+
|+
+
|-
+
! scope="row"| 0H
+
|| Armour and Shields that are not held in the hand (e.g. a Buckler or a Helm)
+
|-
+
! scope="row"| 1H
+
|| Generally a type of Shield that must be held in a hand
+
|-
+
! scope="row"| 2H
+
|| Armour and Shields that use two hands, and/or prevent use of those hands for other things
+
|-
+
! scope="row"| 3H
+
|| Generally siege engines that shield against attacks… (not yet implemented)
+
|-
+
! scope="row"| …
+
|| etc.
+
|}
+
<br>
+
====Armour Group-Types====
+
<p>Armour Types and Group Types determine whether the armour can be used by various Character Classes.  Here are the currently implemented restrictions:</p>
+
{| class="wikitable"
+
|+
+
|-
+
! scope="row"| Warrior
+
|| Any
+
|-
+
! scope="row"| Fighter
+
|| Any
+
|-
+
! scope="row"| Ranger
+
|| Any
+
|-
+
! scope="row"| Paladin
+
|| Any
+
|-
+
! scope="row"| Beastmaster
+
|| Any
+
|-
+
! scope="row"| Barbarian
+
|| padded, leather, hide, brigandine, ring-mail, scale-mail, chain-mail, shield, ring,  magic-item, cloak
+
|-
+
! scope="row"| Defender
+
|| Any
+
|-
+
! scope="row"| Wizard (all types)
+
|| magic-item, ring, cloak
+
|-
+
! scope="row"| Priest / Cleric
+
|| Any
+
|-
+
! scope="row"| Druid
+
|| leather, padded, hide, wooden-shield, magic-item, ring, cloak
+
|-
+
! scope="row"| Healer
+
|| Any
+
|-
+
! scope="row"| Priest of Life
+
|| Any
+
|-
+
! scope="row"| Priest of War
+
|| Any
+
|-
+
! scope="row"| Priest of Light
+
|  studded-leather, ring-mail, chain-mail, shield, ring, magic-item, cloak
+
|-
+
! scope="row"| Priest of Knowledge
+
|| magic-item, ring, cloak
+
|-
+
! scope="row"| Shaman
+
|| padded, leather, hide, brigandine, ring-mail, scale-mail, chain-mail, splint-mail, banded-mail, shield, ring, magic-item, cloak
+
|-
+
! scope="row"| Rogue / Thief
+
|| Any
+
|-
+
! scope="row"| Bard
+
|| padded, leather, hide, brigandine, ring-mail, scale-mail, chain-mail, ring, magic-item, cloak
+
|-
+
! scope="row"| Assassin
+
|| Any
+
|}
+
<br>
+
===Data Sections===
+
<table>
+
<thead>
+
<tr>
+
<th scope="col" rowspan="2">Field</th>
+
<th scope="col" rowspan="2">Format</th>
+
<th scope="col" rowspan="2">Default Value</th>
+
<th scope="col" rowspan="2">Description</th>
+
<th scope="col" colspan="6">Can be used in</th>
+
</tr>
+
<tr>
+
<th scope="col">ToHit<br>Data</th>
+
<th scope="col">Dmg<br>Data</th>
+
<th scope="col">Ammo<br>Data</th>
+
<th scope="col">Range<br>Data</th>
+
<th scope="col">Weapon<br>Data</th>
+
<th scope="col">AC<br>Data</th>
+
</tr>
+
</thead>
+
<tr><td>w:</td><td>< text ></td><td>\'-\'</td><td>Name to be displayed</td> <td>X</td><td>X</td><td>X</td><td> </td><td> </td><td> </td></tr>
+
<tr><td>w:</td><td>< text ></td><td>\'-\'</td><td>Name of spell or power</td> <td> </td><td> </td><td> </td><td> </td><td>X</td><td> </td></tr>
+
<tr><td>a:</td><td>< text ></td><td>\'-\'</td><td>Name to be displayed</td> <td> </td><td> </td><td> </td><td> </td><td> </td><td>X</td></tr>
+
<tr><td>t:</td><td>< text ></td><td>\'\'</td><td>Type</td> <td> </td><td> </td><td>X</td><td>X</td><td> </td><td>X</td></tr>
+
<tr><td>st:</td><td>< text ></td><td>\'\'</td><td>Group Type (aka Tight-Group)</td> <td> </td><td> </td><td>X</td><td>X</td><td> </td><td>X</td></tr>
+
<tr><td>sb:</td><td>0 / 1</td><td>0</td><td>Strength Bonus</td> <td>X</td><td>X</td><td>X</td><td> </td><td> </td><td> </td></tr>
+
<tr><td>db:</td><td>0 / 1</td><td>1</td><td>Dexterity Bonus</td> <td>X</td><td> </td><td> </td><td> </td><td> </td><td>X</td></tr>
+
<tr><td>+:</td><td>[ + / - ] #</td><td>0</td><td>Magical adjustment</td> <td>X</td><td>X</td><td>X</td><td>X</td><td> </td><td>X</td></tr>
+
<tr><td>+m:</td><td>[ + / - ] #</td><td>0</td><td>Missile attack adjustment</td> <td> </td><td> </td><td> </td><td> </td><td> </td><td>X</td></tr>
+
<tr><td>+s:</td><td>[ + / - ] #</td><td>0</td><td>Slashing damage adjustment</td> <td> </td><td> </td><td> </td><td> </td><td> </td><td>X</td></tr>
+
<tr><td>+p:</td><td>[ + / - ] #</td><td>0</td><td>Piercing damage adjustment </td> <td> </td><td> </td><td> </td><td> </td><td> </td><td>X </td></tr>
+
<tr><td>+b:</td><td>[ + / - ] #</td><td>0</td><td>Bludgeoning damage adjustment</td> <td> </td><td> </td><td> </td><td> </td><td> </td><td>X</td></tr>
+
<tr><td>n:</td><td># [ / # ]</td><td>1</td><td>Attacks per round</td> <td>X</td><td> </td><td> </td><td> </td><td> </td><td> </td></tr>
+
<tr><td>dp:</td><td>#</td><td>0</td><td>Dancing proficiency adjustment</td> <td>X</td><td> </td><td> </td><td> </td><td> </td><td> </td></tr>
+
<tr><td>ch:</td><td>1 - 20</td><td>20</td><td>Critical Hit roll value</td> <td>X</td><td> </td><td> </td><td> </td><td> </td><td> </td></tr>
+
<tr><td>cm:</td><td>1 - 20</td><td>1</td><td>Critical Miss roll value</td> <td>X</td><td> </td><td> </td><td> </td><td> </td><td> </td></tr>
+
<tr><td>sz:</td><td>[ t / s / m / l / h ]</td><td>\'\'</td><td>Size of item</td> <td>X</td><td> </td><td>X</td><td> </td><td> </td><td>X</td></tr>
+
<tr><td>r:</td><td>[# /] # / # / #</td><td>\'\'</td><td>Range</td> <td>X</td><td> </td><td> </td><td>X</td><td> </td><td> </td></tr>
+
<tr><td>r:</td><td>[+/-]# [ / [+/-]# / [+/-]# / [+/-]# ]</td><td>0</td><td>Range Modifier</td><td>X</td><td> </td><td> </td><td> </td><td> </td><td> </td></tr>
+
<tr><td>ty:</td><td>SPB any combination</td><td>\'\'</td><td>Type of damage</td> <td>X</td><td> </td><td> </td><td> </td><td> </td><td> </td></tr>
+
<tr><td>sp:</td><td>[-]#</td><td>0</td><td>Speed in segments (1/10 round)</td> <td>X</td><td> </td><td> </td><td> </td><td>X</td><td> </td></tr>
+
<tr><td>sm:</td><td>dice roll format</td><td>0</td><td>Damage roll for Small & Medium opponents</td><td> </td><td>X</td><td>X</td><td> </td><td> </td><td> </td></tr>
+
<tr><td>l:</td><td>dice roll format</td><td>0</td><td>Damage roll for Large & Huge opponents</td><td> </td><td>X</td><td>X</td><td> </td><td> </td><td> </td></tr>
+
<tr><td>ac:</td><td>[-]#</td><td>\'\'</td><td>Armour class</td> <td> </td><td> </td><td> </td><td> </td><td> </td><td>X</td></tr>
+
<tr><td>wt:</td><td>#</td><td>1</td><td>Weight of item in lbs</td> <td>X</td><td> </td><td> </td><td> </td><td> </td><td>X</td></tr>
+
<tr><td>ns:</td><td>#</td><td>0</td><td>Number of spells & powers defined for item</td><td> </td><td> </td><td> </td><td> </td><td>X</td><td>X</td></tr>
+
<tr><td>cl:</td><td>MU / PR / PW</td><td>\'\'</td><td>Type of spell or power</td> <td> </td><td> </td><td> </td><td> </td><td>X</td><td> </td></tr>
+
<tr><td>lv:</td><td>#</td><td>1</td><td>Level at which spell/power is cast</td> <td> </td><td> </td><td> </td><td> </td><td>X</td><td> </td></tr>
+
<tr><td>pd:</td><td>-1 / #</td><td>1</td><td>Number per day (power only)</td> <td> </td><td> </td><td> </td><td> </td><td>X</td><td> </td></tr>
+
<tr><td>rc:</td><td>Charged /<br>Uncharged /<br> Rechargeable /<br>Recharging /<br>Self-charging /<br>Cursed /<br>Charged-Cursed /<br>Recharging-Cursed /<br>Self-charging-Cursed</td><td>Uncharged</td><td>Initial charged and Cursed status of item when found</td><td>X</td><td> </td><td> </td><td> </td><td> </td><td>X</td></tr>
+
</table>
+
<br>
+
===Character Sheet data fields===
+
<p>As stated in section 7, the Character Sheet field mapping to the API script can be altered using the definition of the fields object.  You can find the complete mapping for all APIs in the RPGMaster series, with an explanation of each, in a separate document.</p>
+
 
+
  
 
= Changelog =
 
= Changelog =
 +
 +
{{changelog version|1.5.02|2023-05-31|* Fixed bug with calculation of magic hit adjustment, which was treating numbers as strings.}}
 +
{{changelog version|1.5.01|2023-05-19|* Fixed issues with checking AC for TotalAC item types.
 +
* Added data attribute to suppress a character's dexterity bonus.
 +
* Added warning if trying to change weapon when holding a cursed weapon.
 +
* Support weapons and magic item attacks that use multiple power charges.
 +
* Added ac combination rules to MI database data specifications.
 +
* Fixed ac support for magic helms.
 +
* Support the item charge type 'single-uncharged' for charged items with non-standard discharging mechanisms.
 +
* Display the ac mod effect of each valid item on the Check AC dialog.
 +
* Fix --mod-weap command selection of specified weapons for mod-ing.}}
 +
{{changelog version|1.4.07|2023-04-15|* Added 'discharging' item type which is charged but does not divide.}}
 +
{{changelog version|1.4.06|2023-04-06|* Fixed bug in manual Update Saves dialog which prevented changes.
 +
* Fixed Change Weapon dialog to put rings in correct hand.
 +
* Fixed issues with inconsistencies in hyphenated item names & spell storing items.}}
 +
{{changelog version|1.4.05|2023-03-02|* Added character attribute checks to saving throw functions.
 +
* Added magical attacks by MIs to Attack menu.
 +
* Allow MIs with magical attacks (item class Magic) to be taken in-hand with Change Weapon.
 +
* Added "successcmd" as tag in targeted attacks that have magical charges expended on successful hit.
 +
* Fixed Targeted attack type (i.e. S,P & B) specific calculations for -ve ACs.}}
 +
{{changelog version|1.4.04|2023-01-21|* Fixed error in attack calculations if effects were in play that altered token Thac0 bar.
 +
* Added support for configurable default token bars.
 +
* Added ammo range '=' qualifier which forces literal ranges without multiplication.
 +
* Given Ammo its own list on Edit weapons & armour dialogue.
 +
* Changed attack calcs to show changes to token thac0 as magic-adjust to the To-Hit calc.}}
 +
{{changelog version|1.4.03|2023-01-15|* Allow creature innate attack specs to be either of attk_name,dmg_roll,speed,type or dmg_roll,attk_name,speed,type.
 +
* Fixed error in parsing the class & race dBs for attks}}
 +
{{changelog version|1.4.02|2022-12-16|* Specify weapons and armour for creatures with probability of different sets.
 +
* Also added ammo reuse type 2: becomes only possible ammo of several for that weapon e.g. spitting snake venom, and type 3: reduces in qty by 1, and all other ammo for same weapon increases qty by 1.}}
 +
{{changelog version|1.4.01|2022-11-26|* Added Fighting Style database and implementation.
 +
* Improved the way Situational Modifiers are shown & applied for saves.
 +
* Fixed targeted attack failure on certain armour types.
 +
* Fixed help menu.
 +
* Added support for creature database.}}
 +
{{changelog version|1.3.04|2022-11-15|* Fixed sub-race to-hit bonus calculation.}}
 +
{{changelog version|1.3.03|2022-10-19|* Added Race database parsing & use.
 +
* Fixed error in taking a weapon in hand that can be either 1 or 2 handed (such as a Bastard Sword).}}
 +
{{changelog version|1.3.02|2022-10-14|* Added support for "weaponised" spells - spells that act exactly like weapons (and spells).}}
 +
{{changelog version|1.3.01|2022-10-04|* Fixed bugs in rings that execute 'on:' and 'off:' commands}}
 +
{{changelog version|1.3.00|2022-10-01|* Major release to extract all RPG version-specific data and rule processing to RPGMaster Library API}}
 +
{{changelog version|2.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.}}
 +
{{changelog version|1.042|2022-02-18|* Fixed restricted weapon proficiency calculations.
 +
* Fixed prioritisation of user-defined database entries}}
 
{{changelog version|1.040|2022-02-02|* Added --config command and menu for DM to alter some API behavior.
 
{{changelog version|1.040|2022-02-02|* Added --config command and menu for DM to alter some API behavior.
 
* Multiple weapon changes and additions}}
 
* Multiple weapon changes and additions}}
Line 825: Line 380:
  
 
[[Category:AD&D 2E]]
 
[[Category:AD&D 2E]]
 +
[[Category:API:RPGMaster]]

Latest revision as of 16:52, 11 June 2023

Main Page: API:Script Index

API ScriptAuthor: Richard E
Version: 1.5.02
Last Modified: 2023-05-31
Code: AttackMaster
Dependencies: RPGMlibrary AD+D2e
Conflicts: None

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

[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

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 to manage weapon choice. Weapon definitions are held in weapon databases: see Database-specific handouts for details. All standard weapons 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 Character Sheet setup help handout regarding where the Item table is on the Character Sheet and the data that is held in it. The added weapon must have a listing in the Weapons database.

The easiest way to enter the correct data into the Items table is to 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) 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).</d>
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:Option under DM --config control. The DM can, if they choose, make targeted attacks available which 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 the HP status 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 Characters 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 - see the RoundMaster API Effect Database documentation for details.

Fighting Styles

The Complete Fighter\'s Handbook introduced the concept of Fighters being able to become proficient or a specialist in various styles of fighting, such as with two-handed melee weapons, a weapon and a shield, and such like. These are supported in the RPGMaster APIs via the Styles-DB database, and functions in the CommandMaster API, InitiativeMaster API as well as here in AttackMaster. Each time weapons & shields in-hand are changed using the Attack Menu / Change Weapons menu, AttackMaster checks what is in-hand against any Fighting Styles the character is proficient or specialised in (as defined via the CommandMaster Token-Setup / Set Proficiencies menu). If any are applicable given what is currently in use, AttackMaster will apply the relevant fighting style benefits to the character and their use of their weapons and armour. The APIs are distributed with rules defined for the four styles defined in The Complete Fighter\'s Handbook, and DMs and game authors can add their own as desired. See the Styles Database Help handout for more information.

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 two menus: one to access, review, update and make saving throws and the appropriate modifiers; and the other to make attribute checks, again with the appropriate modifiers.

For each menu, the initial menu presented shows the saving throw and attribute tables 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 or attribute check 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, either automatically (taking into account race, class, level and magic items) or manually.

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.


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

Character?[]@-|:&{}
Substitute^<<>>`~&#124; &amp;&#123;&#125;
Alternative\\ques;\\lbrak;\\rbrak;\\at;\\dash;\\vbar;\\clon;\\amp;\\lbrc;\\rbrc;


[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
where the field_ids are:

w:weapon namet:weapon typest:weapon super-type
sb:strength bonusdb:dexterity bonus+:magical plus
n:number of attacks per roundpl:proficiency levelpd:dancing proficiency level
ch:critical hit rollcm:critical miss rollsz:size
r:range (can be #/#/#)ty:damage typesp:speed in segments
sm:damage vs small & mediuml: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.

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

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.

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


[edit] Ammunition Management

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

[edit] 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 items table (see [RPGMaster CharSheet Setup] handout), 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.


[edit] Armour Class and Saving Throws

[edit] 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 (e.g. see section 5.2 below).

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

[edit] 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 items in the Character's items table (see [RPGMaster CharSheet Setup] handout) 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.

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.

[edit] 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 modify the saving throw table and the modifiers, to apply a "situational modifier" to immediate saving throws (the "situational modifier" only applies to current rolls and is not remembered), and/or to check the current saving throw table automatically (taking into account race, class, level, and magic items on their person). 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.

[edit] Attribute Checks

--attr-check [token_id] | [situation-mod] | [message] | [DCval]

Takes an optional token ID (defaults to the selected token), an optional situational modifier, an optional message to display as the last action, and an optional "DC value".

This command presents a menu which can be used to perform attribute checks for the character. The menu displays the character's attribute values and the currently applicable modifiers for attribute checks. Each line has a button which will run the Attribute Check roll and display success or failure. As for the Saving Throw table, buttons also exist to set a situational modifier and to check the modifiers against current magic items in use and magic in effect.

A DC value parameter is provided to emulate attribute check modifiers for D&D 3e and later, though as these checks and modifiers work very differently this is not a direct equivalence. If a DC value is set as a parameter, 10 minus the DC value is added to all the modifiers.


[edit] Other commands

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

[edit] Configure API behavior

--config [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:

FlagTrueFalse
FANCY-MENUSChat templates will use textured backgroundsChat templates will use plain backgrounds
PROFStrictly apply non-proficient weapon penalties as per PHBUse the non-proficient weapon penalty displayed on the Character Sheet
ALL-WEAPSAllow 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-CLASSWeapons not allowed to a class get a penalty of -100Weapons not allowed to a class get double non-proficient penalty
ALL-ARMOURAll armour types allowed for all classesArmour not allowed to a class not included in AC calculations
MASTER-RANGERanged weapon Mastery gives double damage at Point Blank rangeRanged weapon Mastery not allowed, as per PHB
SPECIALIST-RULESOnly Specialist Wizards specified in the PHB get an extra spell per spell levelAny non-Standard Wizard gets an extra spell per spell level
SPELL-NUMSpellcaster spells per level restricted to PHB rulesSpellcaster spells per level alterable using Misc Spells button
ALL-SPELLSSpellcaster spell schools are unrestrictedSpellcaster spell schools are restricted by class rules

[edit] 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 (see Database-specific handouts). 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).

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

[edit] 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 RoundMaster 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 RoundMaster if the command string parameter is added, where command is the RoundMaster command (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

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


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

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

[edit] Changelog

v1.5.02 (2023-05-31)

  • Fixed bug with calculation of magic hit adjustment, which was treating numbers as strings.


v1.5.01 (2023-05-19)

  • Fixed issues with checking AC for TotalAC item types.
  • Added data attribute to suppress a character's dexterity bonus.
  • Added warning if trying to change weapon when holding a cursed weapon.
  • Support weapons and magic item attacks that use multiple power charges.
  • Added ac combination rules to MI database data specifications.
  • Fixed ac support for magic helms.
  • Support the item charge type 'single-uncharged' for charged items with non-standard discharging mechanisms.
  • Display the ac mod effect of each valid item on the Check AC dialog.
  • Fix --mod-weap command selection of specified weapons for mod-ing.


v1.4.07 (2023-04-15)

  • Added 'discharging' item type which is charged but does not divide.


v1.4.06 (2023-04-06)

  • Fixed bug in manual Update Saves dialog which prevented changes.
  • Fixed Change Weapon dialog to put rings in correct hand.
  • Fixed issues with inconsistencies in hyphenated item names & spell storing items.


v1.4.05 (2023-03-02)

  • Added character attribute checks to saving throw functions.
  • Added magical attacks by MIs to Attack menu.
  • Allow MIs with magical attacks (item class Magic) to be taken in-hand with Change Weapon.
  • Added "successcmd" as tag in targeted attacks that have magical charges expended on successful hit.
  • Fixed Targeted attack type (i.e. S,P & B) specific calculations for -ve ACs.


v1.4.04 (2023-01-21) {{{3}}}


v1.4.03 (2023-01-15)

  • Allow creature innate attack specs to be either of attk_name,dmg_roll,speed,type or dmg_roll,attk_name,speed,type.
  • Fixed error in parsing the class & race dBs for attks


v1.4.02 (2022-12-16)

  • Specify weapons and armour for creatures with probability of different sets.
  • Also added ammo reuse type 2: becomes only possible ammo of several for that weapon e.g. spitting snake venom, and type 3: reduces in qty by 1, and all other ammo for same weapon increases qty by 1.


v1.4.01 (2022-11-26)

  • Added Fighting Style database and implementation.
  • Improved the way Situational Modifiers are shown & applied for saves.
  • Fixed targeted attack failure on certain armour types.
  • Fixed help menu.
  • Added support for creature database.


v1.3.04 (2022-11-15)

  • Fixed sub-race to-hit bonus calculation.


v1.3.03 (2022-10-19)

  • Added Race database parsing & use.
  • Fixed error in taking a weapon in hand that can be either 1 or 2 handed (such as a Bastard Sword).


v1.3.02 (2022-10-14)

  • Added support for "weaponised" spells - spells that act exactly like weapons (and spells).


v1.3.01 (2022-10-04)

  • Fixed bugs in rings that execute 'on:' and 'off:' commands


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