API:RPGMaster-WeaponsArmorDB
From Roll20 Wiki
 | Page Updated: 2022-04-02 |
Contents |
Weapon, Ammo and Armour Databases
General Database information
The RPGMaster APIs use a number of Character Sheets as databases to hold Ability Macros defining weapons, ammo, and items of armour and their specifications. The API is distributed with many weapon, ammo and armour definitions and it also checks for, creates and updates these Character Sheet databases on start-up. DMs can add their own weapons, ammo and armour to additional databases, but the databases provided are totally rewritten when new updates are released so the DM must add their own database sheets. If the provided databases are accidentally deleted, they will be automatically recreated the next time the Campaign is opened. Additional databases should be named as follows:
| Weapons: | additional databases: MI-DB-Weapons-[added name] where [added name] can be replaced with anything you want. |
| Ammo: | additional databases: MI-DB-Ammo-[added name] where [added name] can be replaced with anything you want. |
| Armour: | additional databases: MI-DB-Armour-[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 weapon, ammo or armour specified, and used to describe and provide specifications for using the commands with the AttackMaster API;
- Custom Attributes with the attribute name "ct-ability-macro-name", one per Ability Macro, which defines the speed and type for each item;
- An entry in a list on the character sheet in the spell book of the relevant Character Sheet tab (various spell books for different items - see entry below);
- Optionally, some entries come also with attributes that define Powers and Spells delivered by or stored on the item.
Note: a DM only needs to program the Ability Macro using the formats shown in the next section, and then run the !attk --check-db or !magic --check-db command, which will correctly parse the ability macro and set the rest of the database entries as needed.
Ability Macros can be whatever the DM wants and can be as simple or as complex as desired. Roll Templates are very useful when defining ability macros. When a Player or an NPC or Monster views the specifications of a weapon, ammunition or piece of armour, the APIs run the relevant Ability Macro from the databases as if it had been run by the Player from the chat window. All Roll20 functions for macros are available.
Replacing Provided Weapons
If you want to replace any item provided in any of the databases, you can do so simply by creating an Ability Macro in one of your own databases with 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.
Weapon & Ammunition Databases
Weapon databases are all character sheets that have names that start with MI-DB-Weapon (though in fact, weapons can be in any database starting with MI-DB- if desired), and can have anything put at the end, though those with version numbers of the form v#.# as part of the name will be ignored. Ammunition databases are similar, with the root database MI-DB-Ammo.
As previously stated, each weapon definition has 3 parts in the database (see Section 1): an Ability Macro with a name that is unique and matches the weapon, an Attribute with the name of the Ability Macro preceded by "ct-", and a listing in the database character sheet of the ability macro name separated by '|' along with other weapons. The quickest way to understand these entries is to examine existing entries. Do go to the root databases and take a look (but be careful not to alter anything unless you know what you're doing!)
Note: The DM creating new weapons does not need to worry about anything other than the Ability Macro in the database, as running the AttackMaster or MagicMaster -check-db MI-DB-Weapons command will update all other aspects of the database appropriately for all databases that have a name starting with or including 'MI-DB-Weapons', as long as the Specs and Data fields are correctly defined in the macro. Use the parameter 'MI-DB-Ammo' to check and update the ammunition databases. Running the command -check-db with no parameters will check and update all databases.
Ability macros can be added to a database just by using the [+Add] button at the top of the Abilities column in the Attributes and Abilities tab of the Database Character Sheet, and then using the edit "pencil" icon on the new entry to open it for editing. Ability macros are standard Roll20 functionality and not dependent on the API. Refer to the Roll20 Help Centre for more information.
Here are some examples:
Longsword
/w "@{selected|character_name}" &{template:2Edefault}{{name=Longsword}} {{subtitle=Sword}}{{Speed=[[5]]}} {{Size=Medium}}{{Weapon=1-handed melee long-blade}}Specs=[Longsword,Melee,1H,Long-blade]{{To-hit=+0 + Str bonus}}ToHitData=[w:Longsword, sb:1, +:0, n:1, ch:20, cm:1, sz:M, ty:S, r:5, sp:5]{{Attacks=1 per round + level & specialisation, Slashing}}{{Damage=+0, vs SM:1d8, L:1d12, + Str bonus}}DmgData=[w:Longsword, sb:1, +:0, SM:1d8, L:1d12]{{desc=This is a normal sword. The blade is sharp and keen, but nothing special.}}
The ability specification for this Longsword uses a Roll20 Roll Template, in this case defined by the Advanced D&D 2e Character Sheet by Peter B (see the documentation for the Character Sheet on Roll20 for specifications of this Roll Template), but any Roll Template you desire can be used. The entries in the Roll Template itself can be anything you desire, giving as much or as little information as you want. However, the important elements for the APIs are those highlighted. Each of these elements are inserted between the elements of the Roll Template, meaning they will not be seen by the player when the macro is run. Generally spaces, hyphens and underscores in the data elements are ignored, and case is not significant. Each element is described below:
Specs = [Type, Class, Handedness, Weapon Group]
The Specs section describes what weapon type and proficiency groups this weapon belongs to. These fields must be in this order. This format is identical for all database items, whether in these databases or others used by the Master series of APIs.
| Type | is the type of the weapon, often the same as the ability macro name without magical plusses. |
| Class | is one of Melee, Ranged, or Ammo. |
| Handedness | is #H, where # is the number of hands needed to wield the weapon. |
| Weapon Group | is the group of related weapons that the weapon belongs to. |
ToHitData = [w:Longsword, sb:1, +:0, n:1, ch:20, cm:1, sz:M, ty:S, r:5, sp:5]
The ToHitData section specifies the data relating to an attack with the weapon. These fields can be in any order.
| w: | <text> the name to display for attacks with this weapon |
| sb: | <0/1> strength bonus flag - specifies if the strength bonus is applicable to the To-Hit roll |
| +: | <[+/-]#> the magical attack bonus/penalty - an integer of any size |
| n: | <#[/#]> the basic number of attacks per round: the API will modify to account for specialisation and level |
| ch: | <1-20> the roll for a Critical Hit, shown in the API with a green border to the attack AC achieved |
| cm: | <1-20> the roll for a Critical Miss, shown in the API with a red border to the attack AC achieved |
| sz: | <T/S/M/L/H/G> the size of the weapon |
| ty: | <SPB> the type of damage done by the weapon - Slashing, Piercing and/or Bludgeoning |
| sp: | <#> the speed of the weapon in segments |
| r: | <[+/-/=]# [/#/#/#] > the range or range modifier of the weapon. Ranged weapons use PB / S / M / L |
The number of attacks per round, n:, can be an integer or a fraction such as 3/2 meaning 3 attacks every 2 rounds. If using the InitMaster API the Tracker will have the correct number of entries for the Character relating to the number of attacks in the current round.
The range for the weapon, r:, can be a single integer (representing the range of a melee weapon or simple ranged weapon) or a range modifier, starting with +, -, or =. The range modifier will amend the range of the ammo for a ranged weapon - ranged weapons vary their range with the ammo used. The weapon can use that range or modify it. Ranged weapon range modifiers can be of the form [[+/-]#/][+/-]#/[+/-]#/[+/-]# which will add or subtract a different modifier for each range ([Point Blank] / Short / Medium / Long - Point Blank range is optional)
DmgData = [w:Longsword, sb:1, +:0, SM:1d8, L:1d12]
The DmgData section specifies the data relating to the damage done by the weapon, and relates to melee weapons only (not ranged weapons). These fields can be in any order.
| w: | <text> the name to display for damage calculations for this weapon |
| sb: | <0/1> strength bonus flag - specifies if the strength bonus is applicable to the Damage roll |
| +: | <[+/-]#> the magical damage bonus/penalty - an integer of any size |
| sm: | <dice roll spec> the base dice roll vs. small/medium creatures excluding any magical bonus |
| l: | <dice roll spec> the base dice roll vs. large/huge creatures excluding any magical bonus |
Bastardsword+1
/w "@{selected|character_name}" &{template:2Edefault}{{name=Bastard Sword+1}}{{subtitle=Magic Sword}}{{Speed=[[5]]}}{{Size=Medium}}{{Weapon=1 or 2-handed melee long blade}}Specs=[Bastard-Sword,Melee,1H,Long-blade],[Bastard-Sword,Melee,2H,Long-blade]{{To-hit=+1 + Str Bonus}}ToHitData=[w:Bastard Sword+1, sb:1, +:1, n:1, ch:20, cm:1, sz:M, ty:S, r:5, sp:6,rc:uncharged],[w:Bastard Sword 2H+1, sb:1, +:1, n:1, ch:20, cm:1, sz:M, ty:S, r:5, sp:8,,rc:uncharged]{{Attacks=1 per round + specialisation & level, Slashing}}{{Damage=+1, 1-handed SM:1d8 L:1d12, 2-handed SM:2d4 L:2d8}}DmgData=[w:Bastard Sword+1,sb:1,+:1,SM:1d8,L:1d12],[w:Bastard Sword 2H+1,sb:1,+:1,SM:2d4,L:2d8]{{desc=This is a normal magical sword. The blade is sharp and keen, and is a +[[1]] magical weapon at all times.}}
The Bastardsword can be used either single handed or two handed with different to-hit and damage outcomes. This can be represented in the macro as shown here, with multiple specification sections. When using the AttackMaster API !attk --weapon command to take the Bastardsword in hand, choosing 1 hand (either left or right) will use the 1-handed specifications, and choosing to take it in Both Hands will use the 2-handed specifications.
All the field definitions are the same as for the Longsword example above, but there are (in this case) two sets of data for each section, the first set for 1-handed, the second set for 2-handed as defined by the handedness entry in the Specs section data sets.
Longbow
/w "@{selected|character_name}" &{template:2Edefault}{{name=Longbow}}{{subtitle=Bow}}{{Speed=[[8]]}}{{Size=Medium}}{{Weapon=Ranged 2-handed Bow}}Specs=[Longbow,Ranged,2H,Bow]{{To-hit=+0 + Dex Bonus}}ToHitData=[w:Longbow,sb:0,db:1,+:0,n:2,ch:20,cm:1,sz:L,ty:P,sp:8]{{Attacks=Piercing, 2 per round}}{{desc=This is a normal longbow. The wood is polished, the string taut, but nothing special.}}
A ranged weapon like a Longbow uses the same data section definitions as melee weapons except for the following additions and differences.
ToHitData=[w:Longbow,sb:0,db:1,+:0,n:2,ch:20,cm:1,sz:L,ty:P,sp:8]
The To-Hit section has an extra option:
| db: | <0/1> dexterity bonus flag - specifies if the dexterity bonus is applicable to the To-Hit roll. |
| r: | the range data is not provided because this weapon does not modify the range of its ammo, but could be provided if required. |
There is no DmgData section, as damage is defined by the ammo.
Flight-Arrow+2 (Ammunition Database)
/w "@{selected|character_name}" &{template:2Edefault}{{name=Flight Arrow+2}}{{subtitle=Magic Weapon}}{{Speed=As per bow}}{{Size=Small}}Specs=[Flight-Arrow,Ammo,1H,Arrow],[Flight-Arrow,Ammo,1H,Arrow]{{Ammo=+2,<br> <b>**Warbow**</b> vs. SM:1d8, L:1d8,<br> <b>**Other Bows**</b> vs. SM:1d6, L:1d6, Piercing}}AmmoData=[w:Flight Arrow+2, st:Bow, sb:1, +:2, SM:1d6, L:1d6],[w:Warbow Flight Arrow+2, t:warbow, sb:1, +:2, SM:1d8,L:1d8]{{Range=PB:30, others vary by bow<br> <b>**Shortbow:**</b><br> S:50, M:100, L150,<br> <b>**Longbow:**</b><br> S:60, M:120, L:210,<br> <b>**Warbow:**</b><br> S90, M:160, L:250,<br> <b>**Composite Sbow:**</b><br> S:50, M:100, L:180,<br> <b>**Composite Lbow:**</b><br> S:70, M:140, L:210}}RangeData=[t:longbow, +:2, r:3/6/12/21],[t:shortbow, +:2, r:3/5/10/15],[t:warbow, +:2, r:3/9/16/25],[t:compositelongbow, +:2, r:3/7/14/21],[t:compositeshortbow, +:2, r:3/5/10/18]{{desc=A magical Flight Arrow of very fine quality}}
Ammo has a different specification, as the To-Hit data sections are obviously part of the ranged weapon data. Instead it provides data on which weapons this can be ammo for, and what ranges it has for each. To determine this, it uses the weapon type and group-type set in the Specs section of each of the associated Ranged Weapons.
AmmoData=[w:Flight Arrow+2, st:Bow, sb:1, +:2, SM:1d6, L:1d6],[w:Warbow Flight Arrow+2, t:warbow, sb:1, +:2, SM:1d8,L:1d8]
The AmmoData section has mostly the same as the DmgData sections (order of fields is immaterial and spaces, hyphens and underscores ignored in type and supertype names), but repeated data sets relate to the data for different types of weapon, and in addition:
| t: | <weapon-type> the specific type of ranged weapon this data matches - takes priority over st:. An example is Longbow |
| st: | <group-type> the group-type of ranged weapon this data can be used for. An example is Bow, which means all bows |
| ru: | <-1|0|1> a flag specifying the reusability of the ammo: -1 = Breaks on use, 0 = Recoverable if fetched (if DM agrees not broken), 1 = automatically returns, never breaks |
| rc: | <text> if is 'charged', will break on use and cannot be recovered. Any other value means the ammunition is recoverable. |
RangeData=[t:longbow, +:2, r:3/6/12/21],[t:shortbow, +:2, r:3/5/10/15],[t:warbow, +:2, r:3/9/16/25], [t:compositelongbow, +:2, r:3/7/14/21],[t:compositeshortbow, +:2, r:3/5/10/18],[st:bow, +:2, r:3/5/10/15]
The RangeData section has one or more data sets relating to weapons that result in different ranges. The range specifications can have 3 or 4 parts: if 4, the first is for Point Blank range which is only relevant for specialists; the remaining 3 are always short, medium & long ranges.
Self-ammoed weapons e.g. Warhammer
/w "@{selected|character_name}" &{template:2Edefault}{{name=Warhammer}}{{subtitle=Hammer/Club}} {{Speed=[[4]]}}{{Size=Medium}}{{Weapon=1-handed melee or thrown club}}Specs=[Warhammer,Melee,1H,Clubs],[Warhammer,Ranged,1H,Clubs]{{To-hit=+0 + Str & Dex bonus}}ToHitData=[w:Warhammer, sb:1, +:0, n:1, ch:20, cm:1, sz:M, ty:B, r:5, sp:4],[ w:Warhammer, sb:1, db:1, +:0, n:1, ch:20, cm:1, sz:M, ty:B, sp:4]{{Attacks=1 per round + level & specialisation, Bludgeoning}}{{Damage=+0, vs SM:1d4+1, L:1d4, + Str bonus}}DmgData=[ w:Warhammer, sb:1, +:0, SM:1+1d4, L:1d4][]{{Ammo=+0, vs SM:1d4+1, L:1d4, + Str bonus}}AmmoData=[w:Warhammer,t:Warhammer,st:Throwing-club,sb:1,+:0,SM:1+1d4,L:1d4]{{Range=S:10, M:20, L:30}}RangeData=[t:Warhammer,+:0,r:1/2/3]{{desc=This is a normal warhammer. The blade is sharp and keen, but nothing special.}}
A melee weapon that can also be thrown, and is its own ammunition, is termed a "self-ammoed" weapon. Its definition combines the data elements of melee weapons, ranged weapons and ammunition.
Specs=[Warhammer,Melee,1H,Clubs],[Warhammer,Ranged,1H,Clubs]
Has two data sets, one as a melee weapon and one as a ranged weapon.
ToHitData=[w:Warhammer, sb:1, +:0, n:1, ch:20, cm:1, sz:M, ty:B, r:5, sp:4],[ w:Warhammer, sb:1, db:1, +:0, n:1, ch:20, cm:1, sz:M, ty:B, sp:4]
Also has two sets of data, each of which relates to the corresponding Specs set.
DmgData=[ w:Warhammer, sb:1, +:0, SM:1+1d4, L:1d4],[]
Does have two data sets, but the one corresponding to the ranged data is empty, as this data is in the Ammo data set.
AmmoData=[w:Warhammer,t:Warhammer,st:Throwing-club,sb:1,+:0,SM:1+1d4,L:1d4]
There is only 1 Ammo data set, as it only relates to the one weapon, itself.
RangeData=[t:Warhammer,+:0,r:1/2/3]
And only 1 Range data set, as it only relates to itself.
Artifact sword
/w "@{selected|character_name}" &{template:2Edefault} {{name=Jim the Sun Blade
Intelligent, Neutral}} {{subtitle=Magic Sword}} {{Speed=[[3]]}} WeapData=[w:Jim the Sun Blade,ns:5][cl:PW,w:Jims-Locate-Object,sp:100,lv:6,pd:1],[cl:PW,w:Jims-Find-Traps,sp:5,lv:6,pd:2],[cl:PW,w:Jims-Levitation,sp:2,lv:1,pd:3],[cl:PW,w:Jims-Sunlight,sp:3,lv:6,pd:1],[cl:PW,w:Jims-Fear,sp:4,lv:6,pd:2] {{Size=Special (feels like a Shortsword)}} {{Weapon=1 or 2 handed melee Long or Short blade}} Specs=[Bastard-sword|Short-sword,Melee,1H,Long-blade|Short-blade],[Bastard-sword|Short-sword,Melee,1H,Long-blade|Short-blade],[Bastard-sword,Melee,2H,Long-blade],[Bastard-sword,Melee,2H,Long-blade] {{To-hit=+2, +4 vs Evil + Str Bonus}} ToHitData=[w:Jim +2,sb:1,+:2,n:1,ch:20,cm:1,sz:M,ty:S,r:5,sp:3],[w:Jim vs Evil+4,sb:1,+:4,n:1,ch:20,cm:1,sz:M,ty:S,r:5,sp:3],[w:Jim 2H +2,sb:1,+:2,n:1,ch:20,cm:1,sz:M,ty:S,r:5,sp:3],[w:Jim 2H vs Evil+4,sb:1,+:4,n:1,ch:20,cm:1,sz:M,ty:S,r:5,sp:3] {{Attacks=1 per round}} {{Damage=+2, +4 vs Evil, + 1-handed SM:1d8 L:1d12, 2-handed SM:2d4 L:2d8}} DmgData=[w:Jim+2,sb:1,+:2,SM:1d8,L:1d12],[w:Jim vs Evil+4,sb:1,+:4,SM:2d4,L:2d8],[w:Jim 2H +2,sb:1,+:2,SM:1d8,L:1d12],[w:Jim 2H vs Evil+4,sb:1,+:4,SM:2d4,L:2d8] {{desc=An intelligent weapon: A Sun Blade called Jim (DMs Guide Page 185). It is Neutral. It needs its owner to be proficient with either a Short or Bastard Sword or promise to get such proficiency as soon as possible. It cannot be used by someone who is not proficient. It requires its owner to be Neutral on at least one of its axis, and may not be Evil. NG LN CN and of cause true N are all ok. Abilities:
**1:** It is +2 normally, or +4 against evil creatures, and does Bastard sword damage.
**2:** It feels and react as if it is a short sword and uses short sword striking time.
**3:** [Locate Object](!magic --mi-power @{selected|token_id}|Jims-Locate-Object|Jim-the-Sun-Blade|6) at 6th Level in 120’ radius (1x day).
**4:** [Detect traps](!magic --mi-power @{selected|token_id}|Jims-Find-Traps|Jim-the-Sun-Blade|6) of large size in 10’ radius (2xday).
**5:** [Levitation](!magic --mi-power @{selected|token_id}|Jims-Levitation|Jim-the-Sun-Blade|1) 3x a day for 1 turn (cast at 1st Level).
**6:** [Sunlight](!magic --mi-power @{selected|token_id}|Jims-Sunlight|Jim-the-Sun-Blade|6) Once a day, upon command, the blade can be swung vigorously above the head, and it will shed a bright yellow radiance that is like full daylight. The radiance begins shining in a 10-foot radius around the sword-wielder, spreading outward at 5 feet per round for 10 rounds thereafter, creating a globe of light with a 60-foot radius. When the swinging stops, the radiance fades to a dim glow that persists for another turn before disappearing entirely.
**7:** It has a special purpose namely Defeat Evil.
**8:** On hitting an Evil being it causes [Fear](!magic --mi-power @{selected|token_id}|Jims-Fear|Jim-the-Sun-Blade|6) for 1d4 rounds (unless saving throw is made). It can do this **twice a day** when the wielder desires.
**9:** It speaks Common and its name is Jim. It will talk to the party.
**10:** It has an ego of 16 and is from Yorkshire.
**11:** It will insist on having a Neutral wielder. (See Intelligent weapons on page 187 in DMG).
**12:** If picked by a player, it will be keen to become the players main weapon.
**13:** If picked up by a player who is not Neutral it will do them 16 points of damage}}
An artefact such as an intelligent sword with powers introduces data sets that specify the powers that the artefact has and how often they can be used. These match the API Buttons with calls to the MagicMaster API to enact the powers.
WeapData=[w:Jim the Sun Blade,ns:5][cl:PW,w:Jims-Locate-Object,sp:100,lv:6,pd:1],[cl:PW,w:Jims-Find-Traps,sp:5,lv:6,pd:2],[cl:PW,w:Jims-Levitation,sp:2,lv:1,pd:3],[cl:PW,w:Jims-Sunlight,sp:3,lv:6,pd:1],[cl:PW,w:Jims-Fear,sp:4,lv:6,pd:2]
The WeapData data sets can be used to define the powers that an artefact has (or stored spells - see MagicMaster API for more information on spell storing)
1st data set:
| w: | <text> The name of the weapon (not currently used) |
| ns: | <#> The number of spells or powers for which the specifications follow |
Subsequent data sets:
| cl: | < MU / PR / PW > The type of data: MU=Wizard, PR=Priest, PW=Power |
| w: | <text> Name of the spell or power: must be the same as the corresponding database definition |
| sp: | <#> Speed of the spell/power casting in segments (1/10ths of a round) |
| lv: | <#> The level at which the artefact will cast the spell/power (if omitted will use character's level) |
| pd: | <-1 / #> Number per day, or -1 for "use at will" |
Armour Databases
Armour databases are all character sheets that have names that start with MI-DB-Armour (as with weapons, this can be in any database starting with MI-DB- if desired), and can have anything put at the end, though those with version numbers of the form v#.# as part of the name will be ignored.
As previously stated and as per the weapon and ammunition databases, each armour definition has 3 parts in the database (see Section 1): the Ability Macro, the ct- attribute, and the listing (and occasionally attributes for powers and spells). The quickest way to understand these entries is to examine existing entries. Do go to the root databases and take a look (but be careful not to alter anything unless you know what you're doing!)
Note:The DM creating new armour entries does not need to worry about anything other than the Ability Macro in the database, as running the !attk --check-db MI-DB-Armour or !magic --check-db MI-DB-Armour command will update all other aspects of the database appropriately for all databases that have a name starting with or including 'MI-DB-Armour', as long as the Specs and Data fields are correctly defined. Running the command -check-db with no parameters will check and update all databases.
Here are some examples:
Chain Mail
/w "@{selected|character_name}" &{template:2Edefault}{{name=Chain Mail}}{{subtitle=Armour}}{{Armour=Chain Mail}}Specs=[Chain Mail,Armour,0H,Mail]{{AC=[[5]], -2 vs Slashing, +2 vs Bludgeoning}}ACData=[a:Chain Mail,st:Mail,t:Chain-Mail,+S:2,+P:0,+B:-2,+:0,ac:5,sz:L,wt:40]{{Speed=[[0]]}}{{Size=Large}}{{Immunity=None}}{{Saves=No effect}}{{desc=This armor is made of interlocking metal rings. It is always worn with a layer of quilted fabric padding underneath to prevent painful chafing and to cushion the impact of blows. Several layers of mail are normally hung over vital areas. The links yield easily to blows, absorbing some of the shock. Most of the weight of this armor is carried on the shoulders and it is uncomfortable to wear for long periods of time.}}
The ability specification for this suit of Chain Mail uses a Roll20 Roll Template, in this case defined by the Advanced D&D 2e Character Sheet by Peter B. The entries in the Roll Template itself can be anything you desire, giving as much or as little information as you want. However, the important elements for the AttackMaster API are those highlighted. Each of these elements are inserted between the elements of the Roll Template, meaning they will not be seen by the player when the macro is run. Generally spaces, hyphens and underscores in the data elements are ignored, and case is not significant. Each element is described below:
Specs = [Type, Class, Handedness, Weapon Group]
The Specs section describes what weapon type and proficiency groups this weapon belongs to. These fields must be in this order. This format is identical for all database items, whether in these databases or others used by the Master series of APIs.
| Type | is the type of the weapon, often the same as the ability macro name without magical plusses. |
| Class | is one of Melee, Ranged, or Ammo. |
| Handedness | is #H, where # is the number of hands needed to wield the weapon. |
| Weapon Group | is the group of related weapons that the weapon belongs to. |
Note:The armour Type (the 1st parameter) and Group-Type (the 4th parameter) are used to determine if the character is of a class that can use the armour.
Note: Armour that fits on the body generally does not take any hands to hold, and so the third field, Handedness, is set to '0H'.
ACData=[a:Chain Mail,st:Mail,+:0,ac:5,sz:L,wt:40]
The Armour Class Data (ACData) section holds data specific to the armour. As with other data sections, fields can be in any order, and spaces, hyphens, underscores and case are ignored.
| a: | < text > the name of the armour to be displayed. Often the same as the Ability. |
| st: | < group-type > the supertype of the armour, often the same as the fourth parameter of the Specs section. |
| +: | <[+/-]#> the magical bonus or penalty of the armour (defaults to 0 if not supplied). Plus is beneficial. |
| +s: | <[-/+]#> The magical adjustment specifically against slashing damage. Plus is beneficial. |
| +p: | <[-/+]#> The magical adjustment specifically against piercing damage. Plus is beneficial. |
| +b: | <[-/+]#> The magical adjustment specifically against bludgeoning damage. Plus is beneficial. |
| ac: | <[-]#> the base armour class (excluding magical bonuses) for this type of armour. |
| sz: | <[T/S/M/L/H]> The size of the item (not necessarily indicating its fit). |
| wt: | <#> The weight of the item in lbs (could be considered kg - or any measure - if everything is the same). |
Other possible fields are:
| t: | < armour-type > The specific armour type, often the same as the first parameter of the Specs section. |
| db: | <[-/+]#> The dexterity bonus or penalty that wearing the armour bestowes. Plus is beneficial. |
| +m: | <[-/+]#> The adjustment that the armour gives vs. missiles and ammunition of ranged weapons. Plus is beneficial. |
| sv*** | <[-/+]#> The adjustment to saving throws, where the *** is one of 'par', 'poi', 'dea', 'rod', 'sta', 'wan', 'pet', 'pol', 'bre', 'spe' or 'all' for modifying saves vs. paralysation, poison, death, rods, staves, wands, petrification, polymorph, breath weapons, spells, or all saving throws, respectively. Multiple entries can be provided. Plus is beneficial. |
| rc: | <recharging/curse type> Armour can be "cursed", but generally does not have charges. Default is "uncharged". See MagicMaster API documentation for more information on charges and curses. |
Shield+2
/w "@{selected|character_name}" &{template:2Edefault}{{name=Shield+2}}{{subtitle=Shield}}{{Shield=1-handed +2 Medium Shield made of wood & metal}}Specs=[Medium Shield,Shield,1H,Shields]{{AC=+[[2]] against all attacks from the front}}ACData=[a:Medium Shield+2, st:Shield, +:2,sz:M, wt:10] {{Speed=[[0]]}} {{Size=M}} {{Immunity=None}} {{Saves=No effect}} {{desc=All shields improve a character's Armor Class by 1 or more against a specified number of attacks. A shield is useful only to protect the front and flanks of the user. Attacks from the rear or rear flanks cannot be blocked by a shield (exception: a shield slung across the back does help defend against rear attacks). The reference to the size of the shield is relative to the size of the character. Thus, a human's small shield would have all the effects of a medium shield when used by a gnome.
*The medium shield* is carried on the forearm and gripped with the hand. Its weight prevents the character from using his shield hand for other purposes. With a medium shield, a character can protect against any frontal or flank attacks.}}
As can be seen here, the specification for a Shield is almost identical in structure to that of any other armour, the major difference being in the Specs section type field.
Note: The ac: field in the data section for a shield is always assumed to be '+1', meaning a shield adds 1 to the base AC before magical adjustments are taken into account. However, it can be specified as a different value, if desired.
Note: All shields except a Buckler must be taken in hand using the !attk --weapon command before the Armour Class system of the AttackMaster API adds it to the AC for the character. A Buckler is a special type of very small shield that is strapped to the arm and can counter only 1 blow per melee round, but allows both (all) hands to be free. In fact, any shield can have this functionality if desired, by setting the handedness field of the Specs section to be '0H', meaning it take no hands to hold it.
Armour-of-Vulnerability+-3
/w "@{selected|character_name}" &{template:2Edefault}{{name=Field Plate Armour of Vulnerability+/-3}}{{subtitle=Cursed Armour}}{{Armour=+/-3 selectively magical Field Plate}}Specs=[Armour-of-Vulnerability|Armour-of-Resistance,Armour,0H,Plate]{{AC=[[2]][[0-3]] better AC against Slashing damage
+[[3]] worse AC against any other type}}ACData=[a:Armour-of-Vulnerability+-3,st:Mail,+S:3,+P:-3,+B:-3,ac:2,sz:L,wt:60,sp:0,rc:cursed]{{Speed=0}}{{Size=Large}}{{Immunity=None}}{{Saves=No effect}}{{desc=***Curse.*** This armor is cursed, a fact that is revealed only when an identify spell is cast on the armor or you attune to it. Attuning to the armor curses you until you are targeted by the remove curse spell or similar magic; removing the armor fails to end the curse. While cursed, you have vulnerability to two of the three damage types associated with the armor (not the one to which it grants resistance).}}{{desc1=This armour provides resistance to Slashing damage only, but vulnerability to Piercing and Bludgeoning damage.
This armor is a combination of chain or brigandine with metal plates (cuirass, epaulettes, elbow guards, gauntlets, tasets, and greaves) covering vital areas. The weight is distributed over the whole body and the whole thing is held together by buckles and straps. This is the most common form of heavy armor.
For each +1 bonus to armor, regardless of the type of armor, the wearer's Armor Class moves downward (toward AC 2 . . . to 1 . . . to 0, -1, -2, and so on). Note, however, that Armor Class can never be improved beyond -10}}
This is a slightly more complex type of armour. It is a cursed item, and generally appears initially as Armour-of-Resistance+3, hence the Specs first parameter of armour type having two possible values, separated by '|'.
The use of the damage type specific magical adjustment fields can be seen in the data section, along with the use of the rc: field tag with the value 'cursed'.
Specs & Data field values
Below are lists of the current possible values for the item database Ability macro sections.
Specs sections
Specs=[Type, Item-Class, Handedness, Group-Type]
Weapon Types
There is an infinite list of weapon types: generally the type is the weapon name without any reference to magical plusses, so the Type of a Longsword+2 is Longsword. This Type is used to check for Proficiency.
Weapon Item-Classes
| Melee | Melee weapon which strikes while in hand |
| Ranged | Weapon that causes damage when thrown or with ammunition |
| Ammo | Ammunition for a ranged weapon of a specific Type or Group-Type |
Weapon Handedness
| 0H | A weapon that does not take a hand (e.g. spike on helm) |
| 1H | A weapon that is 1-handed, such as a short sword |
| 2H | A weapon that takes 2 hands to wield, such as a longbow |
| 3H | A weapon that takes 3 hands... |
| 4H | Etc (e.g. a siege weapon that needs 2 people to operate it) |
| ... | ... |
Weapon Group-Types
Weapon Group-Types determine related weapons for weapon proficiency, and whether it can be used by a Character of a specific class. The APIs use the definitions in the AD&D2e Fighter's Handbook section on 'Tight Groups', extended to cover certain additional weapons and weapon types. Any weapon group can be added at any time just by using it in a weapon definition. Examples currently in use are:
| Arrow | Club | Great-Blade | Long-Blade | Short-Blade | Whip |
| Axe | Crossbow | Hook | Medium-Blade | Sling | |
| Blowgun | Dart | Horeshoes | Pick | Spear | |
| Bow | Fencing-Blade | Innate | Polearm | Staff | |
| Bullet | Flail | Lance | Quarrel | Throwing-Blade |
Types and Group-Types that can be used by various Character Classes are defined in the Class-DB Character Class database. At the time of writing, the following restrictions are defined, but these can be altered at any time by adding or replacing the existing class definitions:
| Warrior | Any |
| Fighter | Any |
| Ranger | Any |
| Paladin | Any |
| Beastmaster | Any |
| Barbarian | Any |
| Defender | "axe", "club", "flail", "long-blade", "fencing-blade", "medium-blade", "short-blade", "polearm" |
| Wizard | (all types) "dagger", "staff", "dart", "knife", "sling" |
| Priest / Cleric | "club", "mace", "hammer", "staff" |
| Druid | "club", "sickle", "dart", "spear", "dagger", "scimitar", "sling", "staff" |
| Healer | "club", "quarterstaff", "mancatcher", "sling" |
| Priest of Life | "club", "quarterstaff", "mancatcher", "sling" |
| Priest of War | Any |
| Priest of Light | "dart", "javelin", "spear" |
| Priest of Knowledge | "sling", "quarterstaff" |
| Shaman | "long-blade", "medium-blade", "short--blade", "blowgun", "club", "staff", "shortbow", "horsebow", "hand-xbow" |
| Rogue / Thief | "club", "short-blade", "dart", "hand-xbow", "lasso", "shortbow", "sling", "broadsword", "longsword", "staff" |
| Bard | Any |
| Assassin | Any |
Armour Types
There is an infinite list of armour types: generally the type is the armour name without any reference to magical plusses, so the Type of Plate-Mail+2 is Plate-Mail. This Type is used to check for Proficiency.
Armour Item-Classes
| Armour | Any type of armour that does not need to be held to work |
| Shield | A barrier that is held in hand(s) and defends against one or more attacks from the front |
Armour Handedness
| 0H | Armour and Shields that are not held in the hand (e.g. a Buckler or a Helm) |
| 1H | Generally a type of Shield that must be held in a hand |
| 2H | Armour and Shields that use two hands, and/or prevent use of those hands for other things |
| 3H | Generally siege engines that shield against attacks... (not yet implemented) |
| ... | etc. |
Armour Group-Types
Armour Types and Group Types determine whether the armour can be used by various Character Classes. Here are the currently implemented restrictions:
| Warrior Any | |
| Fighter | Any |
| Ranger | Any |
| Paladin | Any |
| Beastmaster | Any |
| Barbarian | "padded", "leather", "hide", "brigandine", "ring-mail", "scale-mail", "chain-mail", "shield", "ring", "magic-item","cloak" |
| Defender | Any |
| Wizard (all types) | "magic-item", "ring", "cloak" |
| Priest / Cleric | Any |
| Druid | "leather", "padded", "hide", "wooden-shield", "magic-item", "ring", "cloak" |
| Healer | Any |
| Priest of Life | Any |
| Priest of War | Any |
| Priest of Light | "studded-leather", "ring-mail", "chain-mail", "shield", "ring", "magic-item", "cloak" |
| Priest of Knowledge | "magic-item", "ring", "cloak" |
| Shaman | "padded", "leather", "hide", "brigandine", "ring-mail", "scale-mail", "chain-mail", "splint-mail", "banded-mail", "shield", "ring", "magic-item", "cloak" |
| Rogue / Thief | Any |
| Bard | "padded", "leather", "hide", "brigandine", "ring-mail", "scale-mail", "chain-mail", "ring", "magic-item", "cloak" |
| Assassin | Any |
Data Sections
| Field | Format | Default Value | Description | Can be used in | |||||
|---|---|---|---|---|---|---|---|---|---|
| ToHit Data |
Dmg Data |
Ammo Data |
Range Data |
Weapon Data |
AC Data |
||||
| w: | < text > | '-' | Name to be displayed | X | X | X | |||
| w: | < text > | '-' | Name of spell or power | X | |||||
| a: | < text > | '-' | Name to be displayed | X | |||||
| t: | < text > | Type | X | X | X | ||||
| st: | < text > | Group Type (aka Tight-Group) | X | X | X | ||||
| sb: | 0 / 1 | 0 | Strength Bonus | X | X | X | |||
| db: | 0 / 1 | 1 | Dexterity Bonus | X | X | ||||
| +: | [ + / - ] # | 0 | Magical adjustment | X | X | X | X | X | |
| +m: | [ + / - ] # | 0 | Missile attack adjustment | X | |||||
| +s: | [ + / - ] # | 0 | Slashing damage adjustment | X | |||||
| +p: | [ + / - ] # | 0 | Piercing damage adjustment | X | |||||
| +b: | [ + / - ] # | 0 | Bludgeoning damage adjustment | X | |||||
| n: | # [ / # ] | 1 | Attacks per round | X | |||||
| dp: | # | 0 | Dancing proficiency adjustment | X | |||||
| ch: | 1 - 20 | 20 | Critical Hit roll value | X | |||||
| cm: | 1 - 20 | 1 | Critical Miss roll value | X | |||||
| sz: | [ t / s / m / l / h ] | Size of item | X | X | X | ||||
| r: | [# /] # / # / # | Range | X | X | |||||
| r: | [+/-]# [ / [+/-]# / [+/-]# / [+/-]# ] | 0 | Range Modifier | X | |||||
| ty: | SPB any combination | Type of damage | X | ||||||
| sp: | [-]# | 0 | Speed in segments (1/10 round) | X | X | ||||
| sm: | dice roll format | 0 | Damage roll for Small & Medium opponents | X | X | ||||
| l: | dice roll format | 0 | Damage roll for Large & Huge opponents | X | X | ||||
| ac: | [-]# | Armour class | X | ||||||
| wt: | # | 1 | Weight of item in lbs | X | X | ||||
| ns: | # | 0 | Number of spells & powers defined for item | X | X | ||||
| cl: | MU / PR / PW | Type of spell or power | X | ||||||
| lv: | # | 1 | Level at which spell/power is cast | X | |||||
| pd: | -1 / # | 1 | Number per day (power only) | X | |||||
| rc: | Charged / Uncharged / Rechargeable / Recharging / Self-charging / Cursed / Charged-Cursed / Recharging-Cursed / Self-charging-Cursed | Uncharged | Initial charged and Cursed status of item when found | X | X | ||||
Character Sheet data fields
The Character Sheet field mapping to the API script can be altered using the definition of the fields object. You can find the complete mapping for all APIs in the RPGMaster series, with an explanation of each, in a separate document.
