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

Personal tools

Difference between revisions of "API:RPGMaster-MagicItemsDB"

From Roll20 Wiki

Jump to: navigation, search
 
(8 intermediate revisions by one user not shown)
Line 1: Line 1:
 
{{revdate}}{{main|API:RPGMaster}}
 
{{revdate}}{{main|API:RPGMaster}}
==1. General Database information==
+
==Related Wiki Pages==
<p>The MagicMaster API uses a number of databases to hold Ability Macros defining spells, powers and magic items and their effects. The databases are distributed in the game-version-specific <b>RPGMasther Library</b> with many spell, power & magic item definitionsDMs can add their own weapons, ammo and armour to additional databases. Additional databases should be named as follows:</p>
+
[[API:RPGMaster]] - The main Wiki page for the RPGMaster suite of APIs supporting AD&D2e on Roll20<br>
 +
[[Script:MagicMaster]] - The API to manage the use of Spells & Magic Items from the databases<br>
 +
[[Script:AttackMaster]] - The API that manages saving throws, attribute checks, armour class calculations, as well as melee & ranged weapon attacks
 +
==General Database information==
 +
<p>The RPGMaster APIs use a number of databases to hold Macros defining character classes, spells, powers and magic items and their effects. Previous versions of the RPGMaster series of APIs held their databases all externally as character sheets: from this version onwards this is not the case for databases supplied with the APIs, which are now held internally to the APIs. However, the AttackMaster or MagicMaster API command <b>--extract-db</b> can be used to extract any or all standard databases to Character Sheets for examination and update. The APIs are distributed with many class, spell, power & magic item definitions, and DMs can add their own character classes, spells, items, weapons, ammo and armour to additional databases in their own database character sheets, with new definitions for database items held in Ability Macros. Additional database character sheets should be named as follows:</p>
 
<table>
 
<table>
 
<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>
 
<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>
Line 7: Line 11:
 
<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>
 
<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>
 
<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">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>
 +
<tr><th scope="row">Character Races:</th><td>additional databases: Race-DB-<i>[added name]</i> where <i>[added name]</i> can be replaced with anything you want.</td></tr>
 +
<tr><th scope="row">Attack Calculations:</th><td>additional databases: Attacks-DB-<i>[added name]</i> where <i>[added name]</i> can be replaced with anything you want.</td></tr>
 +
<tr><th scope="row">Fighting Styles:</th><td>additional databases: Styles-DB-<i>[added name]</i> where <i>[added name]</i> can be replaced with anything you want.</td></tr>
 
</table>
 
</table>
 
<p><b>However:</b> the system will ignore any database with a name that includes a version number of the form "v#.#" where # can be any number or group of numbers e.g. MI-DB v2.13 will be ignored.  This is so that the DM can version control their databases, with only the current one (without a version number) being live.</p>
 
<p><b>However:</b> the system will ignore any database with a name that includes a version number of the form "v#.#" where # can be any number or group of numbers e.g. MI-DB v2.13 will be ignored.  This is so that the DM can version control their databases, with only the current one (without a version number) being live.</p>
 
<p>There can be as many additional databases as you want. Other Master series APIs come with additional databases, some of which overlap - this does not cause a problem as version control and merging unique macros is managed by the APIs.</p>
 
<p>There can be as many additional databases as you want. Other Master series APIs come with additional databases, some of which overlap - this does not cause a problem as version control and merging unique macros is managed by the APIs.</p>
<p><b>Important Note:</b> all Character Sheet databases <b><u><i>must</i></u></b> have their <i>\'ControlledBy\'</i> value (found under the [Edit] button at the top right of each sheet) set to <i>\'All Players\'</i>.  This must be for all databases, both those provided (set by the API) and any user-defined ones.  Otherwise, Players will not be able to run the macros contained in them.</p>
+
<p><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 Character Sheet database has a similar structure, with:</p>
+
<p>Each added database has a similar structure, with:</p>
 
<ul>
 
<ul>
<li>Ability Macros named as the spell, power or magic item specified, and used to describe and provide effects for spells, powers and magic items using the commands in the Magic Master API;</li>
+
<li>Ability Macros named as the class, spell, power or magic item specified, and used to describe and provide effects for classes, spells, powers and magic items using the commands in the RPGMaster APIs;</li>
<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;</li>
+
<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);</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 Magic Items - see MI entry below).</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 - see Class entry below).</li>
 
</ul>
 
</ul>
<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 spell, power and magic item ability macros.  When a Player or an NPC or Creature views or casts a spell, power or uses a magic item the Magic Master 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>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>[[Script:MagicMaster|MagicMaster API]]</b> command <b>!magic --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>
<p>When a Character, NPC or Creature views or uses an item, or views or casts a spell or power, the system searches the relevant databases for an item, spell or power with the selected name, and copies any database ability macro so found to the Character Sheet of the Character, NPC or Creature - if it already exists it will overwrite it with the latest version. If the system can\'t find a matching entry in any of the databases, API supplied or GM created, it then searches the Character Sheet for a matching ability macro previously saved there - this caters for the character/NPC/creature being moved to a new campaign that, for instance, does not hold a particular GM-created database item, as the macros the Character Sheet needs are always held on it.</p>
+
<p>Ability Macros can be whatever the DM wants and can be as simple or as complex as desired. Roll Templates are very useful when defining 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.</p>
<p>Whenever a new gameplay session is started, or the <b>--check-db</b> command is run, the system indexes all database items, both those in API memory and those held in Character Sheet databases: Character Sheet database items in user-defined databases take preference over API databases extracted to Character Sheet databases, which in turn take preference over API databases held in memory.  This index speeds up access to the database items. However, items in Character Sheet databases are still much slower for the system to access than items in the API databases in memory. Thus it is best not to use extracted API databases in live gameplay, but only for copying items to support development of GM-created items in a GM\'s own databases. After use, the extracted API databases can just be deleted.</p>
+
===Replacing Database Items===
===Replacing Spells & Items===
+
<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>If you want to replace any spell or item provided in any of the databases, you can do so simply by creating an Ability Macro in one of your own databases with exactly the same name as the provided item to be replaced.  The API gives preference to Ability Macros in user-defined databases, so yours will be selected in preference to the one provided with the APIs.</p>
+
 
<br>
 
<br>
 
==Spells and Powers Databases==
 
==Spells and Powers Databases==
Line 29: Line 36:
 
<b>Powers:</b> Powers-DB-[added name]</p>
 
<b>Powers:</b> Powers-DB-[added name]</p>
 
<p>Those with version numbers of the form v#.# as part of the name will be ignored.</p>
 
<p>Those with version numbers of the form v#.# as part of the name will be ignored.</p>
<p>As previously stated, each spell or power definition has 3 parts in the database (see Section 1): 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 extract the root databases using the <b>!magic --extract-db</b> command, and take a look (but remember to delete it after viewing to speed things up, and then reindex the databases using <b>!magic --check-db</b>)</p>
+
<p>As previously stated, each spell or power definition has 3 parts in the database (see Section 1): 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 extract the root databases using the <b>!magic --extract-db</b> command, and take a look (but remember to delete it after viewing to speed things up, and then reindex the databases using <b>!magic --check-db</b>)</p>
 
<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>--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><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>--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>Ability macros can be added to a database just by using the [+Add] button at the top of the Abilities column in the Attributes and Abilities tab of the Database Character Sheet, and then using the edit "pencil" icon on the new entry to open it for editing.  Ability macros are standard Roll20 functionality and not dependent on the API.  Refer to the Roll20 Help Centre for more information.</p>
 
<p>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>
 +
===Simple Spells===
 
<p><b>The Ability Macro</b> for a spell may look something like this:</p>
 
