',
+ grey_button: '"background-color: lightgrey; display: inline-block; border: 1px solid black; border-radius: 5px ; color: dimgrey; font-weight: extra-light; padding: 1px 5px;"',
+ dark_button: '"background-color: lightgrey; display: inline-block; border: 1px solid black; border-radius: 5px ; color: black; font-weight: normal; padding: 1px 5px;"',
+ selected_button: '"display: inline-block; background-color: white; border: 1px solid red; border-radius: 5px ; color: red; font-weight: bold; padding: 1px 5px;"',
+ green_button: '"display: inline-block; background-color: white; border: 1px solid lime; border-radius: 5px ; color: darkgreen; font-weight: bold; padding: 1px 5px;"',
+ boxed_number: '"display: inline-block; background-color: yellow; border: 1px solid blue; padding: 2px; color: black; font-weight: bold;"'
+ });
+
+ /*
+ * Handle for reference to database data relevant to MagicMaster.
+ * Actual data is held in the relevant RPG-specific library. Refer
+ * to the library for full details. See also the help handout for
+ * each database.
+ */
+
+ var dbNames;
+
+ /*
+ * Handle for the Database Index, used for rapid access to the character
+ * sheet ability fields used to hold database items.
+ */
+
+ var DBindex = {};
+
+ /*
+ * Handle for the library object used to pass back RPG & character sheet
+ * specific data tables.
+ */
+
+ var RPGMap = {};
+
+ /*
+ * AttackMaster related help handout information.
+ */
+
+ const handouts = Object.freeze({
+ AttackMaster_Help: {name:'AttackMaster Help',
+ version:4.07,
+ avatar:'https://s3.amazonaws.com/files.d20.io/images/257656656/ckSHhNht7v3u60CRKonRTg/thumb.png?1638050703',
+ bio:'
'
+ +'
Attack Master API v'+version+'
'
+ +'
and later
'
+ +'
'
+ +'
New: in this Help Handout
'
+ +'
Updated: Advantage, Disadvantage and Movement modifiers added to --set-mods command
'
+ +'
Updated: Saving Throw priority can now prioritise magic item effects for best saving throws
'
+ +'
New: Magic resistance can be specified for characters and creatures and will interact with saves
'
+ +'
New: --turn-undead command displays a dialog to support turning undead as speified in the Class and Creature databases
'
+
+ +'
AttackMaster API provides functions to manage weapons, armour & shields, including taking weapons in hand and using them to attack. It uses rules (defined in the RPGMaster Library) 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 are 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; support for Fighting Styles as defined in The Complete Fighter\'s Handbook; plus many other features. This API works best with the databases provided with the RPGMaster series APIs (or added by yourself in custom 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 databases in the RPGMaster Library for the specific game version you are playing. 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 the relevant Database Help handout.
'
+ +'
Note: For some aspects of the APIs to work, the ChatSetAttr API and the Tokenmod API, both from the Roll20 Script Library, must be loaded. It is also highly recommended to load all the other RPGMaster series APIs: RoundMaster, InitiativeMaster, MagicMaster and CommandMaster as well as the mandatory game version specific RPGMaster Library. This will provide the most immersive game-support environment
'
+ +'
Syntax of AttackMaster calls
'
+ +'
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).
'
+ +'
'
+ +'[General API Help]'
+ +'
How To Use AttackMaster
'
+ +'
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:
'
+ +'
- 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 '
+ +'- 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). |
|---|
'
+ +'| 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. |
|---|
'
+
+ +'
Adjustments to Attack Calculations
'
+ +'
The APIs automatically calculate the Thac0 they expect a particular character or creature to have. If the Thac0 is also allocated to a Token Circle, the calculated expected Thac0 will be compared to that set on the Token and any differences highlighted by showing a "Thac0 Bar" on the Token. This difference may be due to current magical effects or other circumstantial aspects (the token circle can be altered manually by the player or GM at any time). The difference is highlighted so that the player and GM can investigate the difference.
'
+ +'
When combined with the RPGM MagicMaster and RoundMaster APIs, magical effects of spells and magic items can automatically adjust the calculated expected Thac0 depending on the properties of the spell or item, such as spells like Prayer or magic items like a Luck Stone. To date, these effects have been hidden in the attack calculations. In order to see an explanation of how these modifiers are calculated, and for the GM to manually adjust these modifiers, the AttackMaster API now provides a dialog under the Attk Menu > Check Thac0 & HP Mods action button menu option for each token, or via the !attk --check-mods command. This dialog also allows the player to select whether to prioritise the best AC, Thac0 (to-hit likelihood), Damage or HP when selecting which magical effects to apply when conflicts arrise.
'
+
+ +'
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.
'
+ +'
When combined with the RPGM MagicMaster and RoundMaster APIs, magical effects of spells and magic items can automatically adjust armour class depending on the properties of the spell or item and these modifications can be viewed in the Attk Menu > Check AC dialog or via the !attk --checkac command.
'
+ +'
New:Magic Resistance & Saves
'
+ +'
The corollary to attacks is saves and New: magic resistance. The system provides three menus: one to make magic resistance checks, one to access, review, update and make saving throws and the appropriate modifiers; and one to make attribute checks, again with the appropriate modifiers.
'
+ +'
Magic Resistance is a property of some creatures specified in the Monstrous Manual: not only as a straight overall percentage resistance to all types of magic, but also as specific full or percentage immunities to certain types of magic (such as Charm magic or Sleep spells). Some PC/NPC races can also have resistances, such as Elves & Half-Elves (others, such as Dwarves and Halflings gain adjustments to saving throws, not magic resistance per se). These resistances and immunities are set within the creature and race databases (see the Race & Creature Database Help handout for details). Very rarely, magic items will confer magic resistance or impact the magic resistance of foes (such as the Robe of the Archmagi).
'
+ +'
If a magical attack is made against a creature or character with any form of magic resistance, a prompt will be made to make an appropriate check - this might be just for rersistance, or for resistance followed by a saving throw if failed as appropriate. For creatures/characters with magic resistance the Other Actions menu will show buttons to check magic resistance & saving throws, or just magic resistance. On the magic resistance menu, the appropriate type of resistance can be selected which will roll the correct dice. If failed and a saving throw is relevant, the saving throws menu will be shown. Otherwise, the magial effect applies.
'
+ +'
For each menu, the initial menu presented shows the magic resistance, saving throw and attribute tables from the Character Sheet (inluding the Monster tab magic resistance if relevant, but saving throws from the Character tab rather than the Monster Tab - monster saving throws should be copied to both). Each type of magic resistance, save or attribute check has a button to make the throw: the system (or the player - see below) 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 for saves to modify the saving throw table, either automatically (taking into account race, class, level and magic items) or manually.
'
+ +'
You can change the way the roll is made using the [PC Rolls] and [You Roll] buttons at the bottom of the saving throw and attribute check menus. If [You Roll] is selected, the player will be presented with a Roll20 Roll Query to enter the result of the roll (though just submitting the dice specification displayed will roll the dice). The option chosen is remembered between game sessions within that campaign.
'
+ +'
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.
'
+ +'
When combined with the RPGM MagicMaster and RoundMaster APIs, magical effects of spells and magic items can automatically adjust saving throws depending on the properties of the spell or item, and these adjustments can be seen on the Other Menu > Saving Throws > Auto-check Saving Throws dialog.
'
+ +'
New:Turning Undead
'
+ +'
Most classes of priest have a power to be able to turn undead. Also some other classes of character can turn undead, but perhaps not as well as clerics. The Class and Creature databases now have data tags that can specify the ability to turn or be turned, and any adjustment to the level or number of hit dice considered on the turning table.
'
+ +'
A new AttackMaster command exists to enact turning of undead as determined by the database entries and the turning table, with all possible outomes enated.
'
+ +'
Rogue Skill Checks
'
+ +'
In a similar way to saves and attribute checks, it is possible to make checks against Rogue skills, such as picking pockets and climbing walls. The initial dialog presented shows a button for each possible check that can be made, and a current target percentage to roll below for success. Clicking any of the buttons will make the named check. However: Some of the checks should be made by the GM. The GM can set a configuration item to allow players to make all checks or for the results of certain checks to only go to the GM. If a check only displays the result to the GM, the players will receive a message to this effect.
'
+ +'
Rolls will either be made automatically or once the player enters a dice roll result (see below). Each result, wherever it is displayed, will also describe how it was calculated and what the implications of the result are for the character. The GM can configure a critical success factor to be 5%, 1% or not allowed (see --config command), which will be taken into account in the calculation. If the natural dice roll achieves a critical success, the skill check will automatically succeed, even for characters who would not normally get any chance of success.
'
+ +'
An additional button is provided on the initial dialog to add a situational modifier with various types listed, or just a general value. Select the appropriate modifier and enter any value prompted for. Any entered modifier will apply to only the next skill check roll, and will apply to any roll made regardless of appropriateness.
'
+ +'
Another button, [Manually Update], will allow the player to check & modify the elements that go to make up each skill check.
'
+
+ +'
A button is also provided to automatically check and update the Rogue Skills values based on the Class, Race, Dexterity, Armour worn and any magical effects in play for the selected token. This can be used for any character, NPC or creature even if not of a Rogue class. If the Auto-check Skill Scores button is selected, Rogue skills will be continually updated as required, ensuring changes to characteristics such as armour and magical items are continuously taken into account. If the Manually Check button is selected, this will not happen and manually entered values will be preserved.
'
+
+ +'
Finally, as for saving throws and attribute checks, buttons are provided for [PC Rolls] and [You Roll] which have the same effects of allowing an automatic roll to take place or for the player to make each roll.
'
+ +'
Note: There are additional commands provided in the MagicMaster API to find traps and to loot containers or other creatures which will prompt "find traps", "remove traps" and "pick pockets" rolls as required. If using these functions on Drag & Drop creatures and containers, the appropriate processes and checks will occur (including asking the GM to make checks as appropriate if the GM has set that RPGMaster configuration) without having to use this dialog.
'
+
+ +'
New:Advantage & Disadvantage
'
+ +'
A D&D5e concept has been implemented as a useful addition to the AD&D2e game, for instance as a possible outcome for a fumble roll (disadvantage on the next attack(s). Having Advantage means two dice of the same type are rolled instead of one, and the more favouable value (either higher or lower) is taken. Having Disadvantage again means two dice instead of one, but the least favourable is then taken. Advantage or Disadvantage can be applied on one or more tokens selected by the DM, or some items (such as drinking an alcoholic potion) will apply Advantage or Disadvantage when used.
'
+
+ +'
'
+ +'
Command Index
'
+ +'
1. Menus
'
+ +'
--menu [token_id]
'
+ +'--other-menu [token_id]
'
+ +'
2. 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]
'
+ +'
3. 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 ]
'
+ +'
4. Ammunition Management
'
+ +'
--ammo [token_id]
'
+ +'--setammo [token_id] | ammo_name | [ [+/-]cur_qty / = ] | [ [+/-]max_qty / = ] | [ SILENT ]
'
+ +'
5. Armour Class, Saving Throws and Skill Checks
'
+ +'
--edit-armour [token_id]
'
+ +'--checkac [token_id] | [ SILENT ] | [SADJ / PADJ / BADJ]
'
+ +'New:--resist[-no-save] [token_id] | [situation-mod]
'
+ +'Updated:--save[-no-resist] [token_id] | [situation-mod]
'
+ +'--build-save [token_id] | save-type | save-value | [macro-name]
'
+ +'--attr-check [token_id] | [situation-mod] | [message] | [DCval]
'
+ +'Updated:--set-mods [token_id / character_id]|cmd|name|spell|mod_spec|[(unused)]|[round_count]
'
+ +'Updated: --set-mod-priority [token_id]|mod_type[|disp_menu]
'
+ +'--check-mods [token_id]|[QUIET/SILENT]
'
+ +'--set-savemod [token_id]|cmd|name|spell|save_spec|[save_count]|[round_count]|[fail_cmd]
'
+ +'--savemod-count [token_id]|[+/-]count
'
+ +'--theive [token_id]
'
+ +'--check-thieving [token_id]|[SILENT]
'
+ +'--set-thieving [token_id]
'
+ +'New:--turn-undead token_id|number of undead|[creature name]|[roll]
'
+ +'New:--advantage token_id|[duration]
'
+ +'
6. Other Commands
'
+ +'
--help
'
+ +'--config [PROF/ALL-WEAPS/WEAP-CLASS/ALL-ARMOUR/MASTER-RANGE/DM-TARGET] | [TRUE/FALSE]
'
+ +'--check-db [ db-name ]
'
+ +'--extract-db db-name
'
+ +'--handshake from | [cmd]
'
+ +'--hsq from | [cmd]
'
+ +'--hsr from | [cmd] | [TRUE/FALSE]
'
+ +'--debug [ ON / OFF ]
'
+ +'
'
+ +'
Command details
'
+ +'
1. Menus
'
+ +'
1.1 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.
'
+ +'
1.2 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; ability checks; rogue skill checks; 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.
'
+ +'
2. Attacking Commands
'
+ +'
2.1 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 | ^ | << | >> | ` | ~ | ¦ | | & | { | } | ( | ) |
|---|
'
+ +' | Alternative | \\ques; | \\lbrak; | \\rbrak; | \\at; | \\dash; | \\vbar; | \\clon; | \\amp; | \\lbrc; | \\rbrc; | \\lpar; | \\rpar; |
|---|
'
+ +'
'
+ +'
'
+ +'2.2 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.
'
+ +'
'
+ +'3. Weapon Management
'
+ +'3.1 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.
'
+ +'3.2 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.
'
+ +'3.3 Manage weapon statistics
'
+ +'--mod-weapon [token_id] | weapon | MELEE / RANGED / DMG / AMMO | adjustments
'
+ +'--quiet-modweap [token_id] | weapon | MELEE / RANGED / DMG / AMMO | adjustments
'
+ +'Each command takes an optional token ID (if not specified uses selected token), a mandatory weapon name, and a mandatory data type.
'
+ +'These commands allow the specifications of any weapon currently in-hand to be adjusted programmatically. E.g. the magical plus on to-hit and damage can be adjusted round by round (as for a Sword of Dancing). The type of data to be adjusted must be identified using the data type parameter: MELEE & RANGED alter To-Hit data, and DMG & AMMO alter Damage.
'
+ +'The weapon parameter can name a specific weapon name, a type of weapon (e.g. bow, long-blade, club etc), a changed weapon name (previously changed by this command), or even \'all\' for all currently held weapons. All data of the specified data type for all weapons that match the weapon parameter may then be altered, using the comma-separated adjustments parameter. Each adjustment is of the format field_id:[=][+/-]value
where the field_ids are:
'
+ +'| w: | weapon name | t: | weapon type | st: | weapon super-type |
'
+ +'| sb: | strength bonus | db: | dexterity bonus | +: | magical plus |
'
+ +'| n: | number of attacks per round | pl: | proficiency level | pd: | dancing proficiency level |
'
+ +'| ch: | critical hit roll | cm: | critical miss roll | sz: | size |
'
+ +'| r: | range (can be #/#/#) | ty: | damage type | sp: | speed in segments |
'
+ +'| sm: | damage vs small & medium | l: | damage vs large |
'
+ +'
'
+ +'Numeric values can be preceeded by + or -, which will adjust rather than replace the current value. To set a value as negative, precede the minus by an equals thus =-value. For attributes that are relevant to multiple data types, only the specified data type will be adjusted. Multiple attributes can be adjusted using one command call by concatenating comma-delimited adjustments. E.g.
'
+ +'--mod-weap @{selected|token_id}|Sword-of-Dancing|MELEE|sb:0,+:+1,sp:-1'
+ +'If the weapon is not found, the GM receives an error message, but no other issues occur.
'
+ +'3.4 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.
'
+ +'3.5 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.
'
+ +'
'
+ +'4. Ammunition Management
'
+ +'4.1 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.
'
+ +'4.2 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.
'
+ +'
'
+ +'5. Armour Class, Saving Throws and Skill Checks
'
+ +'5.1 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.
'
+ +'5.2 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.
'
+ +'New: 5.3 Magic Resistance
'
+ +'--resist[-no-save] [token_id] | [situation-mod]
'
+ +'Takes an optional "command extension" (i.e. --resist can become --resist-no-save), an optional token ID (if not specified uses the selected token), and an optional roll modifier value
'
+ +'If a creature or character has a magic resistance percentage specified on the Monster tab, or entries in the magic resistance table at the Character > Info > Tracker tab of the sheet, this command will display a dialog to allow selection of the appropriate roll, or a [None] option is Magic Resistance is not relevant. If the magic resistance check is prompted by the casting of a spell or other magical effect, a failed check might automatically display the saving throw dialog or, if the optional --resist-no-save command is used or no save is appropriate, automatically apply the status and effect to the token.
'
+ +'5.4 Saving Throws
'
+ +'--save[-no-resist] [token_id] | [ situation-mod ]
'
+ +'--save [token_id] | [ situation-mod ] | save-type | saving-throw
'
+ +'Takes an optional "command extension" (i.e. --save can become --save-no-resist, 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. If no command qualifier is used and the represented character sheet has magic resistance then the magic resistance dialog will be shown - if --save-no-resist is the command then no magic resistance dialog will be shown even if relevant.
'
+ +'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.
'
+ +'5.5 Build Custom Save
'
+ +'--build-save [token_id] | save-type | save-value | [macro-name]
'
+ +'Takes an optional token ID (if not specified uses selected token), a type of save (which can be anything and not restricted to standard save types), not sensitive to case), the value to exceed to succeed the save, and an optional name for the macro to build on the character sheet.
'
+ +'This command builds an ability macro on the character sheet represented by the supplied or selected token. The macro will be to make the named saving throw (the name has no significance) and the specified value to exceed with a d20 dice roll for the represented character to succeed in making the saving throw. The character sheet ability macro will be named using either the provided macro-name, which if not provided will default to Do-not-use-save-type-save. The saving throw can then simply be run using the chat window command %{character-name|macro-name}.
'
+ +'5.6 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.
'
+
+ +'Updated: 5.7 Set AC / Thac0 / Damage / HP / Movement Modifiers
'
+ +'--set-mods [TOKEN_ID / CHARACTER_ID]|cmd|name|spell/item|mod_spec|(unused)|[round_count]|[VERBOSE / SILENT]
'
+ +'Takes an optional token ID or character ID (defaults to the character ID represented by the selected token), a mandatory command, a mandatory mod name, a mandatory spell or item name, a mandaroty modifier specification, an optional number of rounds duration, and an optional verbose or silent specifier (defaults to silent).
'
+ +'Adds, modifies or deletes one or any number of named AC, thac0, damage, HP or movement modifiers that can apply to a limited number of rounds, or just continue indefinately until cancelled.
'
+ +' In addition, the D&D5e concept of Advantage and Disadvantage can be applied to a token or a character sheet, for melee attacks, ranged attacks, damage rolls, saving throws, attribute checks, and rogue skill checks. These conditions require two dice to be rolled instead of one for each situation, the more beneficial being taken for Advantage, and the less beneficial for Disadvantage.
'
+ +'Any number of these conditions of multiple or the same types can be set at the same time for the same token or character sheet. The results applied will be the accumulated effect of all conditions set. Conditions set on a character sheet will apply to all tokens associated with that character sheet across all pages. Conditions set on a token id will only be applied to that token, but will move to any token of the same name representing the same character sheet as the player page is changed (i.e. following the PC/NPC/Creature as it moves between pages).
'
+ +'The cmd can be one of ADD, DEL, DELSPELL, or DELALL. The mod-spec defines the checks that are affected by the modification - multiple check types can be specified, as mods or overrides. The format is:
'
+ +''
+ +'+:[=][+/-]#
or
ac+:[=][+/-]# | The effect on armour class bonus, + being beneficial and - being a penalty |
|---|
'
+ +'| thac0+:[=][+/-]# | The effect on Thac0, + being beneficial and - being a penalty |
|---|
'
+ +'| dmg+:[=][+/-]# | The effect on the damage bonus, + being beneficial and - being a penalty |
|---|
'
+ +'| hp+:[=][+/-]# | Temporary HP, when ends returns to minimum of starting current HP and ending current HP, + being beneficial and - being a penalty |
|---|
'
+ +'| hpt+:[=][+/-]# | Temporary HP, when ends substracted from ending current HP (even to below 0), + being beneficial and - being a penalty |
|---|
'
+ +'| hpp+:[=][+/-]# | Semi-permanent HP, when ends returns to minimum of ending current HP and starting maximum HP, + being beneficial and - being a penalty |
|---|
'
+ +'| hpm+:[=][+/-]# | Modify Maximum HP, when ends reverses the change by the mod amount |
|---|
'
+ +'| move:[=][+/-/*//]# | New:Modify Movement of a character or creature, + being beneficial. Full maths allowed. |
|---|
'
+ +'| adall:[=][+/-]# | New:Set Advantage or Disadvantage for all dice rolls, + for Advantage, - for Disadvantage |
|---|
'
+ +'| admwa:[=][+/-]# | New:Set Advantage or Disadvantage for melee weapon attacks, + for Advantage, - for Disadvantage |
|---|
'
+ +'| adrwa:[=][+/-]# | New:Set Advantage or Disadvantage for ranged weapon attacks, + for Advantage, - for Disadvantage |
|---|
'
+ +'| addam:[=][+/-]# | New:Set Advantage or Disadvantage for damage rolls, + for Advantage, - for Disadvantage |
|---|
'
+ +'| adsav:[=][+/-]# | New:Set Advantage or Disadvantage for saving throws, + for Advantage, - for Disadvantage |
|---|
'
+ +'| adatr:[=][+/-]# | New:Set Advantage or Disadvantage for attribute checks, + for Advantage, - for Disadvantage |
|---|
'
+ +'| adrog:[=][+/-]# | New:Set Advantage or Disadvantage for rouge skill checks, + for Advantage, - for Disadvantage |
|---|
'
+ +'
'
+
+ +'Updated: 5.8 Set Modifier Priorities
'
+ +'--set-mod-priority [token_id]|mod_type[|CHECKAC / CHECKMODS]
'
+ +'Takes an optional token_id (defaults to selected token), a mandatory modifier type specifier, and an optional menu type to display.
'
+ +'Defines which type of modifier takes priority when automatically assessed. This is relevant when more than one item owned and carried by a character of the same type (e.g. two worn rings, or two miscellaneous items, or similar) have two conflicting effects. The API can be requested to prioritise and take into account mods that favour the best outcome for armour class (AC), Thac0 (thac0), Damage (dam), HP (hp), or Saves (saves). If no conflicts exist, all possible modification effects will be optimised.
'
+
+ +'5.9 Set Save Modifiers
'
+ +'--set-savemod [token_id]|cmd|name|spell/item|mod_spec|[mod_count]|[round_count]|[fail_cmd]
'
+ +'Takes an optional token ID (defaults to the selected token), a mandatory command, a mandatory mod name, a mandatory spell or item name, a mandaroty save modifier specification, an optional number of saving throw checks, an optional number of rounds duration, and an optional command to execute on saving throw failure.
'
+ +'Adds, modifies or deletes one or any number of named saving throw or attribute checks that can apply to a specified number of throws and/or a limited number of rounds, or just continue indefinately until cancelled. A command can also be specified to enact if the throw or check fails (saving throws and attribute checks only).
'
+ +'The cmd can be one of ADD, DEL, DELSPELL, DELALL, or a bespoke command type of YYY=XXX (saving throw mods only), where XXX is the 3-letter short form specifying a type of existing base mod type (par, poi, dea, rod, sta, wan, pet, pol, bre, or spe), and YYY is a new 3-letter specification for the named modifier. This bespoke saving throw type will be based on the base type specified, modified by the save-spec. A button will be added to the creature\'s saving throw table, allowing bespoke saves to be made by the creature. E.g. a Bless spell provides an improved save vs. Fear effects so the spell adds a \'Fear\' button to the saving throw table of each creature Blessed for the duration of the spell.
'
+ +'The mod-spec defines the checks that are affected by the modification - multiple saving throw, attribute and other check types can be specified, as mods or overrides. The format is:
'
+ +''
+ +'| svXXX:[=][+/-]# | The effect on various saving throws or attribute checks, specified by XXX, + being beneficial and - being a penalty |
|---|
'
+ +'| YYY=XXX | XXX is as above, and YYY is any 3-letter specification (cannot be anything XXX can be) |
|---|
'
+ +'| XXX | This can be \'par\', \'poi\', \'dea\', \'rod\', \'sta\', \'wan\', \'pet\', \'pol\', \'bre\', or \'spe\' (or the bespoke 3-letter code) for saves, or \'str\', \'con\', \'dex\', \'int\', \'wis\', or \'chr\' for attributes, or \'sav\' for all saves, \'atr\' for all attributes, or \'all\' for everything |
|---|
'
+ +'
'
+
+ +'5.10 Increment/Decrement Save Count
'
+ +'--savemod-count [token_id]|[+/-]count
'
+ +'Takes an optional token ID (defaults to the selected token), and a mandatory count preceeded by an optional + or -.
'
+ +'Saving throw and attribute check modifiers which have durations set using the -set-savemod command have their duration in rounds decremented as the round number increments (requires use of the RoundMaster and InitMaster APIs and the Turn Order tracker, or use of the InitMaster --maint command). The duration in throws/checks reduces as throws/checks are made. However, the number of throws/checks can also be changed using this command. All mods that have a current mod_count specified using the --set-mods or --set-savemod command will have their mod_count impacted by use of this command
'
+
+ +'5.11 Check Current Modifiers
'
+ +'--check-mods [token_id]|[SILENT / QUIET]
'
+ +'Takes an optional token ID (defaults to the selected token), and an optional response qualifier.
'
+ +'Initiates a check of all possible modifiers currently in effect to set the current AC, Thac0, Damage bonus and current / maximum HP for the specified token. If defined as QUIET will not display any feedback, or if SILENT will only display if there is a change in Thac0.
'
+
+ +'5.12 Make a Rogue Skill Check
'
+ +'--theive [token_id]
'
+ +'--set-thieving [token_id]
'
+ +'Each takes an optional token ID (if not specified uses selected token).'
+ +'
Note: this dialog may best be used by the GM for many of the included rogue skill checks. Check with your GM for the approapriate approach.
'
+ +'This command provides an alternative route to making a rogue skill check, rather than using the facilities provided on the character sheet. It works in a very similar way to the Attribute Check dialog (see above). Clicking any of the skill buttons will run an appropriate macro to make the check. Alternatively, you can use the dialog to view the required target and roll your own dice.
'
+ +'The dialog also provides a button to set a modifier to the roll, which might be required by the specific situation the character finds themself in. This modifier will be temporary, only being in effect for the next skill check.
'
+ +'A button at the bottom of the dialog provides access to another dialog to maintain the rogue skills table on the character sheet (also accessed via the --set-thieving command). Select any of the numbers in the table to change it. The number of "points" usable at the rogue\'s level is automatically maintained and the points used in the table are calculated and checked against the allowed number. Note: this is a very wide dialog (as the table is wide) and it is advised to drag the chat window edge to temporarily make it wider and, when finished, return the chat window to your desired width.
'
+
+ +'5.13 Check Current Rogue Skills
'
+ +'--check-thieving [token_id]|[SILENT]
'
+ +'Takes an optional token ID (defaults to the selected token), and an optional response qualifier.
'
+ +'Initiates a check of the factors affecting rogue skills for the specified token, such as current class, race, dexterity, armour worn and magical effects. If not SILENT, will then display a dialoge in which the player can set the additional points due to level, with the remaining allowed unallocated points calculated and displayed.
'
+
+ +'5.14 New:Turning Undead
'
+ +'--turn-undead [token_id]|[number of undead]
'
+ +'Takes an optional token ID (if not specified uses selected token), and an optional number of creatures to turn (defaults to 2d6).
'
+ +'This command examines the class of the character or NPC represented by the specified token, assessing if the Class definition supports turning undead and, if so, whether there is an adjustment to the level (e.g. as for a Paladin turning at two levels lower than a cleric). Where a character has more than one class, the best chance of turning is used.
'
+ +'The dialog presented prompts for the specified number of creatures to be selected: these can be multiple types of creature, which will be sorted with the lowest dice creatures being assessed first. The database definition for each creature is checked for turnability, difficulty of turning, with any adjustment to hit dice.
'
+ +'All possible outomes of turning are atered for. Turned creatures, either automatic turning or due to a sucessful roll, sets a status on the creature. Destroying the creature will mark the creature as destroyed. If destroyed and additional creatures of the same type are turned, the player will be asked to select more creatures of that type.
'
+
+ +'5.15 New:Advantage & Disadvantage
'
+ +'--advantage [token_id]|[duration]
'
+ +'Takes an optional token ID (if not specified uses selected token), and an optional duration in rounds (defaults to 1 round - 99 implies continuous until cancelled by DM).
'
+ +'Presents a dialog which can be used to set advantage or disadvantage on various player dice rolls, or stop current applications. Advantage and Disadvantage are the same as the D&D5e concepts and are not strictly relevant to AD&D2e. However, they have been found to be useful, for instance to provide outcomes for critial hits and fumbles.
'
+
+ +'
'
+ +'6.Other commands
'
+ +'6.1 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.
'
+ +'6.2 Updated:Configure API behavior
'
+ +'--config [PROF/ALL-WEAPS/WEAP-CLASS/WEAP-PLUS/ALL-ARMOUR/MASTER-RANGE/DM-TARGET] | [TRUE/FALSE]
'
+ +'Takes two optional arguments, the first a switchable flag name, and the second TRUE or FALSE.
'
+ +'Allows configuration of several API behaviors. If no arguments given, displays menu for DM to select configuration. Parameters have the following effects:
'
+ +''
+ +' | Flag | True | False |
|---|
'
+ +' | FANCY-MENUS | Chat templates will use textured backgrounds | Chat templates will use plain backgrounds |
|---|
'
+ +' | PROF | Strictly apply non-proficient weapon penalties as per PHB | Use the non-proficient weapon penalty displayed on the Character Sheet |
|---|
'
+ +' | ALL-WEAPS | Allow any character of any class to use and become proficient in any weapon. | Restrict the use of weapons by class to some degree set by WEAP-CLASS |
|---|
'
+ +' | WEAP-CLASS | Weapons not allowed to a class get a penalty of -100 | Weapons not allowed to a class get double non-proficient penalty |
|---|
'
+ +' | WEAP-PLUS | Magical weapons gain a bonus to weapon speed | Magical weapon plusses do not affect weapon speed |
|---|
'
+ +' | ALL-ARMOUR | All armour types allowed for all classes | Armour not allowed to a class not included in AC calculations |
|---|
'
+ +' | MASTER-RANGE | Ranged weapon Mastery gives double damage at Point Blank range | Ranged weapon Mastery not allowed, as per PHB |
|---|
'
+ +' | DM-TARGET | Only the DM can do Targeted Attacks | All players can use Targeted Attacks |
|---|
'
+ +' | ROGUE-CRIT | Strict rogue skill checks | Some level of critical success can apply |
|---|
'
+ +' | ROGUE-CRIT-VAL | If allowed rogue skill critical success is 1% | If allowed rogue skill critical success is 5% |
|---|
'
+ +' | GM-ROLLS | GM makes/sees relevant skill checks | Player makes/sees relevant skill checks |
|---|
'
+ +' | New: SLOTS | Allowed number of Proficiency slots are calculated | Slot number are as set on character sheet |
|---|
'
+ +' New:
ONE-SPECIALIST | PCs can have only one specialist/masterful weapon proficiency | PC specialist/mastery slots are unrestricted |
|---|
'
+ +' New:
ATTR-ROLL | Auto-roll missing NPC attribute values | Leave missing NPC attribute values blank |
|---|
'
+ +' New:
ATTR-RESTRICT | Auto-rolled NPC attributes follow class limits | Auto-rolled NPC attributes ignore class limits |
|---|
'
+ +' | New: TOUCHAC | Some touch attacks ignore base AC of armour | Base AC of armour always applied |
|---|
'
+ +'
'
+ +'6.3 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).
'
+ +'6.4 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.
'
+ +'6.5 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
'
+ +'6.6 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.
'
+ +'
'
+ +'
',
+ },
+ });
+
+ /*
+ * Handles for other RPG and Character Sheet specific data tables.
+ */
+
+ var fieldGroups;
+ var miTypeLists;
+ var clTypeLists;
+ var spTypeLists;
+ var reClassSpecs;
+ var reSpellSpecs;
+ var reWeapSpecs;
+ var reACSpecs;
+ var reThiefSpecs;
+ var reModSpecs;
+ var reSaveSpecs;
+ var spellLevels;
+ var classLevels;
+ var rangedWeapMods;
+ var saveLevels;
+ var baseSaves;
+ var classSaveMods;
+ var raceSaveMods;
+ var attrMods;
+ var saveFormat;
+ var rogueSkills;
+ var rogueDexMods;
+ var thiefSkillFactors;
+ var defaultNonProfPenalty;
+ var classNonProfPenalty;
+ var raceToHitMods;
+ var classAllowedWeaps;
+ var classAllowedArmour;
+ var weapMultiAttks;
+ var punchWrestle;
+ var encumberDef;
+
+ /*
+ * AttackMaster specific global data tables and variables.
+ */
+
+ const PR_Enum = Object.freeze({
+ YESNO: 'YESNO',
+ CUSTOM: 'CUSTOM',
+ });
+
+ const messages = Object.freeze({
+ noChar: '/w "gm" &{template:'+fields.warningTemplate+'}{{name=^^tname^^\'s\nMagic Items Bag}}{{desc=^^tname^^ does not have an associated Character Sheet, and so cannot attack}}',
+ cursedSlot: '&{template:'+fields.warningTemplate+'}{{name=^^cname^^\'s\nMagic Item Bag}}{{desc=Oh what a shame. No, you can\'t overwrite a cursed item with a different item. You\'ll need a *Remove Curse* spell or equivalent to be rid of it!}}',
+ cursedItem: '&{template:'+fields.warningTemplate+'}{{name=^^cname^^\'s\nMagic Item Bag}}{{desc=Oh no! You try putting this away, but it seems to be back where it was... Perhaps you need a *Remove Curse* spell or equivalent to be rid of it!}}',
+ PleaseWait: '**Please wait...** - processing is taking a while',
+ noneLeft: '&{template:'+fields.warningTemplate+'}{{name=^^cname^^\'s\nMagic Item Bag}}{{desc=Whoops! It seems you have none of these left... Recover some you\'ve used or buy some more.}}',
+ targetAttkDisabled: '&{template:'+fields.warningTemplate+'}{{name=^^cname^^\'s\nWeapons}}{{desc=The DM has not enabled targeted attacks for players.}}',
+ cursedWeapon: '&{template:'+fields.warningTemplate+'}{{name=^^cname^^\'s\nMagic Item Bag}}{{desc=Oh no! You try changing weapon, but the previous weapon seems to be back in your hand... Perhaps you need a *Remove Curse* spell or equivalent to be rid of it!}}',
+ cursedRing: '&{template:'+fields.warningTemplate+'}{{name=^^cname^^\'s\nMagic Item Bag}}{{desc=Oh no! You try changing rings, but the previous ring seems to be back on your finger... Perhaps you need a *Remove Curse* spell or equivalent to be rid of it!}}',
+ });
+
+ const MenuState = Object.freeze({
+ ENABLED: false,
+ DISABLED: true,
+ });
+
+ const Attk = Object.freeze({
+ TO_HIT: 'TO_HIT',
+ ROLL: 'ROLL',
+ TARGET: 'TARGET',
+ USER: 'USER',
+ ROLL_3D: 'ROLL_3D',
+ });
+
+ const TwoWeapons = Object.freeze({
+ SINGLE: 0,
+ PRIMARY: 2,
+ SECONDARY: 4,
+ NOPENALTY: ['ranger'],
+ });
+
+ const SkillRoll = Object.freeze({
+ PCROLLS: 'PCROLLS',
+ YOUROLL: 'YOUROLL',
+ });
+
+ const BT = Object.freeze({
+ EXECUTE: 'EXECUTE',
+ MON_ATTACK: 'MON_ATTACK',
+ MON_INNATE: 'MON_INNATE',
+ MON_MELEE: 'MON_MELEE',
+ BACKSTAB: 'BACKSTAB',
+ MELEE: 'MELEE',
+ MW_DMGSM: 'MW_DMGSM',
+ MW_DMGL: 'MW_DMGL',
+ MON_RANGED: 'MON_RANGED',
+ RANGED: 'RANGED',
+ RANGEMOD: 'RANGEMOD',
+ RW_DMGSM: 'RW_DMGSM',
+ RW_DMGL: 'RW_DMGL',
+ MU_SPELL: 'MU_SPELL',
+ PR_SPELL: 'PR_SPELL',
+ POWER: 'POWER',
+ MI_BAG: 'MI_BAG',
+ MI_POWER_USED: 'MI_POWER_USED',
+ MI_POWER_CHARGE_USED: 'MI_POWER_CHARGE_USED',
+ ADD_MIROW: 'ADD_MIROW',
+ EDIT_MI: 'EDIT_MI',
+ EDITMI_OPTION: 'EDITMI_OPTION',
+ CHOOSE_MI: 'CHOOSE_MI',
+ REDO_CHOOSE_MI: 'REDO_CHOOSE_MI',
+ REVIEW_MI: 'REVIEW_MI',
+ SLOT_MI: 'SLOT_MI',
+ STORE_MI: 'STORE_MI',
+ REMOVE_MI: 'REMOVE_MI',
+ THIEF: 'THIEF',
+ MOVE: 'MOVE',
+ CHG_WEAP: 'CHG_WEAP',
+ STAND: 'STAND',
+ SPECIFY: 'SPECIFY',
+ CARRY: 'CARRY',
+ SUBMIT: 'SUBMIT',
+ RIGHT: 'PRIMARY',
+ LEFT: 'OFFHAND',
+ BOTH: 'BOTH',
+ HAND: 'HAND',
+ CS_RIGHT: 'CS_PRIMARY',
+ CS_LEFT: 'CS_OFFHAND',
+ CS_BOTH: 'CS_BOTH',
+ CS_HAND: 'CS_HAND',
+ RIGHT_NOCURSE: 'PRIMARY-NOCURSE',
+ LEFT_NOCURSE: 'OFFHAND-NOCURSE',
+ BOTH_NOCURSE: 'BOTH-NOCURSE',
+ HAND_NOCURSE: 'HAND-NOCURSE',
+ LEFTRING: 'LEFTRING',
+ RIGHTRING: 'RIGHTRING',
+ LEFTRING_NOCURSE: 'LEFTRING-NOCURSE',
+ RIGHTRING_NOCURSE: 'RIGHTRING-NOCURSE',
+ NOHANDS: 'NOHANDS',
+ AUTO_ADD: 'AUTO_ADD',
+ AUTO_DELETE: 'AUTO_DELETE',
+ AMMO: 'AMMO',
+ SAVES: 'SAVES',
+ CHECK_SAVES: 'CHECK_SAVES',
+ ATTR_CHECK: 'ATTR_CHECK',
+ SET_SKILL_ROLL: 'SET_SKILL_ROLL',
+ SET_SAVE_ROLL: 'SET_SAVE_ROLL',
+ SET_ATTR_ROLL: 'SET_ATTR_ROLL',
+ CHECK_MOVE: 'CHECK_MOVE',
+ TURN_SELECTED: 'TURN_SELECTED',
+ TURN_CONFIRMED: 'TURN_CONFIRMED',
+ CTRL_SELECTED: 'CTRL_SELECTED',
+ CTRL_CONFIRMED: 'CTRL_CONFIRMED',
+ ADV_DURATION: 'ADV_DURATION',
+ });
+
+ const reIgnore = /[\s\-\_\(\)]*/gi;
+
+ const replacers = Object.freeze([
+ [/\\api;?/g, "!"],
+ [/\\lbrc;?/g, "{"],
+ [/\\rbrc;?/g, "}"],
+ [/\\gt;?/gm, ">"],
+ [/\\lt;?/gm, "<"],
+ [/<<|«/g, "["],
+ [/\\lbrak;?/g, "["],
+ [/>>|»/g, "]"],
+ [/\\rbrak;?/g, "]"],
+ [/\\\^/g, "?"],
+ [/\\ques;?/g, "?"],
+ [/`/g, "@"],
+ [/\\at;?/g, "@"],
+ [/~/g, "-"],
+ [/\\dash;?/g, "-"],
+ [/\\n/g, "\n"],
+ [/¦/g, "|"],
+ [/\\vbar;?/g, "|"],
+ [/\\clon;?/g, ":"],
+ [/\\amp;?/g, "&"],
+ [/\\lpar;?/g, "("],
+ [/\\rpar;?/g, ")"],
+ [/\\cr;?/g, "\n"],
+ [/\\comma;?/g, ","],
+ ]);
+
+ const dbReplacers = Object.freeze([
+ [/\\amp;?/gm, "&"],
+ [/\\lbrak;?/gm, "["],
+ [/\\rbrak;?/gm, "]"],
+ [/\\ques;?/gm, "?"],
+ [/\\at;?/gm, "@"],
+ [/\\dash;?/gm, "-"],
+ [/\\n/gm, "\n"],
+ [/\\vbar;?/gm, "|"],
+ [/\\clon;?/gm, ":"],
+ [/\\gt;?/gm, ">"],
+ [/\\lt;?/gm, "<"],
+ ]);
+
+ const reRepeatingTable = /^(repeating_.*)_\$(\d+)_.*$/;
+ const reDiceRollSpec = /(?:^\d+$|\d+d\d+)/i;
+ const reWeapon = /}}\s*specs=\s*?(\[.*?(?:melee|ranged|magic).*?\])\s*?{{/im;
+ const reWeapData = /weapdata\s*?=\s*?(\[.*?\])/im;
+ const reToHitData = /}}\s*ToHitData\s*=(.*?){{/im;
+ const reDmgData = /}}\s*DmgData\s*=(.*?){{/im;
+ const reAmmoData = /}}\s*?ammodata\s*?=.*?(?:\n.*?)*{{/im;
+ const reRangeData = /}}\s*?rangedata\s*?=.*?(?:\n.*?)*{{/im;
+ const reACData = /}}\s*acdata\s*=(.*?){{/im;
+ const reRingData = /(?:ring|ac)data\s*?=\s*?(\[.*?\])/im;
+ const reItemData = /}}[\s\w\-]*?(?"><%= text %>'),
+ confirm_box: _.template('
')
+ };
+
+ return {
+ getTemplate: function(tmpArgs, type) {
+ var retval;
+
+ retval = _.find(templates, function(e,i) {
+ if (type === i) {
+ {return true;}
+ }
+ })(tmpArgs);
+
+ return retval;
+ },
+
+ hasTemplate: function(type) {
+ if (!type)
+ {return false;}
+ return !!_.find(_.keys(templates), function(elem) {
+ {return (elem === type);}
+ });
+
+ }
+ };
+ }());
+
+ /**
+ * Init
+ */
+ const init = function() {
+
+ try {
+ if (!state.attackMaster)
+ {state.attackMaster = {};}
+ if (!state.magicMaster)
+ {state.magicMaster = {};}
+ if (_.isUndefined(state.attackMaster.weapRules))
+ {state.attackMaster.weapRules = {oneSpecialist:true,
+ slots:false,
+ prof:true,
+ allowAll:false,
+ classBan:false,
+ criticals:true,
+ naturals:true,
+ allowArmour:false,
+ masterRange:false,
+ dmTarget:false,
+ initPlus:true,
+ rangedMulti:false};
+ }
+ if (_.isUndefined(state.attackMaster.fancy))
+ {state.attackMaster.fancy = true;}
+ if (!state.attackMaster.twoWeapons)
+ {state.attackMaster.twoWeapons = {};}
+ if (_.isUndefined(state.attackMaster.thieveCrit))
+ {state.attackMaster.thieveCrit = 0;}
+ if (_.isUndefined(state.attackMaster.attrRoll))
+ {state.attackMaster.attrRoll = false;}
+ if (_.isUndefined(state.attackMaster.touchAC))
+ {state.attackMaster.touchAC = true;}
+ if (!state.MagicMaster.playerConfig)
+ {state.MagicMaster.playerConfig={};}
+ if (_.isUndefined(state.attackMaster.debug))
+ {state.attackMaster.debug = false;}
+ if (_.isUndefined(state.attackMaster.gmID))
+ {state.attackMaster.gmID = undefined;}
+
+ log('-=> AttackMaster v'+version+' <=- ['+(new Date(lastUpdate*1000))+']');
+
+ [fields,RPGMap] = getRPGMap();
+ dbNames = RPGMap.dbNames;
+ fieldGroups = RPGMap.fieldGroups;
+ miTypeLists = RPGMap.miTypeLists;
+ clTypeLists = RPGMap.clTypeLists;
+ spTypeLists = RPGMap.spTypeLists;
+ spellLevels = RPGMap.spellLevels;
+ classLevels = RPGMap.classLevels;
+ rangedWeapMods = RPGMap.rangedWeapMods;
+ saveLevels = RPGMap.saveLevels;
+ baseSaves = RPGMap.baseSaves;
+ classSaveMods = RPGMap.classSaveMods;
+ raceSaveMods = RPGMap.raceSaveMods;
+ attrMods = RPGMap.attrMods;
+ saveFormat = RPGMap.saveFormat;
+ rogueSkills = RPGMap.rogueSkills;
+ rogueDexMods = RPGMap.rogueDexMods;
+ thiefSkillFactors = RPGMap.thiefSkillFactors;
+ defaultNonProfPenalty = RPGMap.defaultNonProfPenalty;
+ classNonProfPenalty = RPGMap.classNonProfPenalty;
+ raceToHitMods = RPGMap.raceToHitMods;
+ classAllowedWeaps = RPGMap.classAllowedWeaps;
+ classAllowedArmour = RPGMap.classAllowedArmour;
+ weapMultiAttks = RPGMap.weapMultiAttks;
+ punchWrestle = RPGMap.punchWrestle;
+ reClassSpecs = RPGMap.reClassSpecs;
+ reSpellSpecs = RPGMap.reSpellSpecs;
+ reWeapSpecs = RPGMap.reWeapSpecs;
+ reACSpecs = RPGMap.reACSpecs;
+ reThiefSpecs = RPGMap.reThiefSpecs;
+ reModSpecs = RPGMap.reModSpecs;
+ reSaveSpecs = RPGMap.reSaveSpecs;
+ encumberDef = RPGMap.encumberDef;
+ DBindex = undefined;
+ flags.noWaitMsg = true;
+ setTimeout( () => {flags.noWaitMsg = false}, 10000 );
+
+ // Handshake with other APIs to see if they are loaded
+ setTimeout( () => issueHandshakeQuery('magic'), 20);
+ setTimeout( () => issueHandshakeQuery('money'), 20);
+ setTimeout( () => issueHandshakeQuery('cmd'), 20);
+ setTimeout( () => updateHandouts(handouts,true,findTheGM()), 30);
+ setTimeout( updateHitDmgBonus, 200 );
+ setTimeout( cmdMasterRegister, 40 );
+ setTimeout( () => updateDBindex(false), 90); // checking the DB indexing
+
+ } catch (e) {
+ log('AttackMaster Initialisation: JavaScript '+e.name+': '+e.message+' while initialising the API');
+ sendDebug('AttackMaster Initialisation: JavaScript '+e.name+': '+e.message+' while initialising the API');
+ sendCatchError('AttackMaster',null,e,'AttackMaster Init()');
+ }
+ };
+
+// ------------------------------------------------ Deal with in-line expressions --------------------------------
+
+ /**
+ * In the inline roll evaluator from ChatSetAttr script v1.9
+ * by Joe Singhaus and C Levett.
+ **/
+
+ const processInlinerolls = function (msg) {
+ if (msg.inlinerolls && msg.inlinerolls.length) {
+ return msg.inlinerolls.map(v => {
+ const ti = v.results.rolls.filter(v2 => v2.table)
+ .map(v2 => v2.results.map(v3 => v3.tableItem.name).join(", "))
+ .join(", ");
+ return (ti.length && ti) || v.results.total || 0;
+ })
+ .reduce((m, v, k) => m.replace(`$[[${k}]]`, v), msg.content);
+ } else {
+ return msg.content;
+ }
+ };
+
+
+// -------------------------------------------- send messages to chat -----------------------------------------
+
+ // RED 2.050 Chat management functions moved to common library
+
+ /**
+ * RED: v1.207 Send a debugging message if the debugging flag is set
+ */
+
+ const sendDebug = function(msg) {
+ if (!!state.attackMaster.debug) {
+ if (playerIsGM(state.attackMaster.debug)) {
+ log('AttackMaster Debug: '+msg);
+ } else {
+ const player = getObj('player',state.attackMaster.debug);
+ let to;
+ if (player) {
+ to = '/w "' + player.get('_displayname') + '" ';
+ } else
+ {throw {name:'attackMaster Error',message:'sendDebug could not find player'};}
+ if (!msg)
+ {msg = 'No debug msg';}
+ sendChat('attackMaster Debug',to + '
',null,(flags.archive ? null:{noarchive:true}));
+ };
+ };
+ };
+
+ const doSetDebug = function(args,senderId) {
+ const player = getObj('player',senderId);
+ if (!player) throw {name:'attackMaster Error',message:'doSetDebug could not find player: ' + args};
+ let playerName = player.get('_displayname');
+ if (!!args && args.indexOf('off') != 0) {
+ state.attackMaster.debug = senderId;
+ sendResponseError(senderId,'attackMaster Debug set on for ' + playerName,'attackMaster Debug');
+ sendDebug('Debugging turned on');
+ } else {
+ sendResponseError(senderId,'attackMaster Debugging turned off','attackMaster Debug');
+ state.attackMaster.debug = false;
+ }
+ };
+
+ /**
+ * Send a request to run an effect macro to RoundMaster
+ **/
+ const sendAPImacro = function(curToken,msg,effect,macro) {
+
+ if (!curToken || !macro || !effect) {
+ sendDebug('sendAPImacro: a parameter is null');
+ return;
+ }
+ sendAPI( fields.roundMaster + ' --effect '+curToken.id+'|'+msg+'|'+effect+'|'+macro );
+ return;
+ }
+
+// -------------------------------------------- utility functions ----------------------------------------------
+
+ /**
+ * Issue a handshake request to check if another API or
+ * specific API command is present
+ **/
+
+ const issueHandshakeQuery = function( api, cmd ) {
+ const handshake = '!'+api+' --noWaitMsg --hsq attk'+((cmd && cmd.length) ? ('|'+cmd) : '');
+ sendAPI(handshake);
+ if (_.isUndefined(apiCommands[api])) apiCommands[api] = {};
+ apiCommands[api].exists = false;
+ return;
+ };
+
+ /**
+ * Find the GM, generally when a player can't be found
+ */
+
+ const findTheGM = function() {
+ let playerGM;
+ const players = findObjs({ _type:'player' });
+
+ if (players.length !== 0) {
+ if (!_.isUndefined(playerGM = _.find(players, function(player) {
+ if (player) {
+ if (playerIsGM(player.id)) {
+ state.attackMaster.gmID;
+ return player.id;
+ }
+ }
+ }))) {
+ return playerGM.id;
+ }
+ }
+ return state.attackMaster.gmID;
+ }
+
+ /**
+ * Execute a complex series of API commands that can't
+ * be directly executed from an API button
+ **/
+
+ const executeCmdString = function( args, senderId ) {
+
+ let cmdString = args.slice(1).join('|').replace(/ ~~/g,' --').split(' // '),
+ delay = 1;
+ _.each( cmdString, c => {
+ setTimeout( sendAPI, (10*delay++), c, senderId );
+// log('executeCmdString: executing '+c);
+ });
+ };
+
+/* ------------------------- Character Sheet Database Management ------------------------- */
+
+ /*
+ * Check the version of a Character Sheet database and, if
+ * it is earlier than the static data held in this API, update
+ * it to the latest version.
+ */
+
+ const buildDB = function( dbFullName, dbObj, senderId, silent ) {
+
+ return new Promise(resolve => {
+ let errFlag = false;
+ try {
+ const dbName = dbFullName.toLowerCase(),
+ typeList = dbObj.type.includes('spell') ? spTypeLists : (dbObj.type.includes('class') ? clTypeLists : miTypeLists);
+
+ errFlag = buildCSdb( dbFullName, dbObj, typeList, silent );
+ } catch (e) {
+ sendCatchError('AttackMaster',msg_orig[senderId],e);
+ errFlag = true;
+ } finally {
+ setTimeout(() => {
+ resolve(errFlag);
+ }, 10);
+ }
+ });
+ };
+
+ /*
+ * Check all Character Sheets represented by Tokens to ensure
+ * that they have Slash, Pierce & Bludgeon AC fields created.
+ * This is necessary for Targeted Attacks to not cause errors
+ * when used on an opponent and the opponent's AC vs. damage
+ * type is read and displayed.
+ */
+
+ async function checkACvars(forceUpdate,senderId='') {
+
+ try {
+
+ let err, charCS;
+
+ const setAC = function( tokenID ) {
+
+ return new Promise(resolve => {
+ let errFlag;
+ try {
+ errFlag = doCheckAC( [tokenID,'quiet'], findTheGM(), [], true );
+ } catch (e) {
+ log('AttackMaster checkACvars: JavaScript '+e.name+': '+e.message+' while checking AC for tokenID '+tokenID);
+ sendDebug('AttackMaster checkACvars: JavaScript '+e.name+': '+e.message+' while checking AC for tokenID '+tokenID);
+ if (senderId) {
+ sendCatchError('AttackMaster',msg_orig[senderId],e);
+ } else {
+ sendCatchError('AttackMaster',null,e,'AttackMaster checkACvars() on initialisation');
+ }
+ errFlag = true;
+ } finally {
+ setTimeout(() => {
+ resolve(errFlag);
+ }, 10);
+ };
+ });
+ };
+
+ const tokens = filterObjs( function(obj) {
+ if (obj.get('type') !== 'graphic' || obj.get('subtype') !== 'token') return false;
+ if (!(charCS = getObj('character',obj.get('represents')))) return false;
+ return forceUpdate || _.isUndefined(attrLookup( charCS, fields.SlashAC ));
+ });
+
+ for (const t of tokens) {
+ err = await setAC(t.id);
+ if (err) break;
+ };
+ return;
+ } catch (e) {
+ sendCatchError('AttackMaster',(senderId ? msg_orig[senderId] : null),e,'AttackMaster checkACvars()');
+ }
+ };
+
+ /**
+ * Create an internal index of items in the databases
+ * to make searches much faster. Index entries indexed by
+ * database root name & short name (name in lower case with
+ * '-', '_' and ' ' ignored). index[0] = abilityID,
+ * index[1] = ct-attributeID
+ * v3.051 Check that other database-handling APIs have finished
+ * updating their databases and performed a handshake
+ **/
+
+ const updateDBindex = function(forceUpdate=false) {
+
+ apiDBs.magic = !!apiDBs.magic || ('undefined' === typeof MagicMaster);
+
+ DBindex = getDBindex(forceUpdate);
+ parseClassDB(forceUpdate);
+ checkACvars(false);
+ return;
+ }
+
+ /*
+ * Check a character sheet database and update/create the
+ * required attributes from the definitions. This should
+ * be run after updating or adding item or spell definitions.
+ */
+
+ const checkDB = function( args ) {
+
+ checkCSdb( args[0] );
+ apiDBs.attk = true;
+ updateDBindex(true);
+ return;
+ }
+
+/* -------------------------------------------- Utility Functions ------------------------------------------------- */
+
+ /*
+ * Function to return the msVersion of the Character Sheet
+ * i.e. which versions of MagicMaster it is matched to
+ */
+
+ const csVer = (charCS) => parseFloat(((attrLookup( charCS, fields.msVersion ) || '1.5').match(/^\d+\.?\d*/) || ['1.5'])[0]) || 1.5;
+
+ /*
+ * Function to set a selected token as args[0]
+ */
+
+ const setSelected = function( args, selected ) {
+
+ if (!args) args = [];
+ if (!args[0] && selected && selected.length) {
+ args[0] = selected[0]._id;
+ } else if (!args[0]) {
+ sendError('No token selected');
+ return undefined;
+ }
+ return args;
+ };
+
+ /*
+ * Check for magic resistance
+ */
+
+ const checkMagicResist = function( charCS ) {
+ let resistance = (parseInt(attrLookup( charCS, fields.MagicResist )) || 0);
+ if (!resistance || resistance <= 0) {
+ const ResistValTab = getTableField( charCS, {}, fields.Resist_table, fields.Resist_resistance );
+ for (let i=0; i