API:RPGMaster-AttacksDB
From Roll20 Wiki
 | Page Updated: 2022-04-02 |
Contents |
General Database information
The RPGMaster APIs use a number of Character Sheets as databases to hold Ability Macros defining character classes, attack templates, spells, powers and magic items and their effects. The API is distributed with many class, attack, spell, power & magic item definitions, and checks for, creates and updates these Character Sheet databases on start-up. DMs can add their own character classes, attack templates, spells, items, 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 provided databases are accidentally deleted, they will be automatically recreated the next time the Campaign is opened. Additional databases should be named as follows:
| Wizard Spells: | additional databases: MU-Spells-DB-[added name] where [added name] can be replaced with anything you want. |
|---|---|
| Priest Spells: | additional databases: PR-Spells-DB-[added name] where [added name] can be replaced with anything you want. |
| Powers: | additional databases: Powers-DB-[added name] where [added name] can be replaced with anything you want. |
| Magic Items: | additional databases: MI-DB-[added name] where [added name] can be replaced with anything you want. |
| Character Classes: | additional databases: Class-DB-[added name] where [added name] can be replaced with anything you want. |
| Attack Templates: | additional databases: Attacks-DB-[added name] where [added name] can be replaced with anything you want. |
However: 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.
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.
Important Note: all Character Sheet databases must have their 'ControlledBy' value (found under the [Edit] button at the top right of each sheet) set to 'All Players'. 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.
Each database has a similar structure, with:
- Ability Macros named as the class, attack type, spell, power or magic item specified, and used to describe and provide effects for classes, attacks, spells, powers and magic items using the commands in the RPGMaster APIs;
- Custom Attributes with the attribute name "ct-ability-macro-name", one per Ability Macro, which defines the casting time and casting cost for spells & powers, and speed and MI type for magic items (not currently used for Class or Attack definitions, but they still have to exist);
- An entry in a list on the character sheet in the spell book of the relevant Character Sheet tab (Spell Level of the spell defined, Powers tab, or various spell books for different Classes & Magic Items).
However, as with all other Databases in the RPGMaster Suite of APIs, if the Ability Macros are correctly set up using the formats detailed in the Help Documentation, the AttackMaster API command !attk --check-db database-name will check the database and set up all other aspects for you, including the correct Custom Attributes and List entries.
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 class, spell, power and magic item ability macros, and are an essential part of Attack Templates. When a Player or an NPC or Monster makes an attack, the AttackMaster API runs 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.
Replacing Classes, Attacks, Spells & Items
If you want to replace any Ability Macro provided in any of the databases, you can do so simply by creating an Ability Macro in one of your own databases (a database with the same root name) with the Ability Macro you create having exactly the same name as the provided item to be replaced. The API gives preference to Ability Macros in user-defined databases, so yours will be selected in preference to the one provided with the APIs.
How Attacks Work
In order to understand the Attacks Database, it is first important to understand how attacks are executed by the AttackMaster API. Under AD&D 2nd Edition, attacks are quite complex, involving many factors that can vary from moment to moment. Some say that this is why they prefer RPG systems that require less maths and are faster to execute, that the complexity of the AD&D2e combat system interrupts the flow of play. The AttackMaster API handles attacks in such a way as to hide as much of that complexity from the players as possible, and thus allow game-play to flow and players to concentrate on the unfolding story.
In order for the API to achieve this, it must evaluate many factors "on the fly" such as current magical effects in place (generally or on individuals), the current attributes of a character (which can vary as they are affected by game play), the type, range and properties of the weapon combinations used at that point in time for that particular attack, and the effects of the race, class, level and proficiency of the character, among several others. Given that these factors can vary even during a single round, each attack must be fully evaluated from scratch each time it is made.
Another issue is introduced by players feeling much more satisfied if they can see dice rolling for the attack, or they may want to use the Roll20 dice rolling mouse action, or even their own physical dice. Unfortunately for API authors, at the time of writing the API it is only possible to display rolling 3D dice from Chat Window dice rolls, either typed in the entry box by the player or run from Macros displayed in the Chat Window - 3D dice will not work when called by or included in API calls and commands.
So how does the AttackMaster API achieve 3D dice rolls and attack calculations that can accelerate game-play? The answer is that it uses Attack Template definitions which it parses and turns into Ability Macros on the Character Sheet of the character that selects to do an attack. The Melee Weapon templates are parsed and the attack Ability Macros for each Melee weapon in-hand created on the Character Sheet as (in fact just before) the Attack chat window menu is displayed, and Ranged Weapon templates are parsed and their attack Ability Macros are created after the type of Ammo has been selected and just before the relevant range buttons on the Attack menu are enabled for the Player to select. When the Player selects a Melee weapon to attack with, or the relevant range button for a Ranged weapon, the API is then not actually involved at all - the Roll20 Chat Window button just selected is just doing a standard macro call to the relevant attack Ability Macro just created on the Character Sheet. This also means the actual attacks happen at the fastest speed Roll20 can achieve as no API code is being run at that point.
The Attacks Database
The Attack Templates are stored in the Attacks Database, Attacks-DB, and any additional bespoke Attacks Databases the DM/Game Creator adds using the Character Sheet name Attacks-DB-[added name]. There are 17 basic Attacks Templates:
| MW-ToHit | Melee Weapon calculation to assess and display the Armour Class hit by an attack |
|---|---|
| MW-DmgSM | Melee Weapon calculation to assess the damage done to a Medium or smaller opponent if the hit was sucessful |
| MW-DmgL | Melee Weapon calculation to assess the damage done to Large or larger opponents as a result of a successful hit |
| MW-Targeted-Attk | Melee Weapon calculation for using a targeted attack which rolls all attack and damage dice at once, and then displays the AC hit, the damage vs. all types of opponents, and the current AC & HP of the targeted opponent |
| RW-ToHit | Ranged Weapon calculation to assess and display the Armour Class hit by an attack |
| RW-DmgSM | Ranged Weapon calculation to assess the damage done to a Medium or smaller opponent if the hit was sucessful |
| RW-DmgL | Ranged Weapon calculation to assess the damage done to Large or larger opponents as a result of a successful hit |
| RW-Targeted-Attk | Ranged Weapon calculation for using a targeted attack which rolls all attack and damage dice at once, and then displays the AC hit, the damage vs. all types of opponents, and the current AC & HP of the targeted opponent |
| Mon-Attk1 | Monster/Creature attack 1 calculation to assess and display the Armour Class hit by an attack |
| Mon-Attk2 | Monster/Creature attack 2 calculation to assess and display the Armour Class hit by an attack |
| Mon-Attk3 | Monster/Creature attack 3 calculation to assess and display the Armour Class hit by an attack |
| Mon-Dmg1 | Monster/Creature damage 1 calculation to assess and display the damage done by an attack |
| Mon-Dmg2 | Monster/Creature damage 2 calculation to assess and display the damage done by an attack |
| Mon-Dmg3 | Monster/Creature damage 3 calculation to assess and display the damage done by an attack |
| Mon-Targeted-Attk1 | Monster/Creature for a targeted attack 1 calculation to assess and display the Armour Class hit and damage done by an attack, along with the target's current AC and HP |
| Mon-Targeted-Attk2 | Monster/Creature for a targeted attack 2 calculation to assess and display the Armour Class hit and damage done by an attack, along with the target's current AC and HP |
| Mon-Targeted-Attk3 | Monster/Creature for a targeted attack 3 calculation to assess and display the Armour Class hit and damage done by an attack, along with the target's current AC and HP |
The Melee Weapon Attack Templates will be parsed for each Melee Weapon in-hand at the time of the attack, and the Ranged Weapon Attack Templates will be parsed for each possible range of the Ranged Weapon/Ammo combination selected for the attack. Two additional Melee Weapon Attack Templates are parsed if the character making the attack is a Rogue class:
| MW-Backstab-DmgSM | Melee Weapon calculation to assess the damage done to a Medium or smaller opponent if the hit was a Rogue doing a backstab and the attack was successful |
|---|---|
| MW-Backstab-DmgL | Melee Weapon calculation to assess the damage done to a Large or larger opponent if the hit was a Rogue doing a backstab and the attack was successful |
All of the above templates are provided in the Attacks-DB database supplied with the AttackMaster API. They are created to follow AD&D 2nd Edition rules: DMs and Game Creators can create their own attack and damage calculations following whatever rules they want in their own bespoke Attacks Database, using the information provided in the next section.
It is possible to add additional Attack Templates that are specific to particular Races, Classes, or even individual weapons! Indeed, the database supplied with the AttackMaster API includes an example of a bespoke Attack Template set for a thrown prepared Oil Flask. When an attack is the action selected by the Player, the API will search the Attacks-DB and bespoke user Attacks Databases for Melee and Ranged Attack Templates in the following name order (replace the ?W with either MW or RW as appropriate):
- ?W-ToHit-\<weapon name\> Searches for a weapon-specific Attack Template set for the weapon being used to attack with, but if not found then
- ?W-ToHit-\<class name\> Searches for a class-specific Attack Template set for the class (or each class of a multi/dual class) of the attacking character, but if not found then
- ?W-ToHit-\<race\> Searches for a race-specific Attack Template set for the race of the attacking character, but if not found then
- ?W-ToHit Uses the default Attack Template set.
Attack Data Fields
Attack Templates can take the form of any message or macro that can be held in a Roll20 Character Sheet Ability Macro and be displayed in the Chat Window when called. Typically, this will use a Roll Template (standard Roll20 functionality - see Roll20 Help for information), but it can be any format you desire as long as it results in the correct display of information to the Player.
The Attack Template has a large number of template fields that it can call upon to use in its calculations - these are pre-calculated values supplied by the API that the DM / Game Creator writing a new Attack Template can use. The standard Roll20 attribute value notation of @{selected|field-name} is not recommended for use in Attack Templates, as when the template is parsed, and then later the resulting Ability Macro run as part of the attack, there are circumstances where the token for the attacking Character may not be currently selected, resulting in the wrong value being used or, worse, an error occurring and the game halting. Instead, all the following template fields are available:
| All Attack Templates | |
|---|---|
| ^^toWho^^ | Resolves to a Roll20 whisper command to the Character making the attack |
| ^^toWhoPublic^^ | Resolves to a Roll20 chat command to the GM if a GM controlled creature is making the attack, otherwise a public message to all Players |
| ^^defaultTemplate^^ | Resolves to the name of the Default Roll Template name set in the AttackMaster API |
| ^^cname^^ | Resolves to the Character Name of the attacking character |
| ^^tname^^ | Resolves to the Token Name of the attacking character |
| ^^cid^^ | Resolves to the Roll20 Character ID of the attacking character |
| ^^tid^^ | Resolves to the Roll20 Token ID of the attacking character |
| ^^toHitRoll^^ | Depending on if the Player chose for Roll20 to roll the attack dice or to roll their own dice, resolves to one of (a) the attack dice specification provided in the Attack Template's Specs field, or (b) a Roll Query requesting the Player to enter a dice roll result |
| ^^thac0^^ | Resolves to the base thac0 (value "to hit armour class 0") of the attacking character without any adjustments |
| ^^ACfield^^ | Resolves to the Character Sheet field name that holds the target creature's current Armour Class (only used in targeted attacks) |
| ^^targetACfield^^ | Resolves to the targeted token value Armour Class macro call @{target|Select Target|^^ACfield^^} vs. a targeted opponent (only used in targeted attacks) |
| ^^HPfield^^ | Resolves to the Character Sheet field name that holds the target creatures current Hit Points (only used in targeted attacks) |
| ^^targetHPfield^^ | Resolves to the targeted token value Hit Points macro call @{target|Select Target|^^HPfield^^} vs. a targeted opponent (only used in targeted attacks) |
| ^^magicAttkAdj^^ | Resolves to any magical effect attack bonus or penalty resulting from magic currently in effect |
| ^^strAttkBonus^^ | Resolves to the strength to-hit bonus/penalty of the attacking character |
| ^^strDmgBonus^^ | Resolves to the strength damage bonus/penalty of the attacking character |
| ^^slashWeap^^ | Resolves to 1 if the damage type of the weapon includes Slashing (or S), otherwise 0 |
| ^^pierceWeap^^ | Resolves to 1 if the damage type of the weapon includes Piercing (or P), otherwise 0 |
| ^^bludgeonWeap^^ | Resolves to 1 if the damage type of the weapon includes Bludgeoning (or B), otherwise 0 |
| ^^weapType^^ | Resolves to the 3 letter damage type of the weapon (S, P, B or any combination) |
| ^^ACvsNoMods^^ | Resolves to the targeted standard Armour Class macro call @{target|Select Target|AC-field} vs. a targeted opponent (only used in targeted attacks) |
| ^^ACvsSlash^^ | Resolves to the targeted Slashing damage Armour Class macro call @{target|Select Target|SlashAC-field} vs. a targeted opponent (only used in targeted attacks) |
| ^^ACvsPierce^^ | Resolves to the targeted Piercing Armour Class macro call @{target|Select Target|PierceAC-field} vs. a targeted opponent (only used in targeted attacks) |
| ^^ACvsBludgeon^^ | Resolves to the targeted Bludgeoning Armour Class macro call @{target|Select Target|BludgeonAC-field} vs. a targeted opponent (only used in targeted attacks) |
| ^^ACvsNoModsTxt^^ | Resolves to the text "No Mods" |
| ^^ACvsSlashTxt^^ | If this is a slashing weapon, resolves to the text "Slash", otherwise resolves to an empty string |
| ^^ACvsPierceTxt^^ | If this is a piercing weapon, resolves to the text "Pierce", otherwise resolves to an empty string |
| ^^ACvsBludgeonTxt^^ | If this is a bludgeoning weapon, resolves to the text "Bludgeon", otherwise resolves to an empty string |
| ^^ACvsSTxt^^ | If this is a slashing weapon, resolves to the text "S", otherwise resolves to an empty string |
| ^^ACvsPTxt^^ | If this is a piercing weapon, resolves to the text "P", otherwise resolves to an empty string |
| ^^ACvsBTxt^^ | If this is a slashing weapon, resolves to the text "B", otherwise resolves to an empty string |
| Monster Attack Templates | |
|---|---|
| ^^attk1^^ | Resolves to the name of the creature's attack 1, if provided (applies to monster attacks only) |
| ^^attk2^^ | Resolves to the name of the creature's attack 2, if provided (applies to monster attacks only) |
| ^^attk3^^ | Resolves to the name of the creature's attack 3, if provided (applies to monster attacks only) |
| ^^monsterCritHit^^ | Resolves to the critical hit dice roll value of the creature (applies to monster/creature attacks only) |
| ^^monsterCritMiss^^ | Resolves to the critical miss dice roll value of the creature (applies to monster/creature attacks only) |
| ^^monsterDmgMacro1^^ | Resolves to the correct Ability Macro name to use in an API button or macro call to run the matching Monster Ability damage 1 Macro |
| ^^monsterDmgMacro2^^ | Resolves to the correct Ability Macro name to use in an API button or macro call to run the matching Monster Ability damage 2 Macro |
| ^^monsterDmgMacro3^^ | Resolves to the correct Ability Macro name to use in an API button or macro call to run the matching Monster Ability damage 3 Macro |
| ^^monsterDmg1^^ | Depending on if the Player chose for Roll20 to roll the damage dice or to roll their own dice, resolves to one of (a) the damage dice specification for Monster attack 1, or (b) a Roll Query requesting the Player to enter a dice roll result |
| ^^monsterDmg2^^ | Depending on if the Player chose for Roll20 to roll the damage dice or to roll their own dice, resolves to one of (a) the damage dice specification for Monster attack 2, or (b) a Roll Query requesting the Player to enter a dice roll result |
| ^^monsterDmg3^^ | Depending on if the Player chose for Roll20 to roll the damage dice or to roll their own dice, resolves to one of (a) the damage dice specification for Monster attack 3, or (b) a Roll Query requesting the Player to enter a dice roll result |
| Melee Weapon Attack Templates | |
|---|---|
| ^^weapAttkAdj^^ | Resolves to the magical attack adjustment of the weapon |
| ^^weapStrHit^^ | Resolves to a 1 if the character's strength to-hit bonus applies to this weapon, or 0 otherwise |
| ^^profPenalty^^ | Resolves to any proficiency penalty incurred by the attacking character for using a non-proficient or related weapon |
| ^^specProf^^ | Resolves to 1 if the attacking character is a specialist in the weapon, otherwise 0 |
| ^^masterProf^^ | Resolves to 1 if the attacking character is a master (double specialised) in the weapon, otherwise 0 |
| ^^raceBonus^^ | Resolves to the race bonus of the attacking character with this weapon |
| ^^twoWeapPenalty^^ | Resolves to any penalty relevant if the attacking character is using two weapons to attack (is 0 for character classes that can use two weapons without penalty, such as rangers) |
| ^^weapDmgAdj^^ | Resolves to the magical damage adjustment of the weapon |
| ^^magicDmgAdj^^ | Resolves to any magical effect damage bonus or penalty resulting from magic currently in effect |
| ^^backstab^^ | Resolves to a 1 if a backstab is being attempted, otherwise 0 |
| ^^rogueLevel^^ | Resolves to the Rogue class level of the attacking character |
| ^^weapon^^ | Resolves to the name of the weapon |
| ^^weapCritHit^^ | Resolves to the critical hit dice roll value of the weapon |
| ^^weapCritMiss^^ | Resolves to the critical miss dice roll value of the weapon |
| ^^weapDmgSM^^ | Depending on if the Player chose for Roll20 to roll the damage dice or to roll their own dice, resolves to one of (a) the damage dice specification vs. Medium and smaller opponents for the weapon, or (b) a Roll Query requesting the Player to enter a dice roll result |
| ^^weapDmgL^^ | Depending on if the Player chose for Roll20 to roll the damage dice or to roll their own dice, resolves to one of (a) the damage dice specification vs. Large and larger opponents for the weapon, or (b) a Roll Query requesting the Player to enter a dice roll result |
| ^^weapStrDmg^^ | Resolves to a 1 if the character's strength damage bonus applies to this weapon, or 0 otherwise |
| ^^mwSMdmgMacro^^ | Resolves to the correct Ability Macro name to use in an API button or macro call to run the matching Melee weapon Ability damage Macro against Medium and smaller opponents |
| ^^mwLHdmgMacro^^ | Resolves to the correct Ability Macro name to use in an API button or macro call to run the matching Melee weapon Ability damage Macro against Large and larger opponents |
| Ranged Weapon Attack Templates | |
|---|---|
| ^^weapon^^ | Resolves to the name of the weapon |
| ^^dexMissile^^ | Resolves to the dexterity missile adjustment of the attacking character |
| ^^weapDexBonus^^ | Resolves to a 1 if the dexterity missile bonus applies to the weapon, otherwise 0 |
| ^^strAttkBonus^^ | Resolves to the strength to-hit bonus/penalty of the attacking character |
| ^^weapStrHit^^ | Resolves to a 1 if the character's strength to-hit bonus applies to this weapon, or 0 otherwise |
| ^^profPenalty^^ | Resolves to any proficiency penalty incurred by the attacking character for using a non-proficient or related weapon |
| ^^specProf^^ | Resolves to 1 if the attacking character is a specialist in the weapon, otherwise 0 |
| ^^masterProf^^ | Resolves to 1 if the attacking character is a master (double specialised) in the weapon, otherwise 0 |
| ^^raceBonus^^ | Resolves to the race bonus of the attacking character with this weapon |
| ^^twoWeapPenalty^^ | Resolves to any penalty relevant if the attacking character is using two weapons to attack (is 0 for character classes that can use two weapons without penalty, such as rangers) |
| ^^weapDmgAdj^^ | Resolves to the magical damage adjustment of the weapon |
| ^^rangeMod^^ | Resolves to the range attack modifier |
| ^^rangeN^^ | Resolves to 1 if the range is "Near", otherwise 0 |
| ^^rangePB^^ | Resolves to 1 if the range is "Point Blank", otherwise 0 |
| ^^rangeS^^ | Resolves to 1 if the range is "Short", otherwise 0 |
| ^^rangeM^^ | Resolves to 1 if the range is "Medium", otherwise 0 |
| ^^rangeL^^ | Resolves to 1 if the range is "Long", otherwise 0 |
| ^^rangeF^^ | Resolves to 1 if the range is "Far", otherwise 0 |
| ^^rangeSMLF^^ | Resolves to 1 if the range is not "Near" or "Point Blank", otherwise 0 |
| ^^ammoDmgAdj^^ | Resolves to the magical damage adjustment of the selected ammunition of the ranged weapon |
| ^^magicDmgAdj^^ | Resolves to any magical effect damage bonus or penalty resulting from magic currently in effect |
| ^^strDmgBonus^^ | Resolves to the strength damage bonus/penalty of the attacking character |
| ^^weapCritHit^^ | Resolves to the critical hit dice roll value of the weapon |
| ^^weapCritMiss^^ | Resolves to the critical miss dice roll value of the weapon |
| ^^ACvsNoModsMissile^^ | Resolves to the targeted Armour Class vs missiles macro call @{target|Select Target|ACmissile-field} vs. a targeted opponent (only used in targeted attacks) |
| ^^ACvsSlashMissile^^ | Resolves to the targeted Slashing damage Armour Class vs missiles macro call @{target|Select Target|SlashACmissile-field} vs. a targeted opponent (only used in targeted attacks) |
| ^^ACvsPierceMissile^^ | Resolves to the targeted Piercing Armour Class vs missiles macro call @{target|Select Target|PierceACmissile-field} vs. a targeted opponent (only used in targeted attacks) |
| ^^ACvsBludgeonMissile^^ | Resolves to the targeted Bludgeoning Armour Class vs missiles macro call @{target|Select Target|BludgeonACmissile-field} vs. a targeted opponent (only used in targeted attacks) |
| ^^ACvsNoModsMissileTxt^^ | Resolves to the text "No Mods" |
| ^^ACvsSlashMissileTxt^^ | If this is a slashing weapon, resolves to the text "Slash", otherwise resolves to an empty string |
| ^^ACvsPierceMissileTxt^^ | If this is a piercing weapon, resolves to the text "Pierce", otherwise resolves to an empty string |
| ^^ACvsBludgeonMissileTxt^^ | If this is a bludgeoning weapon, resolves to the text "Bludgeon", otherwise resolves to an empty string |
| ^^ACvsSmissileTxt^^ | If this is a slashing weapon, resolves to the text "S", otherwise resolves to an empty string |
| ^^ACvsPmissileTxt^^ | If this is a piercing weapon, resolves to the text "P", otherwise resolves to an empty string |
| ^^ACvsBmissileTxt^^ | If this is a slashing weapon, resolves to the text "B", otherwise resolves to an empty string |
| ^^ammoDmgSM^^ | Depending on if the Player chose for Roll20 to roll the damage dice or to roll their own dice, resolves to one of (a) the damage dice specification vs. Medium and smaller opponents for the ammunition used, or (b) a Roll Query requesting the Player to enter a dice roll result |
| ^^ammoDmgL^^ | Depending on if the Player chose for Roll20 to roll the damage dice or to roll their own dice, resolves to one of (a) the damage dice specification vs. Large and larger opponents for the ammunition used, or (b) a Roll Query requesting the Player to enter a dice roll result |
| ^^ammoStrDmg^^ | Resolves to a 1 if the character's strength damage bonus applies to the selected ammunition, or 0 otherwise |
| ^^ammoLeft^^ | Resolves to the quantity of the selected ammunition left after this attack |
| ^^rwSMdmgMacro^^ | Resolves to the correct Ability Macro name to use in an API button or macro call to run the matching Ranged weapon Ability damage Macro against Medium and smaller opponents |
| ^^rwLHdmgMacro^^ | Resolves to the correct Ability Macro name to use in an API button or macro call to run the matching Ranged weapon Ability damage Macro against Large and larger opponents |
Character (PC & NPC) Attack Templates
As previously described, the Attacks Database contains Attack Templates as Ability Macro entries on the Attributes and Abilities tab of a Character Sheet. For Characters and NPCs that attack using weapons "in-hand" (see AttackMaster API documentation for information on taking weapons "in-hand"), four standard Attack Templates are required: -ToHit; -DmgSM; -DmgL; and -Targeted-Attk.
The "To Hit" Template
The standard To Hit Attack Template looks like this:
MW-ToHit
^^toWhoPublic^^ &{template:^^defaultTemplate^^}{{name=^^tname^^ Attacks with their ^^weapon^^}}Specs=[MWtoHit,AttackMacro,1d20,Attack]{{Hits AC=[[([[^^thac0^^]][Thac0])-([[(([[^^weapAttkAdj^^]][Weapon+])+([[(^^strAttkBonus^^ * ^^weapStrHit^^)]][Strength+])+([[^^profPenalty^^]][Prof Penalty]+[[^^specProf^^]][Specialist]+[[^^masterProf^^*3]][Mastery])+([[^^raceBonus^^]][Race mod])+([[^^magicAttkAdj^^]][Magic hit adj])+([[^^twoWeapPenalty^^]][2-weap penalty]))]][Adjustments])-^^toHitRoll^^cs>^^weapCritHit^^cf<^^weapCritMiss^^]]
^^ACvsSlashTxt^^ ^^ACvsPierceTxt^^ ^^ACvsBludgeonTxt^^ attack}}{{Total Adjustments=[[(([[^^weapAttkAdj^^]][Weapon+])+([[(^^strAttkBonus^^ * ^^weapStrHit^^)]][Strength+])+([[^^profPenalty^^]][Prof Penalty]+[[^^specProf^^]][Specialist]+[[^^masterProf^^*3]][Mastery])+([[^^raceBonus^^]][Race mod])+([[^^magicAttkAdj^^]][Magic hit adj])+([[^^twoWeapPenalty^^]][2-weap penalty]))]]}}
^^toWho^^ &{template:^^defaultTemplate^^}{{name=Do Damage?}}{{desc=If successfully hit
[TSM Damage](~^^mwSMdmgMacro^^) or [LH Damage](~^^mwLHdmgMacro^^)}}
As with all RPGMaster database items, the Attack Templatre has a Specs section:
Specs=[MWtoHit,AttackMacro,1d20,Attack]
The four fields in the Specs data are the standard four used in all Specs fields: Entry Type (MWtoHit), Entry Class (AttackMacro), Handedness (in this case replaced by toHit dice roll spec 1d20), and Entry Supertype (Attack). The key field to note here is the ToHit Dice Roll Specification (which replaces the Handedness field). This can be any valid dice roll, and will be used for the ^^toHitRoll^^ template field if the Player selects Roll20 to roll the attack dice.
This Attack Template is formatted using a Roll20 Roll Template with a type specified using the ^^defaultTemplate^^ template field, but need not be - formatting is up to the creator of the Attack Template. It is important this information is displayed to the right people - Players that control a character, all Players as a public post, or just the DM for attacks by creatures & NPCs. The ^^toWhoPublic^^ template field will check if the attacking token represents a Character/NPC/Creature controlled by a Player and, if so, make a public post that all can see, but otherwise just whisper the results of the attack to the DM only. Similarly, ^^toWho^^ will whisper the attack information either only to the Player(s) that control the attacking character/creature or, if no one does, then to the DM.
The rest of the Attack Template defines the calculations using the API supplied data to display the Armour Class value that would be successfully hit by the attacking character, with the selected weapon under the current conditions. It also defines a display of the adjustments that are made to the dice roll which the Players and DM can hover a mouse over to get an explanation of the calculations. All the calculations and tag display are standard Roll20 functionality, so once the Attack Template Data Fields are replaced by actual values by the API and the resulting Ability Macro saved to the attacking character's Character Sheet, running it like any other Ability Macro will use only Roll20 functionality, and not involve use of the APIs.
The Attack Template shown above is a To Hit template for a Melee weapon attack. That for a Ranged weapon attack is very similar, just using some different and ranged attack related Template Fields.
The "Damage" Templates
There are always two damage Attack Templates to go with each To Hit Template, typically one for damage to Medium and smaller opponents and one for Large and larger. However, as will be seen when discussing the Oil Flask bespoke Attack Templates below, those are not always the outcomes of the two damage Templates. However, they do always start with MW-DmgSM and MW-DmgL for Melee weapon attacks, and RW-DmgSM and RW-DmgL for Ranged weapon attacks (optionally followed by a race, class or weapon name). The standard Damage Attack Template looks like this:
MW-DmgSM
^^toWhoPublic^^ &{template:^^defaultTemplate^^}{{name=^^tname^^ does damage with their ^^weapon^^}}Specs=[MWdmgSM,AttackMacro,1d20,Attack]{{Damage vs TSM=[[([[ ([[^^weapDmgSM^^]][Dice Roll])+([[^^strDmgBonus^^*^^weapStrDmg^^]][Strength+])+([[^^weapDmgAdj^^]][weapon+])+([[^^magicDmgAdj^^]][Magic dmg adj])+([[^^specProf^^*2]][Specialist+]+[[^^masterProf^^*3]][Mastery+])]][Adjustments])]] HP}}{{Total Plusses=[[[[^^strDmgBonus^^*^^weapStrDmg^^]][Strength+]+([[^^weapDmgAdj^^]][weapon+])+([[^^magicDmgAdj^^]][Magic dmg adj])+([[^^specProf^^*2]][Specialist+]+[[^^masterProf^^*3]][Mastery+])]]}}
The damage Attack Template works in the same way as the other Attack Templates as explained above for the ToHit template. While the Specs data includes the "To Hit" dice roll specification, this is not used in the damage Template, and is irrelevant. That field just needs to hold something, and a dice roll specification is what is expected. Hopefully, the rest of this damage Attack Template is self explanatory.
Monster Attack Templates
If a creature specified as a Monster on the Character Sheet uses in-hand weapons, as supported under the RPGMaster APIs, attacks with those weapons (Melee or Ranged) will use the standard To Hit and Damage Attack Templates described above. However, attacks by creatures that are specified on the Monster tab of the Advanced 2nd Edition character sheet, and under AD&D 2nd Edition rules, are much simpler than character attacks with in-hand weapons. The differences mean that such creatures require different Attack Templates. Attacks specified on the Monster tab use the Monster Attack Templates: Mon-Attk1, Mon-Attk2, Mon-Attk3, and Mon-Dmg1, Mon-Dmg2, Mon-Dmg3 (or the Targeted Attack Templates, see later). Remember that the AttackMaster API supports an extension of the Monster Attk fields on the Advanced 2nd Edition Character Sheet: each can contain a comma-separated list consisting of "attack name","dice roll","speed in segments" (see AttackMaster Help for details).
The Monster Attack and Damage Templates look like this:
Mon-Attk1
^^toWhoPublic^^ &{template:^^defaultTemplate^^}{{name=^^tname^^ attacks with their ^^attk1^^}}Specs=[MonAttk1,AttackMacro,1d20,Attack]{{Hits AC=[[ ( ([[^^thac0^^]][Thac0]) - ([[^^magicAttkAdj^^]][Magic hit adj]) - ^^toHitRoll^^cs>^^monsterCritHit^^cf<^^monsterCritMiss^^ )]]}}
^^toWho^^ &{template:^^defaultTemplate^^}{{name=Do Damage?}}{{desc=If this hits [Do Damage](~^^monsterDmgMacro1^^)}}
Mon-Dmg1
^^toWhoPublic^^ &{template:^^defaultTemplate^^}{{name=^^tname^^ does damage with their ^^attk1^^}}Specs=[MonDmg1,AttackMacro,1d20,Attack]{{Damage=[[(([[^^monsterDmg1^^]][^^attk1^^ Dmg])+([[^^magicDmgAdj^^]][Added Magic Dmg]))]] HP}}
Unsurprisingly, these work in exactly the same way as other Attack Templates.
Targeted Attack Templates
The AttackMaster API supports the DM (and optionally, Players) using "targeted attacks". This is an attack that prompts the DM / Player to select a target token, and then performs all attack and damage dice rolls at the same time, displaying the attack results alongside the Armour Class and Hit Points of the targeted opponent. This speeds the attack process even further than having the API do all the attack calculations. Note: the results of the attack are not applied to the targeted opponent - the results are still open to interpretation by the Players and DM, and circumstantial adjustment before manually applying them to the Token / Character Sheet of the opponent.
The Ranged weapon Attack Template looks like this:
^^toWho^^ &{template:^^defaultTemplate^^}{{name=^^tname^^ Attacks @{Target|Select Target|Token_name} with their ^^weapon^^}}Specs=[RWtargetedAttk,AttackMacro,1d20,Attack]{{Hits AC=[[([[^^thac0^^]][Thac0])-(([[^^weapAttkAdj^^]][Weapon+]) + ([[^^ammoDmgAdj^^]][Ammo+]) + ([[ ^^weapDexBonus^^*[[^^dexMissile^^]]]][Dexterity+] )+([[[[^^strAttkBonus^^]]*[[^^weapStrHit^^]]]][Strength+])+([[^^raceBonus^^]][Race mod])+([[^^profPenalty^^]][Prof penalty])+([[^^magicAttkAdj^^]][Magic Hit+])+([[^^twoWeapPenalty^^]][2-weap penalty])+([[^^rangeMod^^]][Range mod]))-^^toHitRoll^^cs\>^^weapCritHit^^cf\<^^weapCritMiss^^ ]] }}{{Target AC=^^ACvsNoModsTxt^^:^^ACvsNoModsMissile^^
^^ACvsSlashMissileTxt^^:^^ACvsSlashMissile^^ ^^ACvsPierceMissileTxt^^:^^ACvsPierceMissile^^ ^^ACvsBludgeonMissileTxt^^:^^ACvsBludgeonMissile^^}}{{Damage if hit SM=[[ floor( [[^^ammoDmgSM^^]][Dice roll] * [[(^^rangeN^^*0.5)+(^^rangePB^^*(1+^^masterProfPB^^))+(^^rangeSMLF^^*1)]]) + ([[^^rangePB^^*^^masterProfPB^^*2]])+ (([[^^ammoDmgAdj^^]][Ammo+])+([[^^magicDmgAdj^^]][Magic dmg+]) +([[^^strDmgBonus^^*^^ammoStrDmg^^]][Strength+])) ]]HP}}{{Damage if hit LH=[[ floor( [[^^ammoDmgL^^]][Dice roll] * [[(^^rangeN^^*0.5)+(^^rangePB^^*(1+^^masterProfPB^^))+(^^rangeSMLF^^*1)]]) + ([[^^rangePB^^*^^masterProfPB^^*2]]) + (([[^^ammoDmgAdj^^]][Ammo+])+([[^^magicDmgAdj^^]][Magic dmg+]) +([[^^strDmgBonus^^*^^ammoStrDmg^^]][Strength+])) ]]HP}}{{Target HP=^^targetHPfield^^ HP}}{{Ammo left=^^ammoLeft^^}}
The key difference, other than doing all of the calculations for the Armour Class hit and both the damage for Medium and smaller and Large and larger, is that several of the Template Fields used resolve to appropriately formatted Roll20 @{target|...} entries, that will display values from the targeted opponent's token and/or character sheet. The API searches for the most appropriate token and character sheet fields to resolve the targeted Template Fields to (it searches the attacking creature's data, and assumes all tokens are set up the same way): if using the standard RPGMaster token settings (as set by the CommandMaster API --abilities command or [Token Setup] DM's Macro button) it will find the data it needs on the token; otherwise it will first search other token fields, then standard Character Sheet character tab fields, then Character Sheet monster tab fields. If the API can't find AC or HP data, it will display appropriate text saying the data was not found, but will not cause an error. Thus it is sensible to use these Template Fields rather than statically defined @{target|...} commands.
8. Bespoke / Custom Attack Templates
All of the above examples and discussion have explored the standard Attack Templates distributed with the AttackMaster API. It will be the case that this will cater for around 95% of attacks and attack-like situations (e.g. there is a weapon called "Touch" which Spell Casters can use for touch-attack spells, which uses the standard Attack Templates without change to achieve the needed outcome). However, for that other 5% (or perhaps closer to 1%) of special cases you can define your own bespoke or custom Attack Templates. Being able to change the way attacks are calculated is also essential if you wish to adapt the API to work for game systems other than Advanced Dungeons & Dragons 2nd Edition.
As stated in Section 1, you should not add Attack Templates to the Attacks-DB database directly as, when updates are released, the whole database will be overwritten and your additions will be lost. Instead, create your own Character Sheet named Attack-DB-[any-name-you-want] and add Attack Templates to it. If you want to replace the Attack Templates provided for Melee weapons, Ranged weapons and/or Monster attacks, just create ones in your added database with the same Ability Macro name and they will automatically be used in preference to the standard versions.
As also mentioned previously, while Attack Templates are always called with names of the format given in Section 3, they do not have to result in standard attacks or damage - the calculations and resulting information provided to players can be whatever is needed as a result of that attack action. An example of this is included in the distributed Attacks-DB, the Oil Flask Attack Template set:
RW-ToHit-Oil-Flask
^^toWhoPublic^^ &{template:^^defaultTemplate^^}{{name=^^tname^^ throws a prepared oil flask}}Specs=[RWtoHit,AttackMacro,1d20,Attack]{{Hits AC=[[([[^^thac0^^]][Thac0])-([[([[^^weapAttkAdj^^]][Weapon+]) + ([[^^ammoDmgAdj^^]][Ammo+]) + ([[ ^^weapDexBonus^^*[[^^dexMissile^^]]]][Dexterity+] )+([[[[^^strAttkBonus^^]]*[[^^weapStrHit^^]]]][Strength+])+([[^^raceBonus^^]][Race mod])+([[^^profPenalty^^]][Prof penalty])+([[^^magicAttkAdj^^</b>]][Magic Hit+])+([[^^twoWeapPenalty^^]][2-weap penalty])+([[^^rangeMod^^]][Range mod])]][Adjustments])-^^toHitRoll^^cs\>^^weapCritHit^^cf\<^^weapCritMiss^^ ]]
^^ACvsSlashMissileTxt^^ ^^ACvsPierceMissileTxt^^ ^^ACvsBludgeonMissileTxt^^ attack}}{{Total Adjustments=[[([[^^weapAttkAdj^^]][Weapon+]) + ([[^^ammoDmgAdj^^]][Ammo+]) + ([[ ^^weapDexBonus^^*[[^^dexMissile^^]]]][Dexterity+] )+([[[[^^strAttkBonus^^]]*[[^^weapStrBonus^^]]]][Strength+])+([[^^raceBonus^^]][Race mod])+([[^^profPenalty^^]][Prof penalty])+([[^^magicAttkAdj^^]][Magic Hit+])+([[^^twoWeapPenalty^^]][2-weap penalty])+([[^^rangeMod^^]][Range mod])]]}}{{Ammo left=^^ammoLeft^^}}
^^toWho^^ &{template:^^defaultTemplate^^}{{name=Do Damage?}}{{desc=Select the appropriate result
[Direct hit](~^^rwSMdmgMacro^^) or [Grenade/Splash](~^^rwLHdmgMacro^^)}}
The To Hit Attack Template is very similar to a normal Ranged weapon Attack Template, except that instead of API buttons indicating damage rolls vs. different sized opponents, it provides one API button to select a [Direct Hit], and another selecting a [Grenade/Splash] outcome. Each of these still calls the same damage Attack Templates using the Template Fields provided but in this case, because the attack is with a weapon called Oil Flask, the Template Fields will resolve to calls to RW-DmgSM-Oil-Flask and RW-DmgL-Oil-Flask respectively, and these custom Attack Templates do damage in a very different way to a normal Ranged Weapon attack.
RW-DmgSM-Oil-Flask
^^toWhoPublic^^ &{template:^^defaultTemplate^^}{{name=^^tname^^'s oil flask scores a direct hit}}Specs=[RWdmgSM,AttackMacro,1d20,Attack]{{subtitle=Fire damage}}{{Round 1=Fire damage [[2d6]]}}{{Round 2=Will be rolled next round}}
!rounds --aoe @{target|Who's the target?|token_id}|circle|feet|0|7|0|fire|true --target single|@{selected|token_id}|@{target|Who's the target?|token_id}|Oil-fire|1|-1|Taking fire damage from burning oil|three-leaves
The Oil Flask version of the RW-DmgSM Attack Template caters for damage done by an Oil Flask successfully scoring a direct hit on an opponent. This results in a damage dice roll for this round of 2d6 with no modifiers, and then also makes an API call to the RoundMaster API with two stacked commands: an Area of Effect call to place fire on the opponent's token, and a Target call to add a status to the opponent's token which will last 2 rounds, causing a Status Effect to run in the second round to prompt for another damage roll of 1d6.
RW-DmgL-Oil-Flask
^^toWhoPublic^^ &{template:^^defaultTemplate^^}{{name=^^tname^^'s oil flask smashes in a ball of flame}}Specs=[RWdmgL,AttackMacro,1d20,Attack]{{subtitle=Fire damage}}{{Location=Drag the crosshair to where the oil flask smashed}}{{Splash=Those splashed take [[ceil([[1d6]]/2)]]HP fire damage}}
!rounds --aoe ^^tid^^|circle|feet|[[(^^rangeN^^*5)+(^^rangePB^^*10)+(^^rangeS^^*10)+(^^rangeM^^*20)+(^^rangeL^^*30)+(^^rangeF^^*30)-5]]|4|0|fire
The Oil Flask version of the RW-DmgL Attack Template caters for an Oil Flask that either missed its intended target, or is deliberately used as a grenade-like missile. This results in a dice roll of 1d3 splash damage to anyone in the area of effect, which is shown using a call to the RoundMaster API Area of Effect command which this time can be positioned where the oil flask landed.
RW-Targeted-Attk-Oil-Flask
^^toWho^^ &{template:^^defaultTemplate^^}{{name=^^tname^^ throws a prepared oil flask at @{Target|Select Target|Token_name}}}Specs=[RWtargetedAttk,AttackMacro,1d20,Attack]{{Hits AC=[[([[^^thac0^^]][Thac0])-(([[^^weapAttkAdj^^]][Weapon+]) + ([[^^ammoDmgAdj^^]][Ammo+]) + ([[ ^^weapDexBonus^^*[[^^dexMissile^^]]]][Dexterity+] )+([[[[^^strAttkBonus^^]]*[[^^weapStrHit^^]]]][Strength+])+([[^^raceBonus^^]][Race mod])+([[^^profPenalty^^]][Prof penalty])+([[^^magicAttkAdj^^]][Magic Hit+])+([[^^twoWeapPenalty^^]][2-weap penalty])+([[^^rangeMod^^]][Range mod]))-^^toHitRoll^^cs>^^weapCritHit^^cf<^^weapCritMiss^^ ]] }}{{Target AC=^^ACvsNoModsTxt^^:^^ACvsNoModsMissile^^
^^ACvsSlashMissileTxt^^:^^ACvsSlashMissile^^ ^^ACvsPierceMissileTxt^^:^^ACvsPierceMissile^^ ^^ACvsBludgeonMissileTxt^^:^^ACvsBludgeonMissile^^}}{{ =Direct Hit}}{{Target=[Direct hit on target](!rounds --aoe @{Target|Select Target|token_id}|circle|feet|0|6|0|fire|true --target single|@{selected|token_id}|@{Target|Select Target|token_id}|Oil-fire|1|-1|Taking fire damage from burning oil|three-leaves)}}{{Dmg Round 1=[[2d6]]HP fire damage}}{{Dmg Round 2=Roll next round}}{{. =Splash Damage}}{{Location=[Select where flask smashed](!rounds --aoe ^^tid^^|circle|feet|[[(^^rangeN^^*5)+(^^rangePB^^*10)+(^^rangeS^^*10)+(^^rangeM^^*20)+(^^rangeL^^*30)+(^^rangeF^^*30)-5]]|4|0|fire)}}{{Damage=[[ceil([[1d6]]/2)]]HP fire damage}}{{Target HP=^^targetHPfield^^ HP}}{{Ammo left=^^ammoLeft^^}}
The Oil Flask version of the RW-Targeted-Attk Attack Template combines the functions and calculations of the other Oil Flask custom Attack Templates in a single result display, with appropriate API buttons to implement the various outcomes of the attack.
Similar or entirely different custom Attack Templates can be created for other individual weapons with non-standard attack outcomes, or for individual classes of character, creatures, or races. Just use the Attack Template naming conventions described in Section 3, and add them to your own Attack Databases as described in Section 1, and you can give Players more interesting situations and means of dealing with them. When combined with the features and capabilities of the RoundMaster API and other APIs of the RPGMaster suite, the possibilities are endless!