<p><b>The Ability Macro</b> for a spell may look something like this:</p>
<h3>Sleep</h3>
+
===Sleep===
<p style="display: inline-block; background-color: lightgrey; border: 1px solid black; padding: 4px; color: dimgrey; font-weight: extra-light;">/w "@{selected|character_name}" &{template:RPGMspell}{{title=@{selected|casting-name} casts Sleep as a level @{selected|casting-level} caster}}{{splevel=Level 1 Wizard}}{{school=Enchantment/Charm}}<mark style="color:green">Specs=[Sleep,MUspellL1,1H,Enchantment-Charm]</mark>{{range=90 ft}}{{components=V, S, M}}{{duration=[[5*({10,@{selected|casting-level}}kl1)]] Rounds}}{{time=1}}{{aoe=[30ft Cube](<span style="color:red">!rounds --aoe @{selected|token_id}|square|feet|90|30||dark</span>)}}{{save=None}}{{damage=[Sleep them](<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>)}}<mark style="color:blue">SpellData=[w:Sleep,lv:1,sp:1,gp:0.01,cs:VSM]</mark>{{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.}}</p>
+
<p style="display: inline-block; background-color: lightgrey; border: 1px solid black; padding: 4px; color: dimgrey; font-weight: extra-light;"><nowiki>&{template:RPGMspell}{{title=@{selected|casting-name} casts Sleep as a level @{selected|casting-level} caster}}{{splevel=Level 1 Wizard}}{{school=Enchantment/Charm}}</nowiki><span style="color:yellow">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><nowiki>)}}</nowiki><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>The ability specification for this Sleep spell uses a Roll20 Roll Template, in this case provided by the RPGMaster Library (see the documentation for the RPGMaster Library 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>
+
<p>The ability specification for this Sleep spell uses a Roll20 Roll Template, in this case provided by the RPGMaster Library (see the documentation for the RPGMaster Library 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.</p>
 +
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>Specs = [Type, Class, Handedness, Spell School]</pre>
 
<pre>Specs = [Type, Class, Handedness, Spell School]</pre>
<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>
+
<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>
 
<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">Type</th><td>the type of the spell, often the same as the ability macro name.</td></tr>
Line 54: Line 63:
 
<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>
 
<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>
 
</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.  E.g. under AD&D2e rules, potions are always of this nature (see the AD&D2e DMG p141).</p>
+
<p>The casting time (or speed) <b>sp:</b> can be negative, meaning it gives a negative modifier to individual initiative (if <b>[[Script:InitMaster|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>[[Script:InitMaster|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.  E.g. under AD&D2e rules, 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 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>The components of the spell, <b>cs:</b>, is currently not used and is for future expansion capabilities.</p>
 +
===Spells that need "To Hit"===
 +
<p>A more complex spell that needs the caster to hit the target with an attack roll, also known as a <i>weaponised</i> spell, might look something like this:</p>
 +
<p style="display: inline-block; background-color: lightgrey; border: 1px solid black; padding: 4px; color: dimgrey; font-weight: extra-light;"><nowiki>&{template:RPGMspell}{{title=@{selected|Casting-name} casts<br>
 +
Spiritual Hammer<br>as a level @{selected|Casting-Level} caster}}</nowiki><span style="color:yellow">Specs=[Spiritual-Hammer,Innate-Melee|PRspellL2,1H,Evocation],[Spiritual-Hammer,Innate-Melee,1H,Clubs],[Spiritual-Hammer,Innate-Melee,1H,Clubs]</span><nowiki>{{splevel=Level 2 Priest}}</nowiki><span style="color:blue">ToHitData=[w:Spiritual Hammer+1,prlv:1:6,+:1,sb:0,n:1,ch:20,cm:1,sz:T,ty:B,sp:3],[w:Spiritual Hammer+2,prlv:7:12,+:2,sb:0,n:1,ch:20,cm:1,sz:T,ty:B,sp:2],[w:Spiritual Hammer+3,prlv:13,+:3,sb:0,n:1,ch:20,cm:1,sz:T,ty:B,sp:1]</span><nowiki>{{school=Invocation}}{{sphere=Combat}}</nowiki><span style="color:red">DmgData=[w:Spiritual Hammer+1,sb:0,+:1,sm:1+1d4,l:1d4],[w:Spiritual Hammer+2,sb:0,+:2,sm:1+1d4,l:1d4],[w:Spiritual Hammer+3,sb:0,+:3,sm:1+1d4,l:1d4]</span><nowiki>{{components=V,S,M}}</nowiki><span style="color:purple">weapData=[on:\\api;rounds --target caster|@{selected|token_id}|Spiritual-Hammer|\\lbrak;\\lbrak;3+@{selected|Casting-Level}\\rbrak;\\rbrak;|-1|Magical weapon in direction facing requires concentration|archery-target,off:\api;!rounds --removetargetstatus @{selected|token_id}|Spiritual-Hmmer]</span><nowiki>{{time=[[5]]}}{{range=[[10*@{selected|Casting-Level}]] yards}}{{duration=[[3+@{selected|Casting-Level}]] rounds}}{{aoe=Special}}{{save=None}}{{reference=PHB p207}}{{damage=SM [1d4+1](!&#13;&#47;r 1d4+1) or L [1d4](!&#13;&#47;r 1d4) +[[{{(ceil(@{selected|Casting-Level}/6)),3}kl1}]]}}{{damagetype=Bludgeoning}}</nowiki><span style="color:violet">SpellData=[w:Spiritual-Hammer,lv:2,sp:5,gp:2,cs:VSM,sph:Combat]</span><nowiki>{{effects=Base Thac0 same as caster [[@{selected|thac0-base}]] without strength bonus plus magical plus of +[[{{(ceil(@{selected|Casting-Level}/6)),3}kl1}]]. Damage is plus magical bonus but no others.}}{{materials=A normal war hammer (cost 2gp) hurled towards opponent, which disappears as spell is cast.}}{{use=Take the Spiritual Hammer in-hand using the *Change Weapon* menu for the duration of the spell, and use it to attack opponents. It will disappear when the duration expires or you *Change Weapon* to another weapon.}}</nowiki></p>
 +
<p>This spell definition combines the elements of spell database specification and those of a weapon specification. The Specs data now includes the Innate-Melee weapon classification as well as the spell type and level, and as well as the SpellData there are weapon ToHitData and DmgData entries. In addition to the explanation here, please refer to the Weapon and Armour Database Help for more information on these sections.</p>
 +
<p>In this case, there are multiple repeating datasets in each data section: there are three possible variants of the Spiritual Hammer depending on the caster's level. The version to be selected is determined using the level specification attribute in the ToHitData section, in this case using "prlv", but there are four alternatives:</p>
 +
<table>
 +
  <tr><th scope="row">lv:</th><td>Min : Max</td><td>The minimum and maximum level of character (both optional)</td></tr>
 +
  <tr><th scope="row">clv:</th><td>Min : Max</td><td>The minimum and maximum level of spell caster, class based on last spell cast (both optional)</td></tr>
 +
  <tr><th scope="row">mulv:</th><td>Min : Max</td><td>The minimum and maximum level of wizard spell caster for this weapon (both optional)</td></tr>
 +
  <tr><th scope="row">prlv:</th><td>Min : Max</td><td>The minimum and maximum level of priest spell caster for this weapon (both optional)</td></tr>
 +
</table>
 +
<p>In each case, the minimum and maximum are separated by a colon, and either can be left out meaning there is no minimum or no maximum. Wizard and Priest spell casters include those other classes that can cast those spells, at their particular level of spell casting compitence: e.g. a 10th level Ranger is a 2nd level Priest spell caster. If the appropriate value for the caster of the spell falls within the range specified, then that weapon dataset will result in creation of a line in the appropriate weapon tables.</p>
 +
<p>If a spell has these weapon datasets included, and is currently memorised, it will appear in the weapon lists on the <i>Change Weapon</i> menu.  Also, if this spell is cast, the <i>Change Weapon</i> menu will appear automatically after the spell description in the Chat window, ready to take the spell "in-hand" as a weapon and attack with it. Whichever way the <i>Change Weapon</i> menu appears, choosing the spell as a weapon <b>will always mark the spell as having been cast</b>. The spell-weapon will remain in-hand until the weapon is changed <i>or</i> the <b>!attk --blank-weapon</b> command is used which might, for instance, be included in the custom attack macro template (e.g. for Chromatic Orb) or in a spell end-effect (e.g. as in the Spiritual-Hammer-end Effect macro).</p>
 +
===Simple Powers===
 
<p><b>The Ability Macro</b> for a Power may look something like this:</p>
 
<p><b>The Ability Macro</b> for a Power may look something like this:</p>
<h3>Turn Undead</h3>
+
===Turn Undead===
<p style="display: inline-block; background-color: lightgrey; border: 1px solid black; padding: 4px; color: dimgrey; font-weight: extra-light;">/w "@{selected|character_name}" &{template:RPGMspell}{{title=@{selected|token_name} attempts to Turn Undead as a level @{selected|pr-casting-level} @{selected|class3}}} {{splevel=Power}} {{school=Necromancy}}<mark style="color:green">Specs=[Turn-Undead,Power,1H,Necromancy]</mark>{{components=V,S}}{{time=[[10]]}}{{range=0}}{{duration=Until broken}}{{aoe=Undead within line of sight}}{{save=See turning table}}{{reference=PHB p103}}{{damage=[Turn It](<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>)}}<mark style="color:blue">SpellData=[w:Turn Undead, sp:10, cs:VS]</mark>{{effects=**Remember that Paladins turn as a Priest of 2 levels lower.**<br>
+
<p style="display: inline-block; background-color: lightgrey; border: 1px solid black; padding: 4px; color: dimgrey; font-weight: extra-light;"><nowiki>&{template:RPGMspell}{{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:yellow">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=[Turn It](</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><nowiki>)}}</nowiki><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.**</nowiki><br><nowiki>
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>
+
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.</nowiki><br><nowiki>
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>
+
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.</nowiki><br><nowiki>
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}}</p>
+
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>
+
<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>
 
==Magic Item Databases==
 
==Magic Item Databases==
Line 69: Line 93:
 
<p> <b>Magic Items:</b> MI-DB-[added name]</p>
 
<p> <b>Magic Items:</b> MI-DB-[added name]</p>
 
<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>
 
<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>
<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, Armour, Ring, Miscellaneous, and also DM Only magic items.  The quickest way to understand these entries is to examine existing entries.  Do extract a root database using the <b>!magic --extract-db</b> command and take a look (but remember to delete it after viewing to speed things up, and then reindex the databases using <b>!magic --check-db</b>)</p>
+
<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, Armour, Ring, Miscellaneous, and also DM Only magic items.  The quickest way to understand these entries is to examine existing entries.  Do extract a root database using the <b>!magic --extract-db</b> command and take a look (but remember to delete it after viewing to speed things up, and then reindex the databases using <b>!magic --check-db</b>)</p>
<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>--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><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>--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>Ability macros can be added to a database just by using the [+Add] button at the top of the Abilities column in the Attributes and Abilities tab of the Database Character Sheet, and then using the edit "pencil" icon on the new entry to open it for editing.  Ability macros are standard Roll20 functionality and not dependent on the API.  Refer to the Roll20 Help Centre for more information.</p>
 
<p>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>
 +
===Simple Magic Items===
 
<p><b>The Ability Macro</b> may look something like this:</p>
 
<p><b>The Ability Macro</b> may look something like this:</p>
<h3>Oil-of-Etherealness</h3>
+
===Oil-of-Etherealness===
<p style="display: inline-block; background-color: lightgrey; border: 1px solid black; padding: 4px; color: dimgrey; font-weight: extra-light;">/w "@{selected|character_name}" &{template:RPGMpotion}{{title=Oil of Etherealness}} {{splevel=Oil}} {{school=Alteration}}<mark style="color:green">Specs=[Oil of Etherealness,Potion,1H,Alteration]</mark>{{components=M}}{{time=[[3]] rounds after application}} <mark style="color:blue">PotionData=[sp:30,rc:charged]</mark>{{range=User}}{{duration=4+1d4 turns}} {{aoe=User}} {{save=None}} {{healing=[Become Ethereal](<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>)}}{{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>
+
<p style="display: inline-block; background-color: lightgrey; border: 1px solid black; padding: 4px; color: dimgrey; font-weight: extra-light;"><nowiki>&{template:RPGMpotion}{{title=Oil of Etherealness}} {{splevel=Oil}} {{school=Alteration}}</nowiki><span style="color:yellow">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*&#40;4+1d4&#41;]&#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.</nowiki><br><nowiki>
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}}</p>
+
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>
 
<p>There is one new field in the data section (in this case called the PotionData section):</p>
 
<p>There is one new field in the data section (in this case called the PotionData section):</p>
 
<table>
 
<table>
Line 81: Line 106:
 
</table>
 
</table>
 
<p>All magic items have a recharging/curse type: for details, see the <b>--gm-edit-mi</b> command in the MagicMaster API help documentation, section 4.1.  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>
 
<p>All magic items have a recharging/curse type: for details, see the <b>--gm-edit-mi</b> command in the MagicMaster API help documentation, section 4.1.  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>
 +
===Items that Protect===
 +
<p>Items like a <i>Ring of Protection</i> or a <i>Luck Blade</i> protect the possessor by improving their saving throws and/or armour class.</p>
 +
===Ring of Protection+2===
 +
<p style="display: inline-block; background-color: lightgrey; border: 1px solid black; padding: 4px; color: dimgrey; font-weight: extra-light;"><nowiki>&{template:RPGMring}&{template:RPGMring}{{name=Ring of Protection}}{{subtitle=Ring}}{{Speed=[[0]]}}{{Size=Tiny}}{{Immunity=None}}{{Protection=+[[2]] on AC}}</nowiki><span style="color:yellow">Specs=[Ring of Protection,Protection Ring,1H,Abjuration-Protection]</span><nowiki>{{Saves=+[[2]] on saves}}</nowiki><span style="color:blue">ACData=[a:Ring of Protection+2,st:Ring,+:2,rules:-magic,sz:T,wt:0,svsav:2,w:Ring of Protection+2,sp:0,rc:uncharged,loc:left finger|right finger]</span><nowiki>{{desc=A ring of protection improves the wearer's Armour Class value and saving throws versus all forms of attack. A ring +1 betters AC by 1 (say, from 10 to 9) and gives a bonus of +1 on saving throw die rolls. The magical properties of a ring of protection are cumulative with all other magical items of protection except as follows:<br>1. The ring does not improve Armour Class if magical armour is worn, although it does add to saving throw die rolls.<br>2. Multiple rings of protection operating on the same person, or in the same area, do not combine protection. Only one such ring—the strongest—functions, so a pair of protection rings +2 provides only +2 protection.}}</nowiki></p>
 +
<p>All items that protect that are not armour or shields have an item class of some type of <i>protection-[item]</i> specified as the second field of the <i>Specs</i> for the item. The <i>[item]</i> text can be anything you desire, e.g. in this case <i>protection-ring</i>, but only the most advantageous <i>protection-[item]</i> that the possessor has on them will operate. E.g. a <i>protection-ring</i> will work with a <i>protection-cloak</i> but not with another <i>protection-ring</i>.</p>
 +
<p>Items that protect that have an effect on armour class must use the <i>ACData</i> section to specify their properties, otherwise the properties can be held in any other '...data=' specification. The <i>Weapons & Armour Database Help</i> handout has full specifications for ACData fields. The data field tags relevant to AC and saves are listed in the table below:</p>
 +
<table width = 100%>
 +
<tr><th scope="row"> +: </th><td> [+/-]# </td><td> The effect on armour class, + being beneficial, - being a penalty (ACData only).</td></tr>
 +
<tr><th scope="row"> rules: </th><td> rule [ | rule | rule | ...] </td><td> Rules specifying what item types / supertypes / classes this item will or will not work with (see below).</td></tr>
 +
<tr><th scope="row"> svXXX: </th><td> [=][+/-]# </td><td> The effect on various saving throws, specified by XXX, + being beneficial, - being a penalty.</td></tr>
 +
</table>
 +
<p>The <b>rules:</b> state conditions and which other items this item will or will not work with to improve armour class and/or saving throws. Each rule is separated by a '|' and preceeded by either '+' or '-'. The rules have the following meanings:</p>
 +
<table width = 100%>
 +
<tr><th scope="row"> +inHand </th><td> This item must be held in hand for them to work, using the <i>Change Weapon</i> dialog</td></tr>
 +
<tr><th scope="row"> +worn </th><td> (Saves only) This item must be of a usable type that can be worn by the class / race of the character - default for AC</td></tr>
 +
<tr><th scope="row"> -magic </th><td> (AC only) This item will not combine with magical armour</td></tr>
 +
<tr><th scope="row"> -shield </th><td> (AC only) This item will not combine with a shield of any type</td></tr>
 +
<tr><th scope="row"> -acall </th><td> (AC only) This item will not combine with any other armour (except that specified with a '+' - see below)</td></tr>
 +
<tr><th scope="row"> -[supertype] </th><td> (AC only) This item will not work with any other item of the <i>supertype</i> specified</td></tr>
 +
<tr><th scope="row"> +[supertype] </th><td> (AC only) This item will always work with any other item of the <i>supertype</i> specified, even if <i>-acall</i> rule has been specified</td></tr>
 +
<tr><th scope="row"> -[item class] </th><td> (Saves only) This item will not combine with any other item of the <i>item class</i> specified</td></tr>
 +
</table>
 +
<p>The <b>svXXX:</b> entries state the effect on saving throws and/or ability checks that this item has if the <i>rules</i> are met. For Saving Throw mods the 'XXX' can be one of 'par', 'poi', 'dea', 'pet', 'pol', 'bre', 'spe', or 'sav' each referring to the first 3 letters of the saving throw affected (or 'sav' for all saving throw mods); and for Attribute Check mods 'XXX' can be 'str', 'con', 'dex', 'int', 'wis', 'chr', and 'atr' each refering to each Character attribute (or 'atr' for all attribute mods); or to change all mods of both types use 'all'. Each svXXX: field tag is followed by a number which can be optionally preceeded by '+' (a beneficial improvement to the mod), '-' (a penalty to the mod), and/or '=' (the mod is set to the value - overrides other changes).</p>
 +
<p><b>Note:</b> Changing the Attribute mods will not affect the ability checks for <i>open doors, bend bars, learn spells</i> etc. These mods can only be adjusted manually using the appropriate button on the Attribute Check menu.</p>
 +
===More Complex Items===
 
<p>Other magic items might use different structures, and be more complex:</p>
 
<p>Other magic items might use different structures, and be more complex:</p>
<h3>Bead-of-Force</h3>
+
===Ring of Human Influence===
<p style="display: inline-block; background-color: lightgrey; border: 1px solid black; padding: 4px; color: dimgrey; font-weight: extra-light;">/w "@{selected|character_name}" &{template:RPGMitem}{{name=Bead of Force}}{{subtitle=Magic Item}}<mark style="color:green">Specs=[Bead of Force,Miscellaneous,1H,Evocation]</mark>{{Speed=[[0]]}}<mark style="color:blue">MiscData=[w:Bead of Force,sp:0,rc:charged]</mark>{{Size=Tiny}}{{Range=[Up to 30yds](<span style="color:red">!rounds --aoe @{selected|token_id}|circle|yards|0|60||dark|true</span>)}}{{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](<span style="color:red">!rounds --target area|@{selected|token_id}|Bead-of-Force|8|-1|\'Held in Sphere of Force\'|fishing-net</span>)}}{{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>
+
<p style="display: inline-block; background-color: lightgrey; border: 1px solid black; padding: 4px; color: dimgrey; font-weight: extra-light;"><nowiki>&{template:RPGMring}{{name=Ring of Human Influence}}{{subtitle=Ring}}</nowiki><span style="color:yellow">Specs=[Ring of Human Influence,Ring,1H,Enchantment-Charm]</span><nowiki>{{Speed=[[0]]}}</nowiki><span style="color:blue">RingData=[w:Ring of Human Influence,sp:3,rc:uncharged,loc:left finger|right finger,on:\\apisetattr --fb-from Magic Items --fb-header Ring of Human Influence - Put on --fb-content _CHARNAME_ chooses to put on the Ring of Human Influence and now has a Charisma of 18 vs Humans and Humanoids --name @{selected|character_name} --RoHI-chr|@{selected|charisma} --charisma|18,off:\\apiresetattr --fb-from Magic Items --fb-header Ring of Human Influence - Take off --fb-content _CHARNAME_ chooses to take off the ring and their Charisma returns to normal --name @{selected|character_name} --RoHI-chr --charisma|@{selected|RoHI-chr},ns:2],[cl:PW,w:Suggestion,sp:3,lv:12,pd:1],[cl:PW,w:MU-Charm-Person,sp:3,lv:12,pd:1]</span><nowiki>{{Size=Tiny}}{{Immunity=None}}{{desc=Has the effect of raising the wearer's Charisma to 18 on encounter reactions with humans and humanoids. The wearer can make a [*suggestion*](</nowiki><span style="color:red">!magic --mi-power @{selected|token_id}|Suggestion|Ring-of-Human-Influence|12</span><nowiki>) to any human or humanoid (saving throw applies). The wearer can also [charm](</nowiki><span style="color:red">!magic --mi-power @{selected|token_id}|Charm-Person|Ring-of-Human-Influence|12</span><nowiki>) up to 21 levels/Hit Dice of human/humanoids (saving throws apply) just as if he were using the wizard spell, *charm person*. The two latter uses of the ring are applicable but once per day. Suggestion or charm has an initiative penalty of +3.}}{{use=Putting on the ring using the Change Weapon function changes Charisma to 18, and taking it off returns Charisma to its previous value. If using InitiativeMaster Group or Individual Initiative, select Initiative for a Magic Item, then the Ring of Human Influence to get the right item speed. Cast the spells by Using the Ring as a Magic Item, then selecting the appropriate spell in the Effect description.}}</nowiki></p>
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>
+
<p>Here, as well as having API buttons to implement powers, the RingData entry specifies commands to execute when the ring is put on using the <i>Change Weapon</i> menu, and another when it is taken off, as well as other aspects of the ring's power - but ignore everything after the "ns:" for now.</p>
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.}}</p>
+
<table width=100%>
<p>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>
+
  <tr><th scope="row"> on: </th><td> Command string </td><td> A simple, single line command to execute on wearing the ring</td></tr>
 +
  <tr><th scope="row"> off: </th><td> Command string </td><td> A simple, single line command to execute on taking off the ring</td></tr>
 +
</table>
 +
===Staff of Striking===
 +
<p style="display: inline-block; background-color: lightgrey; border: 1px solid black; padding: 4px; color: dimgrey; font-weight: extra-light;"><nowiki>&{template:RPGMwand}{{name=Staff of Striking}}</nowiki><span style="color:yellow">Specs=[Staff of Striking|Quarterstaff,Rod|Melee,1H,Staff],[Staff of Striking|Quaretstaff,Melee,1H,Staff],[Staff of Striking|Quarterstaff,Melee,1H,Staff],[Staff of Striking,Rod,1H,Conjuration-Summoning|Animal]</span><nowiki>{{subtitle=Staff}}</nowiki><span style="color:blue">ToHitData=[w:Staff of Striking 1 charge,sb:1,+:3,n:1,ch:20,cm:1,sz:M,ty:SPB,r:5,sp:4,c:1,rc:rechargeable],[w:Staff of Striking 2 charges,sb:1,+:3,n:1,ch:20,cm:1,sz:M,ty:SPB,r:5,sp:4,c:2,rc:rechargeable],[w:Staff of Striking 3 charges,sb:1,+:3,n:1,ch:20,cm:1,sz:M,ty:SPB,r:5,sp:4,c:3,rc:rechargeable]</span><nowiki>{{Speed=[[4]]}}</nowiki><span style="color:orange">WandData=[qty:19+1d6]</span><nowiki>{{Size=Medium}}{{Weapon=1-handed melee oaken staff}}{{To-hit=+3, +Str Bonus}}{{Attacks=1 per round, magically the most favourable weapon type}}{{Damage= SM: 1d6, L:1d6, 1 charge: +3, 2 charges: +6, 3 charges: +9}}</nowiki><span style="color:red">DmgData=[w:Staff of Striking 1 charge,sb:1,+:3,SM:1d6,L:1d6],[w:Staff of Striking 2 charges,sb:1,+:6,SM:1d6,L:1d6],[w:Staff of Striking 3 charges,sb:1,+:9,SM:1d6,L:1d6]</span><nowiki>{{Use=Melee weapon attack as normal, selecting the appropriate plus, which will deduct the number of charges automatically.}}{{desc=This oaken staff is the equivalent of a +3 magical weapon. (If the weapon vs. armor type adjustment is used, the staff of striking is treated as the most favorable weapon type vs. any armor.) It causes 1d6+3 points of damage when a hit is scored. This expends a charge. If two charges are expended, bonus damage is doubled (1d6+6); if three charges are expended, bonus damage is tripled (1d6+9). No more than three charges can be expended per strike. The staff can be recharged.}}</nowiki></p>
 +
<p>The Staff of Striking is a weapon that can do additional damage if more charges are expended.  The database definition uses the multiple attack / damage fields (as specified and explained in the Weapon and Armour Database Help handout) which results in multiple entries for the weapon to appear in the weapons tables on the character sheet, and in the Attack menu.  Each ToHitData definition has the 'c' attribute to define how many charges are expended when that version of the weapon is used:</p>
 +
<table width=100%>
 +
  <tr><th scope="row"> c: </th><td> # </td><td>The number of charges expended when the respective attack is made. Applies only to weapons / magic items that have charges. If in <i>ToHitData</i> is deducted when an attack is made, or if in <i>DmgData</i> only applies if a hit is achieved & damage done. Defaults to 1 charge (ToHitData) or 0 (DmgData) if not specified.<br>If this item is not a weapon and the c: is in the item <i>Data</i> specification, it determines how many charges are deducted when the item is used, defaulting to 1.</td></tr>
 +
  <tr><th scope="row"> qty: </th><td> # or &lt;dice spec&gt; </td><td>The default quantity of charges the item will start with when added by the GM to a container. Can be a dice roll specification, in which case the number will be determined randomly with a dice roll. The GM can optionally alter this number when storing the item.</td></tr>
 +
</table>
 +
<p>When shown in the Attack menu, any version of the weapon which requires more charges than it currently has will be gray, and will not be selectable for an attack.</p>
 +
===Magic Items that must be taken in-hand===
 +
<p>Some magic items, especially Rods, Staves and Wands, must be taken in-hand like a weapon in order for their abilities to become fully available to the character by making an <i>Attack</i> action. The <i>Rod of Smiting</i> described above is a weapon of this nature, but others might have <i>magical</i> attacks as well as, or instead of melee or ranged attacks. Here is an example of one such device:</p>
 +
===Wand of Frost===
 +
<p style="display: inline-block; background-color: lightgrey; border: 1px solid black; padding: 4px; color: dimgrey; font-weight: extra-light;"><nowiki>&{template:RPGMwand}{{title=Wand of Frost}}</nowiki><span style="color:orange">WandData=[w:Wand of Frost,wt:1,sp:2,c:0,rc:rechargeable,loc:left hand|right hand]</span><nowiki>{{splevel=Wand}}{{school=Evocation}}</nowiki><span style="color:yellow">Specs=[Wand of Frost,Magic|Wand,1H,Evocation],[Wand of Frost,Magic|Wand,1H,Evocation],[Wand of Frost,Magic|Wand,1H,Evocation]</span><nowiki>{{components=V,M}}{{time=[[2]]}}{{range=Special}}</nowiki><span style="color:blue">ToHitData=[w:Ice Storm,desc:MU-Ice-Storm,lv:6,sp:2,c:1],[w:Wall of Ice,desc:MU-Wall-of-Ice,lv:6,sp:2,c:1],[w:Cone of Cold,desc:PW-WoF-Cone-of-Cold,lv:6,sp:2,c:2]</span><nowiki>{{duration=Special}}{{aoe=Special}}{{save=Special}}{{effects=</nowiki>A *frost* wand can perform three functions that duplicate wizard spells:<br>
 +
• *Ice storm:* A silvery ray springs forth from the wand and an ice (or sleet) storm occurs up to 60 feet away from the wand holder. This function requires one charge.<br>
 +
• *Wall of ice:* The silvery ray forms a wall of ice, six inches thick, covering a 600-squarefoot area (10' x 60', 20' x 30', etc.). Its initiative modifier is +2, and it uses one charge.<br>
 +
• *Cone of cold:* White crystalline motes spray forth from the wand in a cone with a 60-foot length and a terminal diameter of 20 feet. The initiative modifier is +2, and the effect lasts just one second. The temperature is -100 degrees F., and damage is 6d6, treating all 1s rolled as 2s (6d6, 12-36). The cost is two charges per use. Saving throw vs. wands is applicable.<br>
 +
The wand can function once per round, and may be recharged.<nowiki>}}{{materials=Wand}}{{Use=Take the wand in-hand using the *Change Weapon* dialogue in order to use its powers with the *Attack* action}}</nowiki></p>
 +
<p>This specification introduces a new item <i>Specs</i> class, <b>"Magic"</b>, and one of a new range of <i>ToHitData</i> fields, <b>"desc"</b>:</p>
 +
<table width=100%>
 +
<tr><th scope="row">Magic</th><td> </td><td>The associated entries in the ToHitData will specify a magical attack, rather than a melee or ranged attack. There will not be a matching <i>DmgData</i> specification</td></tr>
 +
<tr><th scope="row">desc:</th><td> ' ' </td><td>The name of an ability macro describing the magical attack - this is a power, wizard or priest spell, or a magic item (even possibly this magic item) which will be displayed to the player when this magical attack is used.</td></tr>
 +
<tr><th scope="row">lv:</th><td>&lt;#&gt;</td><td>The level at which the magic item casts any power or spell. The spell will have effects as if cast at this level when cast from the magic item.</td></tr>
 +
</table>
 +
<p>The power, spell or magic item name used with the <i>desc:</i> field tag will be searched for in all the appropriate databases.  However, some exist in more than one context (e.g. <i>Light</i> is both a Wizard and a Priest spell). It is possible to specify where the specific description can be found by preceding the name with one of "PW-", "MU-", "PR-", or "MI-" for Power, Wizard spell, Priest spell, and Magic Item respectively. Specifying the type also speeds up the search.</p>
 +
<p>There are other field tags that can be used with a <i>Magic</i> class <i>ToHitData</i> specification:</p>
 +
<table width=100%>
 +
<tr><th scope="row">pw:</th><td>' '</td><td>The name of a magic item power (with limited uses per day) to use as a magical attack, specified as per Section 4.1 below</td></tr>
 +
<tr><th scope="row">msg:</th><td>' '</td><td>A message to display to the player when the magical attack is made, encoded with the standard and extended RPGMaster escape sequences</td></tr>
 +
<tr><th scope="row">cmd:</th><td>' '</td><td>An API command to be executed when the magical attack is made, encoded with the standard and extended RPGMaster escape sequences</td></tr>
 +
</table>
 +
<p>Generally speaking, the <i>cmd:</i> and <i>msg:</i> tags can be used together instead of a <i>desc:</i> if there is no equivalent spell or power to display and only a simple status, timer or effect results from the magical attack. The <i>pw:</i> tag operates in an almost identical way to <i>desc:</i> but decrements the <i>"per day"</i> uses for the named power/spell (specified in the item data specification - see Section 4.1 below) each time it is used, which refresh after a Long Rest.</p>
 +
=== Hiding Magic Item Details===
 +
<p>Sometimes, GMs want Players to have to discover the properties of magic items through quests, spell use, trial and error, or paying a high-level wizard to identify them. This is not always the case, and some groups may prefer for some or all items to reveal their nature on first examination. The database specification of an item allows for both approaches. An example of how to define an item to make it easy to hide its details is </p>
 +
===Flask of Curses===
 +
<p style="display: inline-block; background-color: lightgrey; border: 1px solid black; padding: 4px; color: dimgrey; font-weight: extra-light;"><nowiki>&{template:RPGMitem}</nowiki><span style="color:black"><nowiki>{{title=Flask}}{{name= of Curses}}</nowiki></span><nowiki>{{subtitle=Magic Item}}</nowiki><span style="color:yellow">Specs=[Flask of Curses,Miscellaneous,1H,Alteration]</span><nowiki>{{Speed=[[3]]}}</nowiki><span style="color:blue">MiscData=[w:Flask of Curses,st:Flask,wt:1,sp:3,qty:1,rc:charged]</span><nowiki>{{Size=S}}</nowiki><span style="color:white"><nowiki>{{Looks Like=An ordinary flask of some type, containing a little liquid of some unidentifyable sort}}</nowiki></span><nowiki>{{Use=The GM will tell you what happens when you use this item}}{{desc=This item looks like an ordinary beaker, bottle, container, decanter, flask, or jug. It has magical properties, but detection will not reveal the nature of the flask of curses. It may contain a liquid or it may emit smoke. When the flask is first unstoppered, a curse of some sort will be visited upon the person or persons nearby. After that, it is harmless. The type of curse is up to the DM}}{{GM Info=Hide this as some other jug, flask or bottle, using the GM's *Add Items* menu, and set *Reveal* to *on use*. Invent an imaginative curse to enact! Suggestions include the reverse of the priest's bless spell. Typical curses found on scrolls are recommended for use here as well. Or perhaps a monster could appear and attack all creatures in sight.}}</nowiki></p>
 +
<p>Four elements contribute to the "simple" approach to being able to hide the item details from the Player / Character:</p>
 +
<ul>
 +
+ '<li>The splitting of the title & name of the definition: title is always displayed, and name is only added to the title when hidden details are made displayable by the GM.</li>
 +
+ '<li>The optional addition of the <b>st:</b> attribute in the <i>MiscData</i> specification, which specifies the name of the item displayed on buttons while details are hidden. If not specified, defaults to the item class.</li>
 +
+ '<li>The addition of the <i>Looks Like</i> tag which marks text that replaces the <i>desc</i>ription while details are hidden and until the GM reveals the details.</li>
 +
+ '<li>The <i>Hide item as other item</i> function in the GM's <i>Add Items</i> dialog, which will be available for items that have the <i>Looks Like</i> tag, or for which the GM chooses another item to hide this one as.</p>
 +
</ul>
 +
<p>The key element is the inclusion of the <i>Looks Like</i> text tag in the definition of the item. If an item has this tag, the GM's <i>Add Items</i> dialog will have the <i>Hide Item as Item</i> button enabled to hide the item as either what the <b>st:</b> data attribute specifies or (if not specified) the item class in the <i>Specs</i> specification of the item. However, if <i>auto-hiding</i> is set in the <b>!magic --config</b> options, an item with a <i>Looks Like</i> text tag will automatically be hidden in this way when added to any container. If a player character views or uses such a hidden item, they will see only the <i>title</i> and the <i>Looks Like</i> text and nothing else. The GM can either set the item to automatically reveal its "secrets" when the player character <i>views</i> the item, <i>uses</i> the item, or only when revealed <i>manually</i> by the GM. It is also possible for the GM to select to hide the item as a completely different item using the <i>Add Items</i> dialog. For full details see the <b>--gm-edit-mi</b> entry in the <i>MagicMaster Help</i> handout.</p>
 
<br>
 
<br>
 
==Magic Items with Powers or Spell-Storing==
 
==Magic Items with Powers or Spell-Storing==
 
<p>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.</p>
 
<p>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.</p>
<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>
+
<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>
<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 spells.  These are:</p>
+
<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 spells.  These are:</p>
 
<table>
 
<table>
 
<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">mi-muspells-[item-name]:</th><td>Wizard spells able to be stored in the magic item</td></tr>
Line 100: Line 194:
 
<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>--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><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>--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 --edit-mi or --gm-edit-mi, these attributes are automatically added to the character sheet by the APIs 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.</p>
 
<p>When a spell-storing or power wielding magic item is added to a magic item bag or container using --edit-mi or --gm-edit-mi, these attributes are automatically added to the character sheet by the APIs 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.</p>
 +
===Powerful Magic Item===
 
<p>Here is an example of a power wielding magic item:</p>
 
<p>Here is an example of a power wielding magic item:</p>
<h3>Ring-of-Shooting-Stars</h3>
+
===Ring-of-Shooting-Stars===
<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>
+
<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>
/w "@{selected|character_name}" &{template:RPGMring}{{name=Ring of Shooting Stars}}{{subtitle=Ring}}<mark style="color:green">Specs=[Ring of Shooting Stars,Ring,1H,Evocation]</mark>{{Speed=[[5]]}}<mark style="color:blue">RingData=[w:Ring of Shooting Stars,sp:5,rc:charged,ns:6], [cl:PW,w:MU-Dancing-Lights,sp:5,pd:12], [cl:PW,w:MU-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:Faerie-Fire,sp:5,pd:2], [cl:PW,w:RoSS-Spark-Shower,sp:5,pd:1]</mark> {{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>
+
<nowiki>&{template:RPGMring}{{name=Ring of Shooting Stars}}{{subtitle=Ring}}</nowiki><span style="color:yellow">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:MU-Dancing-Lights,sp:5,pd:12], [cl:PW,w:MU-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: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=</nowiki>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''](<span style="color:red">!magic --mi-power @{selected|token_id}|Dancing-Lights|Ring-of-Shooting-Stars|1</span>) as spell (once per hour).<br>- [''Light''](<span style="color:red">!magic --mi-power @{selected|token_id}|Light|Ring-of-Shooting-Stars|1</span>), as spell (twice per night), 120-foot range.<br>- [''Ball lightning''](<span style="color:red">!magic --mi-power @{selected|token_id}|RoSS-Ball-Lightning|Ring-of-Shooting-Stars|1</span>), as power (once per night).<br>
***During night hours, under the open sky***, the shooting stars ring will perform the following functions:<br>
+
- [''Shooting stars''](<span style="color:red">!magic --mi-power @{selected|token_id}|RoSS-Shooting-Stars|Ring-of-Shooting-Stars|1</span>), as power (special).<br>'''Indoors at night, or underground''', the ring of shooting stars has the following properties:<br>[''Faerie fire''](<span style="color:red">!magic --mi-power @{selected|token_id}|PR-Faerie-Fire|Ring-of-Shooting-Stars|1</span>) (twice per day) as spell<br>[''Spark shower''](<span style="color:red">!magic --mi-power @{selected|token_id}|RoSS-Spark-Shower|Ring-of-Shooting-Stars|1</span>) (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>}}</nowiki></p>
- [*Dancing lights*](<span style="color:red">!magic --mi-power @{selected|token_id}|Dancing-Lights|Ring-of-Shooting-Stars|1</span>) as spell (once per hour).<br>
+
<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>
- [*Light*](<span style="color:red">!magic --mi-power @{selected|token_id}|Light|Ring-of-Shooting-Stars|1</span>), as spell (twice per night), 120-foot range.<br>
+
- [*Ball lightning*](<span style="color:red">!magic --mi-power @{selected|token_id}|RoSS-Ball-Lightning|Ring-of-Shooting-Stars|1</span>), as power (once per night).<br>
+
- [*Shooting stars*](<span style="color:red">!magic --mi-power @{selected|token_id}|RoSS-Shooting-Stars|Ring-of-Shooting-Stars|1</span>), as power (special).<br>
+
***Indoors at night, or underground***, the ring of shooting stars has the following properties:<br>
+
[*Faerie fire*](<span style="color:red">!magic --mi-power @{selected|token_id}|PR-Faerie-Fire|Ring-of-Shooting-Stars|1</span>) (twice per day) as spell<br>
+
[*Spark shower*](<span style="color:red">!magic --mi-power @{selected|token_id}|RoSS-Spark-Shower|Ring-of-Shooting-Stars|1</span>) (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}}</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>
 
<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:MU-Dancing-Lights,sp:5,pd:12], … </pre>
 
<pre>RingData=[w:Ring of Shooting Stars,sp:5,rc:charged,ns:6], [cl:PW,w:MU-Dancing-Lights,sp:5,pd:12], … </pre>
Line 120: Line 207:
 
<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">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">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) <i>optionally</i> prefixed by a power type, one of \'PW-\', \'MU-\', \'PR-\', or \'MI-\' for Power, Wizard spell, Priest spell, or Magic Item</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) <i>optionally</i> prefixed by a power type, one of 'PW-', 'MU-', 'PR-', or 'MI-' for Power, Wizard spell, Priest spell, or Magic Item</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">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>
+
<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>
 
</table>
<p>By running the <b>--check-db</b> command (see section 6 and 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. If a power type prefix is included for one or more power name, the respective database is searched for a matching entry: thus a Wizard or Priest spell can be specified as a power without having to explicitly add a duplicate of it to a Powers Database. If no prefix is specified, the system will first search the Powers Databases (API-supplied and user-supplied) for a match and, if not found there, will then search the MU Spells Databases, the Priest Spells Databases, all Magic Items databases, and then the character sheet of the creature wielding the item power for a match, in that order. An error occurs i no matches are found anywhere.</p>
+
<p>By running the <b>--check-db</b> command (see section 6 and 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. If a power type prefix is included for one or more power name, the respective database is searched for a matching entry: thus a Wizard or Priest spell can be specified as a power without having to explicitly add a duplicate of it to a Powers Database. If no prefix is specified, the system will first search the Powers Databases (API-supplied and user-supplied) for a match and, if not found there, will then search the MU Spells Databases, the Priest Spells Databases, all Magic Items databases, and then the character sheet of the creature wielding the item power for a match, in that order. An error occurs if no matches are found anywhere.</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. The GM can use the <b>--gm-edit-mi</b> menu to rename one or both items with a unique name to differentiate them: see the <b>MagicMaster API</b> documentation for details.</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. The GM can use the <b>--gm-edit-mi</b> menu to rename one or both items with a unique name to differentiate them: see the <b>[[Script:MagicMaster|MagicMaster API]]</b> documentation for details.</p>
 
<p>Feel free to just copy the specification for a Ring-of-Shooting-Stars in an extracted copy of 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>Feel free to just copy the specification for a Ring-of-Shooting-Stars in an extracted copy of 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>A blank <i>Ring of Spell Storing</i> is provided in the API Rings database. It is possible to use the <b>--gm-edit-mi</b> command menu to select this blank ring and use the facilities provided by the menu to add spells to this blank ring, and then rename it to reflect what the GM wants the ring to be. Again, see the <b>MagicMaster API</b> documentation for details.</p>
+
===Spell Storing Magic Item===
 
<p>Here is an example of a spell-storing magic item:</p>
 
<p>Here is an example of a spell-storing magic item:</p>
<h3>Ring-of-Spell-Storing-HHSLS</h3>
+
===Ring-of-Spell-Storing-HHSLS===
<p style="display: inline-block; background-color: lightgrey; border: 1px solid black; padding: 4px; color: dimgrey; font-weight: extra-light;">/w "@{selected|character_name}" &{template:RPGMring}{{name=Ring of Spell Storing with Haste x2, Slow, Light & Sleep}}{{subtitle=Ring}}<mark style="color:green">Specs=[Ring of Spell Storing,Ring,1H,Conjuration-Summoning]</mark>{{Speed=[[5]] regardless of spell}}<mark 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]</mark> {{Size=Tiny}}{{Store spell=[Store Priest Spell](<span style="color:red">!magic --mem-spell MI-PR|@{selected|token_id}</span>)<br>
+
<p style="display: inline-block; background-color: lightgrey; border: 1px solid black; padding: 4px; color: dimgrey; font-weight: extra-light;"><nowiki>&{template:RPGMring}{{name=Ring of Spell Storing with Haste x2, Slow, Light & Sleep}}{{subtitle=Ring}}</nowiki><span style="color:yellow">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>)<br>
[Store Wizard Spell](<span style="color:red">!magic --mem-spell MI-MU|@{selected|token_id}</span>)}}{{Cast spell=[View](<span style="color:red">!magic --view-spell mi-muspells|@{selected|token_id}</span>) or [Cast](<span style="color:red">!magic --cast-spell MI|@{selected|token_id}</span>) 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>
+
[Store Wizard Spell](<span style="color:red">!magic --mem-spell MI-MU|@{selected|token_id}</span>)<nowiki>}}{{Cast spell=</nowiki>[View](<span style="color:red">!magic --view-spell mi-muspells|@{selected|token_id}</span>) or [Cast](<span style="color:red">!magic --cast-spell MI|@{selected|token_id}</span>) spells<nowiki>}}{{desc=</nowiki>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>
 
Priest: 1d6, if 6 is rolled, roll 1d4 instead.<br>
 
Wizard: 1d8, if 8 is rolled, roll 1d6 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>
 
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]].}}</p>
+
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>}}</nowiki></p>
<p>This is a specific version of a Ring of Spell Storing as the spells stored are specified in the macro. Alternatively, a blank <i>Ring of Spell Storing</i> is provided in the API Rings database. It is possible to use the <b>--gm-edit-mi</b> command menu to select this blank ring and use the facilities provided by the menu to add spells to this blank ring, and then rename it to reflect what the GM wants the ring to be. Again, see the <b>MagicMaster API</b> documentation for details.</p>
+
<p>This is a specific version of a Ring of Spell Storing as the spells stored are specified in the macro. Alternatively, a blank <i>Ring of Spell Storing</i> is provided in the API Rings database. It is possible to use the <b>--gm-edit-mi</b> command menu to select this blank ring and use the facilities provided by the menu to add spells to this blank ring, and then rename it to reflect what the GM wants the ring to be. Again, see the <b>[[Script:MagicMaster|MagicMaster API]]</b> documentation for details.</p>
 
<p>The only new field in these data sets is:</p>
 
<p>The only new field in these data sets is:</p>
 
<table>
 
<table>
Line 142: Line 229:
 
</table>
 
</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... The GM should use the <b>--gm-edit-mi</b> menu to rename one or both of the rings to give them unique names.</p>
 
<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... The GM should use the <b>--gm-edit-mi</b> menu to rename one or both of the rings to give them unique names.</p>
 +
===Magic-Item-storing Items===
 +
<p>Some items can store other items, including magic items. When such an item is viewed, used or exchanged between containers and characters, a character sheet specifically for the MI-storing item is created, or found if already previously created. The very act of viewing or using the item will trigger the creation or selection - there is no need for the GM or Player to do so. An example of this is a Bag of Holding.</p>
 +
===Bag of Holding===
 +
<p style="display: inline-block; background-color: lightgrey; border: 1px solid black; padding: 4px; color: dimgrey; font-weight: extra-light;"><nowiki>&{template:RPGMitem}{{name=Bag of Holding}}{{subtitle=Magic Item}}</nowiki><span style="color:yellow">Specs=[Bag of Holding,Miscellaneous,1H,Alteration]</span><nowiki>{{Size=[[15]]/[[250]]lbs, 30cu.ft}}</nowiki><span style="color:blue">MiscData=[w:Bag of Holding,st:Bag,sp:0,rc:uncharged,bag:2],[cl:MI,w:Potion-of-Healing,qty:1],[cl:MI,w:Scroll of Protection vs Magic,qty:2]</span><nowiki>{{Access=Drag the *Bag of Holding* token onto the map and use your MI menu *Search* function (to retrieve stuff from it) or *Store* function (to put stuff in it)}}{{desc=</nowiki>As with other magical bags, this one appears to be a common cloth sack of about 2 feet by 4 feet size. The Bag of Holding opens into a nondimensional space, and its inside is larger than its outside dimensions. Regardless of what is put into this item, the bag always weighs a fixed amount. This weight, the bag's weight limit in contents, and its volume limit are 15 lbs. 250 lbs. 30 cu. ft.<br>
 +
If overloaded, or if sharp objects pierce it (from inside or outside), the bag will rupture and be ruined. The contents will be lost forever in the vortices of nilspace.<nowiki>}}</nowiki></p>
 +
<p>The important attributes are:</p>
 +
<table>
 +
<tr><th scope="row">bag:</th><td>&lt;#&gt;</td><td>Identifies the item as generating an item character sheet. Up to # items can be defined as initially being held in the item sheet (default 0)</td></tr>
 +
<tr><th scope="row">cl:</th><td>'MI'</td><td>Subsequent data sets with class 'MI' define items initially held in the item, and will be inserted in a newly created item sheet when first viewed or used</td></tr>
 +
<tr><th scope="row">w:</th><td>&lt;text&gt;</td><td>The name of the item to initially be stored in the item character sheet MI bag.  Should be an item named in a database</td></tr>
 +
<tr><th scope="row">qty:</th><td>&lt;#&gt;</td><td>The initial quantity of this item to be stored in the item-holding item character sheet MI bag (default 1)</td></tr>
 +
</table>
 +
<p>And one additional new attribute:</p>
 +
<table>
 +
<tr><th scope="row">st:</th><td>''</td><td>Defines the "Item Type" (or SuperType) to be displayed when a container is searched that has its properties set to only show the types of items contained. If not provided, defaults to the <i>item class</i> from the <i>Specs</i> definition</td></tr>
 +
</table>
 +
<p>Thus, the definition of the particular Bag of Holding defined above, when a character has it in their Items & Equipment and either views or uses the item, will result in a new separate character sheet being created, named "Bag of Holding" (same as the item), placed in the controlling Player's journal and marked as controlled by that player, and for one Potion of Healing and two Scrolls of Protection vs. Magic to be inserted automatically into the Bag of Holding, ready for the Character to find and use by dragging the bag onto the map from their Journal and Searching the Bag.</p>
 +
<p>Once the Bag is created, the existing items can be taken out into the Character's own items & equipment, or new ones placed in the bag, the bag passed from one Character to another or itself placed in a different container.</p>
 +
<p>It is recommended that, where a GM places multiple item-holding items in a campaign, such as multiple Bags of Holding, that the GM uses the functions of the [Add Items] menu to rename each with a different name in the original container to which they are placed and before each is viewed or used (i.e. before the item character sheet is created by the system) - perhaps naming each after some previous owner or its creator.  This prevents confusion with multiple Character Sheets all with the same name (which Roll20 will allow, but can definately be confusing for the GM who will see them all even if players only see the ones they control).</p>
 
<br>
 
<br>
 
==Weapons (if using AttackMaster API)==
 
==Weapons (if using AttackMaster API)==
<p>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 <b>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>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 <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>See the <b>Weapon & Armour Database Help</b> handout and AttackMaster API documentation 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.</p>
+
<p>See the <b>[[API:RPGMaster-WeaponsArmorDB|Weapon & Armour Database Help]]</b> handout and [[Script:AttackMaster|AttackMaster API]] documentation 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.</p>
 
<br>
 
<br>
 
==Armour & Shields==
 
==Armour & Shields==
<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>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>
+
<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>
<p>See the <b>Weapon & Armour Database Help</b> handout and AttackMaster API documentation 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.</p>
+
<p>See the <b>[[API:RPGMaster-WeaponsArmorDB|Weapon & Armour Database Help]]</b> handout and AttackMaster API documentation 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.</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>Also, see the <b>[[Script:RoundMaster|RoundMaster API]]</b> documentation for how magical effects can be placed on and affect tokens and characters.</p>
 
<br>
 
<br>
 
==Specs & Data field values==
 
==Specs & Data field values==
Line 157: Line 263:
 
<pre>Specs=[Type, Item-Class, Handedness, Group-Type]</pre>
 
<pre>Specs=[Type, Item-Class, Handedness, Group-Type]</pre>
 
<p>There are no default settings for any of the Specs data fields.  All must be explicitly specified.</p>
 
<p>There are no default settings for any of the Specs data fields.  All must be explicitly specified.</p>
<h3>Spell Types</h3>
+
===Spell Types===
 
<p>There is an infinite list of spell types: generally the type is the spell name.</p>
 
<p>There is an infinite list of spell types: generally the type is the spell name.</p>
<h3>Spell Item-Classes</h3>
+
===Spell Item-Classes===
 
<table>
 
<table>
 
<tr><th scope="row">MUSpellL#</th><td>A Wizard spell with the Level specified as a number</td></tr>
 
<tr><th scope="row">MUSpellL#</th><td>A Wizard spell with the Level specified as a number</td></tr>
Line 165: Line 271:
 
<tr><th scope="row">Power</th><td>A Power</td></tr>
 
<tr><th scope="row">Power</th><td>A Power</td></tr>
 
</table>
 
</table>
<h3>Spell Handedness</h3>
+
===Spell Handedness===
 
<p><b>0H</b> A spell/power that does not take a hand (there is no Somatic component)<br>
 
<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>1H</b> A spell/power that requires only 1 hand to cast (most spells are like this)<br>
Line 172: Line 278:
 
<b>4H</b> Etc  No currently programmed spells use more than 2 hands<br>
 
<b>4H</b> Etc  No currently programmed spells use more than 2 hands<br>
 
<b>...</b> ...</p>
 
<b>...</b> ...</p>
<h3>Spell/Power Schools</h3>
+
===Spell/Power Schools===
 
<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>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><i>Abjuration, Alteration, Conjuration-Summoning, Enchantment-Charm, Divination, Illusion-Phantasm, Invocation-Evocation, Necromancy.</i></p>
<p>Note that the \'/\' in School names 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>
+
<p>Note that the '/' in School names 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>
<h3>Magic Item Types</h3>
+
===Magic Item Types===
<p>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 \'|\'</p>
+
<p>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 '|'</p>
<h3>Magic Item Classes</h3>
+
===Magic Item Classes===
 +
<p>Any magic item can have more than one class, each separated by a vertical bar '|'. It will then behave and be listed as each of the specified classes.</p>
 
<table>
 
<table>
 
<tr><th scope="row">Weapon</th><td>Weapons that are not Melee or Ranged weapons or any other class</td></tr>
 
<tr><th scope="row">Weapon</th><td>Weapons that are not Melee or Ranged weapons or any other class</td></tr>
 +
<tr><th scope="row">Magic</th><td>Magic attacks that are not melee or ranged attacks, often a spell or power of a magic item</td></tr>
 
<tr><th scope="row">Melee</th><td>Melee weapons that are used in hand-to-hand combat</td></tr>
 
<tr><th scope="row">Melee</th><td>Melee weapons that are used in hand-to-hand combat</td></tr>
<tr><th scope="row">Innate-Melee</th><td>Melee weapons that do not attact any proficiency penalties</td></tr>
+
<tr><th scope="row">Innate-Melee</th><td>Melee weapons that do not attract any proficiency penalties</td></tr>
 
<tr><th scope="row">Ranged</th><td>Ranged weapons that are either thrown or fire ammunition</td></tr>
 
<tr><th scope="row">Ranged</th><td>Ranged weapons that are either thrown or fire ammunition</td></tr>
 
<tr><th scope="row">Innate-Ranged</th><td>Ranged weapons that do not attract any proficiency penalties</td></tr>
 
<tr><th scope="row">Innate-Ranged</th><td>Ranged weapons that do not attract any proficiency penalties</td></tr>
Line 200: Line 308:
 
<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>
 
<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>
 
<tr><th scope="row">Protection-Ring</th><td>Any special type of ring that imparts protective qualities</td></tr>
 
<tr><th scope="row">Protection-Ring</th><td>Any special type of ring that imparts protective qualities</td></tr>
 +
<tr><th scope="row">Protection-<i>[item]</i></th><td>Any item (other than clothing or a ring) that imparts protective qualities</td></tr>
 
<tr><th scope="row">Light</th><td>All types of lantern, torch, and other illumination</td></tr>
 
<tr><th scope="row">Light</th><td>All types of lantern, torch, and other illumination</td></tr>
 
<tr><th scope="row">DM-item</th><td>An item that only appears in a list button on the menu displayed by <b>--gm-edit-mi</b></td></tr>
 
<tr><th scope="row">DM-item</th><td>An item that only appears in a list button on the menu displayed by <b>--gm-edit-mi</b></td></tr>
Line 206: Line 315:
 
<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>
 
<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>
 
</table>
 
</table>
<h3>Armour Handedness</h3>
+
===Armour Handedness===
 
<p><b>0H</b> Items that do not require to be held to work (e.g. a Ring, Buckler or a Helm)<br>
 
<p><b>0H</b> Items that do not require to be held to work (e.g. a Ring, Buckler or a Helm)<br>
 
<b>1H</b> An item that must be held in one hand to work, such as a Wand<br>
 
<b>1H</b> An item that must be held in one hand to work, such as a Wand<br>
 
<b>2H</b> Items that need two hands to wield, like a Staff<br>
 
<b>2H</b> Items that need two hands to wield, like a Staff<br>
<b>3H</b> Items that need three hands to use, perhaps by two characters... (not yet implemented)<br>
+
<b>3H</b> Items that need three hands to use, perhaps by two characters... <br>
 
<b>...</b> etc.</p>
 
<b>...</b> etc.</p>
<h3>Item Schools</h3>
+
===Item Schools===
 
<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>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>
<h3>Data Sections</h3>
+
===Data Sections===
 
<p>Definitions for Data Section field types for Weapons & Armour can be found in the AttackMaster API documentation.  Below are the definitions for Spell, Power & other Magical Item types.</p>
 
<p>Definitions for Data Section field types for Weapons & Armour can be found in the AttackMaster API documentation.  Below are the definitions for Spell, Power & other Magical Item types.</p>
 
<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><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>
Line 224: Line 333:
 
<th scope="col" rowspan="2">Default Value</th>
 
<th scope="col" rowspan="2">Default Value</th>
 
<th scope="col" rowspan="2">Description</th>
 
<th scope="col" rowspan="2">Description</th>
<th scope="col" colspan="8">Can be used in</th>
+
<th scope="col" colspan="10">Can be used in</th>
 
</tr>
 
</tr>
 
<tr>
 
<tr>
Line 235: Line 344:
 
<th scope="col">Ring<br>Data</th>
 
<th scope="col">Ring<br>Data</th>
 
<th scope="col">Misc<br>Data</th>
 
<th scope="col">Misc<br>Data</th>
 +
<th scope="col">ToHit<br>Data</th>
 +
<th scope="col">AC<br>Data</th>
 
</tr>
 
</tr>
 
</thead>
 
</thead>
<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>
+
<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><td>X</td><td>X</td></tr>
<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>
+
<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><td> </td><td> </td></tr>
<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>
+
<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><td> </td><td>X</td><td>X</td></tr>
<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>
+
<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><td>X</td><td> </td></tr>
<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>
+
<tr><th scope="row">st:</th><td>' '</td><td>''</td><td>Item type to display</td><td> </td><td>X</td><td>X</td><td>X</td><td>X</td><td>X</td><td>X</td><td>X</td><td> </td><td>X</td></tr>
<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>
+
<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><td>X</td><td>X</td></tr>
<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">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><td>X</td><td> </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">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><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>
+
<tr><th scope="row">rules:</th><td>[+/-][rule] | ...</td><td>0</td><td>Save / Check rules</td><td> </td><td> </td><td> </td><td>X</td><td>X</td><td>X</td><td>X</td><td>X</td><td> </td><td>X</td></tr>
<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">svXXX:</th><td>[=][+/-]#</td><td>0</td><td>Save / Check mod</td><td> </td><td> </td><td> </td><td>X</td><td>X</td><td>X</td><td>X</td><td>X</td><td> </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>
+
<tr><th scope="row">on:</th><td>command</td><td>''</td><td>Cmd to execute when worn</td><td> </td><td> </td><td> </td><td>X</td><td>X</td><td>X</td><td>X</td><td> </td><td> </td><td> </td></tr>
<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>
+
<tr><th scope="row">off:</th><td>command</td><td>''</td><td>Cmd to execute when removed</td><td> </td><td> </td><td> </td><td>X</td><td>X</td><td>X</td><td>X</td><td> </td><td> </td><td> </td></tr>
<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>
+
<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><td> </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> </td><td> </td><td>X</td><td>X</td><td>X</td><td>X</td><td>X</td><td>X</td><td> </td><td>X</td></tr>
 +
<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><td> </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><td> </td><td>X</td></tr>
 +
<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><td> </td><td>X</td></tr>
 +
<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><td>X</td><td>X</td></tr>
 +
<tr><th scope="row">c:</th><td>#</td><td>1</td><td>The number of charges expended by using a charged magic item. Uncharged items always use 0 charges</td><td> </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><td>X</td></tr>
 +
<tr><th scope="row">desc:</th><td>[MU-/PR-/PW-/MI-]name</td><td>' '</td><td>Power or Spell to display</td><td> </td><td> </td><td>X</td><td> </td><td> </td><td> </td><td> </td><td> </td><td>X</td><td> </td></tr>
 +
<tr><th scope="row">msg:</th><td>< text ></td><td>' '</td><td>Attack message</td><td> </td><td> </td><td>X</td><td> </td><td> </td><td> </td><td> </td><td> </td><td>X</td><td> </td></tr>
 +
<tr><th scope="row">cmd:</th><td>Command</td><td>' '</td><td>Attack API command</td><td> </td><td> </td><td>X</td><td> </td><td> </td><td> </td><td> </td><td> </td><td>X</td><td> </td></tr>
 
</table>
 
</table>
 
<br>
 
<br>
 
===Character Sheet data fields===
 
===Character Sheet data fields===
<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 the game-version-specific RPGMaster Library API for the game-version you are using.  You can find the complete mapping for all APIs in the RPGMaster series, with an explanation of each, in a separate document - ask the Author for a copy.</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 the game-version-specific RPGMaster Library API for the game-version you are using.  You can find the complete mapping for all APIs in the [[API:RPGMaster|RPGMaster series]], with an explanation of each, in a separate document - ask the Author for a copy.</p>
 +
 
 +
[[Category:API:RPGMaster]]

Latest revision as of 11:35, 19 June 2023

Main Page: API:RPGMaster

Contents

[edit] Related Wiki Pages

API:RPGMaster - The main Wiki page for the RPGMaster suite of APIs supporting AD&D2e on Roll20
Script:MagicMaster - The API to manage the use of Spells & Magic Items from the databases
Script:AttackMaster - The API that manages saving throws, attribute checks, armour class calculations, as well as melee & ranged weapon attacks

[edit] General Database information

The RPGMaster APIs use a number of databases to hold Macros defining character classes, spells, powers and magic items and their effects. Previous versions of the RPGMaster series of APIs held their databases all externally as character sheets: from this version onwards this is not the case for databases supplied with the APIs, which are now held internally to the APIs. However, the AttackMaster or MagicMaster API command --extract-db can be used to extract any or all standard databases to Character Sheets for examination and update. The APIs are distributed with many class, spell, power & magic item definitions, and DMs can add their own character classes, spells, items, weapons, ammo and armour to additional databases in their own database character sheets, with new definitions for database items held in Ability Macros. Additional database character sheets 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.
Character Races:additional databases: Race-DB-[added name] where [added name] can be replaced with anything you want.
Attack Calculations:additional databases: Attacks-DB-[added name] where [added name] can be replaced with anything you want.
Fighting Styles:additional databases: Styles-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 added database has a similar structure, with:

  • Ability Macros named as the class, spell, power or magic item specified, and used to describe and provide effects for classes, 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);
  • 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 - see Class entry below).

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 MagicMaster API command !magic --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.

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


[edit] Spells and Powers Databases

Spells/Powers databases 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, each spell or power definition has 3 parts in the database (see Section 1): 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 extract the root databases using the !magic --extract-db command, and take a look (but remember to delete it after viewing to speed things up, and then reindex the databases using !magic --check-db)

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.

[edit] Simple Spells

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

[edit] Sleep

&{template:RPGMspell}{{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 provided by the RPGMaster Library (see the documentation for the RPGMaster Library 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>

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. E.g. under AD&D2e rules, 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.

[edit] Spells that need "To Hit"

A more complex spell that needs the caster to hit the target with an attack roll, also known as a weaponised spell, might look something like this:

&{template:RPGMspell}{{title=@{selected|Casting-name} casts<br> Spiritual Hammer<br>as a level @{selected|Casting-Level} caster}}Specs=[Spiritual-Hammer,Innate-Melee|PRspellL2,1H,Evocation],[Spiritual-Hammer,Innate-Melee,1H,Clubs],[Spiritual-Hammer,Innate-Melee,1H,Clubs]{{splevel=Level 2 Priest}}ToHitData=[w:Spiritual Hammer+1,prlv:1:6,+:1,sb:0,n:1,ch:20,cm:1,sz:T,ty:B,sp:3],[w:Spiritual Hammer+2,prlv:7:12,+:2,sb:0,n:1,ch:20,cm:1,sz:T,ty:B,sp:2],[w:Spiritual Hammer+3,prlv:13,+:3,sb:0,n:1,ch:20,cm:1,sz:T,ty:B,sp:1]{{school=Invocation}}{{sphere=Combat}}DmgData=[w:Spiritual Hammer+1,sb:0,+:1,sm:1+1d4,l:1d4],[w:Spiritual Hammer+2,sb:0,+:2,sm:1+1d4,l:1d4],[w:Spiritual Hammer+3,sb:0,+:3,sm:1+1d4,l:1d4]{{components=V,S,M}}weapData=[on:\\api;rounds --target caster|@{selected|token_id}|Spiritual-Hammer|\\lbrak;\\lbrak;3+@{selected|Casting-Level}\\rbrak;\\rbrak;|-1|Magical weapon in direction facing requires concentration|archery-target,off:\api;!rounds --removetargetstatus @{selected|token_id}|Spiritual-Hmmer]{{time=[[5]]}}{{range=[[10*@{selected|Casting-Level}]] yards}}{{duration=[[3+@{selected|Casting-Level}]] rounds}}{{aoe=Special}}{{save=None}}{{reference=PHB p207}}{{damage=SM [1d4+1](! /r 1d4+1) or L [1d4](! /r 1d4) +[[{{(ceil(@{selected|Casting-Level}/6)),3}kl1}]]}}{{damagetype=Bludgeoning}}SpellData=[w:Spiritual-Hammer,lv:2,sp:5,gp:2,cs:VSM,sph:Combat]{{effects=Base Thac0 same as caster [[@{selected|thac0-base}]] without strength bonus plus magical plus of +[[{{(ceil(@{selected|Casting-Level}/6)),3}kl1}]]. Damage is plus magical bonus but no others.}}{{materials=A normal war hammer (cost 2gp) hurled towards opponent, which disappears as spell is cast.}}{{use=Take the Spiritual Hammer in-hand using the *Change Weapon* menu for the duration of the spell, and use it to attack opponents. It will disappear when the duration expires or you *Change Weapon* to another weapon.}}

This spell definition combines the elements of spell database specification and those of a weapon specification. The Specs data now includes the Innate-Melee weapon classification as well as the spell type and level, and as well as the SpellData there are weapon ToHitData and DmgData entries. In addition to the explanation here, please refer to the Weapon and Armour Database Help for more information on these sections.

In this case, there are multiple repeating datasets in each data section: there are three possible variants of the Spiritual Hammer depending on the caster's level. The version to be selected is determined using the level specification attribute in the ToHitData section, in this case using "prlv", but there are four alternatives:

lv:Min : MaxThe minimum and maximum level of character (both optional)
clv:Min : MaxThe minimum and maximum level of spell caster, class based on last spell cast (both optional)
mulv:Min : MaxThe minimum and maximum level of wizard spell caster for this weapon (both optional)
prlv:Min : MaxThe minimum and maximum level of priest spell caster for this weapon (both optional)

In each case, the minimum and maximum are separated by a colon, and either can be left out meaning there is no minimum or no maximum. Wizard and Priest spell casters include those other classes that can cast those spells, at their particular level of spell casting compitence: e.g. a 10th level Ranger is a 2nd level Priest spell caster. If the appropriate value for the caster of the spell falls within the range specified, then that weapon dataset will result in creation of a line in the appropriate weapon tables.

If a spell has these weapon datasets included, and is currently memorised, it will appear in the weapon lists on the Change Weapon menu. Also, if this spell is cast, the Change Weapon menu will appear automatically after the spell description in the Chat window, ready to take the spell "in-hand" as a weapon and attack with it. Whichever way the Change Weapon menu appears, choosing the spell as a weapon will always mark the spell as having been cast. The spell-weapon will remain in-hand until the weapon is changed or the !attk --blank-weapon command is used which might, for instance, be included in the custom attack macro template (e.g. for Chromatic Orb) or in a spell end-effect (e.g. as in the Spiritual-Hammer-end Effect macro).

[edit] Simple Powers

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

[edit] Turn Undead

&{template:RPGMspell}{{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=[Turn It](!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.**
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.
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.
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.


[edit] Magic Item Databases

Magic Item databases 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, Armour, Ring, Miscellaneous, and also DM Only magic items. The quickest way to understand these entries is to examine existing entries. Do extract a root database using the !magic --extract-db command and take a look (but remember to delete it after viewing to speed things up, and then reindex the databases using !magic --check-db)

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

[edit] Simple Magic Items

The Ability Macro may look something like this:

[edit] Oil-of-Etherealness

&{template:RPGMpotion}{{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.
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}}

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, section 4.1. 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.

[edit] Items that Protect

Items like a Ring of Protection or a Luck Blade protect the possessor by improving their saving throws and/or armour class.

[edit] Ring of Protection+2

&{template:RPGMring}&{template:RPGMring}{{name=Ring of Protection}}{{subtitle=Ring}}{{Speed=[[0]]}}{{Size=Tiny}}{{Immunity=None}}{{Protection=+[[2]] on AC}}Specs=[Ring of Protection,Protection Ring,1H,Abjuration-Protection]{{Saves=+[[2]] on saves}}ACData=[a:Ring of Protection+2,st:Ring,+:2,rules:-magic,sz:T,wt:0,svsav:2,w:Ring of Protection+2,sp:0,rc:uncharged,loc:left finger|right finger]{{desc=A ring of protection improves the wearer's Armour Class value and saving throws versus all forms of attack. A ring +1 betters AC by 1 (say, from 10 to 9) and gives a bonus of +1 on saving throw die rolls. The magical properties of a ring of protection are cumulative with all other magical items of protection except as follows:<br>1. The ring does not improve Armour Class if magical armour is worn, although it does add to saving throw die rolls.<br>2. Multiple rings of protection operating on the same person, or in the same area, do not combine protection. Only one such ring—the strongest—functions, so a pair of protection rings +2 provides only +2 protection.}}

All items that protect that are not armour or shields have an item class of some type of protection-[item] specified as the second field of the Specs for the item. The [item] text can be anything you desire, e.g. in this case protection-ring, but only the most advantageous protection-[item] that the possessor has on them will operate. E.g. a protection-ring will work with a protection-cloak but not with another protection-ring.

Items that protect that have an effect on armour class must use the ACData section to specify their properties, otherwise the properties can be held in any other '...data=' specification. The Weapons & Armour Database Help handout has full specifications for ACData fields. The data field tags relevant to AC and saves are listed in the table below:

+: [+/-]# The effect on armour class, + being beneficial, - being a penalty (ACData only).
rules: rule [ | rule | rule | ...] Rules specifying what item types / supertypes / classes this item will or will not work with (see below).
svXXX: [=][+/-]# The effect on various saving throws, specified by XXX, + being beneficial, - being a penalty.

The rules: state conditions and which other items this item will or will not work with to improve armour class and/or saving throws. Each rule is separated by a '|' and preceeded by either '+' or '-'. The rules have the following meanings:

+inHand This item must be held in hand for them to work, using the Change Weapon dialog
+worn (Saves only) This item must be of a usable type that can be worn by the class / race of the character - default for AC
-magic (AC only) This item will not combine with magical armour
-shield (AC only) This item will not combine with a shield of any type
-acall (AC only) This item will not combine with any other armour (except that specified with a '+' - see below)
-[supertype] (AC only) This item will not work with any other item of the supertype specified
+[supertype] (AC only) This item will always work with any other item of the supertype specified, even if -acall rule has been specified
-[item class] (Saves only) This item will not combine with any other item of the item class specified

The svXXX: entries state the effect on saving throws and/or ability checks that this item has if the rules are met. For Saving Throw mods the 'XXX' can be one of 'par', 'poi', 'dea', 'pet', 'pol', 'bre', 'spe', or 'sav' each referring to the first 3 letters of the saving throw affected (or 'sav' for all saving throw mods); and for Attribute Check mods 'XXX' can be 'str', 'con', 'dex', 'int', 'wis', 'chr', and 'atr' each refering to each Character attribute (or 'atr' for all attribute mods); or to change all mods of both types use 'all'. Each svXXX: field tag is followed by a number which can be optionally preceeded by '+' (a beneficial improvement to the mod), '-' (a penalty to the mod), and/or '=' (the mod is set to the value - overrides other changes).

Note: Changing the Attribute mods will not affect the ability checks for open doors, bend bars, learn spells etc. These mods can only be adjusted manually using the appropriate button on the Attribute Check menu.

[edit] More Complex Items

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

[edit] Ring of Human Influence

&{template:RPGMring}{{name=Ring of Human Influence}}{{subtitle=Ring}}Specs=[Ring of Human Influence,Ring,1H,Enchantment-Charm]{{Speed=[[0]]}}RingData=[w:Ring of Human Influence,sp:3,rc:uncharged,loc:left finger|right finger,on:\\apisetattr --fb-from Magic Items --fb-header Ring of Human Influence - Put on --fb-content _CHARNAME_ chooses to put on the Ring of Human Influence and now has a Charisma of 18 vs Humans and Humanoids --name @{selected|character_name} --RoHI-chr|@{selected|charisma} --charisma|18,off:\\apiresetattr --fb-from Magic Items --fb-header Ring of Human Influence - Take off --fb-content _CHARNAME_ chooses to take off the ring and their Charisma returns to normal --name @{selected|character_name} --RoHI-chr --charisma|@{selected|RoHI-chr},ns:2],[cl:PW,w:Suggestion,sp:3,lv:12,pd:1],[cl:PW,w:MU-Charm-Person,sp:3,lv:12,pd:1]{{Size=Tiny}}{{Immunity=None}}{{desc=Has the effect of raising the wearer's Charisma to 18 on encounter reactions with humans and humanoids. The wearer can make a [*suggestion*](!magic --mi-power @{selected|token_id}|Suggestion|Ring-of-Human-Influence|12) to any human or humanoid (saving throw applies). The wearer can also [charm](!magic --mi-power @{selected|token_id}|Charm-Person|Ring-of-Human-Influence|12) up to 21 levels/Hit Dice of human/humanoids (saving throws apply) just as if he were using the wizard spell, *charm person*. The two latter uses of the ring are applicable but once per day. Suggestion or charm has an initiative penalty of +3.}}{{use=Putting on the ring using the Change Weapon function changes Charisma to 18, and taking it off returns Charisma to its previous value. If using InitiativeMaster Group or Individual Initiative, select Initiative for a Magic Item, then the Ring of Human Influence to get the right item speed. Cast the spells by Using the Ring as a Magic Item, then selecting the appropriate spell in the Effect description.}}

Here, as well as having API buttons to implement powers, the RingData entry specifies commands to execute when the ring is put on using the Change Weapon menu, and another when it is taken off, as well as other aspects of the ring's power - but ignore everything after the "ns:" for now.

on: Command string A simple, single line command to execute on wearing the ring
off: Command string A simple, single line command to execute on taking off the ring

[edit] Staff of Striking

&{template:RPGMwand}{{name=Staff of Striking}}Specs=[Staff of Striking|Quarterstaff,Rod|Melee,1H,Staff],[Staff of Striking|Quaretstaff,Melee,1H,Staff],[Staff of Striking|Quarterstaff,Melee,1H,Staff],[Staff of Striking,Rod,1H,Conjuration-Summoning|Animal]{{subtitle=Staff}}ToHitData=[w:Staff of Striking 1 charge,sb:1,+:3,n:1,ch:20,cm:1,sz:M,ty:SPB,r:5,sp:4,c:1,rc:rechargeable],[w:Staff of Striking 2 charges,sb:1,+:3,n:1,ch:20,cm:1,sz:M,ty:SPB,r:5,sp:4,c:2,rc:rechargeable],[w:Staff of Striking 3 charges,sb:1,+:3,n:1,ch:20,cm:1,sz:M,ty:SPB,r:5,sp:4,c:3,rc:rechargeable]{{Speed=[[4]]}}WandData=[qty:19+1d6]{{Size=Medium}}{{Weapon=1-handed melee oaken staff}}{{To-hit=+3, +Str Bonus}}{{Attacks=1 per round, magically the most favourable weapon type}}{{Damage= SM: 1d6, L:1d6, 1 charge: +3, 2 charges: +6, 3 charges: +9}}DmgData=[w:Staff of Striking 1 charge,sb:1,+:3,SM:1d6,L:1d6],[w:Staff of Striking 2 charges,sb:1,+:6,SM:1d6,L:1d6],[w:Staff of Striking 3 charges,sb:1,+:9,SM:1d6,L:1d6]{{Use=Melee weapon attack as normal, selecting the appropriate plus, which will deduct the number of charges automatically.}}{{desc=This oaken staff is the equivalent of a +3 magical weapon. (If the weapon vs. armor type adjustment is used, the staff of striking is treated as the most favorable weapon type vs. any armor.) It causes 1d6+3 points of damage when a hit is scored. This expends a charge. If two charges are expended, bonus damage is doubled (1d6+6); if three charges are expended, bonus damage is tripled (1d6+9). No more than three charges can be expended per strike. The staff can be recharged.}}

The Staff of Striking is a weapon that can do additional damage if more charges are expended. The database definition uses the multiple attack / damage fields (as specified and explained in the Weapon and Armour Database Help handout) which results in multiple entries for the weapon to appear in the weapons tables on the character sheet, and in the Attack menu. Each ToHitData definition has the 'c' attribute to define how many charges are expended when that version of the weapon is used:

c: # The number of charges expended when the respective attack is made. Applies only to weapons / magic items that have charges. If in ToHitData is deducted when an attack is made, or if in DmgData only applies if a hit is achieved & damage done. Defaults to 1 charge (ToHitData) or 0 (DmgData) if not specified.
If this item is not a weapon and the c: is in the item Data specification, it determines how many charges are deducted when the item is used, defaulting to 1.
qty: # or <dice spec> The default quantity of charges the item will start with when added by the GM to a container. Can be a dice roll specification, in which case the number will be determined randomly with a dice roll. The GM can optionally alter this number when storing the item.

When shown in the Attack menu, any version of the weapon which requires more charges than it currently has will be gray, and will not be selectable for an attack.

[edit] Magic Items that must be taken in-hand

Some magic items, especially Rods, Staves and Wands, must be taken in-hand like a weapon in order for their abilities to become fully available to the character by making an Attack action. The Rod of Smiting described above is a weapon of this nature, but others might have magical attacks as well as, or instead of melee or ranged attacks. Here is an example of one such device:

[edit] Wand of Frost

&{template:RPGMwand}{{title=Wand of Frost}}WandData=[w:Wand of Frost,wt:1,sp:2,c:0,rc:rechargeable,loc:left hand|right hand]{{splevel=Wand}}{{school=Evocation}}Specs=[Wand of Frost,Magic|Wand,1H,Evocation],[Wand of Frost,Magic|Wand,1H,Evocation],[Wand of Frost,Magic|Wand,1H,Evocation]{{components=V,M}}{{time=[[2]]}}{{range=Special}}ToHitData=[w:Ice Storm,desc:MU-Ice-Storm,lv:6,sp:2,c:1],[w:Wall of Ice,desc:MU-Wall-of-Ice,lv:6,sp:2,c:1],[w:Cone of Cold,desc:PW-WoF-Cone-of-Cold,lv:6,sp:2,c:2]{{duration=Special}}{{aoe=Special}}{{save=Special}}{{effects=A *frost* wand can perform three functions that duplicate wizard spells:
• *Ice storm:* A silvery ray springs forth from the wand and an ice (or sleet) storm occurs up to 60 feet away from the wand holder. This function requires one charge.
• *Wall of ice:* The silvery ray forms a wall of ice, six inches thick, covering a 600-squarefoot area (10' x 60', 20' x 30', etc.). Its initiative modifier is +2, and it uses one charge.
• *Cone of cold:* White crystalline motes spray forth from the wand in a cone with a 60-foot length and a terminal diameter of 20 feet. The initiative modifier is +2, and the effect lasts just one second. The temperature is -100 degrees F., and damage is 6d6, treating all 1s rolled as 2s (6d6, 12-36). The cost is two charges per use. Saving throw vs. wands is applicable.
The wand can function once per round, and may be recharged.}}{{materials=Wand}}{{Use=Take the wand in-hand using the *Change Weapon* dialogue in order to use its powers with the *Attack* action}}

This specification introduces a new item Specs class, "Magic", and one of a new range of ToHitData fields, "desc":

Magic The associated entries in the ToHitData will specify a magical attack, rather than a melee or ranged attack. There will not be a matching DmgData specification
desc: ' ' The name of an ability macro describing the magical attack - this is a power, wizard or priest spell, or a magic item (even possibly this magic item) which will be displayed to the player when this magical attack is used.
lv:<#>The level at which the magic item casts any power or spell. The spell will have effects as if cast at this level when cast from the magic item.

The power, spell or magic item name used with the desc: field tag will be searched for in all the appropriate databases. However, some exist in more than one context (e.g. Light is both a Wizard and a Priest spell). It is possible to specify where the specific description can be found by preceding the name with one of "PW-", "MU-", "PR-", or "MI-" for Power, Wizard spell, Priest spell, and Magic Item respectively. Specifying the type also speeds up the search.

There are other field tags that can be used with a Magic class ToHitData specification:

pw:' 'The name of a magic item power (with limited uses per day) to use as a magical attack, specified as per Section 4.1 below
msg:' 'A message to display to the player when the magical attack is made, encoded with the standard and extended RPGMaster escape sequences
cmd:' 'An API command to be executed when the magical attack is made, encoded with the standard and extended RPGMaster escape sequences

Generally speaking, the cmd: and msg: tags can be used together instead of a desc: if there is no equivalent spell or power to display and only a simple status, timer or effect results from the magical attack. The pw: tag operates in an almost identical way to desc: but decrements the "per day" uses for the named power/spell (specified in the item data specification - see Section 4.1 below) each time it is used, which refresh after a Long Rest.

[edit] Hiding Magic Item Details

Sometimes, GMs want Players to have to discover the properties of magic items through quests, spell use, trial and error, or paying a high-level wizard to identify them. This is not always the case, and some groups may prefer for some or all items to reveal their nature on first examination. The database specification of an item allows for both approaches. An example of how to define an item to make it easy to hide its details is

[edit] Flask of Curses

&{template:RPGMitem}{{title=Flask}}{{name= of Curses}}{{subtitle=Magic Item}}Specs=[Flask of Curses,Miscellaneous,1H,Alteration]{{Speed=[[3]]}}MiscData=[w:Flask of Curses,st:Flask,wt:1,sp:3,qty:1,rc:charged]{{Size=S}}{{Looks Like=An ordinary flask of some type, containing a little liquid of some unidentifyable sort}}{{Use=The GM will tell you what happens when you use this item}}{{desc=This item looks like an ordinary beaker, bottle, container, decanter, flask, or jug. It has magical properties, but detection will not reveal the nature of the flask of curses. It may contain a liquid or it may emit smoke. When the flask is first unstoppered, a curse of some sort will be visited upon the person or persons nearby. After that, it is harmless. The type of curse is up to the DM}}{{GM Info=Hide this as some other jug, flask or bottle, using the GM's *Add Items* menu, and set *Reveal* to *on use*. Invent an imaginative curse to enact! Suggestions include the reverse of the priest's bless spell. Typical curses found on scrolls are recommended for use here as well. Or perhaps a monster could appear and attack all creatures in sight.}}

Four elements contribute to the "simple" approach to being able to hide the item details from the Player / Character:

    + '
  • The splitting of the title & name of the definition: title is always displayed, and name is only added to the title when hidden details are made displayable by the GM.
  • + '
  • The optional addition of the st: attribute in the MiscData specification, which specifies the name of the item displayed on buttons while details are hidden. If not specified, defaults to the item class.
  • + '
  • The addition of the Looks Like tag which marks text that replaces the description while details are hidden and until the GM reveals the details.
  • + '
  • The Hide item as other item function in the GM's Add Items dialog, which will be available for items that have the Looks Like tag, or for which the GM chooses another item to hide this one as.</p>

The key element is the inclusion of the Looks Like text tag in the definition of the item. If an item has this tag, the GM's Add Items dialog will have the Hide Item as Item button enabled to hide the item as either what the st: data attribute specifies or (if not specified) the item class in the Specs specification of the item. However, if auto-hiding is set in the !magic --config options, an item with a Looks Like text tag will automatically be hidden in this way when added to any container. If a player character views or uses such a hidden item, they will see only the title and the Looks Like text and nothing else. The GM can either set the item to automatically reveal its "secrets" when the player character views the item, uses the item, or only when revealed manually by the GM. It is also possible for the GM to select to hide the item as a completely different item using the Add Items dialog. For full details see the --gm-edit-mi entry in the MagicMaster Help handout.


[edit] 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 --edit-mi or --gm-edit-mi, these attributes are automatically added to the character sheet by the APIs 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.

[edit] Powerful Magic Item

Here is an example of a power wielding magic item:

[edit] Ring-of-Shooting-Stars

!setattr --silent --sel --casting-level|1 --casting-name|@{selected|token_name}'s Ring of Shooting Stars
&{template:RPGMring}{{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:MU-Dancing-Lights,sp:5,pd:12], [cl:PW,w:MU-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: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.
During night hours, under the open sky, the shooting stars ring will perform the following functions:
- [Dancing lights](!magic --mi-power @{selected|token_id}|Dancing-Lights|Ring-of-Shooting-Stars|1) as spell (once per hour).
- [Light](!magic --mi-power @{selected|token_id}|Light|Ring-of-Shooting-Stars|1), as spell (twice per night), 120-foot range.
- [Ball lightning](!magic --mi-power @{selected|token_id}|RoSS-Ball-Lightning|Ring-of-Shooting-Stars|1), as power (once per night).
- [Shooting stars](!magic --mi-power @{selected|token_id}|RoSS-Shooting-Stars|Ring-of-Shooting-Stars|1), as power (special).
Indoors at night, or underground, the ring of shooting stars has the following properties:
[Faerie fire](!magic --mi-power @{selected|token_id}|PR-Faerie-Fire|Ring-of-Shooting-Stars|1) (twice per day) as spell
[Spark shower](!magic --mi-power @{selected|token_id}|RoSS-Spark-Shower|Ring-of-Shooting-Stars|1) (once per day) as power
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:MU-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) optionally prefixed by a power type, one of 'PW-', 'MU-', 'PR-', or 'MI-' for Power, Wizard spell, Priest spell, or Magic Item
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 section 6 and 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. If a power type prefix is included for one or more power name, the respective database is searched for a matching entry: thus a Wizard or Priest spell can be specified as a power without having to explicitly add a duplicate of it to a Powers Database. If no prefix is specified, the system will first search the Powers Databases (API-supplied and user-supplied) for a match and, if not found there, will then search the MU Spells Databases, the Priest Spells Databases, all Magic Items databases, and then the character sheet of the creature wielding the item power for a match, in that order. An error occurs if no matches are found anywhere.

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. The GM can use the --gm-edit-mi menu to rename one or both items with a unique name to differentiate them: see the MagicMaster API documentation for details.

Feel free to just copy the specification for a Ring-of-Shooting-Stars in an extracted copy of 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.

[edit] Spell Storing Magic Item

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

[edit] Ring-of-Spell-Storing-HHSLS

&{template:RPGMring}{{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})
[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:
Priest: 1d6, if 6 is rolled, roll 1d4 instead.
Wizard: 1d8, if 8 is rolled, roll 1d6 instead.
Which spell type of any given level is contained by the ring is also randomly determined.
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. Alternatively, a blank Ring of Spell Storing is provided in the API Rings database. It is possible to use the --gm-edit-mi command menu to select this blank ring and use the facilities provided by the menu to add spells to this blank ring, and then rename it to reflect what the GM wants the ring to be. Again, see the MagicMaster API documentation for details.

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... The GM should use the --gm-edit-mi menu to rename one or both of the rings to give them unique names.

[edit] Magic-Item-storing Items

Some items can store other items, including magic items. When such an item is viewed, used or exchanged between containers and characters, a character sheet specifically for the MI-storing item is created, or found if already previously created. The very act of viewing or using the item will trigger the creation or selection - there is no need for the GM or Player to do so. An example of this is a Bag of Holding.

[edit] Bag of Holding

&{template:RPGMitem}{{name=Bag of Holding}}{{subtitle=Magic Item}}Specs=[Bag of Holding,Miscellaneous,1H,Alteration]{{Size=[[15]]/[[250]]lbs, 30cu.ft}}MiscData=[w:Bag of Holding,st:Bag,sp:0,rc:uncharged,bag:2],[cl:MI,w:Potion-of-Healing,qty:1],[cl:MI,w:Scroll of Protection vs Magic,qty:2]{{Access=Drag the *Bag of Holding* token onto the map and use your MI menu *Search* function (to retrieve stuff from it) or *Store* function (to put stuff in it)}}{{desc=As with other magical bags, this one appears to be a common cloth sack of about 2 feet by 4 feet size. The Bag of Holding opens into a nondimensional space, and its inside is larger than its outside dimensions. Regardless of what is put into this item, the bag always weighs a fixed amount. This weight, the bag's weight limit in contents, and its volume limit are 15 lbs. 250 lbs. 30 cu. ft.
If overloaded, or if sharp objects pierce it (from inside or outside), the bag will rupture and be ruined. The contents will be lost forever in the vortices of nilspace.}}

The important attributes are:

bag:<#>Identifies the item as generating an item character sheet. Up to # items can be defined as initially being held in the item sheet (default 0)
cl:'MI'Subsequent data sets with class 'MI' define items initially held in the item, and will be inserted in a newly created item sheet when first viewed or used
w:<text>The name of the item to initially be stored in the item character sheet MI bag. Should be an item named in a database
qty:<#>The initial quantity of this item to be stored in the item-holding item character sheet MI bag (default 1)

And one additional new attribute:

st:Defines the "Item Type" (or SuperType) to be displayed when a container is searched that has its properties set to only show the types of items contained. If not provided, defaults to the item class from the Specs definition

Thus, the definition of the particular Bag of Holding defined above, when a character has it in their Items & Equipment and either views or uses the item, will result in a new separate character sheet being created, named "Bag of Holding" (same as the item), placed in the controlling Player's journal and marked as controlled by that player, and for one Potion of Healing and two Scrolls of Protection vs. Magic to be inserted automatically into the Bag of Holding, ready for the Character to find and use by dragging the bag onto the map from their Journal and Searching the Bag.

Once the Bag is created, the existing items can be taken out into the Character's own items & equipment, or new ones placed in the bag, the bag passed from one Character to another or itself placed in a different container.

It is recommended that, where a GM places multiple item-holding items in a campaign, such as multiple Bags of Holding, that the GM uses the functions of the [Add Items] menu to rename each with a different name in the original container to which they are placed and before each is viewed or used (i.e. before the item character sheet is created by the system) - perhaps naming each after some previous owner or its creator. This prevents confusion with multiple Character Sheets all with the same name (which Roll20 will allow, but can definately be confusing for the GM who will see them all even if players only see the ones they control).


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


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


[edit] Specs & Data field values

Below are lists of the current possible values for the item database Ability macro sections.

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

[edit] Spell Types

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

[edit] Spell Item-Classes

MUSpellL#A Wizard spell with the Level specified as a number
PRSpellL#A Priest spell with the Level specified as a number
PowerA Power

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

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


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

[edit] Magic Item Classes

Any magic item can have more than one class, each separated by a vertical bar '|'. It will then behave and be listed as each of the specified classes.

WeaponWeapons that are not Melee or Ranged weapons or any other class
MagicMagic attacks that are not melee or ranged attacks, often a spell or power of a magic item
MeleeMelee weapons that are used in hand-to-hand combat
Innate-MeleeMelee weapons that do not attract any proficiency penalties
RangedRanged weapons that are either thrown or fire ammunition
Innate-RangedRanged weapons that do not attract any proficiency penalties
AmmoAll types of ammunition that is used by Ranged weapons
ArmourAny type of armour that does not need to be held to work
ArmorThe same as Armour
HelmAny type of armour or clothing worn on the head
ShieldA barrier that is held in hand(s) and defends against one or more attacks from the front
Protection-cloakAny type of clothing that has protective qualities
PotionAny type of potion, oil, pill or similar that is consumed or rubbed on
ScrollScrolls and spell books, that contain one or multiple spells
ScrollcaseAn object that can hold a scroll
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
Protection-RingAny special type of ring that imparts protective qualities
Protection-[item]Any item (other than clothing or a ring) that imparts protective qualities
LightAll types of lantern, torch, and other illumination
DM-itemAn item that only appears in a list button on the menu displayed by --gm-edit-mi
Attack-macroAn attack macro template for a magic item held in a MI database
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

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

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

[edit] Data Sections

Definitions for Data Section field types for Weapons & Armour can be found in the AttackMaster API documentation. 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.

<thead> </thead>
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
ToHit
Data
AC
Data
w:< text >'-'Name to be displayed XXXXXXXXX
w:< text >Name of spell or power (Not case sensitive)X
+:[ + / - ] #0Magical adjustment XXXX XX
n:# [ / # ]1Attacks per round XXX XX
st:' 'Item type to display XXXXXXX X
sz:[ t / s / m / l / h ]Size of item XXXXXXX
sp:[-]# or Dice Roll spec0Speed in segments (1/10 round)XXXXXXXXX
wt:#1Weight of item in lbs X XXX XX
rules:[+/-][rule] | ...0Save / Check rules XXXXX X
svXXX:[=][+/-]#0Save / Check mod XXXXX X
on:commandCmd to execute when worn XXXX
off:commandCmd to execute when removed XXXX
ns:#0Number of stored spells & powers defined for item XXXXXX X
w:< text >'-'Name of stored spell or power (Not case sensitive) XXXXXX X
cl:MU / PR / PWType of stored spell or power XXXXXX X
lv:#1Level at which spell/power is cast XXXXX X
pd:-1 / #1Number per day (power only) XXXXX X
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 XXXXXXXXX
c:#1The number of charges expended by using a charged magic item. Uncharged items always use 0 charges XXXXXXXXX
desc:[MU-/PR-/PW-/MI-]name' 'Power or Spell to display X X
msg:< text >' 'Attack message X X
cmd:Command' 'Attack API command X X


[edit] 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 the game-version-specific RPGMaster Library API for the game-version you are using. You can find the complete mapping for all APIs in the RPGMaster series, with an explanation of each, in a separate document - ask the Author for a copy.