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

Personal tools

From Roll20 Wiki

Jump to: navigation, search
(Dancing weapons)
 
(27 intermediate revisions by one user not shown)
Line 1: Line 1:
{{revdate}}
+
<h1>Spell, Power & Magic Item Databases</h1>
{{main|API:Script Index}}
+
<h2>General Database information</h2>
{{script overview
+
{| role="presentation" class="wikitable mw-collapsible mw-collapsed"
|name=AttackMaster
+
|
|author=[[Richard E]]
+
|-
|version=2.046
+
|<p>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-upDMs 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:</p>
|lastmodified=2022-03-28
+
<table>
|code=AttackMaster
+
<tr><th scope="row">Wizard Spells:</th><td>additional databases: MU-Spells-DB-<i>[added name]</i> where <i>[added name]</i> can be replaced with anything you want.</td></tr>
|dependencies=None
+
<tr><th scope="row">Priest Spells:</th><td>additional databases: PR-Spells-DB-<i>[added name]</i> where <i>[added name]</i> can be replaced with anything you want.</td></tr>
|conflicts=None}}
+
<tr><th scope="row">Powers:</th><td>additional databases: Powers-DB-<i>[added name]</i> where <i>[added name]</i> can be replaced with anything you want.</td></tr>
'''AttackMaster''' API provides functions to manage weapons, armour & shields, including taking weapons in hand and using them to attack, for the AD&D 2E sheet. It's a part of the '''[[RPGMaster]]''' suite of APIs.
+
<tr><th scope="row">Magic Items:</th><td>additional databases: MI-DB-<i>[added name]</i> where <i>[added name]</i> can be replaced with anything you want.</td></tr>
 
+
<tr><th scope="row">Character Classes:</th><td>additional databases: Class-DB-<i>[added name]</i> where <i>[added name]</i> can be replaced with anything you want.</td></tr>
It uses the attack definitions defined in the [[API:RPGMaster-AttacksDB|<b>Attacks-DB</b> attack definition database]] (which the [[GM]] / Game Creator can add to or replace), taking into account: ranged weapon ammo management with ranges varying appropriately and range penalties/bonuses applied; Strength & Dexterity bonuses where appropriate; any magic bonuses to attacks that is in effect (if used with [[Script:RoundMaster|RoundMaster]] API effects); penalties & bonuses for non-proficiency, proficiency, specialisation & mastery; penalties for non-Rangers attacking with two weapons; use of 1-handed, 2-handed or many-handed weapons and restrictions on the number of weapons & shields that can be held at the same time; plus many other featuresThis API works best with the '''[[Script:MagicMaster|MagicMaster API]]''' and its databases which hold the data for automatic definition of weapons and armour.  However, some attack commands will generally work with manual entry of weapons onto the character sheet.  The <b>[[Script:CommandMaster|CommandMaster API]]</b> can be used by the GM to easily manage weapon proficiencies.
+
<tr><th scope="row">Attack Templates:</th><td>additional databases: Attacks-DB-<i>[added name]</i> where <i>[added name]</i> can be replaced with anything you want.</td></tr>
<p>Specification for weapons, armour & shields are implemented as ability macros in specific database character sheets.  This API comes with a wide selection of weapon and armour macros, held in the [[API:RPGMaster-WeaponsArmorDB|<b>MI-DB-Weapons, -Ammo and -Armour</b> databases]] that are created and updated automatically when the API is run.  If the MagicMaster API is also loaded, it provides many more specifications for standard and magic items that are beneficial to melee actions and armour class.  The [[GM]] can add to the provided items in the databases using standard Roll20 Character Sheet editing, as explained in the associated [[ and the specifications of weapons, ammo & armour in the [[API:RPGMaster-WeaponsArmorDB|Help Handout and Wiki page.]]</p>
+
</table>
 
+
<p><b>However:</b> the system will ignore any database with a name that includes a version number of the form "v#.#" where # can be any number or group of numbers e.g. MI-DB v2.13 will be ignored. This is so that the DM can version control their databases, with only the current one (without a version number) being live.</p>
= Forum =
+
<p>There can be as many additional databases as you want. Other Master series APIs come with additional databases, some of which overlap - this does not cause a problem as version control and merging unique macros is managed by the APIs.</p>
[https://app.roll20.net/forum/post/10607093/script-rpgmaster-apis-for-ad-and-d-2e RPGMaster Forum]
+
<p><b>Important Note:</b> all Character Sheet databases <b><u><i>must</i></u></b> have their <i>'ControlledBy'</i> value (found under the [Edit] button at the top right of each sheet) set to <i>'All Players'</i>.  This must be for all databases, both those provided (set by the API) and any user-defined ones.  Otherwise, Players will not be able to run the macros contained in them.</p>
 
+
<p>Each database has a similar structure, with:</p>
=How AttackMaster Works=
+
<ul>
==Specifying a token==
+
<li>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;</li>
<p>Most of the AttackMaster API commands need to know the token_id of the token that represents the character, NPC or creature that is to be acted upon. This ID can be specified in two possible ways:</p>
+
<li>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);</li>
<ol><li>explicitly in the command call using either a literal Roll20 token ID or using @{selected|token_id} or @{target|token_id} in the command string to read the token_id of a selected token on the map window,<br>or</li>
+
<li>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).</li>
<li>by having a token selected on the map window, not specifying the token_id in the command call, and allowing the API to discover the selected token_id.</li></ol>
+
</ul>
<p>In either case, if more than one token is selected at the time of the call then using either @{selected|token_id} to specify the token in the command call, or allowing the command to find a selected token, is likely (but not guaranteed) to take the first token that was selected.  To avoid ambiguity, it is generally recommended to make command calls with only one token selected on the map window.</p>
+
<p>However, as with all other Databases in the RPGMaster Suite of APIs, if the <i>Ability Macros</i> are correctly set up using the formats detailed in the Help Documentation, the <b>AttackMaster API</b> command <b>!attk --check-db database-name</b> will check the database and set up all other aspects for you, including the correct Custom Attributes and List entries.</p>
==Who can make AttackMaster API command calls==
+
<p>Ability Macros can be whatever the DM wants and can be as simple or as complex as desired. Roll Templates are very useful when defining class, spell, power and magic item ability macros, and are an essential part of Attack TemplatesWhen 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.</p>
<p>The majority of API command calls can be made by both the GM and all Players.  The typical means for command calls to be made is via Character Sheet Token Action Buttons (standard Roll20 functionality - see Roll20 Help Centre for information) which trigger Ability macros on the Character Sheet which simply make the API command call.  The Character Sheets can be controlled by the GM or Players.  The API knows if it is a GM or a Player that has triggered the call, and reacts accordingly.</p>
+
<h3>Replacing Classes, Attacks, Spells & Items</h3>
==Weapons that can be used==
+
<p>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.</p>
<p>Any weapon in the Weapons tables on the Character Sheet can be used for attacks.  However, the very best approach is to use the functions in this and other RPGMaster APIs (especially <b>MagicMaster</b>) to manage weapon choice.  Weapon definitions are held in weapon databases.  All standard weapons from the AD&D 2e Players Handbook are included, as well as many magic variations.</p>
+
==Allocating weapons to a Character==
+
<p>Weapons and ammunition are held in the Items table, which holds data on all items that the Character / NPC / creature has on their person - see the [[API:RPGMaster-CharacterSheets|RPGMaster Character Sheet & Token Setup handout & Wiki page]] regarding where the Item table is on the Character Sheet and the data that is held in it.  The added weapon should have a listing in the Weapons database to be fully functional.</p>
+
<p>The easiest way to enter the correct data into the Items table is to use the <b>[[Script:AttackMaster#Display_a_menu_to_do_actions_relating_to_attacks|!attk --menu]]</b> menu and select to edit weapons and armour, or use the <b>[[Script:AttackMaster#Adding_.26_removing_weapons_and_ammunition|!attk --edit-weapons]]</b> command to bring up the edit weapons menu,  or use the <b>MagicMaster API</b>, which supports [[Script:MagicMaster#Search_tokens_for_Magic_Items_and_Treasure|finding and looting weapons]] e.g. from a chest or a dead body, or just the DM or Player choosing weapons from a menu.  If a Ranged Weapon that uses ammunition is added, a quantity of the respective ammunition (or multiple types of ammunition) must also be added to the Items table.</p>
+
<p>Multiple weapons of many different types can be added, including those with magical properties.  The system will take all the weapon statistics into account using the information in the associated databases.</p>
+
 
+
==Selecting weapons to attack with==
+
<p>Each Character / NPC / creature has a defined number of hands (which can be different from 2), and AttackMaster provides [[Script:AttackMaster#Change_weapons_currently_in_hand|a menu to take any weapon(s) that are in the Items table in hand]].  Doing so enters all the correct information from the weapons database into the Weapons, Damage and Ranged Weapons tables, and the correct ammunition type(s) held in the Items table into the Ammo table.</p>
+
 
+
==Making attacks==
+
<p>Several different attack approaches are supported by the API.</p>
+
<table><tr><th scope="row">Roll20 rolls:</th><td>the system makes an attack dice roll and modifies it using the data on the Character Sheet, then displays the results to the Player.  Hovering the mouse over the displayed values of AC (armour class) hit and the Adjustments will display information explaining the values.  Buttons are displayed to make Damage rolls which can be used if the attack was deemed successful (the target's AC was the same or worse than the AC hit).</td></tr>
+
<tr><th scope="row">Player rolls:</th><td>the system prompts for the Player to roll a dice and enter the result, and then modifies the roll entered using the data on the Character Sheet and displays the result to the Player.  As above, hovering the mouse over the displayed results will explain how the amounts were calculated.  Buttons to make Damage rolls are also displayed, which will also prompt the user to make a dice roll (showing the dice that should be rolled).</td></tr>
+
<tr><th scope="row">Targeted attack:</th><td>A targeted attack 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 HP of the target for quick analysis.</td></tr></table>
+
 
+
==Ammunition==
+
<p>The system handles both Ranged weapons that take ammunition, such as bows and slings, and also “self-ammoed” Ranged weapons like daggers, that can be thrown at a target.  The quantity of ammunition or self-ammoed weapons is managed by the system: as they are used in attacks, the quantity in the Character's Item table decreases. A menu can be called to [[Script:AttackMaster#Ammunition_recovery|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 [[API:RPGMaster-WeaponsArmorDB#Flight-Arrow.2B2_.28Ammunition_Database.29|always breaks and can't be recovered]] (for example glass arrows) - this is charged ammo.</p>
+
 
+
==Ranged weapon and ammunition ranges==
+
<p>Each type of ammunition has a range with the weapon used to fire it.  These ranges can be different for different types of weapon - thus a longbow can fire an flight arrow further than a short bow, and a sheaf arrow has different ranges than the flight arrow with each.  The ranges that can be achieved by the weapon and ammunition combination are displayed when they are used in an attack, and the Player is asked to select which range to use, which then applies the correct range modifier to the attack roll.</p>
+
==Dancing weapons==
+
<p>The system can support any weapon becoming a [[Script:AttackMaster#Manage_a_dancing_weapon|dancing weapon]], with qualities that can be the same as or different from a Sword of Dancing.  In the system a dancing weapon does not have to be held in hand in order for it to be available for attacks and, if using the <b>InitiativeMaster API</b>, the weapon is also automatically added to the Turn Order Tracker for its attacks to be performed in battle sequence.  All of this can be achieved automatically if used with the <b>RoundMaster API</b>, with durations of 'warm up' and 'dancing' dealt with, as well as magical properties changing as the rounds progress - that function requires some editing of the Effects database to adapt for a particular weapon - see section 8 of the RoundMaster API documentation for details.</p>
+
 
+
==Armour Class management==
+
<p>The system continually checks the Armour Class of each Character / NPC / creature by examining the information on the Character Sheet and the items in the Item table.  Armour and Shields can be placed in the Items table which will be discovered, and the specifications from the Armour database used to calculate the appropriate AC under various conditions and display them to the Player.  The process the system made to achieve the calculated AC will be shown.</p>
+
<p>Many magic items have AC qualities, such as Bracers of Defence and Rings of Protection, and if the <b>MagicMaster API</b> is used these are also taken into account - invalid combinations will also be prevented, such as Rings of Protection with magical armourIf allocated to a Token Circle, the calculated AC is compared to the displayed Token AC and any difference highlighted - this may be due to magical effects currently in place, for instance - the highlight allows the Player to review why this might be.</p>
+
==Saves==
+
<p>The corollary to attacks is saves.  The system provides a menu to access, review, update and make saving throws and the appropriate modifiers.</p>
+
<p>The initial menu presented shows the saving throw table from the Character Sheet (always the one from the Character tab rather than the Monster Tab - monster saving throws should be copied to both).  Each type of save has a button to make the saving throw: the system will perform the roll and display the result with an indication of success or failure.  The menu also shows buttons to add a situational adjustment (as per the AD&D 2e PHB) and to modify the saving throw table.</p>
+
<p>The easiest way to set the correct saving throws for each type of save, based on class, level & race, is to use the <b>CommandMaster API</b> Character Sheet setup commands.</p>
+
 
<br>
 
<br>
 
+
|}
=How To Use AttackMaster=
+
<h2>Spells and Powers Databases</h2>
== Installation and Configuration ==
+
<p>Spells/Powers databases are all character sheets that have names that start with</p>
Copy the script's code, available from the menu on the right and stored at Roll20's [https://github.com/Roll20/roll20-api-scripts API GitHub Repository]. Paste the code into a new script in your campaign's [[API:Use_Guide#The_Script_Editor|API Script Editor]]. Save the new script and it will be available inside your campaign. It will install several new Character Sheets & Handouts: The handout '''AttackMaster Help''' provides a full manual of how to use AttackMaster.  The handout '''RPGMaster CharSheet Setup''' provides information on setting up a character sheet for use with AttackMaster.  The handout '''Weapon & Armour Database Help'' provides information on the databases that come with the API, and how to add to and change them.
+
<p> <b>Wizard Spells:</b> MU-Spells-DB-[added name]<br>
== Script Use ==
+
<b>Priest Spells:</b> PR-Spells-DB-[added name]<br>
After installing the script, refer the the handout '''AttackMaster Help''' for full information on useBelow is a copy of the contents of that handout.
+
<b>Powers:</b> Powers-DB-[added name]</p>
== Syntax ==
+
<p>Those with version numbers of the form v#.# as part of the name will be ignored.</p>
<p>The AttackMaster API is called using !attk.</p>
+
<p>As previously stated in the General Database Information section, each spell or power definition has 3 parts in the database: an Ability Macro with a name that is unique and matches the spell or power, 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 others of the same level in the spell book of the level of the spell or power.  The quickest way to understand these entries is to examine existing entries.  Do go to the root databases and take a look (but be careful not to alter anything unless you know what you're doing!)</p>
<pre>!attk --help</pre>
+
<p><b>Note:</b> The DM creating new spells and powers does not need to worry about anything other than the Ability Macro in the database, as running the command <b><i>[[Script:MagicMaster#Check_database_completeness_.26_integrity_.28GM_only.29|--check-db]]</i></b> will update all other aspects of the database appropriately for all databases, as long as the Specs and Data fields are correctly defined. Use the name of the particular database as a parameter to check and update just that database. Running the command <b><i>--check-db</i></b> with no parameters will check and update all databases.</p>
<p>Commands to be sent to the AttackMaster API must be preceded by two hyphens <b>--</b> as above for the <b>--help</b> command.  Parameters to these commands are separated by vertical bars ‘|’, for example:</p>
+
<p>Ability macros can be added to a database just by using the [+Add] button at the top of the Abilities column in the Attributes and Abilities tab of the Database Character Sheet, and then using the edit "pencil" icon on the new entry to open it for editing.  Ability macros are standard Roll20 functionality and not dependent on the APIRefer to the Roll20 Help Centre for more information.</p>
<pre>!attk --attk-hit token_id | [message] | [monster weap1] | [monster weap2] | [monster weap3]</pre>
+
<p><b>The Ability Macro</b> for a spell may look something like this:</p>
<p>If optional parameters are not to be included, but subsequent parameters are needed, use two vertical bars together with nothing between them, e.g.</p>
+
<h3>Sleep</h3>
<pre>!attk --checkac token_id || [SADJ / PADJ / BADJ]</pre>
+
<p style="display: inline-block; background-color: lightgrey; border: 1px solid black; padding: 4px; color: dimgrey; font-weight: extra-light;">/w "@{selected|character_name}" <nowiki>&{template:2Espell}{{title=@{selected|casting-name} casts Sleep as a level @{selected|casting-level} caster}}{{splevel=Level 1 Wizard}}{{school=Enchantment/Charm}}</nowiki><span style="color:green">Specs=[Sleep,MUspellL1,1H,Enchantment-Charm]</span><nowiki>{{range=90 ft}}{{components=V, S, M}}{{duration=[[5*({10,@{selected|casting-level}}kl1)]] Rounds}}{{time=1}}{{aoe=[30ft Cube](</nowiki><span style="color:red">!rounds --aoe @{selected|token_id}|square|feet|90|30||dark</span><nowiki>)}}{{save=None}}{{damage=[Sleep them](</nowiki><span style="color:red">!rounds --target area|@{selected|token_id}|&#64;{target|Select who to sleep|token_id}|Sleep|[[5*({10,@{selected|casting-level}}kl1)]]|-1|Snoring away, shake to awaken|sleepy</span>)}}<span style="color:blue">SpellData=[w:Sleep,lv:1,sp:1,gp:0.01,cs:VSM]</span><nowiki>{{effects=Up to [2d4](!\&#13;\&#47;r 2d4) Hit Dice of creatures with 4 HD or less are put to sleep beginning with the lowest HD creatures in the Area of Effect.}}{{materials=a pinch of fine sand, rose petals, or a live cricket.}}</nowiki></p>
<p>Commands can be stacked in the call, for example:</p>
+
<p>The ability specification for this Sleep spell 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 MagicMaster API are those highlighted.  In red, two API buttons grant the player access to run RoundMaster API commands to show the Area of Effect of the spell, and then to mark affected tokens with a "Sleepy" status.  Each of the elements important to the database are inserted between the elements of the Roll Template, meaning they will not be seen by the player when the macro is run. Generally spaces, hyphens and underscores in the data elements are ignored, and case is not significant. Each element is described below:</p>
<pre>!attk --checkac token_id | [ SILENT ] | [SADJ / PADJ / BADJ] –weapon token_id</pre>
+
<pre>Specs = [Type, Class, Handedness, Spell School]</pre>
<p>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 documentParameters 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).</p>
+
<p>The Specs section describes what spell type and school this spell 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. Where there are multiple answers for a field, separate each by '|'. <b>Note:</b>Only A-Z, a-z, 0-9, hyphen/minus(-), plus(+), equals(=) point(.) and vertical bar(|) are allowed.  Replace any forward slash with hyphen.</p>
 +
<table>
 +
<tr><th scope="row">Type</th><td>the type of the spell, often the same as the ability macro name.</td></tr>
 +
<tr><th scope="row">Class</th><td>one of MUSpellL#, PRSpellL#, or Power, where # is replaced by the spell level number.</td></tr>
 +
<tr><th scope="row">Handedness</th><td>#H, where # is the number of hands needed to cast the spell - i.e. does it have a somatic component.</td></tr>
 +
<tr><th scope="row">Spell School</th><td>the group of related spells that the spell belongs to.</td></tr>
 +
</table>
 +
<pre>SpellData=[w:Sleep,lv:1,sp:1,gp:1,cs:VSM]</pre>
 +
<p>The SpellData section specifies the data relating to the use of the spell.  These fields can be in any order.</p>
 +
<table>
 +
<tr><th scope="row">w:</th><td>&lt;text&gt;</td><td>the name of the spell</td></tr>
 +
<tr><th scope="row">sph:</th><td>&lt;text&gt;</td><td>the sphere of a priest spell (not used for wizard spells)</td></tr>
 +
<tr><th scope="row">lv:</th><td>&lt;#&gt;</td><td>the level of the spell</td></tr>
 +
<tr><th scope="row">sp:</th><td>&lt;[-]# or dice roll spec&gt;</td><td>the casting time in segments for the spell.  Can be >10 e.g. 20 for 2 rounds, or negative, or even a dice roll</td></tr>
 +
<tr><th scope="row">gp:</th><td>&lt;#[.#]&gt;</td><td>the cost of the material components of the spell in GP: fractions converted to SP & CP</td></tr>
 +
<tr><th scope="row">cs:</th><td>&lt;VSM&gt;</td><td>the component of the spell (Verbal, Somatic, Material) - can be any combination</td></tr>
 +
</table>
 +
<p>The casting time (or speed) <b>sp:</b> can be negative, meaning it gives a negative modifier to individual initiative (if <b>InitMaster API</b> is being used)It can also be greater than 10 segments, meaning it takes longer than 1 Round to cast.  Multiply the number of Rounds it will take to cast by 10, or the number of Turns it will take to cast by 100 (if using the <b>InitMaster API</b> the rounds will be automatically counted down and the spell actually cast in the appropriate round, unless the casting is interrupted).  It can also be a dice roll specification, which will be rolled at the point that a character selects the spell, power or item to use in a particular round, which means the speed can vary from round to round.  Potions are always of this nature (see the AD&D2e DMG p141).</p>
 +
<p>The cost of material components, <b>gp:</b>, is deducted from the Caster's money on their Character Sheet each time the spell is cast.  The GM is informed of the spell being cast, by whom, and how much money it cost and how much money the Caster has left for each casting.</p>
 +
<p>The components of the spell, <b>cs:</b>, is currently not used and is for future expansion capabilities.</p>
 +
<p><b>The Ability Macro</b> for a Power may look something like this:</p>
 +
<h3>Turn Undead</h3>
 +
<p style="display: inline-block; background-color: lightgrey; border: 1px solid black; padding: 4px; color: dimgrey; font-weight: extra-light;">/w "@{selected|character_name}" <nowiki>&{template:2Espell}{{title=@{selected|token_name} attempts to Turn Undead as a level @{selected|pr-casting-level} @{selected|class3}}} {{splevel=Power}} {{school=Necromancy}}</nowiki><span style="color:green">Specs=[Turn-Undead,Power,1H,Necromancy]</span><nowiki>{{components=V,S}}{{time=[[10]]}}{{range=0}}{{duration=Until broken}}{{aoe=Undead within line of sight}}{{save=See turning table}}{{reference=PHB p103}}{{damage=[Roll 1d20](</nowiki><span style="color:red">!&#13;&#47;r 1d20 check vs. your turning table</span><nowiki>) then if successful [Turn Them](</nowiki><span style="color:red">!rounds --target area|@{selected|token_id}|&#64;{target|Select undead|token_id}|Turned|99|0|Turned undead, flee if free-willed, stand aside if controlled|screaming</span>)}}<span style="color:blue">SpellData=[w:Turn Undead, sp:10, cs:VS]</span><nowiki>{{effects=**Remember that Paladins turn as a Priest of 2 levels lower.**<br>
 +
Attempting to turn counts as an action, requiring one round and occurring during the character's turn in the initiative order (thus, the undead may get to act before the character can turn them). The mere presence of the character is not enough--a touch of drama from the character is important. Speech and gestures are important, so the character must have his hands free and be in a position to speak. However, turning is not like spellcasting and is not interrupted if the character is attacked during the attempt.<br>
 +
To resolve a turning attempt, look on Table 61. Cross-index the Hit Dice or type of the undead with the level of the character (two levels lower for a paladin). If there is a number listed, roll 1d20. If the number rolled is equal to or greater than that listed, the attempt is successful. If the letter "T" (for "turned") appears, the attempt is automatically successful without a die roll. If the letter "D" (for "dispel") is given, the turning utterly destroys the undead. A dash (--) means that a priest or paladin of that level cannot turn that type of undead. A successful turn or dispel affects 2d6 undead. If the undead are a mixed group, the lowest Hit Dice creatures are turned first.<br>
 +
Only one die is rolled regardless of the number of undead the character is attempting to turn in a given round. The result is read individually for each type of undead.}}{{material=The Priest's holy symbol}}</nowiki></p>
 +
<p>Essentially, Powers are just Spells by another name, that can be cast multiple times per day, and are innate to the Character's class, or to a creature.  The specification is, therefore, almost identical to a spell.  In the author's campaigns, Powers do not consume material components and therefore do not cost money to use (except in rare circumstances) hence there being no <b>gp:</b> specification (it defaults to 0gp), but other DMs can add material costs for Powers if desired.  Powers are all 1 level, hence no <b>lv:</b> specification.</p>
 
<br>
 
<br>
 
+
<h2>Magic Item Databases</h2>
=Command Index=
+
<p>Magic Item databases are all character sheets that have names such as</p>
===Menus===
+
<p> <b>Magic Items:</b> MI-DB-[added name]</p>
<pre>--menu [token_id]
+
<p>And can have anything put at the end, though those with version numbers of the form v#.# as part of the name will be ignored.</p>
--other-menu [token_id]</pre>
+
<p>As previously stated and as for other magic, each magic item definition has 3 parts in the database (see Section 1): an Ability Macro with a name that is unique and identifies the magic item, 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 others of the same magic item type, which is one of: Potion, Scroll, Rod/Stave/Wand, Weapon & Ammo, Armour, Ring, Miscellaneous, and also DM Only magic items.  The quickest way to understand these entries is to examine existing entries.  Do go to the root database and take a look (but be careful not to alter anything unless you know what you're doing!)</p>
===Attacking commands===
+
<p><b>Note:</b> The DM creating new magic items does not need to worry about anything other than the Ability Macro in the database, as running the command <b><i>[[Script:MagicMaster#Check_database_completeness_.26_integrity_.28GM_only.29|--check-db]]</i></b> will update all other aspects of the database appropriately for all databases, as long as the Specs and Data fields are correctly defined. Use the name of the particular database as a parameter to check and update just that database.</p>
<pre>--attk-hit [token_id] | [message] | [monster weap1] | [monster weap2] | [monster weap3]
+
<p>Ability macros can be added to a database just by using the [+Add] button at the top of the Abilities column in the Attributes and Abilities tab of the Database Character Sheet, and then using the edit "pencil" icon on the new entry to open it for editing.  Ability macros are standard Roll20 functionality and not dependent on the API.  Refer to the Roll20 Help Centre for more information.</p>
--attk-roll [token_id] | [message] | [monster weap1] | [monster weap2] | [monster weap3]
+
<p><b>The Ability Macro</b> may look something like this:</p>
--attk-target [token_id] | [message] | [monster weap1] | [monster weap2] | [monster weap3]
+
<h3>Oil-of-Etherealness</h3>
--twoswords [token_id]|[prime-weapon]</pre>
+
<p style="display: inline-block; background-color: lightgrey; border: 1px solid black; padding: 4px; color: dimgrey; font-weight: extra-light;">/w "@{selected|character_name}" <nowiki>&{template:2Espell}{{title=Oil of Etherealness}} {{splevel=Oil}} {{school=Alteration}}</nowiki><span style="color:green">Specs=[Oil of Etherealness,Potion,1H,Alteration]</span><nowiki>{{components=M}}{{time=[[3]] rounds after application}} </nowiki><span style="color:blue">PotionData=[sp:30,rc:charged]</span><nowiki>{{range=User}}{{duration=4+1d4 turns}} {{aoe=User}} {{save=None}} {{healing=[Become Ethereal](</nowiki><span style="color:red">!rounds --target single|@{selected|token_id}|&#64;{target|Select a target|token_id}|Oil-of-Etherealness|&#91;[10*(4+1d4)]&#93;|-1|Ethereal|Ninja-mask</span><nowiki>)}}{{effects=This potion is actually a light oil that is applied externally to clothes and exposed flesh, conferring etherealness. In the ethereal state, the individual can pass through solid objects in any direction - sideways, upward, downward - or to different planes. The individual cannot touch non-ethereal objects.<br>
===Weapon Management===
+
The oil takes effect three rounds after application, and it lasts for 4+1d4 turns unless removed with a weak acidic solution prior to the expiration of its normal effective duration. It can be applied to objects as well as creatures. One potion is sufficient to anoint a normal human and such gear as he typically carries (two or three weapons, garments, armor, shield, and miscellaneous gear). Ethereal individuals are invisible.}}{{materials=Oil}}</nowiki></p>
<pre>--weapon [token_id]
+
<p>You might notice that the structure of this macro is extremely similar to that of a spell: indeed, it uses the same Roll Template.  As this is an Oil that achieves the same effect as a spell, this is not surprising.</p>
--dance [token_id] | weapon  | [ STOP ]
+
<p>However, there is one new field in the data section (in this case called the PotionData section):</p>
--mod-weapon [token_id] | weapon | MELEE / RANGED / DMG / AMMO | adjustments
+
<table>
--quiet-modweap [token_id] | weapon | MELEE / RANGED / DMG / AMMO | adjustments
+
<tr><th scope="row">rc:</th><td>&lt;MI-type&gt;</td><td>the recharging/curse type of the magic item.</td></tr>
--edit-weapons [token_id]</pre>
+
</table>
===Ammunition Management===
+
<p>All magic items have a recharging/curse type: for details, see the <b>[[Script:MagicMaster#DM.2FGM_version_of_Magic_Item_management|--gm-edit-mi]]</b> command in the MagicMaster API help documentation.  If not supplied for a magic item definition, it defaults to uncharged.  Generally, items in the database are not cursed-, but can have their type changed to cursed or some recharging cursed type when the DM stores them in a container or gives them to a Character using the <b>--gm-edit-mi</b> command.</p>
<pre>--ammo [token_id]
+
<p>Other magic items might use different structures, and be more complex:</p>
--setammo [token_id] | ammo_name | [ [+/-]cur_qty / = ] | [ [+/-]max_qty / = ] | [ SILENT ]</pre>
+
<h3>Bead-of-Force</h3>
===Armour Class and Saving Throws===
+
<p style="display: inline-block; background-color: lightgrey; border: 1px solid black; padding: 4px; color: dimgrey; font-weight: extra-light;">/w "@{selected|character_name}" <nowiki>&{template:'+fields.defaultTemplate+'}{{name=Bead of Force}}{{subtitle=Magic Item}}</nowiki><span style="color:green">Specs=[Bead of Force,Miscellaneous,1H,Evocation]</span><nowiki>{{Speed=[[0]]}}</nowiki><span style="color:blue">MiscData=[w:Bead of Force,sp:0,rc:charged]</span><nowiki>{{Size=Tiny}}{{Range=[Up to 30yds](</nowiki><span style="color:red">!rounds --aoe @{selected|token_id}|circle|yards|0|60||dark|true</span><nowiki>)}}{{damage=[5d4](!&#13;&#47;gmroll 5d4 damage from Bead of Force in 10ft redius) damage in 10ft radius}}{{duration=3d4 rounds}}{{Save=[To escape sphere](!&#13;&#47;gmroll 1d20 Save vs. spell or captured in *Sphere of Force*)}}{{Effect=[Trapped in Sphere](</nowiki><span style="color:red">!rounds --target area|@{selected|token_id}|Bead-of-Force|8|-1|'Held in Sphere of Force'|fishing-net</span><nowiki>)}}{{desc=These small, black spheres might be mistaken for common beads, marbles, or unusually black but lusterless pearls. From 5-8 of these beads are usually found at one time. Each is about three-quarters of an inch in diameter and quite heavy, weighing almost an ounce. One can be hurled up to 30 yards.<br>
<pre>--edit-armour [token_id]
+
Upon impact, the bead sends forth a burst of force that inflicts 5d4 points of damage upon all creatures within a 10-foot radius of its center. Each victim is allowed a saving throw vs. spell. Those who save will be thrown out of the blast area, but those who fail to save will be encapsulated by a sphere of force after taking damage.<br>
--checkac [token_id] | [ SILENT ] | [SADJ / PADJ / BADJ]
+
The sphere will form around any and all such creatures in the 10-foot-radius area, even those of large size, and will persist for 3d4 rounds. Victims will be unable to escape except by the same means and used to bring down a wall of force spell.}}</nowiki></p>
--save [token_id] | [situation-mod]</pre>
+
<p>The Bead of Force ability macro uses a Default Roll Template, which means the only mandatory field is the {{name=}} field, and the DM can define any other fields they want to describe and enact the magic item.  Here, an API button exists to do a saving throw with documented outcomes, and another API button can target an area with multiple tokens in to entrap them (if the DM rejects or confirms as they make or fail each saving throw).</p>
===Other Commands===
+
<pre>--help
+
--check-db [ db-name ]
+
--handshake from | [cmd]
+
--hsq from | [cmd]
+
--hsr from | [cmd] | [TRUE/FALSE]
+
--debug [ ON / OFF ]</pre>
+
 
<br>
 
<br>
=Command Details=
+
<h2>Magic Items with Powers or Spell-Storing</h2>
==Menus==
+
<p>Some magic items, especially artefacts and sentient items, can store spells and/or have powers similar to charactersMagicMaster supports magic items of this type to a degree, although there are inevitably exceptions that the DM will have to get creative in their development!  These items use API buttons that call various MagicMaster commands to deliver their capabilities.</p>
===Display a menu to do actions relating to attacks===
+
<p>First to note is that <b>items that have powers and spells use spell slots in the owning character's character sheet</b>.  These spell slots should not be used by characters in your campaign.  If they are, errors might occur.  By default, on the AD&D2E character sheet the system uses Wizard Level 14 spell slots for magic item powers, and Wizard Level 15 spell slots for spell-storing magic items.  As standard AD&D2E only has spells up to level 9 this generally works without causing problems.</p>
<pre>--menu [token_id]</pre>
+
<p>Next, in addition to the three standard elements of the Ability Macro, the 'ct-' attribute and the listing, these items require a 4th element which specifies their powers and spellsThese are:</p>
<p>Takes an optional token ID – if not specified uses selected token</p>
+
<p>Displays a Chat menu with buttons for: Attacking, with either Roll20 rolling a dice, or the Player entering a dice roll result; changing what is in the Character’s (or NPC’s) hands; to recover spent ammo; and to check the current Armour Class for the Character under various circumstancesIf the GM uses the menu, an additional button for a Targeted Hit appears, which allows the GM to select both the attacker and the target and get full specs on the hit and damage done, and the AC & current hit Points of the target.</p>
+
===Display a menu of other actions===
+
<pre>--other-menu [token_id]</pre>
+
<p>Takes an optional token ID – if not specified uses selected token</p>
+
<p>Displays a Chat menu with buttons for: saving throws and saving throw management; and managing light sources for the character’s token (if Dynamic Lighting is being used) (requires <b>MagicMaster API</b> to work).  If the GM uses the menu, two further options appear: mark the token selected as Dead (which also marks the body as an inanimate object that can be looted); and the ability to adjust damage for the selected token for any arbitrary reason, which can also be noted.</p>
+
==Attacking Commands==
+
===Attack an opponent with a weapon===
+
<pre>--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]</pre>
+
<p>Each takes an optional token ID (if not specified uses selected token), an optional formatted message to include with the attack damage, and up to three optional names for each of the monster attacks that are displayed on the attack menu.</p>
+
<p>Each 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 attacksRanged weapon attacks will prompt the Player to specify which range to fire at. Selecting one of the possible attacks has different outcomes based on the command used:</p>
+
 
<table>
 
<table>
<tr><th scope="row">--attk-hit</th><td>prompts Roll20 to make an attack roll, using 3D dice if they are enabled, displays the AC hit with supporting information on how this was calculated and displays buttons to roll for damage if the attack is successful.</td></tr>
+
<tr><th scope="row">mi-muspells-[item-name]:</th><td>Wizard spells able to be stored in the magic item</td></tr>
<tr><th scope="row">--attk-roll</th><td>displays an entry field to allow the Player to enter the value of their own dice roll (for those that prefer to roll their own dice) though the default entry will also roll the dice for the player.  Subsequently, the process is the same as --attk-hit.</td></tr>
+
<tr><th scope="row">mi-prspells-[item-name]:</th><td>Priest spells able to be stored in the magic item</td></tr>
<tr><th scope="row">--attk-target</th><td>is only available to the GM.  It asks the GM to select a target token for the attack. It then displays the AC the attack roll will hit and the AC of the selected target.  It also automatically rolls damage for Small/Medium and Large targets, and displays the current Hit Points for the targeted token.</td></tr>
+
<tr><th scope="row">mi-powers-[item-name]:</th><td>Powers able to be used by the magic item</td></tr>
<p>The optional message is displayed as part of the display of the damage done on a successful hitIf a monster, the message can be three concatenated messages separated by ‘$$’The message can include API Buttons if needed. The following characters must be replaced (escaped) using these replacements:</p>
+
</table>
{| class="wikitable"
+
<p>In each case the <i>[item-name]</i> is replaced by the Ability macro name (which is not case sensitive).</p>
|+
+
<p><b>Note:</b> The DM creating new spell storing or power wielding magic items does not need to worry about anything other than the Ability Macro in the database, as running the command <b><i>[[Script:MagicMaster#Check_database_completeness_.26_integrity_.28GM_only.29|--check-db]]</i></b> will update all other aspects of the database appropriately for all databases, as long as the Specs and Data fields are correctly defined. Use the name of the particular database as a parameter to check and update just that database. Running the command <b><i>--check-db</i></b> with no parameters will check and update all databases.</p>
|-
+
<p>When a spell-storing or power wielding magic item is added to a magic item bag or container using [[Script:MagicMaster#Edit_a_Magic_Item_bag|!magic --edit-mi]] or [[Script:MagicMaster#DM.2FGM_version_of_Magic_Item_management|!magic --gm-edit-mi]], these attributes are added to the character sheet and also they are parsed by the system and the spells and/or powers are created in the relevant spell books automaticallyWhen such an item is found in a container by a character, or passed from character to character, all of the stored spells & powers are deleted from the old character and created in the new characterA character gaining such an item can use its spells and powers immediately.</p>
! scope="row" | Character
+
<p>Here is an example of a power wielding magic item:</p>
|| Parameter separator || ? || [ || ] || &lt; || &gt; || @ || - || &#124; || : || & || { || }
+
<h3>Ring-of-Shooting-Stars</h3>
|-
+
<p style="display: inline-block; background-color: lightgrey; border: 1px solid black; padding: 4px; color: dimgrey; font-weight: extra-light;"><span style="color:red">!setattr --silent --sel --casting-level|1 --casting-name|@{selected|token_name}'s Ring of Shooting Stars</span><br>
! scope="row" | Substitute
+
/w "@{selected|character_name}" <nowiki>&{template:'+fields.defaultTemplate+'}{{name=Ring of Shooting Stars}}{{subtitle=Ring}}</nowiki><span style="color:green">Specs=[Ring of Shooting Stars,Ring,1H,Evocation]</span><nowiki>{{Speed=[[5]]}}</nowiki><span style="color:blue">RingData=[w:Ring of Shooting Stars,sp:5,rc:charged,ns:6], [cl:PW,w:RoSS-Dancing-Lights,sp:5,pd:12], [cl:PW,w:RoSS-Light,sp:5,pd:2], [cl:PW,w:RoSS-Ball-Lightning,sp:5,pd:1], [cl:PW,w:RoSS-Shooting-Stars,sp:5,pd:3], [cl:PW,w:RoSS-Faerie-Fire,sp:5,pd:2], [cl:PW,w:RoSS-Spark-Shower,sp:5,pd:1]</span><nowiki> {{Size=Tiny}} {{Immunity=None}} {{Resistance=None}} {{Saves=None}} {{desc=This ring has two modes of operation - at night and underground - both of which work only in relative darkness.<br>
|| %% || ^ || &lt;&lt; || &gt;&gt; || || || ` || ~ || ¦ ||  || &amp;amp; || &amp;#123; || &amp;#125;
+
***During night hours, under the open sky***, the shooting stars ring will perform the following functions:<br>
|-
+
- [*Dancing lights*](</nowiki><span style="color:red">!magic --mi-power @{selected|token_id}|RoSS-Dancing-Lights|Ring-of-Shooting-Stars|1</span><nowiki>) as spell (once per hour).<br>
! scope="row" | Alternative<br>(no ; )
+
- [*Light*](</nowiki><span style="color:red">!magic --mi-power @{selected|token_id}|RoSS-Light|Ring-of-Shooting-Stars|1</span><nowiki>), as spell (twice per night), 120-foot range.<br>
|| \vbar || \ques || \lbrak || \rbrak || \lt || \gt || \at || \dash || \vbar || \clon || \amp || \lbrc || \rbrc
+
- [*Ball lightning*](</nowiki><span style="color:red">!magic --mi-power @{selected|token_id}|RoSS-Ball-Lightning|Ring-of-Shooting-Stars|1</span><nowiki>), as power (once per night).<br>
|}
+
- [*Shooting stars*](</nowiki><span style="color:red">!magic --mi-power @{selected|token_id}|RoSS-Shooting-Stars|Ring-of-Shooting-Stars|1</span><nowiki>), as power (special).<br>
 +
***Indoors at night, or underground***, the ring of shooting stars has the following properties:<br>
 +
[*Faerie fire*](</nowiki><span style="color:red">!magic --mi-power @{selected|token_id}|RoSS-Faerie-Fire|Ring-of-Shooting-Stars|1</span><nowiki>) (twice per day) as spell<br>
 +
[*Spark shower*](</nowiki><span style="color:red">!magic --mi-power @{selected|token_id}|RoSS-Spark-Shower|Ring-of-Shooting-Stars|1</span><nowiki>) (once per day) as power<br>
 +
Range, duration, and area of effect of functions are the minimum for the comparable spell unless otherwise stated. Casting time is 5}}</nowiki></p>
 +
<p>Note that the ability macro starts with a call to the <b>ChatSetAttr API</b> to set the <i>casting-level</i> to 1 and the name of the caster to be <i><Character-name>'s Ring of Shooting Stars</i>.  Not strictly necessary, but a nice cosmetic.</p>
 +
<p>The data section now includes repeating data sets, one for each of the powers that the item has:</p>
 +
<pre>RingData=[w:Ring of Shooting Stars,sp:5,rc:charged,ns:6], [cl:PW,w:RoSS-Dancing-Lights,sp:5,pd:12], … </pre>
 +
<p>The first data set is very similar to the standard magic item data, with the addition of the <b>ns:</b> field, and is then followed by a number of repeated data sets specifying each of the powers:</p>
 +
<table>
 +
<tr><th scope="row">ns:</th><td>&lt;#&gt;</td><td>The number of powers (or spells) that the item can wield or store</td></tr>
 +
<tr><th scope="row">cl:</th><td>&lt;MU/PR/PW&gt;</td><td>The type of the power/spell specification: PW=power, MU=wizard spell, PR=priest spell</td></tr>
 +
<tr><th scope="row">w:</th><td>&lt;text&gt;</td><td>The name of the power/spell - must be exactly the same as the database name (case ignored)</td></tr>
 +
<tr><th scope="row">sp:</th><td>&lt;[-/+]# / dice roll spec&gt;</td><td>The speed or casting time of the power/spell in segments</td></tr>
 +
<tr><th scope="row">pd:</th><td>&lt;-1/#&gt;</td><td>The available casts per day, or -1 for <i>'at will'</i></td></tr>
 +
</table>
 +
<p>By running the <b>--check-db</b> command (see the note above) these data sets are used to correctly set up the database with the powers wielded, so that when a Character receives this item, the Character also gains the powers to use through the item.</p>
 +
<p><b>Note:</b> if a Character picks up two Power-wielding items with exactly the same item name (i.e. two copies of the same item) the results are unpredictable.  This is best avoided.</p>
 +
<p>Feel free to just copy the specification for a Ring-of-Shooting-Stars in the Rings database and save it to a new Ability Macro with a different name, and then alter the power names, speeds, and uses per day, as well as the API Button <b>--mi-power</b> commands and the other text, to form new power-wielding magic items.  Also, the Ring does not have to have 6 powers - just remove or add one or more repeating data sets to reduce or increase the number of powers.</p>
 +
<p>Here is an example of a spell-storing magic item:</p>
 +
<h3>Ring-of-Spell-Storing-HHSLS</h3>
 +
<p style="display: inline-block; background-color: lightgrey; border: 1px solid black; padding: 4px; color: dimgrey; font-weight: extra-light;">/w "@{selected|character_name}" <nowiki>&{template:'+fields.defaultTemplate+'}{{name=Ring of Spell Storing with Haste x2, Slow, Light & Sleep}}{{subtitle=Ring}}</nowiki><span style="color:green">Specs=[Ring of Spell Storing,Ring,1H,Conjuration-Summoning]</span><nowiki>{{Speed=[[5]] regardless of spell}}</nowiki><span style="color:blue">RingData=[w:Ring of Spell Storing HHSLS,sp:5,rc:uncharged,ns:5], [cl:MU,w:Haste,sp:5,lv:6], [cl:MU,w:Haste,sp:5,lv:6], [cl:MU,w:Slow,sp:5,lv:7], [cl:MU,w:Light,sp:5,lv:3], [cl:MU,w:Sleep,sp:5,lv:3]</span><nowiki> {{Size=Tiny}}{{Store spell=[Store Priest Spell](</nowiki><span style="color:red">!magic --mem-spell MI-PR|@{selected|token_id}</span><nowiki>)<br>
 +
[Store Wizard Spell](</nowiki><span style="color:red">!magic --mem-spell MI-MU|@{selected|token_id}</span><nowiki>)}}{{Cast spell=[View](</nowiki><span style="color:red">!magic --view-spell mi-muspells|@{selected|token_id}</span><nowiki>) or [Cast](</nowiki><span style="color:red">!magic --cast-spell MI|@{selected|token_id}</span><nowiki>) spells}}{{desc=A ring of spell storing contains 1d4+1 spells which the wearer can employ as if he were a spellcaster of the level required to use the stored spells. The class of spells contained within the ring is determined in the same fashion as the spells on scrolls (see "Scrolls"). The level of each spell is determined by rolling 1d6 (for priests) or 1d8 (for wizards). The number rolled is the level of the spell, as follows:<br>
 +
Priest: 1d6, if 6 is rolled, roll 1d4 instead.<br>
 +
Wizard: 1d8, if 8 is rolled, roll 1d6 instead.<br>
 +
Which spell type of any given level is contained by the ring is also randomly determined.<br>
 +
The ring empathically imparts to the wearer the names of its spells. Once spell class, level, and type are determined, the properties of the ring are fixed and unchangeable. Once a spell is cast from the ring, it can be restored only by a character of appropriate class and level of experience (i.e., a 12th-level wizard is needed to restore a 6th-level magical spell to the ring). Stored spells have a casting time of [[5]].}}</nowiki></p>
 +
<p>This is a specific version of a Ring of Spell Storing.  As the spells stored are specified in the macro, if you want there to be multiple rings of spell storing in your campaign they each need to be individually programmed (easy cut & paste job) & named differently.</p>
 +
<p>The only new field in these data sets is:</p>
 +
<table>
 +
<tr><th scope="row">lv:</th><td>&lt;#&gt;</td><td>The level of the caster who cast the spell into the ring.  The spell will have effects as if cast at this level when cast from the ring.</td></tr>
 +
</table>
 +
<p>The <b>lv:</b> field only specifies the level of the initial spell caster when the item is first found.  Once owned and used, the level of the spell caster is recorded each time a spell is refreshed by casting into the item.  As the item is then passed from one Character to another, or stored in a container and recovered later, the levels at which the spells were cast is retained.  However, if the item is reloaded from the databases, or a duplicate of the item is placed by the DM and found by another character, that version of the item will have the spell caster levels from the database definitions.  Note that if a single Character picks up two versions of exactly the same spell storing item (i.e. with the same item name) the results are unpredicable...</p>
 +
<p>Feel free to just copy the specification for a Ring-of-Spell-Storing in the Rings database and save it to a new Ability Macro with a different name, and then alter the spell names and casting levels as desired, to form new Rings of Spell Storing or other magic items.  Also, the Ring does not have to have 5 spells - just remove or add one or more repeating data sets to reduce or increase the number of stored spells (though the official definition of a Ring of Spell Storing states a maximum of 5 spells).</p>
 +
<p>The key command in the Spell-Storing item that supports it casting the defined spells is <b>!magic --cast-spell MI</b>, called in this case via an API button.  Any item specified with this command somewhere in the definition can store spells which can be specified, added or changed by the DM/Game Creator using the <b>[[Script:MagicMaster#Define_the_spells_a_spell-storing_Item_can_store|!magic --store-spell]]</b> command.</p>
 
<br>
 
<br>
===Use two weapons to attack===
+
<h2>Weapons (if using AttackMaster API)</h2>
<pre>--twoswords [token_id]|[prime-weapon]</pre>
+
<p>Weapons, magical or not, are special types of items in the Magic Items databasesIf coded properly (in the same way as those in the MI-DB-Weapons database), they can be used with the <b>[[Script:AttackMaster|AttackMaster API]]</b> to implement fully automatic weapon management, the ability to hold weapons "in-hand" or sheathed, to have automatic ammo and range management for ranged weapons, automatic entry of weapons into the melee and/or ranged weapons tables, ready to make attacks with magical plusses and other specifications all set up, and support for dancing weapons (ones that can attack without being held by the Character), creatures with more than 2 hands, and 1-handed weapons, 2-handed weapons, and even weapons that need more than 2 hands!</p>
<p>Takes an optional token ID (if not specified uses selected token) and an optional weapon name.</p>
+
<p>See the <b>[[API:RPGMaster-WeaponsArmorDB|Weapon & Armour Database Help]]</b> handout and wiki for how Weapon definitions should be structured for use with the <b>AttackMaster API</b>, which are just a few additions to the standard definition of an item.</p>
<p>This command sets the system up to apply the correct penalties / bonuses when using two weapons to attack.  Under AD&D 2e rules, only types of Fighter & Rogue can use 2 weapons at a time to attack in a round, and only Rangers do so without penaltyUsing this command with the name of a <i>prime-weapon</i> specified will mark that weapon as the Primary which will get the smaller penalty of the two and will also be allowed multiple attacks per round (if using <b>InitiativeMaster API</b>).  Use of any other weapon during the current or subsequent rounds will incur a larger penalty and be restricted to one attack per round regardless of type of weapon, level & proficiency.  Penalties are adjusted by the Dexterity Reaction Adjustment.  See AD&D 2e PHB p96 for full explanation of rules applied.</p>
+
<p>Calling this command without a prime-weapon specified will terminate two-weapon mode and no penalties will be applied for the current and subsequent rounds.</p>
+
 
<br>
 
<br>
==Weapon Management==
+
<h2>Armour & Shields</h2>
===Change weapons currently in hand===
+
<p>Like weapons, armour and shields of all types (including magical armour like magical Bracers and Rings of Protection) can be coded to be used with the <b>[[Script:AttackMaster|AttackMaster API]]</b> to automatically calculate the appropriate AC for various scenarios (such as with & without Shield, from the back, if surprised, etc)This will take into account if the armour is valid for the character class, determine which is the best armour combination that the character has, if various armour elements can or can't work together, and add in Dexterity bonuses or impairments. It will also allow magical effects cast on the character to take effect or be adjusted via the token "circles" and highlight when such an effect is in place by showing the relevant token bar (only when there is a difference between the token AC and calculated AC).</p>
<pre>--weapon [token_id]</pre>
+
<p>See the <b>[[API:RPGMaster-WeaponsArmorDB|Weapon & Armour Database Help]]</b> handout and wiki page for how Armour & Shield definitions should be structured for use with the <b>AttackMaster API</b>, which are just a few additions to the standard definition of an item.</p>
<p>Takes an optional token ID – if not specified uses selected token.</p>
+
<p>Also, see the <b>RoundMaster API</b> documentation for how magical effects can be placed on and affect tokens and characters.</p>
<p>This command displays a chat menu displaying what is currently in the Character’s (or NPC or creature’s) hands, and allowing the Player to change what is held to any weapon or shield that they have in their backpack.  Subsequent attacks will then use the newly specified weapon(s).  Selecting a ranged weapon that uses ammunition, the appropriate ammunition held in their backpack is also loaded into the character’s “quiver”.</p>
+
<p>Selecting a hand (either Left or Right) will display any 1-handed weapons that can be used for selection in a list.  Selecting the Both Hands button will display all the 2-handed weapons (including bows) that can be used for selection in a list.  Some weapons can be used either 1-handed or 2-handed, and the appropriate stats will be given based on the selection made.</p>
+
<p>If being used by the GM, the menu also has an option to change the number of hands the creature has, which will then allow the creature to hold (and attack with) more than two items, or to hold items that require more than two hands.</p>
+
<p><b>Note:</b> this function is dependent on the weapon and shield definitions including certain key information in a specified format: see section 8 below.</p>
+
===Manage a dancing weapon===
+
<pre>--dance [token_id] | weapon  | [ STOP ]</pre>
+
<p>Takes an optional token ID (if not specified uses selected token), a mandatory weapon name, and an optional STOP command.</p>
+
<p>This command marks the named weapon as “dancing” which means it will no longer occupy a hand, but will still appear in the list of possible attacks when an attack is made.  When started, the --weapon command is automatically run so that an additional weapon can be taken in the freed-up hand.</p>
+
<p>Appending the “STOP” command will un-mark the weapon as dancingThe Player will have to take the no-longer dancing weapon back in hand, if they so desire, using the --weapon command.</p>
+
<p><b>Note:</b> the most effective use of the --dance command is when combined with the RoundMaster effect management system, to count down rounds of use, automatically call the --dance command at the appropriate time, and stop the dancing automatically after the appropriate duration.</p>
+
===Manage weapon statistics===
+
<pre>--mod-weapon [token_id] | weapon | MELEE / RANGED / DMG / AMMO | adjustments
+
--quiet-modweap [token_id] | weapon | MELEE / RANGED / DMG / AMMO | adjustments</pre>
+
<p>Each command takes an optional token ID (if not specified uses selected token), a mandatory weapon name, and a mandatory data type.</p>
+
<p>These commands allow the specifications of any weapon currently in-hand to be adjusted programmatically.  E.g. the magical plus on to-hit and damage can be adjusted round by round (as for a Sword of Dancing.  The type of data to be adjusted must be identified using the data type parameter: MELEE & RANGED alter To-Hit data, and DMG & AMMO alter Damage.</p>
+
<p>The weapon parameter can name a specific weapon name, a type of weapon (e.g. bow, long-blade, club etc), a changed weapon name (previously changed by this command), or even ‘all’ for all currently held weapons.  All data of the specified data type for all weapons that match the weapon parameter may then be altered, using the comma-separated adjustments parameter.  Each adjustment is of the format <i><pre>field_id:[=][+/-]value</pre></i> where the field_ids are:</p>
+
<table><tr><td>w:</td><td>weapon name</td><td>t:</td><td>weapon type</td><td>st:</td><td>weapon super-type</td></tr>
+
<tr><td>sb:</td><td>strength bonus</td><td>db:</td><td>dexterity bonus</td><td>+:</td><td>magical plus</td></tr>
+
<tr><td>n:</td><td>number of attacks per round</td><td>pl:</td><td>proficiency level</td><td>pd:</td><td>dancing proficiency level</td></tr>
+
<tr><td>ch:</td><td>critical hit roll</td><td>cm:</td><td>critical miss roll</td><td>sz:</td><td>size</td></tr>
+
<tr><td>r:</td><td>range (can be #/#/#)</td><td>ty:</td><td>damage type</td><td>sp:</td><td>speed in segments</td></tr>
+
<tr><td>sm:</td><td>damage vs small & medium</td><td>l:</td><td>damage vs large</td></tr></table>
+
 
<br>
 
<br>
<p>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 adjustedMultiple attributes can be adjusted using one command call by concatenating comma-delimited adjustments. E.g. </p>
+
<h2>Specs & Data field values</h2>
<pre>--mod-weap @{selected|token_id}|Sword-of-Dancing|MELEE|sb:0,+:+1,sp:-1</pre>
+
<p>Below are lists of the current possible values for the item database Ability macro sections.</p>
<p>If the weapon is not found, the GM receives an error message, but no other issues occur.</p>
+
<h3>Specs sections</h3>
===Adding & removing weapons and ammunition===
+
<pre>Specs=[Type, Item-Class, Handedness, Group-Type]</pre>
<pre>--edit-weapons [token_id]</pre>
+
<p>There are no default settings for any of the Specs data fieldsAll must be explicitly specified.</p>
<p>Takes an optional token ID – if not specified uses selected token.</p>
+
<h4>Spell Types</h4>
<p>The very best way for the Character, NPC or creature to acquire weapons (or any other items including magic items) is to use the <b>MagicMaster API</b> and its commands and databases.  However, AttackMaster provides a small subset of those facilities to allow the DM and/or Players to add weapons, ammo & armour to their Character Sheet item bagsOnce added, these items can be taken ‘in-hand’ by the Character (using the <b>--weapon</b> command) and then used to attack.</p>
+
<p>There is an infinite list of spell types: generally the type is the spell name.</p>
<p>The advantage of doing this over just typing the item names into the Character Sheet tables is that the items are assured to exist in the weapon, ammo & armour databases that come with the API and so all other aspects of the API will work properly.</p>
+
<h4>Spell Item-Classes</h4>
<p>This command and <b>--edit-armour</b> are identical, and call the same menu.</p>
+
<table>
 +
<tr><th scope="row">MUSpellL\<1-9\></th><td>A Wizard spell with the Level specified as a number from 1 to 9</td></tr>
 +
<tr><th scope="row">PRSpellL\<1-9\></th><td>A Priest spell with the Level specified as a number from 1 to 9</td></tr>
 +
<tr><th scope="row">Power</th><td>A Power</td></tr>
 +
</table>
 +
<h4>Spell Handedness</h4>
 +
<p><b>0H</b> A spell/power that does not take a hand (there is no Somatic component)<br>
 +
<b>1H</b> A spell/power that requires only 1 hand to cast (most spells are like this)<br>
 +
<b>2H</b> A spell/power that requires 2 hands to cast (perhaps a scroll must be held)<br>
 +
<b>3H</b> A spell/power that takes 3 hands... perhaps more than 1 caster together?<br>
 +
<b>4H</b> Etc No currently programmed spells use more than 2 hands<br>
 +
<b>...</b> ...</p>
 +
<h4>Spell/Power Schools</h4>
 +
<p>From MagicMaster v2.048 onwards, Spell Schools are specified by Class in the Class-DB definitions and, depending on the API configuration set with the <b>--config</b> command, will be checked by the system or otherwise. Those implemented so far for the Spells databases are:</p>
 +
<p><i>Abjuration, Alteration, Conjuration-Summoning, Enchantment-Charm, Divination, Illusion-Phantasm, Invocation-Evocation, Necromancy.</i></p>
 +
<p>Note that the '/' in School names in the AD&D2e PHB have been replaced by hyphens. It is also allowed to use just one half of any hyphenated school name where appropriate. If a spell or power is of more than one school, separate each with a vertical bar character '|'</p>
 
<br>
 
<br>
==Ammunition Management==
+
<h4>Magic Item Types</h4>
===Ammunition recovery===
+
<p>There is an infinite list of magic item types: generally the type is the magic item nameA magic item can have more than one type, with each separated by a vertical bar character '|'</p>
<pre>--ammo [token_id]</pre>
+
<h4>Magic Item Classes</h4>
<p>Takes an optional token ID – if not specified uses selected token.</p>
+
<table>
<p>This command displays a chat menu of ammunition that the Character has on their person (not just the ammo that they have in their quiver or in-hand) including any ammunition that has run-out but might still be recoverableThe Player can ask the DM if they can retrieve any ammunition of the types displayed that they have recently used and, once the DM responds with the amount recovered, click on the type of ammunition in the list and enter the amount recovered.  Both the amount on their person, and any amount in their quiver or in-hand are updated.</p>
+
<tr><th scope="row">Weapon</th><td>Weapons that are not Melee or Ranged weapons or any other class</td></tr>
<p><b>Note:</b> enter the amount recovered <em>not</em> the new total.  The amount entered will be added to the current amount held, and then this new value set as the new maximum.  A negative amount can also be entered, which will be removed from the current quantity and will also set the new maximum.</p>
+
<tr><th scope="row">Melee</th><td>Melee weapons that are used in hand-to-hand combat</td></tr>
<p><b>Note:</b> after a Long Rest (see <b>MagicMaster API</b>) all ammunition maximum totals are set to current quantities at that time.  It is assumed that during the period of a long rest, some creature will have found any loose ammo, or it will otherwise have been broken or lost.</p>
+
<tr><th scope="row">Ranged</th><td>Ranged weapons that are either thrown or fire ammunition</td></tr>
<p><b>Note:</b> ammunition that has the item-type of <i>‘charged’</i> will appear on the menu with a grey box which cannot be selected, indicating that the ammo cannot be recovered – such ammunition always breaks on contact: e.g. glass arrows.</p>
+
<tr><th scope="row">Ammo</th><td>All types of ammunition that is used by Ranged weapons</td></tr>
===Ammunition quantity amendment===
+
<tr><th scope="row">Armour</th><td>Any type of armour that does not need to be held to work</td></tr>
<pre>--setammo [token_id] | ammo_name | [ [+/-]cur_qty / = ] | [ [+/-]max_qty / = ] | [ SILENT ]</pre>
+
<tr><th scope="row">Shield</th><td>A barrier that is held in hand(s) and defends against one or more attacks from the front</td></tr>
<p>Takes an optional token ID (if not specified uses selected token), the unique name of the ammunition, an optional value for the current quantity, optionally preceded by +/- or replaced by an =, an optional value for the maximum quantity with the same +/- & = possibilities, and an optional parameter of “Silent” (case insensitive).</p>
+
<tr><th scope="row">Potion</th><td>Any type of potion, oil, pill or similar that is consumed or rubbed on</td></tr>
<p>This command allows programmatic or macro alteration of the quantity of a type of ammo:</p>
+
<tr><th scope="row">Scroll</th><td>Scrolls and spell books, that contain one or multiple spells</td></tr>
<ul><li>The current quantity and/or the maximum held (i.e. the amount to which ammunition can be recovered up to – see section 4.1 Ammunition Recovery, above) can be set to absolute values just by entering numbers for the parameters.</li>
+
<tr><th scope="row">Wand</th><td>Wands that cast spells or spell-like effects when wielded in the hand</td></tr>
<li>Either parameter can be preceded by a + or -, in which case the parameter will modify the corresponding current value, rather than replacing it.</li>
+
<tr><th scope="row">Staff</th><td>Quarterstaffs and similar large bludgeoning items that can also have spell-like abilities</td></tr>
<li>Either parameter can be an = by itself.  In this instance, the corresponding value is set to the other corresponding value (after any modification) i.e. putting = for cur_qty sets the current quantity held to be the maximum possible, or putting = for max_qty sets the maximum possible to be the current quantity.  Putting = for both does nothing.</li>
+
<tr><th scope="row">Rod</th><td>Walking-stick sized rods that can do spell-like effects, especially when used to attack</td></tr>
<li>No value can go below 0, and the current quantity will be constrained at or below the maximum quantity.</li></ul>
+
<tr><th scope="row">Ring</th><td>Rings that are worn on a finger, one to each hand, that protect, have powers or spells</td></tr>
<p>So, for example, this command will set the maximum quantity to 10 and set the current quantity to be equal to it:</p>
+
<tr><th scope="row">Light</th><td>All types of lantern, torch, and other illumination</td></tr>
<pre>!attk –setammo @{selected|token_id}|Flight-Arrow+1|=|10|silent</pre>
+
<tr><th scope="row">Miscellaneous</th><td>Anything that does not fit in one of the other categories</td></tr>
<p>If the “Silent” parameter is not specified, then the Ammunition Recovery chat menu will display with the amended values once complete, and a message is displayed with the changes that occurred.</p>
+
<tr><th scope="row"><i>Unspecified</i></th><td>Items without any Specs section or an empty Class definition are listed under DM-Only</td></tr>
<p><b>Note:</b> if more than one ammo item of the same name is listed in the backpack table (see section 7 on Character Sheet Setup), only the first item found will be amended.  If no item of that name is found, nothing happens and no menus or messages are displayed.</p>
+
</table>
<br>
+
<h4>Armour Handedness</h4>
==Armour Class and Saving Throws==
+
<p><b>0H</b> Items that do not require to be held to work (e.g. a Ring, Buckler or a Helm)<br>
===Edit Armour===
+
<b>1H</b> An item that must be held in one hand to work, such as a Wand<br>
<pre>--edit-armour [token_id]
+
<b>2H</b> Items that need two hands to wield, like a Staff<br>
--edit-armor [token_id]</pre>
+
<b>3H</b> Items that need three hands to use, perhaps by two characters... (not yet implemented)<br>
<p>Takes an optional token ID – if not specified uses selected token.</p>
+
<b>...</b> etc.</p>
<p>The very best way for the Character, NPC or creature to acquire armour (or any other items including magic items) is to use the <b>MagicMaster API</b> and its commands and databases.  However, AttackMaster provides a small subset of those facilities to allow the DM and/or Players to add weapons, ammo & armour to their Character Sheet item bags.  Once added, these items can be taken ‘in-hand’ by the Character (using the <b>--weapon</b> command), and improve the Armour Class of the Character appropriately.</p>
+
<h4>Item Schools</h4>
<p>The advantage of doing this over just typing the item names into the Character Sheet tables is that the items are assured to exist in the weapon, ammo & armour databases that come with the API and so all other aspects of the API will work properly (see section 5.2 below).</p>
+
<p>Currently, all Magic Items other than Weapons and Armour use the same set of magical schools as for Spells & Powers, as they mostly perform spell-like effects.  See section 7.1(d) for the list.</p>
<p>This command is identical to the <b>--edit-weapons</b> command and uses the same menu.</p>
+
<h4>Data Sections</h4>
===Review Armour Class===
+
<p>Definitions for Data Section field types for Weapons & Armour can be found in the [[API:RPGMaster-WeaponsArmorDB#Specs_.26_Data_field_values|Weapons & Armour Database help]] handout & wiki pageBelow are the definitions for Spell, Power & other Magical Item types.</p>
<pre>--checkac [token_id] | [ SILENT ] | [SADJ / PADJ / BADJ]</pre>
+
<p><b>Note:</b> Always refer to the database specification definitions in other sections above for detailed information on the use of these Field specifiers.  Not all specifiers have an obvious use.</p>
<p>Takes an optional token ID (if not specified uses selected token), an optional “Silent” command, and an optional damage type which can be “SADJ”, “PADJ” or “BADJ” (the “Silent” and damage type parameters are not case sensitive).</p>
+
<table>
<p>This command analyses the items in the Character’s backpack table (see section 7 on Character Sheet Setup) using the information in the various item databases supplied / created by the API(s), and taking into account the current Dexterity bonuses calculates the current Armour Class of the Character.  It then displays a chat message with its results and an explanation of how it came to them.  If the optional damage type is provided, the calculation takes this into account.</p>
+
                <tr>
<p>The system can use the information in the databases to take into account magical armour plusses, combined effects of armour that can work together (like Armour and Shields), exclude combinations that are not allowed (like Rings of Protection with magical armour), and the armour types allowed for various character classes and races including specialist variations.</p>
+
<th scope="col" rowspan="2">Field</th>
<p>The system automatically updates this information any time the Character changes what is in their hands (e.g. if they pick up or put down a shield) using the <b>--weapon</b> command. If using the InitMaster API, the command is also run every time the character does an Initiative roll. If using the MagicMaster API, the command is also run any time items are looted from a chest or NPC, or stored away or given to another character.</p>
+
<th scope="col" rowspan="2">Format</th>
<p>The system remembers on the Character Sheet what its calculations are each time.  If the most recent calculation results in a change in Armour Class for the character, the character’s token AC (if displayed) will be modified by the difference between the old and new values.  This modified value will be shown on the Armour Class Review message in the chat window if it is different from the calculated value.</p>
+
<th scope="col" rowspan="2">Default Value</th>
<p><b>Note:</b> the token displayed AC is only modified by the difference between the previous and current calculations.  This allows magical and other effects (such as those managed by the RoundMaster API) to alter the token displayed AC and not be overwritten by a change in calculated AC, but still take into account the change.  The token AC can be manually updated at any time without impact on this functionality, to overcome any errors.</p>
+
<th scope="col" rowspan="2">Description</th>
<p><b>Note:</b> if the token is configured following the Master Series API standard (see CommandMaster API documentation), the token bar for the displayed AC is normally hidden. if the calculated AC and token displayed AC are different (see above) then the AC token bar appears, representing the difference between the two. This acts as a visual reminder to the DM and Player that the token is the subject of some effect on AC – it also helps to identify if there is a difference in error, so that this can be manually rectified (by manually altering the token displayed AC).  Once the two are again the same and the <b>–check-ac</b> command run, the token AC bar will again be hidden.</p>
+
<th scope="col" colspan="8">Can be used in</th>
===Saving Throws===
+
</tr>
<pre>--save [token_id] | [ situation-mod ]
+
<tr>
--save [token_id] | [ situation-mod ] | save-type | saving-throw</pre>
+
<th scope="col">Spell<br>Data</th>
<p>Takes an optional token ID (if not specified uses selected token), and different forms of the command take an optional situational modifier to the saving throw, a type of save (which can be one of ‘paralysis’, ‘poison’, ‘death’, ‘rod’, ‘staff’, ‘wand’, ‘petrification’, ‘polymorph’, ‘breath’, or ‘spell’, not sensitive to case), and the base, unmodified saving throw achieved on a dice.</p>
+
<th scope="col">Potion<br>Data</th>
<p>This command can either display a menu from which to display and manage the saving throw table, and make saving throws or, in its second form, to make a saving throw and check the result against the saving throw table.</p>
+
<th scope="col">Scroll<br>Data</th>
<p>The first form shows all the possible saves that can be made, the saving through that needs to be achieved to make the save, and any modifiers that apply to this particular characterThere are buttons to modify the saving throw table and the modifiers, and/or to apply a “situational modifier” to immediate saving throws (the “situational modifier” only applies to current rolls and is not remembered).  Also, each type of saving throw can actually be made by clicking the buttons provided.  Doing so effectively runs the second form of the command.</p>
+
<th scope="col">Wand<br>Data</th>
<p>The situational modifier can optionally be passed in as a value with the command call if so desired, instead of selecting via the button on the menu.</p>
+
<th scope="col">Staff<br>Data</th>
<p>Running the second form of the command (or selecting to make a saving throw from the first form’s menu) will execute the saving throw (as a dice roll if this is specified instead of a straight value) of the specified type, using the data in the character’s saving throw table to assess success or failure, displaying the outcome and the calculation behind it in the chat window.</p>
+
<th scope="col">Rod<br>Data</th>
<br>
+
<th scope="col">Ring<br>Data</th>
==Other commands==
+
<th scope="col">Misc<br>Data</th>
===Display help on these commands===
+
</tr>
<pre>--help</pre>
+
<tr><th scope="row">w:</th><td>< text ></td><td>'-'</td><td>Name to be displayed</td><td> </td><td>X</td><td>X</td><td>X</td><td>X</td><td>X</td><td>X</td><td>X</td></tr>
<p>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.</p>
+
<tr><th scope="row">w:</th><td>< text ></td><td>''</td><td>Name of spell or power (Not case sensitive)</td><td>X</td><td> </td><td> </td><td> </td><td> </td><td> </td><td> </td><td> </td></tr>
===Configure API behavior===
+
<tr><th scope="row">+:</th><td>[ + / - ] #</td><td>0</td><td>Magical adjustment</td><td> </td><td> </td><td> </td><td>X</td><td>X</td><td>X</td><td>X</td></tr>
<pre>--config [PROF/ALL-WEAPS/WEAP-CLASS/ALL-ARMOUR/MASTER-RANGE/SPECIALIST-RULES/SPELL-NUM] | [TRUE/FALSE]</pre>
+
<tr><th scope="row">n:</th><td># [ / # ]</td><td>1</td><td>Attacks per round</td><td> </td><td> </td><td> </td><td>X</td><td>X</td><td>X</td><td> </td><td>X</td></tr>
<p>Takes two optional arguments, the first a switchable flag name, and the second TRUE or FALSE.</p>
+
<tr><th scope="row">sz:</th><td>[ t / s / m / l / h ]</td><td>''</td><td>Size of item</td><td> </td><td> </td><td> </td><td>X</td><td>X</td><td>X</td><td>X</td><td>X</td></tr>
<p>Allows configuration of several API behaviors.  If no arguments given, displays menu for DM to select configuration.  Parameters have the following effects:</p>
+
<tr><th scope="row">sp:</th><td>[-]# or Dice Roll spec</td><td>0</td><td>Speed in segments (1/10 round)</td><td>X</td><td>X</td><td>X</td><td>X</td><td>X</td><td>X</td><td>X</td><td>X</td></tr>
{| class="wikitable"
+
<tr><th scope="row">wt:</th><td>#</td><td>1</td><td>Weight of item in lbs</td><td> </td><td>X</td><td> </td><td>X</td><td>X</td><td>X</td><td> </td><td>X</td></tr>
|+
+
<tr><th scope="row">ns:</th><td>#</td><td>0</td><td>Number of stored spells & powers defined for item</td><td> </td><td> </td><td>X</td><td>X</td><td>X</td><td>X</td><td>X</td><td>X</td></tr>
|-
+
<tr><th scope="row">w:</th><td>< text ></td><td>'-'</td><td>Name of stored spell or power (Not case sensitive)</td><td>X</td><td> </td><td>X</td><td>X</td><td>X</td><td>X</td><td>X</td><td>X</td></tr>
! Flag !! True  !! False
+
<tr><th scope="row">cl:</th><td>MU / PR / PW</td><td>''</td><td>Type of stored spell or power</td><td> </td><td> </td><td>X</td><td>X</td><td>X</td><td>X</td><td>X</td><td>X</td></tr>
|-
+
<tr><th scope="row">lv:</th><td>#</td><td>1</td><td>Level at which spell/power is cast</td><td> </td><td> </td><td> </td><td>X</td><td>X</td><td>X</td><td>X</td><td>X</td></tr>
! scope="row" | PROF
+
<tr><th scope="row">pd:</th><td>-1 / #</td><td>1</td><td>Number per day (power only)</td><td> </td><td> </td><td> </td><td>X</td><td>X</td><td>X</td><td>X</td><td>X</td></tr>
|| Strictly apply non-proficient weapon penalties as per PHB || Use the non-proficient weapon penalty displayed on the Character Sheet
+
<tr><th scope="row">rc:</th><td>Charged / Uncharged / Rechargeable / Recharging / Self-chargeable / Cursed / Charged-Cursed / Recharging-Cursed / Self-chargeable-Cursed</td><td>Uncharged</td><td>Initial charged and Cursed status of item when found (Can be changed by DM using -gm-only-mi command once added to Character Sheet) Not case sensitive</td><td> </td><td>X</td><td>X</td><td>X</td><td>X</td><td>X</td><td>X</td><td>X</td></tr>
|-
+
</table>
! scope="row" | 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
+
|-
+
! scope="row" | WEAP-CLASS
+
|| Weapons not allowed to a class get a penalty of -100 || Weapons not allowed to a class get double non-proficient penalty
+
|-
+
! scope="row" | ALL-ARMOUR
+
|| All armour types allowed for all classes || Armour not allowed to a class not included in AC calculations
+
|-
+
! scope="row" | MASTER-RANGE
+
|| Ranged weapon Mastery gives double damage at Point Blank range || Ranged weapon Mastery not allowed, as per PHB
+
|-
+
! scope="row" | SPECIALIST-RULES
+
|| Only Specialist Wizards specified in the PHB get an extra spell per spell level || Any non-Standard Wizard gets an extra spell per spell level
+
|-
+
! scope="row" | SPELL-NUM
+
|| Spellcaster spells per level restricted to PHB rules || Spellcaster spells per level alterable using Misc Spells button
+
|}
+
===Check database completeness & integrity===
+
<pre>--check-db [ db-name ]</pre>
+
<p>Takes an optional database name or part of a database name: if a partial name, checks all character sheets with the provided text in their name that also have ‘-db’ as part of their name.  If omitted, checks all character sheets with ‘-db’ in the name.  Not case sensitive.  Can only be used by the GM.</p>
+
<p>This command finds all databases that match the name or partial name provided (not case sensitive), and checks them for completeness and integrity.  The command does not alter any ability macros, but ensures that the casting time (‘ct-‘) attributes are correctly created, that the item lists are sorted and complete, and that any item-specific power & spell specifications are correctly built and saved.</p>
+
<p>This command is very useful to run after creating/adding new items as ability macros to the databases (see section 8 below).  It does not check if the ability macro definition itself is valid, but if it is then it ensures all other aspects of the database consistently reflect the new ability(s).</p>
+
===Handshake with other APIs===
+
<pre>–hsq from|[command]
+
–handshake from|[command]</pre>
+
<p>Either form performs a handshake with another API, whose call (without the ‘!’) is specified as <i>from</i> in the command parameters (the response is always an <b>–hsr</b> command).  The command calls the <i>from</i> API command responding with its own command to confirm that RoundMaster is loaded and running: e.g. </p>
+
'''Received:''' <code>!attk –hsq init</code><br>
+
'''Response:''' <code>!init –hsr attk</code>
+
<p>Optionally, a command query can be made to see if the command is supported by RoundMaster if the <i>command</i> string parameter is added, where <i>command</i> is the RoundMaster command (the ‘--’ text without the ‘--‘).  This will respond with a <i>true/false</i> response: e.g.</p>
+
'''Received:''' <code>!attk –handshake init|menu</code><br>
+
'''Response:''' <code>!init –hsr attk|menu|true</code>
+
===Switch on or off Debug mode===
+
<pre>--debug (ON/OFF)</pre>
+
<p>Takes one mandatory argument which should be ON or OFF.</p>
+
<p>The command turns on a verbose diagnostic mode for the API which will trace what commands are being processed, including internal commands, what attributes are being set and changed, and more detail about any errors that are occurring.  The command can be used by the DM or any Player – so the DM or a technical advisor can play as a Player and see the debugging messages.</p>
+
 
<br>
 
<br>
=Configuring the Token and Character Sheet for use with the API=
+
<h3>Character Sheet data fields</h3>
<p>At the time of writing this Wiki, the RPGMaster APIs, including AttackMaster, are initially configured and distributed to support the Advanced Dungeons & Dragons 2nd Edition RPG and matching Advanced 2nd Edition Character Sheet on Roll20.  The Character Sheets and tokens that represent them are best set up for game play by using the facilities provided by the APIs, and especially those menus and commands provided by the [[Script:CommandMaster#Setup_Tokens_.26_Character_Sheets|CommandMaster API]].  However, if desired, it is possible to set up Character Sheets and tokens manually (especially if not using all the APIs): instructions on how to achieve this are provided in the [[API:RPGMaster-CharacterSheets|RPGMaster Character Sheet and Token setup Handout and Wiki page]].</p>
+
<p>The Character Sheet field mapping to the API script can be altered using the definition of the fields object, the definition for which can be found at the top of each API.  You can find the complete mapping for all APIs in the RPGMaster series, with an explanation of each, in a separate document - as the Author for a copy.</p>
<p>The APIs are currently capable of being adjusted to support any RPG and Character Sheet by adjusting the mappings and database entries supplied as default, but at present this is a significant task.  The RPGMaster Character Sheet and Token Setup handout & Wiki, and the individual [[API:RPGMaster#Related_Pages|database help handouts and wiki pages]] provide information on how to do thisA future development currently planned (but with no date for release) is to reprogram the APIs to include a RPG-defining Library API, one for each supported game system, that will include the RPG rules for the RPGMaster APIs and adjust the API behaviours to work for the RPG the Library is for.</p>
+
 
+
=Weapon, Ammo & Armour Databases=
+
<p>As with other items that can be acquired and used by Characters, NPCs and Creatures in the RPGMaster suite, the definitions for Weapons, Ammunition and Armour four use by the AttackMaster API are held in Character Sheet databases.  See the [[API:RPGMaster-WeaponsArmorDB|Weapon, Ammo & Armour Database Help handout and Wiki page]] for information on these databases.</p>
+
 
+
= Changelog =
+
{{changelog version|2.046|2022-03-28|* Added Class database with PHB Character Class definitions.
+
* Added Attacks database with standard attack calculation definitions.
+
* Added full support for damage types (S, P & B) for both weapons and armour.
+
* Added support for non-standard fractional numbers of weapon attacks per round.
+
* Updated saving throw table calculations to automatically add in appropriate Magic Item bonuses.
+
* Made several long running processes asynchronous to eliminate "infinite loop" detection errors.
+
* Fixed handling of manual character sheet table entries.}}
+
{{changelog version|1.042|2022-02-18|* Fixed restricted weapon proficiency calculations.
+
* Fixed prioritisation of user-defined database entries}}
+
{{changelog version|1.040|2022-02-02|* Added --config command and menu for DM to alter some API behavior.
+
* Multiple weapon changes and additions}}
+
{{changelog version|1.039|2022-01-23|* Fixed Spear definition for self-ammo-ed ranged weapon & added powerful-longsword
+
* Fixed illegal characters not rendered by One-Click install
+
* Added Bow mastery to do double damage at PB range (removed from specialist)}}
+
{{changelog version|1.038|2022-01-09|* Improved Indexing & Performance
+
* Changed data tags to reflect newest standard
+
* Fixed bug relating to AC0 when calculating AC
+
* Added magically summoned weapons (e.g. Mordenkainen's Sword) for new spells}}
+
{{changelog version|1.037|2021-12-14|* First version for public release}}
+
 
+
[[Category:AD&D 2E]]
+

Latest revision as of 11:03, 5 April 2022

Contents

Spell, Power & Magic Item Databases

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.


Spells and Powers Databases

Spells/Powers databases are all character sheets that have names that start with

Wizard Spells: MU-Spells-DB-[added name]
Priest Spells: PR-Spells-DB-[added name]
Powers: Powers-DB-[added name]

Those with version numbers of the form v#.# as part of the name will be ignored.

As previously stated in the General Database Information section, each spell or power definition has 3 parts in the database: an Ability Macro with a name that is unique and matches the spell or power, 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 others of the same level in the spell book of the level of the spell or power. 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 spells and powers does not need to worry about anything other than the Ability Macro in the database, as running the command --check-db will update all other aspects of the database appropriately for all databases, as long as the Specs and Data fields are correctly defined. Use the name of the particular database as a parameter to check and update just that database. 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.

The Ability Macro for a spell may look something like this:

Sleep

/w "@{selected|character_name}" &{template:2Espell}{{title=@{selected|casting-name} casts Sleep as a level @{selected|casting-level} caster}}{{splevel=Level 1 Wizard}}{{school=Enchantment/Charm}}Specs=[Sleep,MUspellL1,1H,Enchantment-Charm]{{range=90 ft}}{{components=V, S, M}}{{duration=[[5*({10,@{selected|casting-level}}kl1)]] Rounds}}{{time=1}}{{aoe=[30ft Cube](!rounds --aoe @{selected|token_id}|square|feet|90|30||dark)}}{{save=None}}{{damage=[Sleep them](!rounds --target area|@{selected|token_id}|@{target|Select who to sleep|token_id}|Sleep|[[5*({10,@{selected|casting-level}}kl1)]]|-1|Snoring away, shake to awaken|sleepy)}}SpellData=[w:Sleep,lv:1,sp:1,gp:0.01,cs:VSM]{{effects=Up to [2d4](!\ \/r 2d4) Hit Dice of creatures with 4 HD or less are put to sleep beginning with the lowest HD creatures in the Area of Effect.}}{{materials=a pinch of fine sand, rose petals, or a live cricket.}}

The ability specification for this Sleep spell 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 MagicMaster API are those highlighted. In red, two API buttons grant the player access to run RoundMaster API commands to show the Area of Effect of the spell, and then to mark affected tokens with a "Sleepy" status. Each of the elements important to the database 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, Spell School]

The Specs section describes what spell type and school this spell 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. Where there are multiple answers for a field, separate each by '|'. Note:Only A-Z, a-z, 0-9, hyphen/minus(-), plus(+), equals(=) point(.) and vertical bar(|) are allowed. Replace any forward slash with hyphen.

Typethe type of the spell, often the same as the ability macro name.
Classone of MUSpellL#, PRSpellL#, or Power, where # is replaced by the spell level number.
Handedness#H, where # is the number of hands needed to cast the spell - i.e. does it have a somatic component.
Spell Schoolthe group of related spells that the spell belongs to.
SpellData=[w:Sleep,lv:1,sp:1,gp:1,cs:VSM]

The SpellData section specifies the data relating to the use of the spell. These fields can be in any order.

w:<text>the name of the spell
sph:<text>the sphere of a priest spell (not used for wizard spells)
lv:<#>the level of the spell
sp:<[-]# or dice roll spec>the casting time in segments for the spell. Can be >10 e.g. 20 for 2 rounds, or negative, or even a dice roll
gp:<#[.#]>the cost of the material components of the spell in GP: fractions converted to SP & CP
cs:<VSM>the component of the spell (Verbal, Somatic, Material) - can be any combination

The casting time (or speed) sp: can be negative, meaning it gives a negative modifier to individual initiative (if InitMaster API is being used). It can also be greater than 10 segments, meaning it takes longer than 1 Round to cast. Multiply the number of Rounds it will take to cast by 10, or the number of Turns it will take to cast by 100 (if using the InitMaster API the rounds will be automatically counted down and the spell actually cast in the appropriate round, unless the casting is interrupted). It can also be a dice roll specification, which will be rolled at the point that a character selects the spell, power or item to use in a particular round, which means the speed can vary from round to round. Potions are always of this nature (see the AD&D2e DMG p141).

The cost of material components, gp:, is deducted from the Caster's money on their Character Sheet each time the spell is cast. The GM is informed of the spell being cast, by whom, and how much money it cost and how much money the Caster has left for each casting.

The components of the spell, cs:, is currently not used and is for future expansion capabilities.

The Ability Macro for a Power may look something like this:

Turn Undead

/w "@{selected|character_name}" &{template:2Espell}{{title=@{selected|token_name} attempts to Turn Undead as a level @{selected|pr-casting-level} @{selected|class3}}} {{splevel=Power}} {{school=Necromancy}}Specs=[Turn-Undead,Power,1H,Necromancy]{{components=V,S}}{{time=[[10]]}}{{range=0}}{{duration=Until broken}}{{aoe=Undead within line of sight}}{{save=See turning table}}{{reference=PHB p103}}{{damage=[Roll 1d20](! /r 1d20 check vs. your turning table) then if successful [Turn Them](!rounds --target area|@{selected|token_id}|@{target|Select undead|token_id}|Turned|99|0|Turned undead, flee if free-willed, stand aside if controlled|screaming)}}SpellData=[w:Turn Undead, sp:10, cs:VS]{{effects=**Remember that Paladins turn as a Priest of 2 levels lower.**<br> Attempting to turn counts as an action, requiring one round and occurring during the character's turn in the initiative order (thus, the undead may get to act before the character can turn them). The mere presence of the character is not enough--a touch of drama from the character is important. Speech and gestures are important, so the character must have his hands free and be in a position to speak. However, turning is not like spellcasting and is not interrupted if the character is attacked during the attempt.<br> To resolve a turning attempt, look on Table 61. Cross-index the Hit Dice or type of the undead with the level of the character (two levels lower for a paladin). If there is a number listed, roll 1d20. If the number rolled is equal to or greater than that listed, the attempt is successful. If the letter "T" (for "turned") appears, the attempt is automatically successful without a die roll. If the letter "D" (for "dispel") is given, the turning utterly destroys the undead. A dash (--) means that a priest or paladin of that level cannot turn that type of undead. A successful turn or dispel affects 2d6 undead. If the undead are a mixed group, the lowest Hit Dice creatures are turned first.<br> Only one die is rolled regardless of the number of undead the character is attempting to turn in a given round. The result is read individually for each type of undead.}}{{material=The Priest's holy symbol}}

Essentially, Powers are just Spells by another name, that can be cast multiple times per day, and are innate to the Character's class, or to a creature. The specification is, therefore, almost identical to a spell. In the author's campaigns, Powers do not consume material components and therefore do not cost money to use (except in rare circumstances) hence there being no gp: specification (it defaults to 0gp), but other DMs can add material costs for Powers if desired. Powers are all 1 level, hence no lv: specification.


Magic Item Databases

Magic Item databases are all character sheets that have names such as

Magic Items: MI-DB-[added name]

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 for other magic, each magic item definition has 3 parts in the database (see Section 1): an Ability Macro with a name that is unique and identifies the magic item, 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 others of the same magic item type, which is one of: Potion, Scroll, Rod/Stave/Wand, Weapon & Ammo, Armour, Ring, Miscellaneous, and also DM Only magic items. The quickest way to understand these entries is to examine existing entries. Do go to the root database and take a look (but be careful not to alter anything unless you know what you're doing!)

Note: The DM creating new magic items does not need to worry about anything other than the Ability Macro in the database, as running the command --check-db will update all other aspects of the database appropriately for all databases, as long as the Specs and Data fields are correctly defined. Use the name of the particular database as a parameter to check and update just that database.

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.

The Ability Macro may look something like this:

Oil-of-Etherealness

/w "@{selected|character_name}" &{template:2Espell}{{title=Oil of Etherealness}} {{splevel=Oil}} {{school=Alteration}}Specs=[Oil of Etherealness,Potion,1H,Alteration]{{components=M}}{{time=[[3]] rounds after application}} PotionData=[sp:30,rc:charged]{{range=User}}{{duration=4+1d4 turns}} {{aoe=User}} {{save=None}} {{healing=[Become Ethereal](!rounds --target single|@{selected|token_id}|@{target|Select a target|token_id}|Oil-of-Etherealness|[[10*(4+1d4)]]|-1|Ethereal|Ninja-mask)}}{{effects=This potion is actually a light oil that is applied externally to clothes and exposed flesh, conferring etherealness. In the ethereal state, the individual can pass through solid objects in any direction - sideways, upward, downward - or to different planes. The individual cannot touch non-ethereal objects.<br> The oil takes effect three rounds after application, and it lasts for 4+1d4 turns unless removed with a weak acidic solution prior to the expiration of its normal effective duration. It can be applied to objects as well as creatures. One potion is sufficient to anoint a normal human and such gear as he typically carries (two or three weapons, garments, armor, shield, and miscellaneous gear). Ethereal individuals are invisible.}}{{materials=Oil}}

You might notice that the structure of this macro is extremely similar to that of a spell: indeed, it uses the same Roll Template. As this is an Oil that achieves the same effect as a spell, this is not surprising.

However, there is one new field in the data section (in this case called the PotionData section):

rc:<MI-type>the recharging/curse type of the magic item.

All magic items have a recharging/curse type: for details, see the --gm-edit-mi command in the MagicMaster API help documentation. If not supplied for a magic item definition, it defaults to uncharged. Generally, items in the database are not cursed-, but can have their type changed to cursed or some recharging cursed type when the DM stores them in a container or gives them to a Character using the --gm-edit-mi command.

Other magic items might use different structures, and be more complex:

Bead-of-Force

/w "@{selected|character_name}" &{template:'+fields.defaultTemplate+'}{{name=Bead of Force}}{{subtitle=Magic Item}}Specs=[Bead of Force,Miscellaneous,1H,Evocation]{{Speed=[[0]]}}MiscData=[w:Bead of Force,sp:0,rc:charged]{{Size=Tiny}}{{Range=[Up to 30yds](!rounds --aoe @{selected|token_id}|circle|yards|0|60||dark|true)}}{{damage=[5d4](! /gmroll 5d4 damage from Bead of Force in 10ft redius) damage in 10ft radius}}{{duration=3d4 rounds}}{{Save=[To escape sphere](! /gmroll 1d20 Save vs. spell or captured in *Sphere of Force*)}}{{Effect=[Trapped in Sphere](!rounds --target area|@{selected|token_id}|Bead-of-Force|8|-1|'Held in Sphere of Force'|fishing-net)}}{{desc=These small, black spheres might be mistaken for common beads, marbles, or unusually black but lusterless pearls. From 5-8 of these beads are usually found at one time. Each is about three-quarters of an inch in diameter and quite heavy, weighing almost an ounce. One can be hurled up to 30 yards.<br> Upon impact, the bead sends forth a burst of force that inflicts 5d4 points of damage upon all creatures within a 10-foot radius of its center. Each victim is allowed a saving throw vs. spell. Those who save will be thrown out of the blast area, but those who fail to save will be encapsulated by a sphere of force after taking damage.<br> The sphere will form around any and all such creatures in the 10-foot-radius area, even those of large size, and will persist for 3d4 rounds. Victims will be unable to escape except by the same means and used to bring down a wall of force spell.}}

The Bead of Force ability macro uses a Default Roll Template, which means the only mandatory field is the Template:Name= field, and the DM can define any other fields they want to describe and enact the magic item. Here, an API button exists to do a saving throw with documented outcomes, and another API button can target an area with multiple tokens in to entrap them (if the DM rejects or confirms as they make or fail each saving throw).


Magic Items with Powers or Spell-Storing

Some magic items, especially artefacts and sentient items, can store spells and/or have powers similar to characters. MagicMaster supports magic items of this type to a degree, although there are inevitably exceptions that the DM will have to get creative in their development! These items use API buttons that call various MagicMaster commands to deliver their capabilities.

First to note is that items that have powers and spells use spell slots in the owning character's character sheet. These spell slots should not be used by characters in your campaign. If they are, errors might occur. By default, on the AD&D2E character sheet the system uses Wizard Level 14 spell slots for magic item powers, and Wizard Level 15 spell slots for spell-storing magic items. As standard AD&D2E only has spells up to level 9 this generally works without causing problems.

Next, in addition to the three standard elements of the Ability Macro, the 'ct-' attribute and the listing, these items require a 4th element which specifies their powers and spells. These are:

mi-muspells-[item-name]:Wizard spells able to be stored in the magic item
mi-prspells-[item-name]:Priest spells able to be stored in the magic item
mi-powers-[item-name]:Powers able to be used by the magic item

In each case the [item-name] is replaced by the Ability macro name (which is not case sensitive).

Note: The DM creating new spell storing or power wielding magic items does not need to worry about anything other than the Ability Macro in the database, as running the command --check-db will update all other aspects of the database appropriately for all databases, as long as the Specs and Data fields are correctly defined. Use the name of the particular database as a parameter to check and update just that database. Running the command --check-db with no parameters will check and update all databases.

When a spell-storing or power wielding magic item is added to a magic item bag or container using !magic --edit-mi or !magic --gm-edit-mi, these attributes are added to the character sheet and also they are parsed by the system and the spells and/or powers are created in the relevant spell books automatically. When such an item is found in a container by a character, or passed from character to character, all of the stored spells & powers are deleted from the old character and created in the new character. A character gaining such an item can use its spells and powers immediately.

Here is an example of a power wielding magic item:

Ring-of-Shooting-Stars

!setattr --silent --sel --casting-level|1 --casting-name|@{selected|token_name}'s Ring of Shooting Stars
/w "@{selected|character_name}" &{template:'+fields.defaultTemplate+'}{{name=Ring of Shooting Stars}}{{subtitle=Ring}}Specs=[Ring of Shooting Stars,Ring,1H,Evocation]{{Speed=[[5]]}}RingData=[w:Ring of Shooting Stars,sp:5,rc:charged,ns:6], [cl:PW,w:RoSS-Dancing-Lights,sp:5,pd:12], [cl:PW,w:RoSS-Light,sp:5,pd:2], [cl:PW,w:RoSS-Ball-Lightning,sp:5,pd:1], [cl:PW,w:RoSS-Shooting-Stars,sp:5,pd:3], [cl:PW,w:RoSS-Faerie-Fire,sp:5,pd:2], [cl:PW,w:RoSS-Spark-Shower,sp:5,pd:1] {{Size=Tiny}} {{Immunity=None}} {{Resistance=None}} {{Saves=None}} {{desc=This ring has two modes of operation - at night and underground - both of which work only in relative darkness.<br> ***During night hours, under the open sky***, the shooting stars ring will perform the following functions:<br> - [*Dancing lights*](!magic --mi-power @{selected|token_id}|RoSS-Dancing-Lights|Ring-of-Shooting-Stars|1) as spell (once per hour).<br> - [*Light*](!magic --mi-power @{selected|token_id}|RoSS-Light|Ring-of-Shooting-Stars|1), as spell (twice per night), 120-foot range.<br> - [*Ball lightning*](!magic --mi-power @{selected|token_id}|RoSS-Ball-Lightning|Ring-of-Shooting-Stars|1), as power (once per night).<br> - [*Shooting stars*](!magic --mi-power @{selected|token_id}|RoSS-Shooting-Stars|Ring-of-Shooting-Stars|1), as power (special).<br> ***Indoors at night, or underground***, the ring of shooting stars has the following properties:<br> [*Faerie fire*](!magic --mi-power @{selected|token_id}|RoSS-Faerie-Fire|Ring-of-Shooting-Stars|1) (twice per day) as spell<br> [*Spark shower*](!magic --mi-power @{selected|token_id}|RoSS-Spark-Shower|Ring-of-Shooting-Stars|1) (once per day) as power<br> Range, duration, and area of effect of functions are the minimum for the comparable spell unless otherwise stated. Casting time is 5}}

Note that the ability macro starts with a call to the ChatSetAttr API to set the casting-level to 1 and the name of the caster to be <Character-name>'s Ring of Shooting Stars. Not strictly necessary, but a nice cosmetic.

The data section now includes repeating data sets, one for each of the powers that the item has:

RingData=[w:Ring of Shooting Stars,sp:5,rc:charged,ns:6], [cl:PW,w:RoSS-Dancing-Lights,sp:5,pd:12], … 

The first data set is very similar to the standard magic item data, with the addition of the ns: field, and is then followed by a number of repeated data sets specifying each of the powers:

ns:<#>The number of powers (or spells) that the item can wield or store
cl:<MU/PR/PW>The type of the power/spell specification: PW=power, MU=wizard spell, PR=priest spell
w:<text>The name of the power/spell - must be exactly the same as the database name (case ignored)
sp:<[-/+]# / dice roll spec>The speed or casting time of the power/spell in segments
pd:<-1/#>The available casts per day, or -1 for 'at will'

By running the --check-db command (see the note above) these data sets are used to correctly set up the database with the powers wielded, so that when a Character receives this item, the Character also gains the powers to use through the item.

Note: if a Character picks up two Power-wielding items with exactly the same item name (i.e. two copies of the same item) the results are unpredictable. This is best avoided.

Feel free to just copy the specification for a Ring-of-Shooting-Stars in the Rings database and save it to a new Ability Macro with a different name, and then alter the power names, speeds, and uses per day, as well as the API Button --mi-power commands and the other text, to form new power-wielding magic items. Also, the Ring does not have to have 6 powers - just remove or add one or more repeating data sets to reduce or increase the number of powers.

Here is an example of a spell-storing magic item:

Ring-of-Spell-Storing-HHSLS

/w "@{selected|character_name}" &{template:'+fields.defaultTemplate+'}{{name=Ring of Spell Storing with Haste x2, Slow, Light & Sleep}}{{subtitle=Ring}}Specs=[Ring of Spell Storing,Ring,1H,Conjuration-Summoning]{{Speed=[[5]] regardless of spell}}RingData=[w:Ring of Spell Storing HHSLS,sp:5,rc:uncharged,ns:5], [cl:MU,w:Haste,sp:5,lv:6], [cl:MU,w:Haste,sp:5,lv:6], [cl:MU,w:Slow,sp:5,lv:7], [cl:MU,w:Light,sp:5,lv:3], [cl:MU,w:Sleep,sp:5,lv:3] {{Size=Tiny}}{{Store spell=[Store Priest Spell](!magic --mem-spell MI-PR|@{selected|token_id})<br> [Store Wizard Spell](!magic --mem-spell MI-MU|@{selected|token_id})}}{{Cast spell=[View](!magic --view-spell mi-muspells|@{selected|token_id}) or [Cast](!magic --cast-spell MI|@{selected|token_id}) spells}}{{desc=A ring of spell storing contains 1d4+1 spells which the wearer can employ as if he were a spellcaster of the level required to use the stored spells. The class of spells contained within the ring is determined in the same fashion as the spells on scrolls (see "Scrolls"). The level of each spell is determined by rolling 1d6 (for priests) or 1d8 (for wizards). The number rolled is the level of the spell, as follows:<br> Priest: 1d6, if 6 is rolled, roll 1d4 instead.<br> Wizard: 1d8, if 8 is rolled, roll 1d6 instead.<br> Which spell type of any given level is contained by the ring is also randomly determined.<br> The ring empathically imparts to the wearer the names of its spells. Once spell class, level, and type are determined, the properties of the ring are fixed and unchangeable. Once a spell is cast from the ring, it can be restored only by a character of appropriate class and level of experience (i.e., a 12th-level wizard is needed to restore a 6th-level magical spell to the ring). Stored spells have a casting time of [[5]].}}

This is a specific version of a Ring of Spell Storing. As the spells stored are specified in the macro, if you want there to be multiple rings of spell storing in your campaign they each need to be individually programmed (easy cut & paste job) & named differently.

The only new field in these data sets is:

lv:<#>The level of the caster who cast the spell into the ring. The spell will have effects as if cast at this level when cast from the ring.

The lv: field only specifies the level of the initial spell caster when the item is first found. Once owned and used, the level of the spell caster is recorded each time a spell is refreshed by casting into the item. As the item is then passed from one Character to another, or stored in a container and recovered later, the levels at which the spells were cast is retained. However, if the item is reloaded from the databases, or a duplicate of the item is placed by the DM and found by another character, that version of the item will have the spell caster levels from the database definitions. Note that if a single Character picks up two versions of exactly the same spell storing item (i.e. with the same item name) the results are unpredicable...

Feel free to just copy the specification for a Ring-of-Spell-Storing in the Rings database and save it to a new Ability Macro with a different name, and then alter the spell names and casting levels as desired, to form new Rings of Spell Storing or other magic items. Also, the Ring does not have to have 5 spells - just remove or add one or more repeating data sets to reduce or increase the number of stored spells (though the official definition of a Ring of Spell Storing states a maximum of 5 spells).

The key command in the Spell-Storing item that supports it casting the defined spells is !magic --cast-spell MI, called in this case via an API button. Any item specified with this command somewhere in the definition can store spells which can be specified, added or changed by the DM/Game Creator using the !magic --store-spell command.


Weapons (if using AttackMaster API)

Weapons, magical or not, are special types of items in the Magic Items databases. If coded properly (in the same way as those in the MI-DB-Weapons database), they can be used with the AttackMaster API to implement fully automatic weapon management, the ability to hold weapons "in-hand" or sheathed, to have automatic ammo and range management for ranged weapons, automatic entry of weapons into the melee and/or ranged weapons tables, ready to make attacks with magical plusses and other specifications all set up, and support for dancing weapons (ones that can attack without being held by the Character), creatures with more than 2 hands, and 1-handed weapons, 2-handed weapons, and even weapons that need more than 2 hands!

See the Weapon & Armour Database Help handout and wiki for how Weapon definitions should be structured for use with the AttackMaster API, which are just a few additions to the standard definition of an item.


Armour & Shields

Like weapons, armour and shields of all types (including magical armour like magical Bracers and Rings of Protection) can be coded to be used with the AttackMaster API to automatically calculate the appropriate AC for various scenarios (such as with & without Shield, from the back, if surprised, etc). This will take into account if the armour is valid for the character class, determine which is the best armour combination that the character has, if various armour elements can or can't work together, and add in Dexterity bonuses or impairments. It will also allow magical effects cast on the character to take effect or be adjusted via the token "circles" and highlight when such an effect is in place by showing the relevant token bar (only when there is a difference between the token AC and calculated AC).

See the Weapon & Armour Database Help handout and wiki page for how Armour & Shield definitions should be structured for use with the AttackMaster API, which are just a few additions to the standard definition of an item.

Also, see the RoundMaster API documentation for how magical effects can be placed on and affect tokens and characters.


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]

There are no default settings for any of the Specs data fields. All must be explicitly specified.

Spell Types

There is an infinite list of spell types: generally the type is the spell name.

Spell Item-Classes

MUSpellL\<1-9\>A Wizard spell with the Level specified as a number from 1 to 9
PRSpellL\<1-9\>A Priest spell with the Level specified as a number from 1 to 9
PowerA Power

Spell Handedness

0H A spell/power that does not take a hand (there is no Somatic component)
1H A spell/power that requires only 1 hand to cast (most spells are like this)
2H A spell/power that requires 2 hands to cast (perhaps a scroll must be held)
3H A spell/power that takes 3 hands... perhaps more than 1 caster together?
4H Etc No currently programmed spells use more than 2 hands
... ...

Spell/Power Schools

From MagicMaster v2.048 onwards, Spell Schools are specified by Class in the Class-DB definitions and, depending on the API configuration set with the --config command, will be checked by the system or otherwise. Those implemented so far for the Spells databases are:

Abjuration, Alteration, Conjuration-Summoning, Enchantment-Charm, Divination, Illusion-Phantasm, Invocation-Evocation, Necromancy.

Note that the '/' in School names in the AD&D2e PHB have been replaced by hyphens. It is also allowed to use just one half of any hyphenated school name where appropriate. If a spell or power is of more than one school, separate each with a vertical bar character '|'


Magic Item Types

There is an infinite list of magic item types: generally the type is the magic item name. A magic item can have more than one type, with each separated by a vertical bar character '|'

Magic Item Classes

WeaponWeapons that are not Melee or Ranged weapons or any other class
MeleeMelee weapons that are used in hand-to-hand combat
RangedRanged weapons that are either thrown or fire ammunition
AmmoAll types of ammunition that is used by Ranged weapons
ArmourAny type of armour that does not need to be held to work
ShieldA barrier that is held in hand(s) and defends against one or more attacks from the front
PotionAny type of potion, oil, pill or similar that is consumed or rubbed on
ScrollScrolls and spell books, that contain one or multiple spells
WandWands that cast spells or spell-like effects when wielded in the hand
StaffQuarterstaffs and similar large bludgeoning items that can also have spell-like abilities
RodWalking-stick sized rods that can do spell-like effects, especially when used to attack
RingRings that are worn on a finger, one to each hand, that protect, have powers or spells
LightAll types of lantern, torch, and other illumination
MiscellaneousAnything that does not fit in one of the other categories
UnspecifiedItems without any Specs section or an empty Class definition are listed under DM-Only

Armour Handedness

0H Items that do not require to be held to work (e.g. a Ring, Buckler or a Helm)
1H An item that must be held in one hand to work, such as a Wand
2H Items that need two hands to wield, like a Staff
3H Items that need three hands to use, perhaps by two characters... (not yet implemented)
... etc.

Item Schools

Currently, all Magic Items other than Weapons and Armour use the same set of magical schools as for Spells & Powers, as they mostly perform spell-like effects. See section 7.1(d) for the list.

Data Sections

Definitions for Data Section field types for Weapons & Armour can be found in the Weapons & Armour Database help handout & wiki page. Below are the definitions for Spell, Power & other Magical Item types.

Note: Always refer to the database specification definitions in other sections above for detailed information on the use of these Field specifiers. Not all specifiers have an obvious use.

Field Format Default Value Description Can be used in
Spell
Data
Potion
Data
Scroll
Data
Wand
Data
Staff
Data
Rod
Data
Ring
Data
Misc
Data
w:< text >'-'Name to be displayed XXXXXXX
w:< text >Name of spell or power (Not case sensitive)X
+:[ + / - ] #0Magical adjustment XXXX
n:# [ / # ]1Attacks per round XXX X
sz:[ t / s / m / l / h ]Size of item XXXXX
sp:[-]# or Dice Roll spec0Speed in segments (1/10 round)XXXXXXXX
wt:#1Weight of item in lbs X XXX X
ns:#0Number of stored spells & powers defined for item XXXXXX
w:< text >'-'Name of stored spell or power (Not case sensitive)X XXXXXX
cl:MU / PR / PWType of stored spell or power XXXXXX
lv:#1Level at which spell/power is cast XXXXX
pd:-1 / #1Number per day (power only) XXXXX
rc:Charged / Uncharged / Rechargeable / Recharging / Self-chargeable / Cursed / Charged-Cursed / Recharging-Cursed / Self-chargeable-CursedUnchargedInitial charged and Cursed status of item when found (Can be changed by DM using -gm-only-mi command once added to Character Sheet) Not case sensitive XXXXXXX


Character Sheet data fields

The Character Sheet field mapping to the API script can be altered using the definition of the fields object, the definition for which can be found at the top of each API. You can find the complete mapping for all APIs in the RPGMaster series, with an explanation of each, in a separate document - as the Author for a copy.