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

Personal tools

From Roll20 Wiki

Jump to: navigation, search
 
(129 intermediate revisions by one user not shown)
Line 1: Line 1:
{{revdate}}
+
<h1>Spell, Power & Magic Item Databases</h1>
This API supports initiative for RPGs (initially only AD&D 2e) using the Turn Order and the Tracker window.  The InitiativeMaster API provides functions dealing with all aspects of: managing how initiative is done; rolling for initiative; for “group” and “individual” initiative types providing Character action selection to determine the speed and number of attacks of weapons, the casting time of spells & the usage speed of magic items; supporting initiative for multiple attacks with one or multiple weapons per round; supporting and tracking actions that take multiple rounds; managing the resulting Turn Order; as well as performing the “End of Day” activityIt works very closely with the RoundMaster API to the extent that InitiativeMaster cannot work without RoundMaster (though the reverse is possible).  InitiativeMaster also works closely with AttackMaster API and MagicMaster API and uses the data configured on the Character Sheet by these other APIs, although it can use manually completed Character Sheets once correctly configured.<br>
+
<h2>General Database information</h2>
This API is currently configured to only use the AD&D2e Character Sheet from Peter BIt uses the Roll Templates defined in that sheet extensivelyIt may be possible to use it with other character sheets if you follow the instructions in the Section on '''Configuring the Token and Character Sheet for use''' and future development will focus on implementing more generic functionality.
+
{| role="presentation" class="wikitable mw-collapsible mw-collapsed"
{{script overview
+
|
|name=RoundMaster
+
|-
|author={{user profile|6497708|Richard E}}
+
|<p>The RPGMaster APIs use a number of Character Sheets as databases to hold Ability Macros defining character classes, attack templates, spells, powers and magic items and their effectsThe API is distributed with many class, attack, spell, power & magic item definitions, and checks for, creates and updates these Character Sheet databases on start-upDMs can add their own character classes, attack templates, spells, items, weapons, ammo and armour to additional databases, but the databases provided are totally rewritten when new updates are released so the DM must add their own database sheetsIf the provided databases are accidentally deleted, they will be automatically recreated the next time the Campaign is opened. Additional databases should be named as follows:</p>
|version=1.037
+
<table>
|lastmodified=2021-12-02
+
<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>
|code=InitMaster
+
<tr><th scope="row">Priest Spells:</th><td>additional databases: PR-Spells-DB-<i>[added name]</i> where <i>[added name]</i> can be replaced with anything you want.</td></tr>
|dependencies={{api repository link|RoundMaster}}
+
<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>
|conflicts=None}}
+
<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>
== Syntax ==
+
<tr><th scope="row">Attack Templates:</th><td>additional databases: Attacks-DB-<i>[added name]</i> where <i>[added name]</i> can be replaced with anything you want.</td></tr>
The InitiativeMaster API is called using !init.  
+
</table>
<pre>!init --help</pre>
+
<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>
Commands to be sent to the InitiativeMaster API must be preceeded by two hyphens ‘--’ as above for the --help command. Parameters to these commands are separated by vertical bars ‘|’, for example:
+
<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>
<pre>!init --init [party-roll]|[foes-roll]</pre>
+
<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 onesOtherwise, Players will not be able to run the macros contained in them.</p>
If optional parameters are not to be included, but subsequent parameters are needed, use two vertical bars together with nothing between them, e.g.
+
<p>Each database has a similar structure, with:</p>
<pre>!--init  |[foes-roll]</pre>
+
<ul>
Commands can be stacked in the call, for example:
+
<li>Ability Macros named as the class, attack type, spell, power or magic item specified, and used to describe and provide effects for classes, attacks, spells, powers and magic items using the commands in the RPGMaster APIs;</li>
<pre>!init --doCharList  ALL  --init </pre>
+
<li>Custom Attributes with the attribute name "ct-ability-macro-name", one per Ability Macro, which defines the casting time and casting cost for spells & powers, and speed and MI type for magic items (not currently used for Class or Attack definitions, but they still have to exist);</li>
When specifying the commands in this document, parameters enclosed in square brackets [like this] are optional: the square brackets are not included when calling the command with an optional parameter, they are just for description purposes in this document.  Parameters that can be one of a small number of options have those options listed, separated by forward slash ‘/’, meaning at least one of those listed must be provided (unless the parameter is also specified in [] as optional): again, the slash ‘/’ is not part of the command. Parameters in UPPERCASE are literal, and must be spelt as shown (though their case is actually irrelevant).
+
<li>An entry in a list on the character sheet in the spell book of the relevant Character Sheet tab (Spell Level of the spell defined, Powers tab, or various spell books for different Classes & Magic Items).</li>
 
+
</ul>
== Installation and Configuration ==
+
<p>However, as with all other Databases in the RPGMaster Suite of APIs, if the <i>Ability Macros</i> are correctly set up using the formats detailed in the Help Documentation, the <b>AttackMaster API</b> command <b>!attk --check-db database-name</b> will check the database and set up all other aspects for you, including the correct Custom Attributes and List entries.</p>
Copy the script's code, available from the menu on the right and stored at Roll20's [https://github.com/Roll20/roll20-api-scripts API GitHub Repository]. Paste the code into a new script in your campaign's [[API:Use_Guide#The_Script_Editor|API Script Editor]]. Save the new script and it will be available inside your campaignIt will install several new Character Sheets & Handouts: The handout '''InitiativeMaster Help''' provides a full manual of how to use InitiativeMaster. The handout '''RPGMaster CharSheet Setup''' provides information on setting up a character sheet for use with InitiativeMaster.
+
<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>
 
+
<h3>Replacing Classes, Attacks, Spells & Items</h3>
== Script Use ==
+
<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>
After installing the script, refer the the handout '''InitiativeMaster Help''' for full information on use.  Below is a copy of the contents of that handout.
+
 
+
=Command Index=
+
All commands are preceded by !init unless otherwise stated.
+
==Manage Initiative type, rolls & party==
+
<pre>--init [party-roll]|[foes-roll]
+
--type < STANDARD / GROUP / INDIVIDUAL ></pre>
+
==Show group / individual Initiative menus==
+
<pre>--menu [token-id]
+
--monmenu [token-id]</pre>
+
==Show action-specific Initiative menus==
+
<pre>--weapon [token-id]
+
--monster [token-id]
+
--complex [token-id]
+
--muspell [token-id]
+
--prspell [token-id]
+
--power [token-id]
+
--mibag [token-id]
+
--thief [token-id]
+
--other [token-id]</pre>
+
==Maintain the Turn Order and Rounds==
+
<pre>--maint
+
--check-tracker
+
--list-pcs  ALL / MAP / REPLACE / ADD</pre>
+
==End of Day processing==
+
<pre>--end-of-day [cost]</pre>
+
==Other commands==
+
<pre>--help
+
--hsq from|[command]
+
--handshake from|[command]
+
--debug ON/OFF</pre>
+
==Configuring the Token and Character Sheet for use==
+
==Character Sheet data fields==
+
 
<br>
 
<br>
 +
|}
 +
<h2>Spells and Powers Databases</h2>
 +
<p>Spells/Powers databases are all character sheets that have names that start with</p>
 +
<p> <b>Wizard Spells:</b> MU-Spells-DB-[added name]<br>
 +
<b>Priest Spells:</b> PR-Spells-DB-[added name]<br>
 +
<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>As previously stated in the General Database Information section, each spell or power definition has 3 parts in the database: an Ability Macro with a name that is unique and matches the spell or power, an Attribute with the name of the Ability Macro preceded by "ct-", and a listing in the database character sheet of the ability macro name separated by '|' along with others of the same level in the spell book of the level of the spell or power.  The quickest way to understand these entries is to examine existing entries.  Do go to the root databases and take a look (but be careful not to alter anything unless you know what you're doing!)</p>
 +
<p><b>Note:</b> The DM creating new spells and powers does not need to worry about anything other than the Ability Macro in the database, as running the command <b><i>[[Script:MagicMaster#Check_database_completeness_.26_integrity_.28GM_only.29|--check-db]]</i></b> will update all other aspects of the database appropriately for all databases, as long as the Specs and Data fields are correctly defined. Use the name of the particular database as a parameter to check and update just that database.  Running the command <b><i>--check-db</i></b> with no parameters will check and update all databases.</p>
 +
<p>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><b>The Ability Macro</b> for a spell may look something like this:</p>
 +
<h3>Sleep</h3>
 +
<p style="display: inline-block; background-color: lightgrey; border: 1px solid black; padding: 4px; color: dimgrey; font-weight: extra-light;">/w "@{selected|character_name}" <nowiki>&{template:2Espell}{{title=@{selected|casting-name} casts Sleep as a level @{selected|casting-level} caster}}{{splevel=Level 1 Wizard}}{{school=Enchantment/Charm}}</nowiki><span style="color:green">Specs=[Sleep,MUspellL1,1H,Enchantment-Charm]</span><nowiki>{{range=90 ft}}{{components=V, S, M}}{{duration=[[5*({10,@{selected|casting-level}}kl1)]] Rounds}}{{time=1}}{{aoe=[30ft Cube](</nowiki><span style="color:red">!rounds --aoe @{selected|token_id}|square|feet|90|30||dark</span><nowiki>)}}{{save=None}}{{damage=[Sleep them](</nowiki><span style="color:red">!rounds --target area|@{selected|token_id}|&#64;{target|Select who to sleep|token_id}|Sleep|[[5*({10,@{selected|casting-level}}kl1)]]|-1|Snoring away, shake to awaken|sleepy</span>)}}<span style="color:blue">SpellData=[w:Sleep,lv:1,sp:1,gp:0.01,cs:VSM]</span><nowiki>{{effects=Up to [2d4](!\&#13;\&#47;r 2d4) Hit Dice of creatures with 4 HD or less are put to sleep beginning with the lowest HD creatures in the Area of Effect.}}{{materials=a pinch of fine sand, rose petals, or a live cricket.}}</nowiki></p>
 +
<p>The ability specification for this Sleep spell uses a Roll20 Roll Template, in this case defined by the Advanced D&D 2e Character Sheet by Peter B (see the documentation for the Character Sheet on Roll20 for specifications of this Roll Template), but any Roll Template you desire can be used.  The entries in the Roll Template itself can be anything you desire, giving as much or as little information as you want.  However, the important elements for the MagicMaster API are those highlighted.  In red, two API buttons grant the player access to run RoundMaster API commands to show the Area of Effect of the spell, and then to mark affected tokens with a "Sleepy" status.  Each of the elements important to the database are inserted between the elements of the Roll Template, meaning they will not be seen by the player when the macro is run.  Generally spaces, hyphens and underscores in the data elements are ignored, and case is not significant.  Each element is described below:</p>
 +
<pre>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>
 +
<table>
 +
<tr><th scope="row">Type</th><td>the type of the spell, often the same as the ability macro name.</td></tr>
 +
<tr><th scope="row">Class</th><td>one of MUSpellL#, PRSpellL#, or Power, where # is replaced by the spell level number.</td></tr>
 +
<tr><th scope="row">Handedness</th><td>#H, where # is the number of hands needed to cast the spell - i.e. does it have a somatic component.</td></tr>
 +
<tr><th scope="row">Spell School</th><td>the group of related spells that the spell belongs to.</td></tr>
 +
</table>
 +
<pre>SpellData=[w:Sleep,lv:1,sp:1,gp:1,cs:VSM]</pre>
 +
<p>The SpellData section specifies the data relating to the use of the spell.  These fields can be in any order.</p>
 +
<table>
 +
<tr><th scope="row">w:</th><td>&lt;text&gt;</td><td>the name of the spell</td></tr>
 +
<tr><th scope="row">sph:</th><td>&lt;text&gt;</td><td>the sphere of a priest spell (not used for wizard spells)</td></tr>
 +
<tr><th scope="row">lv:</th><td>&lt;#&gt;</td><td>the level of the spell</td></tr>
 +
<tr><th scope="row">sp:</th><td>&lt;[-]# or dice roll spec&gt;</td><td>the casting time in segments for the spell.  Can be >10 e.g. 20 for 2 rounds, or negative, or even a dice roll</td></tr>
 +
<tr><th scope="row">gp:</th><td>&lt;#[.#]&gt;</td><td>the cost of the material components of the spell in GP: fractions converted to SP & CP</td></tr>
 +
<tr><th scope="row">cs:</th><td>&lt;VSM&gt;</td><td>the component of the spell (Verbal, Somatic, Material) - can be any combination</td></tr>
 +
</table>
 +
<p>The casting time (or speed) <b>sp:</b> can be negative, meaning it gives a negative modifier to individual initiative (if <b>InitMaster API</b> is being used).  It can also be greater than 10 segments, meaning it takes longer than 1 Round to cast.  Multiply the number of Rounds it will take to cast by 10, or the number of Turns it will take to cast by 100 (if using the <b>InitMaster API</b> the rounds will be automatically counted down and the spell actually cast in the appropriate round, unless the casting is interrupted).  It can also be a dice roll specification, which will be rolled at the point that a character selects the spell, power or item to use in a particular round, which means the speed can vary from round to round.  Potions are always of this nature (see the AD&D2e DMG p141).</p>
 +
<p>The cost of material components, <b>gp:</b>, is deducted from the Caster's money on their Character Sheet each time the spell is cast.  The GM is informed of the spell being cast, by whom, and how much money it cost and how much money the Caster has left for each casting.</p>
 +
<p>The components of the spell, <b>cs:</b>, is currently not used and is for future expansion capabilities.</p>
 +
<p><b>The Ability Macro</b> for a Power may look something like this:</p>
 +
<h3>Turn Undead</h3>
 +
<p style="display: inline-block; background-color: lightgrey; border: 1px solid black; padding: 4px; color: dimgrey; font-weight: extra-light;">/w "@{selected|character_name}" <nowiki>&{template:2Espell}{{title=@{selected|token_name} attempts to Turn Undead as a level @{selected|pr-casting-level} @{selected|class3}}} {{splevel=Power}} {{school=Necromancy}}</nowiki><span style="color:green">Specs=[Turn-Undead,Power,1H,Necromancy]</span><nowiki>{{components=V,S}}{{time=[[10]]}}{{range=0}}{{duration=Until broken}}{{aoe=Undead within line of sight}}{{save=See turning table}}{{reference=PHB p103}}{{damage=[Roll 1d20](</nowiki><span style="color:red">!&#13;&#47;r 1d20 check vs. your turning table</span><nowiki>) then if successful [Turn Them](</nowiki><span style="color:red">!rounds --target area|@{selected|token_id}|&#64;{target|Select undead|token_id}|Turned|99|0|Turned undead, flee if free-willed, stand aside if controlled|screaming</span>)}}<span style="color:blue">SpellData=[w:Turn Undead, sp:10, cs:VS]</span><nowiki>{{effects=**Remember that Paladins turn as a Priest of 2 levels lower.**<br>
 +
Attempting to turn counts as an action, requiring one round and occurring during the character's turn in the initiative order (thus, the undead may get to act before the character can turn them). The mere presence of the character is not enough--a touch of drama from the character is important. Speech and gestures are important, so the character must have his hands free and be in a position to speak. However, turning is not like spellcasting and is not interrupted if the character is attacked during the attempt.<br>
 +
To resolve a turning attempt, look on Table 61. Cross-index the Hit Dice or type of the undead with the level of the character (two levels lower for a paladin). If there is a number listed, roll 1d20. If the number rolled is equal to or greater than that listed, the attempt is successful. If the letter "T" (for "turned") appears, the attempt is automatically successful without a die roll. If the letter "D" (for "dispel") is given, the turning utterly destroys the undead. A dash (--) means that a priest or paladin of that level cannot turn that type of undead. A successful turn or dispel affects 2d6 undead. If the undead are a mixed group, the lowest Hit Dice creatures are turned first.<br>
 +
Only one die is rolled regardless of the number of undead the character is attempting to turn in a given round. The result is read individually for each type of undead.}}{{material=The Priest's holy symbol}}</nowiki></p>
 +
<p>Essentially, Powers are just Spells by another name, that can be cast multiple times per day, and are innate to the Character's class, or to a creature.  The specification is, therefore, almost identical to a spell.  In the author's campaigns, Powers do not consume material components and therefore do not cost money to use (except in rare circumstances) hence there being no <b>gp:</b> specification (it defaults to 0gp), but other DMs can add material costs for Powers if desired.  Powers are all 1 level, hence no <b>lv:</b> specification.</p>
 
<br>
 
<br>
=Command Details=
+
<h2>Magic Item Databases</h2>
==Manage Initiative type, rolls & party==
+
<p>Magic Item databases are all character sheets that have names such as</p>
===Manage the Initiative process===
+
<p> <b>Magic Items:</b> MI-DB-[added name]</p>
<pre>--init [party-roll]|[foes-roll]</pre>
+
<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>
DM Only command.  Takes an optional dice roll result for the Party, and an optional dice roll result for the foes.<br>
+
<p>As previously stated and as for other magic, each magic item definition has 3 parts in the database (see Section 1): an Ability Macro with a name that is unique and identifies the magic item, an Attribute with the name of the Ability Macro preceded by "ct-", and a listing in the database character sheet of the ability macro name separated by '|' along with others of the same magic item type, which is one of: Potion, Scroll, Rod/Stave/Wand, Weapon & Ammo, Armour, Ring, Miscellaneous, and also DM Only magic items.  The quickest way to understand these entries is to examine existing entries.  Do go to the root database and take a look (but be careful not to alter anything unless you know what you're doing!)</p>
This command displays a chat menu to specify:<br>
+
<p><b>Note:</b> The DM creating new magic items does not need to worry about anything other than the Ability Macro in the database, as running the command <b><i>[[Script:MagicMaster#Check_database_completeness_.26_integrity_.28GM_only.29|--check-db]]</i></b> will update all other aspects of the database appropriately for all databases, as long as the Specs and Data fields are correctly defined. Use the name of the particular database as a parameter to check and update just that database.</p>
<ul><li>the type of initiative to do (standard, group or individual),</li>
+
<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 editingAbility macros are standard Roll20 functionality and not dependent on the APIRefer to the Roll20 Help Centre for more information.</p>
<li>the initiative rolls for the Party and the Foes (for standard and group initiative),</li>
+
<p><b>The Ability Macro</b> may look something like this:</p>
<li>who is in the Party,</li>
+
<h3>Oil-of-Etherealness</h3>
<li>to check if everyone has selected their action for the next round (for group and individual initiative),</li>
+
<p style="display: inline-block; background-color: lightgrey; border: 1px solid black; padding: 4px; color: dimgrey; font-weight: extra-light;">/w "@{selected|character_name}" <nowiki>&{template:2Espell}{{title=Oil of Etherealness}} {{splevel=Oil}} {{school=Alteration}}</nowiki><span style="color:green">Specs=[Oil of Etherealness,Potion,1H,Alteration]</span><nowiki>{{components=M}}{{time=[[3]] rounds after application}} </nowiki><span style="color:blue">PotionData=[sp:30,rc:charged]</span><nowiki>{{range=User}}{{duration=4+1d4 turns}} {{aoe=User}} {{save=None}} {{healing=[Become Ethereal](</nowiki><span style="color:red">!rounds --target single|@{selected|token_id}|&#64;{target|Select a target|token_id}|Oil-of-Etherealness|&#91;[10*(4+1d4)]&#93;|-1|Ethereal|Ninja-mask</span><nowiki>)}}{{effects=This potion is actually a light oil that is applied externally to clothes and exposed flesh, conferring etherealness. In the ethereal state, the individual can pass through solid objects in any direction - sideways, upward, downward - or to different planes. The individual cannot touch non-ethereal objects.<br>
<li>and whether to show this menu automatically as each new round starts.</li></ul>
+
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>
The different types of AD&D2e Initiative process are explained in the DMG p55, and consist of “standard”, “group”, and “initiative”:<br>
+
<p>You might notice that the structure of this macro is extremely similar to that of a spell: indeed, it uses the same Roll TemplateAs this is an Oil that achieves the same effect as a spell, this is not surprising.</p>
{| class="wikitable"
+
<p>However, there is one new field in the data section (in this case called the PotionData section):</p>
|+
+
<table>
|-
+
<tr><th scope="row">rc:</th><td>&lt;MI-type&gt;</td><td>the recharging/curse type of the magic item.</td></tr>
! scope="row"| Standard:
+
</table>
|| the Party and the Foes (DM) each roll 1d10, and all of whichever gets the lowest roll goes first.  The system supports taking the two rolls, and putting entries in the Turn Order for all defined Party members, and one entry for the Foes.
+
<p>All magic items have a recharging/curse type: for details, see the <b>[[Script:MagicMaster#DM.2FGM_version_of_Magic_Item_management|--gm-edit-mi]]</b> command in the MagicMaster API help documentation.  If not supplied for a magic item definition, it defaults to unchargedGenerally, 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>Other magic items might use different structures, and be more complex:</p>
! scope="row"| Group:
+
<h3>Bead-of-Force</h3>
|| the Party and the Foes (DM) each roll 1d10, and then all Party members and all Foes choose what actions they will perform during the next round.  The speed/casting time of the Character’s / Foes selected action will then be added to the relevant roll to define the Character’s / Foes initiative(s) which are added to the Turn Order.
+
<p style="display: inline-block; background-color: lightgrey; border: 1px solid black; padding: 4px; color: dimgrey; font-weight: extra-light;">/w "@{selected|character_name}" <nowiki>&{template:'+fields.defaultTemplate+'}{{name=Bead of Force}}{{subtitle=Magic Item}}</nowiki><span style="color:green">Specs=[Bead of Force,Miscellaneous,1H,Evocation]</span><nowiki>{{Speed=[[0]]}}</nowiki><span style="color:blue">MiscData=[w:Bead of Force,sp:0,rc:charged]</span><nowiki>{{Size=Tiny}}{{Range=[Up to 30yds](</nowiki><span style="color:red">!rounds --aoe @{selected|token_id}|circle|yards|0|60||dark|true</span><nowiki>)}}{{damage=[5d4](!&#13;&#47;gmroll 5d4 damage from Bead of Force in 10ft redius) damage in 10ft radius}}{{duration=3d4 rounds}}{{Save=[To escape sphere](!&#13;&#47;gmroll 1d20 Save vs. spell or captured in *Sphere of Force*)}}{{Effect=[Trapped in Sphere](</nowiki><span style="color:red">!rounds --target area|@{selected|token_id}|Bead-of-Force|8|-1|'Held in Sphere of Force'|fishing-net</span><nowiki>)}}{{desc=These small, black spheres might be mistaken for common beads, marbles, or unusually black but lusterless pearls. From 5-8 of these beads are usually found at one time. Each is about three-quarters of an inch in diameter and quite heavy, weighing almost an ounce. One can be hurled up to 30 yards.<br>
|-
+
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>
! scope="row"| Individual:
+
The sphere will form around any and all such creatures in the 10-foot-radius area, even those of large size, and will persist for 3d4 rounds. Victims will be unable to escape except by the same means and used to bring down a wall of force spell.}}</nowiki></p>
|| each individual Character & Foe chooses what action they will do each round, and the speed/casting time of that action is added to an individual system-rolled 1d10 for that Character / Foe resulting in each Character’s initiative(s) which are all added to the Turn Order.
+
<p>The Bead of Force ability macro uses a Default Roll Template, which means the only mandatory field is the {{name=}} field, and the DM can define any other fields they want to describe and enact the magic itemHere, 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>
|}
+
<br>
The type of initiative selected persists between game sessions.<br>
+
<h2>Magic Items with Powers or Spell-Storing</h2>
Who is in the party can be defined by using API Buttons on the menu to do one of:<br>
+
<p>Some magic items, especially artefacts and sentient items, can store spells and/or have powers similar to charactersMagicMaster supports magic items of this type to a degree, although there are inevitably exceptions that the DM will have to get creative in their development!  These items use API buttons that call various MagicMaster commands to deliver their capabilities.</p>
<ul><li>search all maps in the Campaign for tokens controlled by Players;</li>
+
<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 occurBy 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 itemsAs standard AD&D2E only has spells up to level 9 this generally works without causing problems.</p>
<li>search just the map the Players are on for tokens controlled by Players;</li>
+
<p>Next, in addition to the three standard elements of the Ability Macro, the 'ct-' attribute and the listing, these items require a 4th element which specifies their powers and spellsThese are:</p>
<li>select a number of tokens on any map and add them to the list; or</li>
+
<table>
<li>replace the whole list with the selected tokens.</li></ul>
+
<tr><th scope="row">mi-muspells-[item-name]:</th><td>Wizard spells able to be stored in the magic item</td></tr>
Another API button checks to see if the Turn Order contains entries for every token listed as being in the Party, i.e. that everybody has selected their actions for the next round.<br>
+
<tr><th scope="row">mi-prspells-[item-name]:</th><td>Priest spells able to be stored in the magic item</td></tr>
This menu can appear automatically as each completed round finishes if RoundMaster API is managing the Turn Order and RoundsThis is useful for standard and group initiative, as the first thing that needs to happen is for the Party & Foe initiative dice rolls to be enteredIt is less useful for this menu to appear for individual initiative, and it can be turned off with another API Button.<br>
+
<tr><th scope="row">mi-powers-[item-name]:</th><td>Powers able to be used by the magic item</td></tr>
 
+
</table>
===Set the type of Initiative being used in the Campaign===
+
<p>In each case the <i>[item-name]</i> is replaced by the Ability macro name (which is not case sensitive).</p>
<pre>--type < STANDARD / GROUP / INDIVIDUAL ></pre>
+
<p><b>Note:</b> The DM creating new spell storing or power wielding magic items does not need to worry about anything other than the Ability Macro in the database, as running the command <b><i>[[Script:MagicMaster#Check_database_completeness_.26_integrity_.28GM_only.29|--check-db]]</i></b> will update all other aspects of the database appropriately for all databases, as long as the Specs and Data fields are correctly defined. Use the name of the particular database as a parameter to check and update just that database. Running the command <b><i>--check-db</i></b> with no parameters will check and update all databases.</p>
Takes a mandatory initiative type which must be one of those shown.<br>
+
<p>When a spell-storing or power wielding magic item is added to a magic item bag or container using [[Script:MagicMaster#Edit_a_Magic_Item_bag|!magic --edit-mi]] or [[Script:MagicMaster#DM.2FGM_version_of_Magic_Item_management|!magic --gm-edit-mi]], these attributes are added to the character sheet and also they are parsed by the system and the spells and/or powers are created in the relevant spell books automaticallyWhen such an item is found in a container by a character, or passed from character to character, all of the stored spells & powers are deleted from the old character and created in the new character.  A character gaining such an item can use its spells and powers immediately.</p>
This command sets the initiative type to the specified type without bringing up the complete --init menu.  The type of initiative specified persists between game sessions.<br>
+
<p>Here is an example of a power wielding magic item:</p>
 
+
<h3>Ring-of-Shooting-Stars</h3>
==Show Group / Individual initiative action selection menus==
+
<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}" <nowiki>&{template:'+fields.defaultTemplate+'}{{name=Ring of Shooting Stars}}{{subtitle=Ring}}</nowiki><span style="color:green">Specs=[Ring of Shooting Stars,Ring,1H,Evocation]</span><nowiki>{{Speed=[[5]]}}</nowiki><span style="color:blue">RingData=[w:Ring of Shooting Stars,sp:5,rc:charged,ns:6], [cl:PW,w:RoSS-Dancing-Lights,sp:5,pd:12], [cl:PW,w:RoSS-Light,sp:5,pd:2], [cl:PW,w:RoSS-Ball-Lightning,sp:5,pd:1], [cl:PW,w:RoSS-Shooting-Stars,sp:5,pd:3], [cl:PW,w:RoSS-Faerie-Fire,sp:5,pd:2], [cl:PW,w:RoSS-Spark-Shower,sp:5,pd:1]</span><nowiki> {{Size=Tiny}} {{Immunity=None}} {{Resistance=None}} {{Saves=None}} {{desc=This ring has two modes of operation - at night and underground - both of which work only in relative darkness.<br>
===Display a menu of possible actions for the selected Character / NPC===
+
***During night hours, under the open sky***, the shooting stars ring will perform the following functions:<br>
<pre>--menu [token-id]</pre>
+
- [*Dancing lights*](</nowiki><span style="color:red">!magic --mi-power @{selected|token_id}|RoSS-Dancing-Lights|Ring-of-Shooting-Stars|1</span><nowiki>) as spell (once per hour).<br>
Takes an optional token ID.  If token ID is not supplied, the selected token is used.<br>
+
- [*Light*](</nowiki><span style="color:red">!magic --mi-power @{selected|token_id}|RoSS-Light|Ring-of-Shooting-Stars|1</span><nowiki>), as spell (twice per night), 120-foot range.<br>
This command displays a chat menu of buttons for types of action that the Character / NPC / creature can perform.  Each of these buttons may take the Player to a more detailed list of specific action buttons. Selecting any of the buttons will add the speed/casting time and correct number of instances of the selected action to the group or individual initiative dice roll (1d10) and enter the result in the Turn Order using the RoundMaster API – ‘individual’-type initiative dice rolls are performed in the background by the API and there is currently no option for the Player to do the roll instead.<br>
+
- [*Ball lightning*](</nowiki><span style="color:red">!magic --mi-power @{selected|token_id}|RoSS-Ball-Lightning|Ring-of-Shooting-Stars|1</span><nowiki>), as power (once per night).<br>
The system displays immediately and also records the action selected and the speed of that action along with any modifiers as a message to display when the Character’s / NPCs / creature’s turn comes around. For each type of action, once chosen, the “rate” is displayed as the number of attacks per round multiplied by any magical modifier (such as a Haste spell). The “speed” is displayed as the speed of the action in segments (1/10ths of a round), and the “modifier” is the bonus or penalty to the roll for other magical effects (such as a Slow spell).<br>
+
- [*Shooting stars*](</nowiki><span style="color:red">!magic --mi-power @{selected|token_id}|RoSS-Shooting-Stars|Ring-of-Shooting-Stars|1</span><nowiki>), as power (special).<br>
For multiple actions per round, those subsequent to the first action with the same item have speeds in the Turn Order incremented from each other by the speed of the action: thus multiple attacks with a Longbow (2 per round, speed 8), after an initiative roll of 5 on a 1d10, will happen at priority 13 & 21For attacks by a Fighter with two weapons, such as a Longsword (sp 5) in their left hand and a Short sword (sp 3) in their right hand, after an initiative roll of 5, the Short sword will get a Turn Order priority of 8 and the Longsword 10 – that is they are consecutive not sequential.<br>
+
***Indoors at night, or underground***, the ring of shooting stars has the following properties:<br>
See the individual menu explanations for more detail on each type of action.<br>
+
[*Faerie fire*](</nowiki><span style="color:red">!magic --mi-power @{selected|token_id}|RoSS-Faerie-Fire|Ring-of-Shooting-Stars|1</span><nowiki>) (twice per day) as spell<br>
 
+
[*Spark shower*](</nowiki><span style="color:red">!magic --mi-power @{selected|token_id}|RoSS-Spark-Shower|Ring-of-Shooting-Stars|1</span><nowiki>) (once per day) as power<br>
===Display a menu of possible actions for the selected creature===
+
Range, duration, and area of effect of functions are the minimum for the comparable spell unless otherwise stated. Casting time is 5}}</nowiki></p>
<pre>--monmenu [token-id]</pre>
+
<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>
Takes an optional token ID.  If token ID is not supplied, the selected token is used.<br>
+
<p>The data section now includes repeating data sets, one for each of the powers that the item has:</p>
This produces a slightly simpler form of the initiative action menu for creaturesOtherwise, all actions result in similar processing as per the normal action selection.
+
<pre>RingData=[w:Ring of Shooting Stars,sp:5,rc:charged,ns:6], [cl:PW,w:RoSS-Dancing-Lights,sp:5,pd:12], … </pre>
If the creature is very simple (only uses the simple attack lines on the Monster tab of the AD&D2e Character Sheet), then it might be sensible to use the --monster command instead: see below.<br>
+
<p>The first data set is very similar to the standard magic item data, with the addition of the <b>ns:</b> field, and is then followed by a number of repeated data sets specifying each of the powers:</p>
 
+
<table>
==Action specific Initiative menus==
+
<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>
===Display initiative actions to attack with the weapons ‘in-hand’===
+
<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>
<pre>--weapon [token-id]</pre>
+
<tr><th scope="row">w:</th><td>&lt;text&gt;</td><td>The name of the power/spell - must be exactly the same as the database name (case ignored)</td></tr>
Takes an optional token ID. If token ID is not supplied, the selected token is used.<br>
+
<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>
Displays a chat menu listing all the weapons that the Character / NPC / creature has ‘in-hand’ (i.e. that are currently in the Weapon and Ranged tables), with additional options as appropriate to the Character Sheet.  Rogue class characters will get a ‘Backstab’ option which will apply the Rogue backstab multiplier as appropriate. Fighter & Rogue classes will get an option to choose two weapons (if there are two one-handed weapons in-hand) which presents the option of selecting a Primary and a Secondary weapon to do initiative for. Weapons can be those typed into the Character Sheet weapons tables (see Section 7 below) or loaded using AttackMaster API (see AttackMaster documentation).<br>
+
<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>
If the Character / NPC / creature has Powers or Magic Items they can use, buttons also appear on the menu to go to the menus to select these instead of doing a weapon initiative – see the --power and --mibag commandsThere is also a button for ‘Other’ actions, such as Moving, Changing Weapon (which takes a round), doing nothing, or Player-specified actions – see the --other command.<br>
+
</table>
 
+
<p>By running the <b>--check-db</b> command (see the note above) these data sets are used to correctly set up the database with the powers wielded, so that when a Character receives this item, the Character also gains the powers to use through the item.</p>
===Display initiative actions for a simple creature to attack===
+
<p><b>Note:</b> if a Character picks up two Power-wielding items with exactly the same item name (i.e. two copies of the same item) the results are unpredictable.  This is best avoided.</p>
<pre>--monster [token-id]</pre>
+
<p>Feel free to just copy the specification for a Ring-of-Shooting-Stars in the Rings database and save it to a new Ability Macro with a different name, and then alter the power names, speeds, and uses per day, as well as the API Button <b>--mi-power</b> commands and the other text, to form new power-wielding magic itemsAlso, 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>
Takes an optional token IDIf token ID is not supplied, the selected token is used.<br>
+
<p>Here is an example of a spell-storing magic item:</p>
Displays a chat menu only listing innate monster attacks from the Monster tab of the AD&D2e Character Sheet.<br>
+
<h3>Ring-of-Spell-Storing-HHSLS</h3>
Creatures using the Innate Monster Attack fields on the AD&D2e Character Sheet Monster tab benefit from an extended syntax for entries in these fields: each field can take [<Attack name>,]<damage dice roll>[,<speed>] for example Claw,1d8,2 and Sword+1,2d4+1,5.  These will result in possible initiative actions for that creature for Claw and Sword+1.  If Attack Name is omitted, the dice roll is displayed as the action name insteadIf the speed is omitted, the Innate attack speed field value is used insteadThe speed will then be used to calculate the Turn Order priority.<br>
+
<p style="display: inline-block; background-color: lightgrey; border: 1px solid black; padding: 4px; color: dimgrey; font-weight: extra-light;">/w "@{selected|character_name}" <nowiki>&{template:'+fields.defaultTemplate+'}{{name=Ring of Spell Storing with Haste x2, Slow, Light & Sleep}}{{subtitle=Ring}}</nowiki><span style="color:green">Specs=[Ring of Spell Storing,Ring,1H,Conjuration-Summoning]</span><nowiki>{{Speed=[[5]] regardless of spell}}</nowiki><span style="color:blue">RingData=[w:Ring of Spell Storing HHSLS,sp:5,rc:uncharged,ns:5], [cl:MU,w:Haste,sp:5,lv:6], [cl:MU,w:Haste,sp:5,lv:6], [cl:MU,w:Slow,sp:5,lv:7], [cl:MU,w:Light,sp:5,lv:3], [cl:MU,w:Sleep,sp:5,lv:3]</span><nowiki> {{Size=Tiny}}{{Store spell=[Store Priest Spell](</nowiki><span style="color:red">!magic --mem-spell MI-PR|@{selected|token_id}</span><nowiki>)<br>
 
+
[Store Wizard Spell](</nowiki><span style="color:red">!magic --mem-spell MI-MU|@{selected|token_id}</span><nowiki>)}}{{Cast spell=[View](</nowiki><span style="color:red">!magic --view-spell mi-muspells|@{selected|token_id}</span><nowiki>) or [Cast](</nowiki><span style="color:red">!magic --cast-spell MI|@{selected|token_id}</span><nowiki>) spells}}{{desc=A ring of spell storing contains 1d4+1 spells which the wearer can employ as if he were a spellcaster of the level required to use the stored spells. The class of spells contained within the ring is determined in the same fashion as the spells on scrolls (see "Scrolls"). The level of each spell is determined by rolling 1d6 (for priests) or 1d8 (for wizards). The number rolled is the level of the spell, as follows:<br>
===Display initiative actions for a weapon-wielding creature to attack===
+
Priest: 1d6, if 6 is rolled, roll 1d4 instead.<br>
<pre>--complex [token-id]</pre>
+
Wizard: 1d8, if 8 is rolled, roll 1d6 instead.<br>
Takes an optional token ID.  If token ID is not supplied, the selected token is used.<br>
+
Which spell type of any given level is contained by the ring is also randomly determined.<br>
Displays a more complex monster attack menu, with both ‘Innate’ attacks from the Monster tab as well as weapon attacks from the Character tab weapons tables (the API does not use the recently introduced Weapon table for Monsters on the Monster tab so that the AttackMaster API only has to deal with one set of tables) – see 3.1 above for entering weapons and 3.2 for setting up monster attacks.  If the creature has powers or magic items, it will also offer action menu buttons for thoseThe selected attack or weapon speed will then be used to calculate the Turn Order priority.<br>
+
The ring empathically imparts to the wearer the names of its spells. Once spell class, level, and type are determined, the properties of the ring are fixed and unchangeable. Once a spell is cast from the ring, it can be restored only by a character of appropriate class and level of experience (i.e., a 12th-level wizard is needed to restore a 6th-level magical spell to the ring). Stored spells have a casting time of [[5]].}}</nowiki></p>
 
+
<p>This is a specific version of a Ring of Spell StoringAs the spells stored are specified in the macro, if you want there to be multiple rings of spell storing in your campaign they each need to be individually programmed (easy cut & paste job) & named differently.</p>
===Display initiative actions for Wizard spells===
+
<p>The only new field in these data sets is:</p>
<pre>--muspell [token-id]</pre>
+
<table>
Takes an optional token ID.  If token ID is not supplied, the selected token is used.<br>
+
<tr><th scope="row">lv:</th><td>&lt;#&gt;</td><td>The level of the caster who cast the spell into the ringThe spell will have effects as if cast at this level when cast from the ring.</td></tr>
Displays a menu of Wizard spells that the Character / NPC has memorised (see the MagicMaster API documentation for memorising spells, or see Section 7 below for entering spells manually).  Any spell that is still memorised can be selected for initiative, and the relevant casting time will be used to calculate the Turn Order priority.<br>
+
</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 retainedHowever, if the item is reloaded from the databases, or a duplicate of the item is placed by the DM and found by another character, that version of the item will have the spell caster levels from the database definitions.  Note that if a single Character picks up two versions of exactly the same spell storing item (i.e. with the same item name) the results are unpredicable...</p>
===Display initiative actions for Priest spells===
+
<p>Feel free to just copy the specification for a Ring-of-Spell-Storing in the Rings database and save it to a new Ability Macro with a different name, and then alter the spell names and casting levels as desired, to form new Rings of Spell Storing or other magic items. Also, the Ring does not have to have 5 spells - just remove or add one or more repeating data sets to reduce or increase the number of stored spells (though the official definition of a Ring of Spell Storing states a maximum of 5 spells).</p>
--prspell [token-id]
+
<p>The key command in the Spell-Storing item that supports it casting the defined spells is <b>!magic --cast-spell MI</b>, called in this case via an API buttonAny item specified with this command somewhere in the definition can store spells which can be specified, added or changed by the DM/Game Creator using the <b>[[Script:MagicMaster#Define_the_spells_a_spell-storing_Item_can_store|!magic --store-spell]]</b> command.</p>
Takes an optional token ID.  If token ID is not supplied, the selected token is used.<br>
+
<br>
Displays a menu of Priest spells that the Character / NPC has memorised (see the MagicMaster API documentation for memorising spells, or see Section 7 below for entering spells manually).  Any spell that is still memorised can be selected for initiative, and the relevant casting time will be used to calculate the Turn Order priority.<br>
+
<h2>Weapons (if using AttackMaster API)</h2>
 
+
<p>Weapons, magical or not, are special types of items in the Magic Items databasesIf coded properly (in the same way as those in the MI-DB-Weapons database), they can be used with the <b>[[Script:AttackMaster|AttackMaster API]]</b> to implement fully automatic weapon management, the ability to hold weapons "in-hand" or sheathed, to have automatic ammo and range management for ranged weapons, automatic entry of weapons into the melee and/or ranged weapons tables, ready to make attacks with magical plusses and other specifications all set up, and support for dancing weapons (ones that can attack without being held by the Character), creatures with more than 2 hands, and 1-handed weapons, 2-handed weapons, and even weapons that need more than 2 hands!</p>
===Display initiative actions for powers===
+
<p>See the <b>[[API:RPGMaster-WeaponsArmorDB|Weapon & Armour Database Help]]</b> handout and wiki for how Weapon definitions should be structured for use with the <b>AttackMaster API</b>, which are just a few additions to the standard definition of an item.</p>
<pre>--power [token-id]</pre>
+
<br>
Takes an optional token ID.  If token ID is not supplied, the selected token is used.<br>
+
<h2>Armour & Shields</h2>
Displays a menu of Powers that the Character / NPC has been granted (see the MagicMaster API documentation for managing powers, or see Section 7 below for entering powers manually).  Any power that has not been consumed can be selected for initiative, and the relevant casting time will be used to calculate the Turn Order priority.<br>
+
<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 impairmentsIt 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>[[API:RPGMaster-WeaponsArmorDB|Weapon & Armour Database Help]]</b> handout and wiki page for how Armour & Shield definitions should be structured for use with the <b>AttackMaster API</b>, which are just a few additions to the standard definition of an item.</p>
===Display initiative actions for Magic Items===
+
<p>Also, see the <b>RoundMaster API</b> documentation for how magical effects can be placed on and affect tokens and characters.</p>
<pre>--mibag [token-id]</pre>
+
<br>
Takes an optional token ID.  If token ID is not supplied, the selected token is used.<br>
+
<h2>Specs & Data field values</h2>
Displays a menu of Magic Items and non-magical equipment that the Character / NPC / creature has on their person - that is in the Items table (by default, the Potions table on the AD&D2e character sheet): see Section 7.5 below and the MagicMaster API documentation for information on Items. Selecting an item for initiative uses the speed of action of that item to calculate the Turn Order priority.<br>
+
<p>Below are lists of the current possible values for the item database Ability macro sections.</p>
 
+
<h3>Specs sections</h3>
===Display initiative actions for Thieves===
+
<pre>Specs=[Type, Item-Class, Handedness, Group-Type]</pre>
<pre>--thief [token-id]</pre>
+
<p>There are no default settings for any of the Specs data fields.  All must be explicitly specified.</p>
Takes an optional token ID.  If token ID is not supplied, the selected token is used.<br>
+
<h4>Spell Types</h4>
Displays a menu of Thievish actions (with current percentage proficiencies of each).  Selecting one for initiative uses the speed of action of that item to calculate the Turn Order priority.<br>
+
<p>There is an infinite list of spell types: generally the type is the spell name.</p>
 
+
<h4>Spell Item-Classes</h4>
===Display other actions===
+
<table>
<pre>--other [token-id]</pre>
+
<tr><th scope="row">MUSpellL\<1-9\></th><td>A Wizard spell with the Level specified as a number from 1 to 9</td></tr>
Takes an optional token IDIf token ID is not supplied, the selected token is used.<br>
+
<tr><th scope="row">PRSpellL\<1-9\></th><td>A Priest spell with the Level specified as a number from 1 to 9</td></tr>
Displays a menu of other (non-attacking) actions that the Character / NPC / creature can take, namely: Moving (speed 0 as it is an innate ability); Changing Weapon (also speed 0 but takes all round); Doing Nothing (obviously speed 0); and one that allows the Player to enter a description and specify a speed for that action (presumably with the agreement of the DM).<br>
+
<tr><th scope="row">Power</th><td>A Power</td></tr>
 
+
</table>
==Maintain the Turn Order and Rounds==
+
<h4>Spell Handedness</h4>
===Display the DM’s round maintenance menu===
+
<p><b>0H</b> A spell/power that does not take a hand (there is no Somatic component)<br>
<pre>--maint</pre>
+
<b>1H</b> A spell/power that requires only 1 hand to cast (most spells are like this)<br>
DM Only command.  Does not take any parameters.<br>
+
<b>2H</b> A spell/power that requires 2 hands to cast (perhaps a scroll must be held)<br>
Displays a chat menu of action API Buttons to control the Turn Order Tracker window using commands sent to the RoundMaster API.  The key one is Start/Pause, which initialises RoundMaster and starts it managing the Turn Order, or pauses it so that stepping through the Turn Order does not trigger any RoundMaster actions (such as counting down token status timers or initiating Effects).  The full list of functions is:<br>
+
<b>3H</b> A spell/power that takes 3 hands... perhaps more than 1 caster together?<br>
{| class="wikitable"
+
<b>4H</b> Etc  No currently programmed spells use more than 2 hands<br>
|+
+
<b>...</b> ...</p>
|-
+
<h4>Spell/Power Schools</h4>
! Maintenance Menu Button !! Command Implemented !! Description
+
<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>
! scope="row"| Start / Pause
+
<p>Note that the '/' in School names in the AD&D2e PHB have been replaced by hyphens. It is also allowed to use just one half of any hyphenated school name where appropriate. If a spell or power is of more than one school, separate each with a vertical bar character '|'</p>
|| !rounds --start || Starts / Pauses RoundMaster functioning
+
<br>
|-
+
<h4>Magic Item Types</h4>
! scope="row"| Start Melee
+
<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>
|| !rounds --clearonround on<br>--clear || Causes the Turn Order to automatically clear at the end of each round (once all actions have completed) ready for Players to select actions for their Characters
+
<h4>Magic Item Classes</h4>
|-
+
<table>
! scope="row| Stop Melee
+
<tr><th scope="row">Weapon</th><td>Weapons that are not Melee or Ranged weapons or any other class</td></tr>
|| !rounds --clearonround off || Stops the Turn Order from automatically clearing at the end of each round, so that the Turn Order is preserved.  Can be useful when just wanting to cycle around a list of Characters selected in the !init –init menu command and running ‘Standard’ initiative.
+
<tr><th scope="row">Melee</th><td>Melee weapons that are used in hand-to-hand combat</td></tr>
|-
+
<tr><th scope="row">Ranged</th><td>Ranged weapons that are either thrown or fire ammunition</td></tr>
! scope="row"| Re-start
+
<tr><th scope="row">Ammo</th><td>All types of ammunition that is used by Ranged weapons</td></tr>
|| !rounds --sort || Re-sorts the current Turn Order, effectively re-starting the round.  Useful if the DM accidentally starts the next round by moving the Turn Order on before all Players have completed their initiative actions – allow new actions to be selected and then use Re-start
+
<tr><th scope="row">Armour</th><td>Any type of armour that does not need to be held to work</td></tr>
|-
+
<tr><th scope="row">Shield</th><td>A barrier that is held in hand(s) and defends against one or more attacks from the front</td></tr>
! scope="row"| Set Round Number
+
<tr><th scope="row">Potion</th><td>Any type of potion, oil, pill or similar that is consumed or rubbed on</td></tr>
|| !rounds --reset # || Sets the current Round number to #. If # is larger than the current round, all token status counters will advance by the number of rounds difference, ending if they reach 0 with the consequential Effects triggered
+
<tr><th scope="row">Scroll</th><td>Scrolls and spell books, that contain one or multiple spells</td></tr>
|-
+
<tr><th scope="row">Wand</th><td>Wands that cast spells or spell-like effects when wielded in the hand</td></tr>
! scope="row"| Clear Turn Order
+
<tr><th scope="row">Staff</th><td>Quarterstaffs and similar large bludgeoning items that can also have spell-like abilities</td></tr>
|| !rounds --clear || Clears the Turn Order of all entries (except the round number)
+
<tr><th scope="row">Rod</th><td>Walking-stick sized rods that can do spell-like effects, especially when used to attack</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>
! scope="row"| Remove Tokens from Tracker
+
<tr><th scope="row">Light</th><td>All types of lantern, torch, and other illumination</td></tr>
|| !rounds --removefromtracker || Removes all the selected tokens from the Turn Order and the Tracker window.  Multiple tokens can be selected and removed all at the same time.
+
<tr><th scope="row">Miscellaneous</th><td>Anything that does not fit in one of the other categories</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>
! scope="row"| Edit Selected Tokens
+
</table>
|| !rounds --edit || Displays the status markers on all the selected tokens, and offers options to edit or delete them.  The “spanner” icon edits the status, and the “bin” icon deletes it.
+
<h4>Armour Handedness</h4>
|-
+
<p><b>0H</b> Items that do not require to be held to work (e.g. a Ring, Buckler or a Helm)<br>
! scope="row"| Move Token Status
+
<b>1H</b> An item that must be held in one hand to work, such as a Wand<br>
|| !rounds --moveStatus || For each of the selected tokens in turn, searches for tokens in the whole campaign with the same name and representing the same character sheet, and moves all existing statuses and markers from all the found tokens to the selected token (removing any duplicates)This supports Players moving from one Roll20 map to another and, indeed, roundMaster detects page changes and automatically runs this command for all tokens on the new page controlled by the Players who have moved to the new page.
+
<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>
! scope="row"| Clean Selected Tokens
+
<b>...</b> etc.</p>
|| !rounds --clean || Drops all status markers from the selected token, whether they have associated effects or time left, or are just manually applied markers.  Useful when there might have been corruption, or everyone is just confused!  The token statuses still exist, and associated markers will be correctly rebuilt at the start of the next round or the next trigger event (but not manually added ones).
+
<h4>Item Schools</h4>
|-
+
<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 effectsSee section 7.1(d) for the list.</p>
! scope="row"| Enable Long Rest for PCs
+
<h4>Data Sections</h4>
|| !init –end-of-day <cost> || Run the normal initMaster end-of-day command
+
<p>Definitions for Data Section field types for Weapons & Armour can be found in the [[API:RPGMaster-WeaponsArmorDB#Specs_.26_Data_field_values|Weapons & Armour Database help]] handout & wiki pageBelow are the definitions for Spell, Power & other Magical Item types.</p>
|-
+
<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>
! scope="row"| Enable Long Rest for selected tokens
+
<table>
|| !init –enable-rest || Enable a long rest only for the characters / NPCs / creatures represented by the selected tokens.  See the MagicMaster API documentation for information on Long Rests
+
                <tr>
|-
+
<th scope="col" rowspan="2">Field</th>
! scope="row"| Set Date
+
<th scope="col" rowspan="2">Format</th>
|| || Currently not implemented – future expansion
+
<th scope="col" rowspan="2">Default Value</th>
|-
+
<th scope="col" rowspan="2">Description</th>
! scope="row"| Set Campaign
+
<th scope="col" colspan="8">Can be used in</th>
|| || Currently not implemented – future expansion
+
</tr>
|-
+
<tr>
! scope="row"| Update Selected Tokens
+
<th scope="col">Spell<br>Data</th>
|| !cmd --abilities || Use the CommandMaster API function to setup and maintain Character ability action buttons, weapon proficiencies, spell books & granted powers, saving throws, token “bar & circle” assignment etc.  See CommandMaster API documentation on the –abilities command.
+
<th scope="col">Potion<br>Data</th>
|-
+
<th scope="col">Scroll<br>Data</th>
! scope="row"| Emergency Stop!
+
<th scope="col">Wand<br>Data</th>
|| !rounds --stop || After confirmation, performs a Full Stop and re-start of the RoundMaster API, dropping all internal tables of statuses & effects, token markers, timers etc.  Use with care!
+
<th scope="col">Staff<br>Data</th>
|}
+
<th scope="col">Rod<br>Data</th>
===Display those characters that have not yet had initiative actions selected===
+
<th scope="col">Ring<br>Data</th>
<pre>--check-tracker</pre>
+
<th scope="col">Misc<br>Data</th>
DM Only command.  Does not take any parameters.<br>
+
</tr>
Uses the Player Character name list created & maintained in the –init menu or with the –list-pcs command, and checks that all of the Character’s named have completed initiative selection to the point where their token name is in the Turn Order at least once, and appears in the Tracker window.  Names those that have not in a message to the DM, or states that initiative is complete.<br>
+
<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 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>
===Change the list of characters in the Party===
+
<tr><th scope="row">+:</th><td>[ + / - ] #</td><td>0</td><td>Magical adjustment</td><td> </td><td> </td><td> </td><td>X</td><td>X</td><td>X</td><td>X</td></tr>
<pre>--list-pcs < ALL / MAP / REPLACE / ADD ></pre>
+
<tr><th scope="row">n:</th><td># [ / # ]</td><td>1</td><td>Attacks per round</td><td> </td><td> </td><td> </td><td>X</td><td>X</td><td>X</td><td> </td><td>X</td></tr>
DM Only command.  Takes a specifier for the tokens to have in the Player Character list which must be one of those listed.<br>
+
<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>
Updates the internally held list of Characters that are controlled by Players (and others that the DM can add at will).  This list is displayed on the --init menu, and is used by --check-tracker and --end-of-day commands.  The list persists between sessions of game-playThe following parameters have the following effects:<br>
+
<tr><th scope="row">sp:</th><td>[-]# or Dice Roll spec</td><td>0</td><td>Speed in segments (1/10 round)</td><td>X</td><td>X</td><td>X</td><td>X</td><td>X</td><td>X</td><td>X</td><td>X</td></tr>
{| class="wikitable"
+
<tr><th scope="row">wt:</th><td>#</td><td>1</td><td>Weight of item in lbs</td><td> </td><td>X</td><td> </td><td>X</td><td>X</td><td>X</td><td> </td><td>X</td></tr>
|+
+
<tr><th scope="row">ns:</th><td>#</td><td>0</td><td>Number of stored spells & powers defined for item</td><td> </td><td> </td><td>X</td><td>X</td><td>X</td><td>X</td><td>X</td><td>X</td></tr>
|-
+
<tr><th scope="row">w:</th><td>< text ></td><td>'-'</td><td>Name of stored spell or power (Not case sensitive)</td><td>X</td><td> </td><td>X</td><td>X</td><td>X</td><td>X</td><td>X</td><td>X</td></tr>
! scope="row"| all:
+
<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>
|| looks across all tokens in the campaign and creates a new list composed of those representing Character Sheets controlled by a Player (standard Roll20 Character Sheet functionality – refer to the Help Centre for information on setting Players to control Character Sheets and their tokens).
+
<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">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>
! scope="row"| map:
+
<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>
|| creates a new list that only has Characters represented by tokens on the current Player map that are controlled by Players.  (See Roll20 Help Centre on how to select the current Player map).
+
</table>
|-
+
! scope="row"| replace:
+
|| creates a new list including all the currently selected token(s) (whomever controls them), and no others.
+
|-
+
! scope="row"| add:
+
|| adds the currently selected token(s) (whomever controls them) to the existing list leaving all the others unchanged.
+
|}
+
 
+
==End of Day processing==
+
<pre>--end-of-day [ASK/ASKTOREST/OVERNIGHT/REST/SET/FOES]|[=][cost]</pre>
+
DM Only command.  Takes an optional type of rest (which, if provided, must be one of those shown – defaults to ASK) and an optional cost parameter, optionally preceded by an ‘=’ character.  If cost is not provided, it defaults to that previously set with SET and/or ‘=’.<br>
+
This command performs the ‘End-of-Day’ processing for the campaign.  This consists of enabling Long Rests for all Characters / NPCs / creatures to regain their spells and powers, and for recharging Magic Items to regain their charges (see MagicMaster API documentation for information on Long Rests).  It also removes spent ammunition from quivers that has not been recovered, as it is assumed to be lost, broken or taken by other creatures during the period of the night (see AttackMaster API documentation about recovery of ammunition and its loss over a Long Rest).<br>
+
Each day can cost or earn the members of the Party money, perhaps depending on where they stay overnight, whether they eat just camp rations or lavish meals, use an Inn and drink too much, or earn money doing a job.  The optional cost parameter can be set to a positive cost to the party which will be deducted from every member, or a negative quantity which will be earned (a negative cost).<br>
+
{| class="wikitable"
+
|+
+
|-
+
! scope="row"| ASK:
+
|| If no rest type is supplied, or ASK is used, the DM is asked to confirm if they wish the cost to be deducted from/earned by all the Characters listed.  If No is selected, nothing is deducted or earned.  The system then sets flags to allow Players to perform a Rest command on their characters (see MagicMaster API).
+
|-
+
! scope="row"| ASKTOREST:
+
|| Asks the DM to confirm the cost/earnings in the same way as ASK, but then automatically performs the MagicMaster API –rest command for each character in the party, and the Players do not need to do so.
+
|-
+
! scope="row"| OVERNIGHT:
+
|| Applies the cost to the Party members and enables them to rest (they have to do the rest themselves). If cost (or the previously set default cost) is not a number (e.g. a Roll Query), asks if a charge is to be made.
+
|-
+
! scope="row"| REST:
+
|| Does the same as OVERNIGHT, but automatically runs the MagicMaster API –rest command for all characters in the party, and the Players do not need to do so.
+
|-
+
! scope="row"| FOES:
+
|| Does the same as OVERNIGHT, but for all NPCs and Monsters, allowing them to rest.
+
|-
+
! scope="row"| SET:
+
|| If the rest type is SET and/or there is an ‘=’ before the cost, will not run the ‘End-of-Day’, but instead will set the standard cost for each night if no cost parameter is given when other commands are used. If the ‘=’ is followed by a Roll Query (see Roll20 Help Centre for information on Roll Queries), the Roll Query will be run each time the –end-of-day command is run without a cost parameter, allowing (for instance) the DM to select from a list of possible daily costs or earningsHowever, remember to replace the ‘?’ at the start of the Roll Query with &amp;#63; so that the Roll Query does not run when it is passed in to be set. Other characters can be substituted as follows:
+
|}
+
{| class="wikitable"
+
|+
+
|-
+
! Character !! ? !! [ !! ] !! < !! > !! @ !! - !! &#124; !! : !! & !! { !! }
+
|-
+
! scope="row"| Substitute
+
|| ^ || << || >> ||  ||  || ` || ~ || ¦ ||  || &amp;amp; || &amp;#123; || &amp;#125;
+
|-
+
! scope="row"| Alternative (no ; )
+
|| \ques || \lbrak || \rbrak || \lt || \gt || \at || \dash || \vbar || \clon || \amp || \lbrc || \rbrc
+
|}
+
 
+
==Other Commands==
+
===Display help on these commands===
+
<pre>--help</pre>
+
This command does not take any argumentsIt displays a very short version of this document, showing the mandatory and optional arguments, and a brief description of each command.<br>
+
 
+
===Handshake with other APIs===
+
<pre>!rounds –hsq from|[command]
+
!rounds –handshake from|[command]</pre>
+
Either form performs a handshake with another API, whose call (without the ‘!’) is specified as from in the command parameters (the response is always an –hsr command)The API receiving the command calls the from API command responding with its own command to confirm that it is loaded and running: e.g. <br>
+
'''Received:''' !init --hsq magic<br>
+
'''Response:''' !magic --hsr init<br>
+
Which means the MagicMaster API has requested a handshake with InitiativeMaster to see if it is loaded, and InitiativeMaster has responded, proving it is running and taking commands.<br>
+
Optionally, if the command string parameter is added, a command query can be made to see if the command is supported by InitiativeMaste. ''command'' is the InitiativeMaster command (the --’ text without the ‘--‘)This will respond with a true/false response: e.g.<br>
+
'''Received:''' !init --handshake attk|monster<br>
+
'''Response:''' !attk --hsr init|monster|true<br>
+
Which means AttackMaster has queried if InitiativeMaster has a command called --monster, and InitiativeMaster has responded in the affirmative.<br>
+
 
+
===Switch on or off Debug mode===
+
<pre>--debug (ON/OFF)</pre>
+
Takes one mandatory argument which should be ON or OFF.<br>
+
The command turns on a verbose diagnostic mode for the API which will trace what commands are being processed, including internal commands, what attributes are being set and changed, and more detail about any errors that are occurringThe command can be used by the DM or any Player – so the DM or a technical advisor can play as a Player and see the debugging messages.<br>
+
 
+
=Configuring the Token and Character Sheet for use with the API=
+
==Token configuration==
+
The API can work with any Token configuration but requires tokens that are going to participate in initiative actions for ‘Group’ and ‘Individual’ initiative to represent a Character Sheet, so that actions relevant to the token can be selected.<br>
+
A single Character Sheet can have multiple Tokens representing it, and each of these are able to do individual initiative using the actions made possible by the data on the Character Sheet jointly represented.  However, if such multi-token Characters / NPCs / creatures are likely to encounter spells that will affect the Character Sheet (such as Haste and Slow) they must be split with each Token representing a separate Character Sheet, or else the one spell will affect all tokens associated with the Character Sheet, whether they were targeted or not!  In fact, it is recommended that tokens and character sheets are 1-to-1 to keep things simple.<br>
+
The recommended Token Bar assignments for all APIs in the Master Series are:<br>
+
{| class="wikitable"
+
|+
+
|-
+
! scope="row"| Bar1 (Green Circle):
+
|| Armour Class (AC field) – only current value
+
|-
+
! scope="row"| Bar2 (Blue Circle):
+
|| Base Thac0 (thac0-base field) before adjustments – only current value
+
|-
+
! scope="row"| Bar3 (Red Circle):
+
|| Hit Points (HP field) – current & max
+
|}
+
It is recommended to use these assignments, and they are the bar assignments set by the CommandMaster API if its facilities are used to set up the tokens.  All tokens must be set the same way, whatever way you eventually choose.<br>
+
These assignments can be changed in the APIs that use them, by changing the ''fields'' object near the top of the API script, but InitiativeMaster does not use these fields, so they are not mapped.<br>
+
 
+
==Use with various game system character sheets==
+
The API issued is initially set up to work with the AD&D 2E character sheet (as this is what the author mostly plays).  However, it can be set up for any character sheet.  In each API script, right at the top, is an object definition called ''fields'': see the next section for details.  This can be altered to get the API to work with other character sheets.<br>
+
The Initiative API, as with all the other RPGMaster series APIs use Roll20 Roll Templates extensivelyThis is sometimes the only way to get Roll20 to roll 3D animated dice (using a Character Sheet ability macro triggered by a Player), as 3D animated dice do not work when commanded by an API via a sendchat() call, due to a reported bug. Of course, there is a default Roll Template provided by the Roll20 system, but it is a bit clunky and Roll Templates provided by Character Sheet coders are often better. InitiativeMaster and other RPGMaster APIs use these Character Sheet-defined Roll Templates, by default from the AD&D 2e Character Sheet.  As with every other field, the Roll Templates used can be altered in the ''fields'' object.<br>
+
The coding of the API is designed to use the AD&D 2E system of initiative systems and calculations. If you use another system, it might be that one of the "Standard", "Group", or "Individual" initiative rule systems implemented in the system will work for you.<br>
+
 
+
==Matching the API to a type of Character Sheet==
+
The API has an object definition called ''fields'', which contains items of the form<br>
+
''Internal_api_name: [sheet_field_name, field_attribute, optional_default_value, optional_set_with_worker_flag]''<br>
+
A typical example might be:<br>
+
<pre> Fighter_level:['level-class1','current'],
+
Or
+
MUSpellNo_memable:['spell-level-castable','current','',true],</pre>
+
Table names are slightly different: always have an internal_api_name ending in ‘_table’ and their definition specifies the repeating table name and the index of the starting row of the table or -1 for a static field as the 1st row, with the 2nd row starting at repeating row number 0.<br>
+
''Internal_api_table: [sheet_repeating_table_name,starting_index]''<br>
+
An example is:<br>
+
<pre>MW_table:['repeating_weapons',0],</pre>
+
<u>'''The internal_api_name must not be altered!'''</u> Doing so will cause the system not to work. However, the sheet_repeating_table_name and starting_index can be altered to match any character sheet.<br>
+
Each character sheet must have repeating tables to hold weapons, ammo and magic items. By default, melee weapons ‘in hand’ are held in sections of the repeating_weapons table, melee weapon damage in the repeating_weapons-damage table, ranged weapons in the repeating_weapons2 table, ammo in the repeating_ammo table, and magic items are held in the repeating_potions table.  Other repeating tables are also used, some of which are intended to be hidden and not visible in the Character Sheet.  The table management system provided by the API creates, expands and writes to repeating attributes automatically, and the DM & Players do not need to worry about altering or updating any of these tables on the Character Sheet.<br>
+
 
+
==Character Attributes, Races, Classes and Levels==
+
Character Attributes of Strength, Dexterity, Constitution, Intelligence, Wisdom and Charisma are not directly important to the Initiative Master API, but the resulting bonuses and penalties are. All Attributes and resulting modifiers should be entered into the Character Sheet in the appropriate places (that is in the Character Sheet fields identified in the ''fields'' API object as noted in the section above).<br>
+
The Character’s race is also important for calculating saves and ability to use certain items.  The race should be set in the appropriate Character Sheet field. Currently, the races ‘dwarf’, ‘elf’, ‘gnome’, ‘halfelf’, ‘halfling’, ‘half-orc’, and ‘human’ are implemented (not case sensitive, and spaces, hyphens and underscores are ignored).  If not specified, human is assumed.  The race impacts saves, some magic items and armour, and bonuses on some attacks.<br>
+
The system supports single-class and multi-class characters.  Classes must be entered in the appropriate fields on the Character Sheet.  Classes and levels affect spell casting ability, weapon multiple attack numbers per round, ability to do two-weapon attacks with or without penalty, and the ability to backstab and the related modifiers among other things.  Class and level also determine valid armour, shields, some magic items and saves.<br>
+
'''Note:''' on the Advanced D&D 2e Character Sheet, Fighter classes '''must''' be in the ''first'' class column, Wizard classes in the ''second'' column, Priest classes in the ''third'', Rogues in the ''fourth'', and Psions (or any others) in the ''fifth''.  It is important that these locations are adhered to.<br>
+
'''Note:''' classes of Fighter and Rogue (such as Paladins, Rangers and Bards) that can use clerical &/or wizard spells will automatically be allowed to cast spells once they reach the appropriate level by AD&D 2e rules, but not before.<br>
+
The following Classes are currently supported, and the class name must be entered into the class field.  If missing, the top row is assumed in each case:<br>
+
{| class="wikitable"
+
|+
+
|-
+
! Fighter classes !! Wizard Classes !! Priest Classes !! Rogue Classes
+
|-
+
| Warrior || Wizard || Priest || Rogue
+
|-
+
| Fighter || Mage || Cleric || Thief
+
|-
+
| Ranger || Abjurer || Druid || Bard
+
|-
+
| Paladin || Conjurer || Healer || Assassin
+
|-
+
| Beastmaster || Diviner || Priest of Life ||
+
|-
+
| Barbarian || Enchanter || Priest of War ||
+
|-
+
| Defender (Dwarven) || Illusionist || Priest of Light ||
+
|-
+
| || Invoker || Priest of Knowledge ||
+
|-
+
| || Necromancer || Shaman ||
+
|-
+
| || Transmuter || ||
+
|}
+
The level for each class must be entered in the corresponding field.  Multiple classes and levels can be entered, and will be dealt with accordingly.  Generally, the most beneficial outcome for any combination will be used.  If not entered, 0 (zero) is assumed (i.e. a commoner)<br>
+
 
+
==Spells and Powers==
+
The best (and easiest) way to give a Character or NPC spells and powers is to use the MagicMaster API.  However, for the purposes of just doing initiative and selecting which spell to cast in the round, the spells and powers can be entered manually onto the character sheet.  Spells are held in the relevant section of the Spells table, which by default is set to the character sheet spells table, repeating_spells.  As with other fields, this can be changed in the ''fields'' object.  Note that on the Advanced D&D 2e character sheet Wizard spells, Priest spells & Powers are all stored in various parts of this one very large table.<br>
+
If you are just using the character sheet fields to type into, add spells (or powers) to the relevant “Spells Memorised” section (using the [+Add] buttons to add more as required) a complete row at a time (that is add columns before starting the next row).  Enter the spell names into the “Spell Name” field, and “1” into each of the “current” & “maximum” “Cast Today” fields – the API suite counts down to zero on using a spell, so in order for a spell to appear as available (not greyed out) on the initiative menus, the “current” number left must be > 0. This makes spells consistent with other tables in the system (e.g. potion dose quantities also count down as they are consumed, etc).<br>
+
Then, you need to set the “Spell Slots” values on each level of spell to be correct for the level of casterJust enter numbers into each of the “Level”, “Misc.” and “Wisdom” (for Priests) fields, and/or tick “Specialist” for the Wizard levels as relevant. This will determine the maximum number of spells memorised each day, that will appear in the spells Initiative MenuDo the same for Powers using the “Powers Available” field. As with other fields on the character sheet, each of these fields can be re-mapped by altering the ''fields'' object in the APIs.<br>
+
 
+
==Magic Items and Equipment==
+
All magic items and standard equipment, including weapons, armour, lanterns etc, are held in the Items table, which by default is set to the potions table, repeating_potions, on the Character Sheet.  As with other fields, this can be changed in the ''fields'' object.  The best way to put items into this table is by using the MagicMaster API.  However, it generally is possible to enter item names and quantities directly into the table and use them within the system.  Only items that also exist in the supplied databases will actually work fully with the API (i.e. be recognised by the API as weapons, armour, ammo, etc).  Initial weapon, ammunition and armour databases are provided with the AttackMaster API, and in addition to these Initial magic item, spell and power databases are provided with the MagicMaster API.  Other items can be in the table and used for undertaking initiative actions but will not otherwise be effective.  New databases and database items can be added using the specifications and instructions contained in the AttackMaster and MagicMaster API documentation.<br>
+
==Weapons and Ammo==
+
For the InitiativeMaster API to support weapon attack actions melee weapons, damage, ranged weapons and ammo must be entered directly into the melee weapon, damage, ranged weapon and ammo tables on the Character Sheet.  This is best done using the AttackMaster API, which will ensure all the right values are entered in the right fields, including taking into account the impact of weapon proficiencies, specialisation, mastery, character races and class/level.  However, manual entry will generally work to the extent to allow weapon attack initiative actions to be selected.  Weapon name, speed and number of attacks are the most important fields for initiative.<br>
+
 
<br>
 
<br>
=Character Sheet data fields =
+
<h3>Character Sheet data fields</h3>
As stated in the previous section, the Character Sheet field mapping to the API script can be altered using the definition of the ''fields'' object.  You can find the complete mapping for all APIs in the RPGMaster series, with an explanation of each, in a separate document.
+
<p>The Character Sheet field mapping to the API script can be altered using the definition of the fields object, the definition for which can be found at the top of each API.  You can find the complete mapping for all APIs in the RPGMaster series, with an explanation of each, in a separate document - as the Author for a copy.</p>
 
+
= Changelog =
+
{{changelog version|1.037|2021-12-24|* First version for public release}}
+

Latest revision as of 11:03, 5 April 2022

Contents

Spell, Power & Magic Item Databases

General Database information

The RPGMaster APIs use a number of Character Sheets as databases to hold Ability Macros defining character classes, attack templates, spells, powers and magic items and their effects. The API is distributed with many class, attack, spell, power & magic item definitions, and checks for, creates and updates these Character Sheet databases on start-up. DMs can add their own character classes, attack templates, spells, items, weapons, ammo and armour to additional databases, but the databases provided are totally rewritten when new updates are released so the DM must add their own database sheets. If the provided databases are accidentally deleted, they will be automatically recreated the next time the Campaign is opened. Additional databases should be named as follows:

Wizard Spells:additional databases: MU-Spells-DB-[added name] where [added name] can be replaced with anything you want.
Priest Spells:additional databases: PR-Spells-DB-[added name] where [added name] can be replaced with anything you want.
Powers:additional databases: Powers-DB-[added name] where [added name] can be replaced with anything you want.
Magic Items:additional databases: MI-DB-[added name] where [added name] can be replaced with anything you want.
Character Classes:additional databases: Class-DB-[added name] where [added name] can be replaced with anything you want.
Attack Templates:additional databases: Attacks-DB-[added name] where [added name] can be replaced with anything you want.

However: the system will ignore any database with a name that includes a version number of the form "v#.#" where # can be any number or group of numbers e.g. MI-DB v2.13 will be ignored. This is so that the DM can version control their databases, with only the current one (without a version number) being live.

There can be as many additional databases as you want. Other Master series APIs come with additional databases, some of which overlap - this does not cause a problem as version control and merging unique macros is managed by the APIs.

Important Note: all Character Sheet databases must have their 'ControlledBy' value (found under the [Edit] button at the top right of each sheet) set to 'All Players'. This must be for all databases, both those provided (set by the API) and any user-defined ones. Otherwise, Players will not be able to run the macros contained in them.

Each database has a similar structure, with:

  • Ability Macros named as the class, attack type, spell, power or magic item specified, and used to describe and provide effects for classes, attacks, spells, powers and magic items using the commands in the RPGMaster APIs;
  • Custom Attributes with the attribute name "ct-ability-macro-name", one per Ability Macro, which defines the casting time and casting cost for spells & powers, and speed and MI type for magic items (not currently used for Class or Attack definitions, but they still have to exist);
  • An entry in a list on the character sheet in the spell book of the relevant Character Sheet tab (Spell Level of the spell defined, Powers tab, or various spell books for different Classes & Magic Items).

However, as with all other Databases in the RPGMaster Suite of APIs, if the Ability Macros are correctly set up using the formats detailed in the Help Documentation, the AttackMaster API command !attk --check-db database-name will check the database and set up all other aspects for you, including the correct Custom Attributes and List entries.

Ability Macros can be whatever the DM wants and can be as simple or as complex as desired. Roll Templates are very useful when defining class, spell, power and magic item ability macros, and are an essential part of Attack Templates. When a Player or an NPC or Monster makes an attack, the AttackMaster API runs the relevant Ability Macro from the databases as if it had been run by the Player from the chat window. All Roll20 functions for macros are available.

Replacing Classes, Attacks, Spells & Items

If you want to replace any Ability Macro provided in any of the databases, you can do so simply by creating an Ability Macro in one of your own databases (a database with the same root name) with the Ability Macro you create having exactly the same name as the provided item to be replaced. The API gives preference to Ability Macros in user-defined databases, so yours will be selected in preference to the one provided with the APIs.


Spells and Powers Databases

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

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

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

As previously stated in the General Database Information section, each spell or power definition has 3 parts in the database: an Ability Macro with a name that is unique and matches the spell or power, an Attribute with the name of the Ability Macro preceded by "ct-", and a listing in the database character sheet of the ability macro name separated by '|' along with others of the same level in the spell book of the level of the spell or power. The quickest way to understand these entries is to examine existing entries. Do go to the root databases and take a look (but be careful not to alter anything unless you know what you're doing!)

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

Ability macros can be added to a database just by using the [+Add] button at the top of the Abilities column in the Attributes and Abilities tab of the Database Character Sheet, and then using the edit "pencil" icon on the new entry to open it for editing. Ability macros are standard Roll20 functionality and not dependent on the API. Refer to the Roll20 Help Centre for more information.

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

Sleep

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

The ability specification for this Sleep spell uses a Roll20 Roll Template, in this case defined by the Advanced D&D 2e Character Sheet by Peter B (see the documentation for the Character Sheet on Roll20 for specifications of this Roll Template), but any Roll Template you desire can be used. The entries in the Roll Template itself can be anything you desire, giving as much or as little information as you want. However, the important elements for the MagicMaster API are those highlighted. In red, two API buttons grant the player access to run RoundMaster API commands to show the Area of Effect of the spell, and then to mark affected tokens with a "Sleepy" status. Each of the elements important to the database are inserted between the elements of the Roll Template, meaning they will not be seen by the player when the macro is run. Generally spaces, hyphens and underscores in the data elements are ignored, and case is not significant. Each element is described below:

Specs = [Type, Class, Handedness, Spell School]

The Specs section describes what spell type and school this spell belongs to. These fields must be in this order. This format is identical for all database items, whether in these databases or others used by the Master series of APIs. Where there are multiple answers for a field, separate each by '|'. Note:Only A-Z, a-z, 0-9, hyphen/minus(-), plus(+), equals(=) point(.) and vertical bar(|) are allowed. Replace any forward slash with hyphen.

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

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

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

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

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

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

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

Turn Undead

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

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


Magic Item Databases

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

Magic Items: MI-DB-[added name]

And can have anything put at the end, though those with version numbers of the form v#.# as part of the name will be ignored.

As previously stated and as for other magic, each magic item definition has 3 parts in the database (see Section 1): an Ability Macro with a name that is unique and identifies the magic item, an Attribute with the name of the Ability Macro preceded by "ct-", and a listing in the database character sheet of the ability macro name separated by '|' along with others of the same magic item type, which is one of: Potion, Scroll, Rod/Stave/Wand, Weapon & Ammo, Armour, Ring, Miscellaneous, and also DM Only magic items. The quickest way to understand these entries is to examine existing entries. Do go to the root database and take a look (but be careful not to alter anything unless you know what you're doing!)

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

Ability macros can be added to a database just by using the [+Add] button at the top of the Abilities column in the Attributes and Abilities tab of the Database Character Sheet, and then using the edit "pencil" icon on the new entry to open it for editing. Ability macros are standard Roll20 functionality and not dependent on the API. Refer to the Roll20 Help Centre for more information.

The Ability Macro may look something like this:

Oil-of-Etherealness

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

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

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

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

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

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

Bead-of-Force

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

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


Magic Items with Powers or Spell-Storing

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

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

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

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

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

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

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

Here is an example of a power wielding magic item:

Ring-of-Shooting-Stars

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

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

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

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

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

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

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

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

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

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

Ring-of-Spell-Storing-HHSLS

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

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

The only new field in these data sets is:

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

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

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

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


Weapons (if using AttackMaster API)

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

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


Armour & Shields

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

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

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


Specs & Data field values

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

Specs sections

Specs=[Type, Item-Class, Handedness, Group-Type]

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

Spell Types

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

Spell Item-Classes

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

Spell Handedness

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

Spell/Power Schools

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

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

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


Magic Item Types

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

Magic Item Classes

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

Armour Handedness

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

Item Schools

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

Data Sections

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

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

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


Character Sheet data fields

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