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

Personal tools

Difference between revisions of "Script:MagicMaster"

From Roll20 Wiki

Jump to: navigation, search
(How to use MagicMaster)
 
(15 intermediate revisions by one user not shown)
Line 4: Line 4:
 
|name=MagicMaster
 
|name=MagicMaster
 
|author=[[Richard E]]
 
|author=[[Richard E]]
|version=2.051
+
|version=1.5.02
|lastmodified=2022-03-10
+
|lastmodified=2023-05-24
 
|code=MagicMaster
 
|code=MagicMaster
|dependencies={{api repository link|ChatSetAttr}},{{api repository link|TokenMod}}, {{api repository link|RoundMaster}}, {{api repository link|InitMaster}}, {{api repository link|AttackMaster}}, {{api repository link|CommandMaster}}
+
|dependencies={{api repository link|ChatSetAttr}},{{api repository link|TokenMod}}, {{api repository link|RoundMaster}}, {{api repository link|InitMaster}}, {{api repository link|AttackMaster}}, {{api repository link|CommandMaster}}, {{api repository link|RPGMlibrary AD+D2e}}
 
|conflicts=None}}
 
|conflicts=None}}
 
'''MagicMaster''' API provides functions for AD&D-2E (though 5e and other spells could be added) to manage all types of magic, including Wizard & Priest spell use and effects; Character, NPC & Monster Powers; and discovery, looting, use and cursing of Magic Items. It's a part of the '''[[RPGMaster]]''' suite of APIs.
 
'''MagicMaster''' API provides functions for AD&D-2E (though 5e and other spells could be added) to manage all types of magic, including Wizard & Priest spell use and effects; Character, NPC & Monster Powers; and discovery, looting, use and cursing of Magic Items. It's a part of the '''[[RPGMaster]]''' suite of APIs.
 +
 +
'''Note:''' This API ''requires'' that a '''[[Script:RPGMaster Library|RPGMaster Library]]''' API is loaded, which provides RPG version-specific and Roll20 Character Sheet version-specific data, rulesets and processing (as well as other goodies!).
  
 
All magical aspects can work with the <b>[[Script:RoundMaster|RoundMaster API]]</b> to implement token markers that show and measure durations, and produce actual effects that can change character sheet attributes temporarily for the duration of the spell or permanently if so desired.  They can also work with the <b>[[Script:InitMaster|InitiativeMaster API]]</b> to provide menus of initiative choices and correctly adjust individual initiative rolls, including effects of Haste and Slow and similar spells.  Spells can summon weapons to hand via the <b>[[Script:AttackMaster|AttackMaster API]]</b> and change bonuses on attacks and damage, by weapon or for one or more party members.  This API can also interact with the <b>[[Script:MoneyMaster|MoneyMaster API]]</b> (under development) to factor in the passing of time, the cost of spell material use, the cost of accommodation for resting, and the cost of training for leveling up as a spell caster (Wizard, Priest or any other).
 
All magical aspects can work with the <b>[[Script:RoundMaster|RoundMaster API]]</b> to implement token markers that show and measure durations, and produce actual effects that can change character sheet attributes temporarily for the duration of the spell or permanently if so desired.  They can also work with the <b>[[Script:InitMaster|InitiativeMaster API]]</b> to provide menus of initiative choices and correctly adjust individual initiative rolls, including effects of Haste and Slow and similar spells.  Spells can summon weapons to hand via the <b>[[Script:AttackMaster|AttackMaster API]]</b> and change bonuses on attacks and damage, by weapon or for one or more party members.  This API can also interact with the <b>[[Script:MoneyMaster|MoneyMaster API]]</b> (under development) to factor in the passing of time, the cost of spell material use, the cost of accommodation for resting, and the cost of training for leveling up as a spell caster (Wizard, Priest or any other).
Line 16: Line 18:
  
 
= Forum =
 
= Forum =
[https://app.roll20.net/forum/post/10607093/script-rpgmaster-apis-for-ad-and-d-2e RPGMaster Forum]
+
[https://app.roll20.net/forum/post/11115777/script-rpgmaster-apis-for-ad-and-d-2e RPGMaster Forum]
 
+
= MagicMaster Database Help =
 +
[[API:RPGMaster-MagicItemsDB|RPGMaster Magic Spells & Items DB]] - RPGMaster Spells & Magic Items databases Wiki page
 +
= Configuring Character Sheets =
 +
[[API:RPGMaster-CharacterSheets|RPGMaster Character Sheet setup]] - RPGMaster Character Sheet setup Wiki page
 
=What MagicMaster does=
 
=What MagicMaster does=
<p style="font-size: 150%">Class, Item, Spell and Power databases</p>
+
{| role="presentation" class="wikitable mw-collapsible mw-collapsed"
<p>MagicMaster uses a large range of items held in databases.  The current versions of these databases are distributed with the API, will be automatically created in any campaign the API is installed in and updated as new versions are released via Roll20.  Spell, Power and Item Databases are implemented as ability macros in specific library character sheets.  These macros can do anything that can be programmed in Roll20 using ability macros and calls to APIs, and are found and called by the MagicMaster API when the Player selects them using the menus provided by the MagicMaster functions.  The GM can add to the provided items in the databases using standard Roll20 Character Sheet editing, following the instructions provided in the <b>Magic Database Handout</b>.</p>
+
|
 +
|-
 +
|<p style="font-size: 150%">Race, Class, Item, Spell and Power databases</p>
 +
<p>MagicMaster uses a large range of items held in databases.  The current versions of these databases are distributed with the game-version-specific <b>[[Script:RPGMaster Library|RPGMaster Library]]</b>, updated as new versions are released via Roll20.  The provided databases are held in memory, but can be extracted to ability macros in database character sheets using the <b>!magic --extract-db</b> command.  These macros can do anything that can be programmed in Roll20 using ability macros and calls to APIs, and are found (either in the Character Sheet database or the internal database in memory) and called by the MagicMaster API when the Player selects them using the menus provided by the MagicMaster functions.  The GM can add to the provided items in the databases using standard Roll20 Character Sheet editing, following the instructions provided in the <b>[[API:RPGMaster-MagicItemsDB|Magic Database Handout]]</b>.</p>
 +
<p style="font-size: 150%">Races & Classes</p>
 +
<p>The definitions for character Races & Classes held in the Race-DB and Class-DB databases include a description of the race and class and its capabilities, the powers/non-weapon proficiencies that it comes with, any restrictions on weapons, armour and spells that it is subject to, and other class-specific aspects such as alignments and races.  As you might expect, these are not just descriptions, but restrict the player character to the characteristics defined (alterable by using the <b>!magic --config</b> command).  The <b>[[API:RPGMaster-ClassDB|Class & Race Database handout]]</b> provides information on the structure of the race & class specifications and how the GM / game creator can add their own races and classes and alter those provided.</p>
 
<p style="font-size: 150%">Spells and Powers</p>
 
<p style="font-size: 150%">Spells and Powers</p>
<p>The Ability Macros for spells and powers include descriptions of the spell they represent (limited, I'm afraid, to avoid copyright issues), and also can optionally have API Buttons embedded in them which, if selected by the Player, can enact the actions of the spell or power.  The API Buttons call one or more of the API commands listed in this document, or commands provided by other APIs.  This is most powerful when combined with the <b>RoundMaster API</b> to implement token statuses and status markers with durations and effect macros, enabling the spells & powers to make temporary (or permanent, if desired) changes to the targeted creature's token and character sheet attributes.</p>
+
<p>The Ability Macros for spells and powers include descriptions of the spell they represent (limited, I'm afraid, to avoid copyright issues), and also can optionally have API Buttons embedded in them which, if selected by the Player, can enact the actions of the spell or power.  The API Buttons call one or more of the API commands listed in this document, or commands provided by other APIs.  This is most powerful when combined with the <b>[[Script:RoundMaster|RoundMaster API]]</b> to implement token statuses and status markers with durations and effect macros, enabling the spells & powers to make temporary (or permanent, if desired) changes to the targeted creature's token and character sheet attributes.</p>
 
<p>The best way to learn about these capabilities is to look at example spell definitions in the databases and use those spells or powers to see what they do.</p>
 
<p>The best way to learn about these capabilities is to look at example spell definitions in the databases and use those spells or powers to see what they do.</p>
<p style="font-size: 150%">Adding Spells & Powers to the Character</p>
 
<p>Spells need to be added in two steps: 1. adding to a Character's or NPC's spell book; and 2. Memorising the spells each day.</p>
 
<p>The simplest way to add spells to a Character's spell books is to use the <b>CommandMaster API</b> functions that set up Character Sheets from scratch.  However, spells can be added to the Character Sheet manually: see the <b>RPG Master CharSheet Setup handout</b> (created by the API) for details of how to do this.  Either approach results in the Character having a list of spells at each spell level they can use that they have available to memorise.</p>
 
<p>Spells can be memorised using the <b>--mem-spell</b> MagicMaster command.  This limits the number of spells memorised at each level to the number that is valid for the Character, with their specific characteristics, class, level and other valid adjustments (though it is possible to add a “fudge factor” if needed via the menu).  Once memorised, they can be rememorised or changed at any time, though the DM usually limits this in game play to once each in-game day.  If a Player is happy with the spells a Character has, the Character just needs to rest at the end of the day to regain their spells (and powers, and recharging magic item charges) automatically.</p>
 
<p>Powers are added in exactly the same way as Spells.  The difference between the two is that Powers are granted to a Character, either as a function of the class they have adopted, or from being granted powers in game-play.  Of course, NPCs and creatures also have many various powers.  Some Powers can be used more than once a day, or even 'at will' (an example is Priests turning undead).</p>
 
<p style="font-size: 150%">Casting spells and using powers</p>
 
<p>Spells memorised by the Character can be cast using MagicMaster menus.  As with items, when used with the <b>InitiativeMaster API</b> the action for the next round can be the casting of a specific spell, with the speed of the Casting Time.  Casting a spell will remove it from memory for the rest of the day, but a rest will bring it back.  Like items, spells use Roll20 ability macros and thus can perform any function a macro or an API call can achieve.  The same capability to affect tokens and Character Sheets is available if used with the RoundMaster API.</p>
 
 
<p style="font-size: 150%">Types of Item Provided</p>
 
<p style="font-size: 150%">Types of Item Provided</p>
<p>The Item database is split into nine parts: Weapons, Ammunition, Armour, Lights, Potions, Scrolls & Spellbooks, Wands Staves & Rods, Rings, and Miscellaneous.  More might be added in future releases, and any DM can add more databases with their own items. </p>
+
<p>The Item database is currently split into nine parts: Weapons, Ammunition, Armour, Lights, Potions, Scrolls & Spellbooks, Wands Staves & Rods, Rings, and Miscellaneous.  More might be added in future releases, and any DM can add more databases with their own items.</p>
<p>Armour can be used by the <b>AttackMaster API</b> to automatically set the Character's Armour Class, including altering AC as a shield is taken in hand or put away, and taking into account items such as Rings of Protection and Bracers of Defense.  Weapons and Ammunition can also be taken in hand to attack with.  Weapons can dance, and thrown weapons and ammunition can be magically self-returning (they don't have to be retrieved by the AttackMaster <i>Recover Ammo</i> function).</p>
+
<p>Many magic items have actions that they can perform in the same way as Spells & Powers, using API Buttons in their macros that call MagicMaster API commands, or commands from other APIs.  As with spells & powers, this is most powerful when combined with the capabilities of the <b>[[Script:RoundMaster|RoundMaster API]]</b>.</p>
<p>Many magic items have actions that they can perform in the same way as Spells & Powers, using API Buttons in their macros that call MagicMaster API commands, or commands from other APIs.  As with spells & powers, this is most powerful when combined with the capabilities of the <b>RoundMaster API</b>.</p>
+
<p>Items can have stored spells (like Rings of Spell Storing) and the spells can be cast from them, and/or can have powers that can be consumed and are refreshed each day.  Again, using the RoundMaster API, the spells and powers can have temporary or permanent effects on Tokens and Character Sheets, if desired.</p>
<p>Items can have stored spells (like <i>Rings of Spell Storing</i>) and the spells can be cast from them, and/or can have powers that can be consumed and are refreshed each day.  The spells and powers can have temporary or permanent effects on Tokens and Character Sheets, if desired, via RoundMaster functions.</p>
+
 
<p style="font-size: 150%">Adding Items to the Character</p>
 
<p style="font-size: 150%">Adding Items to the Character</p>
 +
<p>Classes are set using the <b>[[Script:CommandMaster|CommandMaster API]]</b> or via the <b>AttackMaster !attk --other-menu</b> menu (or can be set manually on the Character Sheet).  Classes can be those provided in the Class-DB, or any other class.  Class names that are not in the database will adopt the attributes of the standard classes depending on the character sheet field the class name and level are entered into: <i>Warrior, Wizard, Priest, Rogue,</i> and <i>Psion</i>.  Depending on the settings selected by the GM under the <b>--config</b> menu, the choise of class will restrict or grant the character's ability to use certain items and cast certain spells.</p>
 
<p>The MagicMaster API provides commands to perform menu-driven addition of items to the Character Sheet.  Using these commands will set up all the necessary fields so that the Player can use the items with the other APIs - if using MagicMaster then items should not be added directly to the Character Sheet.</p>
 
<p>The MagicMaster API provides commands to perform menu-driven addition of items to the Character Sheet.  Using these commands will set up all the necessary fields so that the Player can use the items with the other APIs - if using MagicMaster then items should not be added directly to the Character Sheet.</p>
<p>Items can also be acquired by finding them in chests or on tables (tokens with images of chests & tables that represent Character Sheets with items added to them) that can be looted, or even dead bodies of NPCs that have been killed in battle.  MagicMaster provides commands that support a menu-driven way to perform looting.  Characters, especially Rogues, can even try to Pick Pockets to take items from NPCs (or even other Characters…), though failure may alert the DM (or other Player) to the attempt.  Containers can even be trapped, with magical consequences if the trap goes off!  On the other hand, Characters can also put items away into chests or onto tables or other storage places, or give them to other Characters or NPCs, all using easy menus and button clicks.</p>
+
<p>Items can also be acquired by finding them in chests or on tables (simply tokens with images of chests or tables that represent Character Sheets with items added to them) that can be looted, or even dead bodies of NPCs that have been killed in battle.  MagicMaster provides commands that support a menu-driven way to perform looting.  Characters, especially Rogues, can even try to Pick Pockets to take items from NPCs (or even other Characters...), though failure may alert the DM (or other Player) to the attempt.  Containers can even be trapped, with magical consequences if the trap goes off!  On the other hand, Characters can also put items away into chests or onto tables or other storage places, or give them to other Characters or NPCs.</p>
 +
<p style="font-size: 150%">Adding Spells & Powers to the Character</p>
 +
<p>Spells need to be added in two steps: 1. adding to a Character's or NPC's spell book; and 2. Memorising the spells each day.</p>
 +
<p>The simplest way to add spells to a Character's spell books is to use the <b>[[Script:CommandMaster|CommandMaster API]]</b> functions that set up Character Sheets from scratch.  However, spells can be added to the Character Sheet manually: see the <b>[[API:RPGMaster-CharacterSheets|RPGMaster Character Sheet setup handout]]</b> for details of how to do this.  Either approach results in the Character having a list of spells at each spell level they can use that they have available to memorise.</p>
 +
<p>Spells can be memorised using the MagicMaster menus or via the <b>!magic --mem-spell</b> MagicMaster command.  This limits the number of spells memorised at each level to the number that is valid for the Character, with their specific characteristics, class, level and other valid adjustments (though it is possible to add a "fudge factor" if needed).  Once memorised, they can be rememorised or changed at any time, though the DM usually limits this in game play to once each in-game day.  If a Player is happy with the spells a Character has, the Character just needs to rest at the end of the day to regain their spells (and powers, and recharging magic item charges).</p>
 +
<p>Powers are added in exactly the same way as Spells.  The difference between the two is that Powers are granted to a Character, either as a function of the class they have adopted, or from being granted powers in game-play.  Of course, NPCs and creatures also have many various powers.  Some Powers can be used more than once a day, or even 'at will' (an example is Priests turning undead).</p>
 
<p style="font-size: 150%">Using Items</p>
 
<p style="font-size: 150%">Using Items</p>
<p>Items possessed by the Character can be used to perform their functions, using MagicMaster menus.  When used with the <b>InitiativeMaster API</b>, the action for the next round can be the use of a specific item the Character has on them, with the speed of that item.  This may use charges or consume quantities of the item, and these charges may or may not be regained overnight, or through other means.  The items use Roll20 ability macros that can be as simple as putting text in the chat window explaining what the item does, through to much more complex targeting of effects on the user, a single other target, or all tokens in a defined area.  When used with the <b>RoundMaster API</b>, targeted tokens can have a status marker applied with a pre-determined duration and associated effects at the start, each round and when it finishes.  Items that are totally consumed will automatically disappear from the Character Sheet.</p>
+
<p>Items possessed by the Character can be used to perform their functions, using MagicMaster menus.  When used with the [[Script:InitMaster|InitiativeMaster API]], the action for the next round can be the use of a specific item the Character has on them, with the speed of that item.  This may use charges or consume quantities of the item, and these charges may or may not be regained overnight, or through other means.  The items use Roll20 ability macros that can be as simple as putting text in the chat window explaining what the item does, through to much more complex targeting of effects on the user, a single other target, or all tokens in a defined area.  When used with the RoundMaster API, targeted tokens can have a status marker applied with a pre-determined duration and associated effects at the start, each round and when it finishes.  Items that are totally consumed will automatically disappear from the Character Sheet.</p>
 +
<p style="font-size: 150%">Casting spells and using powers</p>
 +
<p>Spells memorised by the Character can be cast using MagicMaster menus.  As with items, when used with the InitiativeMaster API with <i>Group</i> or <i>Individual</i> initiative, the action for the next round can be the casting of a specific spell with the speed of the Casting Time.  Casting a spell will remove it from memory for the rest of the day, but a rest will bring it back.  Like items, spells use Roll20 ability macros and thus can perform any function a macro or an API call can achieve.  The same capability to affect tokens and Character Sheets is available if used with the RoundMaster API.</p>
 
<p style="font-size: 150%">Dynamic lighting for tokens</p>
 
<p style="font-size: 150%">Dynamic lighting for tokens</p>
 
<p>MagicMaster API provides commands to change the lighting settings of the token to reflect illumination, as if holding various light sources.  This includes both radiant light sources such as hooded lanterns, torches, continual light gems, magic items and magic armour, and also directed light sources such as beacon lanterns and bullseye lanterns which only illuminate in beams.</p>
 
<p>MagicMaster API provides commands to change the lighting settings of the token to reflect illumination, as if holding various light sources.  This includes both radiant light sources such as hooded lanterns, torches, continual light gems, magic items and magic armour, and also directed light sources such as beacon lanterns and bullseye lanterns which only illuminate in beams.</p>
 
<p style="font-size: 150%">DM tools</p>
 
<p style="font-size: 150%">DM tools</p>
 
<p>The DM is provided with tools to be able to add items to chests, NPCs, Characters etc.  These tools allow the DM to also change certain aspects of the items, including the displayed name and the cursed status of the item.  Items that are cursed are not obvious to Characters and Players, and such items can be 'hidden' and appear to be other items until revealed as the cursed item by the DM.</p>
 
<p>The DM is provided with tools to be able to add items to chests, NPCs, Characters etc.  These tools allow the DM to also change certain aspects of the items, including the displayed name and the cursed status of the item.  Items that are cursed are not obvious to Characters and Players, and such items can be 'hidden' and appear to be other items until revealed as the cursed item by the DM.</p>
<p>The tools also allow the DM to increase or restrict the number of items Characters can have on their person: it is then possible to give each Character a 'backpack' token/character sheet, which the Character can store items to and get items from - of course, retrieving an item from the backpack takes a round…  They can even have horses with saddlebags that can hold items.</p>
+
<p>The tools also allow the DM to increase or restrict the number of items Characters can have on their person: it is then possible to give each Character a 'backpack' token/character sheet, which the Character can store items to and get items from - of course, retrieving an item from the backpack takes a round (at the DM's discression - the system does not impose this).</p>
<p>DMs can also add their own items, spells and powers to additional databases (the provided databases should not be added to, but entries can be replaced by new entries in your own databases - updates will not overwrite items you create in your own databases).  This requires some knowledge of Roll20 macro programming and use of APIs.  See the Roll20 Help Centre for information, and the information in Section 11 of this document.</p>
+
<p>DMs can also add their own items, spells and powers to additional databases (the provided databases should not be added to, but entries can be replaced by new entries in your own databases - updates will not replace your own databases - see the <b>[[API:RPGMaster-MagicItemsDB|RPGMaster Magic Spells & Items Database handout]]</b>).  This requires some knowledge of Roll20 macro programming and use of APIs.  See the Roll20 Help Centre for information.</p>
 +
|}
 
<br>
 
<br>
  
 
=How to use MagicMaster=
 
=How to use MagicMaster=
 
<p style="font-size: 150%">Installation and Configuration</p>
 
<p style="font-size: 150%">Installation and Configuration</p>
Copy the script's code, available either via the <i>Roll20 One-Click Install</i> system, or from the menu on the right and stored at Roll20's [https://github.com/Roll20/roll20-api-scripts API GitHub Repository] and paste the code into a new script in your campaign's [[API:Use_Guide#The_Script_Editor|API Script Editor]]. Save the new script and it will be available inside your campaign.  It will install several new Character Sheets and Handouts: The handout '''MagicMaster Help''' provides a full manual of how to use MagicMaster.  The handout '''RPGMaster CharSheet Setup''' provides information on setting up a character sheet for use with MagicMaster and the rest of the RPGMaster API series.  The handout '''Magic Database Help''' provides information on use and adding to the Magic Item, Spell & Power databases.
+
Copy the script's code, available either via the <i>Roll20 One-Click Install</i> system, or from the menu on the right and stored at Roll20's [https://github.com/Roll20/roll20-api-scripts API GitHub Repository] and paste the code into a new script in your campaign's [[API:Use_Guide#The_Script_Editor|API Script Editor]]. Save the new script and it will be available inside your campaign.  It will install several new Character Sheets and Handouts: The handout '''MagicMaster Help''' provides a full manual of how to use MagicMaster.  The handout [[API:RPGMaster-CharacterSheets|RPGMaster CharSheet Setup]] provides information on setting up a character sheet for use with MagicMaster and the rest of the RPGMaster API series.  The handout [[API:RPGMaster-MagicItemsDB|Magic Database Help]] provides information on use and adding to the Magic Item, Spell & Power databases.
 
<br>
 
<br>
 
<p style="font-size: 150%">Script Use</p>
 
<p style="font-size: 150%">Script Use</p>
Line 67: Line 78:
 
<p>When specifying the commands in this document, parameters enclosed in square brackets [like this] are optional: the square brackets are not included when calling the command with an optional parameter, they are just for description purposes in this 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).</p>
 
<p>When specifying the commands in this document, parameters enclosed in square brackets [like this] are optional: the square brackets are not included when calling the command with an optional parameter, they are just for description purposes in this 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).</p>
 
<br>
 
<br>
 
+
===Roll Query Extension===
=Command Index=
+
<p>The syntax of the Roll20 Roll Query has been extended within the RPGMaster MagicMaster API to support !magic API commands with Roll Queries that the GM is forced to answer, rather than the player regardless of who issued the command. The standard syntax and the extended syntax is shown below:</p>
==Commands==
+
<pre>Standard Syntax: ?{Query text|option1|option2|...}<br>
===Spell and Power management===
+
Extended syntax: gm{Query text|option1|option2|...}</pre>
<pre>--spellmenu [token_id]|[MU/PR/POWER]
+
<p>When used in a !magic API command, the extended Roll Query will prompt the GM with a button in the Chat Window for the GM to answer the question posed by the query text.  The result will be fed into the action taken by the API command.  This allows the GM to be involved when, for instance, a Staff of the Magi absorbs levels of spells cast at a character that the character & player can't know.</p>
--mem-spell (MU/PR/POWER)|[token_id]
+
<br>
--view-spell (MU/PR/POWER)|[token_id]
+
==Using Character Sheet Ability/Action buttons==
--cast-spell (MU/PR/POWER/MI)|[token_id]|[casting_level]|[casting_name]
+
<p>The most common approach for the Player to run these commands is to use Ability macros on their Character Sheets which are flagged to appear as Token Action Buttons: Ability macros & Token Action Buttons are standard Roll20 functionality, refer to the Roll20 Help Centre for information on creating and using these.</p>
--cast-again (MU/PR/POWER)|token_id|[spell_name]</pre>
+
<p>In fact, the simplest configuration is to provide only Token Action Buttons for the menu commands: <b>--spellmenu</b> and <b>--mimenu</b>.  From these, most other commands can be accessed.  If using the <b>CommandMaster API</b>, its character sheet setup functions can be used to add the necessary Ability Macros and Token Action Buttons to any Character Sheet.</p>
===Magic Item management===
+
<br>
<pre>--mimenu [token_id]
+
==Command Index==
--edit-mi [token_id]
+
===1.Spell and Power management===
--view-mi [token_id]
+
<pre>--spellmenu [token_id]|[MU/PR/POWER]<br>
--use-mi [token_id]
+
--mem-spell (MU/PR/POWER)|[token_id]<br>
--mi-charges token_id|value|[mi_name]|[maximum]
+
--view-spell (MU/PR/POWER)|[token_id]<br>
--mi-power token_id|power_name|mi_name|[casting-level]
+
--cast-spell (MU/PR/POWER/MI)|[token_id]|[casting_level]|[casting_name]<br>
--mem-spell (MI-MU/MI-PR)|[token_id]
+
--cast-again (MU/PR/POWER)|token_id|[spell_name]<br>
--view-spell (MI-MU/MI-PR/MI-POWER)|[token_id]
+
--mem-all-powers token_id</pre>
--cast-spell MI|[token_id]|[casting_level]|[casting_name]|[CHARGED]|[mi-name]</pre>
+
===2.Magic Item management===
===Spell, power & magic item effects and resting===
+
<pre>--mimenu [token_id]<br>
<pre>!rounds --target CASTER|token_id|spell_name|duration|increment|[msg]|[marker]
+
--edit-mi [token_id]<br>
!rounds --target (SINGLE/AREA)|token_id|target_token_id|spell_name|duration|increment|[msg]|[marker]
+
--view-mi [token_id]<br>
--touch token_id|effect-name|duration|per-round|message|marker
+
--use-mi [token_id]<br>
--rest [token_id]|[SHORT/LONG]|[MU/PR/MU-PR/POWER/MI/MI-POWER]|[timescale]</pre>
+
--mi-charges token_id|value|[mi_name]|[maximum]|[charge_override]<br>
===Treasure & Item container management===
+
--mi-power token_id|power_name|mi_name|[casting-level]<br>
<pre>--gm-edit-mi [token_id]
+
--store-spells token_id|mi-name<br>
--search token_id|pick_id|put_id
+
--mem-spell (MI-MU/MI-PR)[-ANY]|[token_id]|[mi-name]<br>
 +
--view-spell (MI/MI-MU/MI-PR/MI-POWER)|[token_id]|[mi-name]<br>
 +
--cast-spell (MI/MI-POWER)|[token_id]|[casting_level]|[casting_name]|[CHARGED]|[mi-name]</pre>
 +
===3.Spell, power & magic item effects and resting===
 +
<pre>!rounds --target CASTER|caster_token_id|caster_token_id|spell_name|duration|increment|[msg]|[marker]<br>
 +
!rounds --target (SINGLE/AREA)|caster_token_id|target_token_id|spell_name|duration|increment|[msg]|[marker]<br>
 +
--touch token_id|effect-name|duration|per-round|message|marker<br>
 +
--level-change [token_id]|[# of levels]<br>
 +
--change-attr [token_id]|change|[field]|[SILENT]<br>
 +
--rest [token_id]|[SHORT/LONG]|[MU/PR/MU-PR/POWER/MI/MI-POWER]|[timescale]<br>
 +
--mi-rest [token_id]|mi_name|[charges]|[power_name]</pre>
 +
===4.Treasure & Item container management===
 +
<pre>--gm-edit-mi [token_id]<br>
 +
--search token_id|pick_id|put_id<br>
 
--pickorput token_id|pick_id|put_id|[SHORT/LONG]</pre>
 
--pickorput token_id|pick_id|put_id|[SHORT/LONG]</pre>
===Light source management===
+
===5.Light source management===
<pre>--lightsources [token_id]
+
<pre>--lightsources [token_id]<br>
--light token_id|(NONE/WEAPON/TORCH/HOODED/CONTLIGHT/BULLSEYE/BEACON)
+
--light token_id|(NONE/WEAPON/TORCH/HOODED/CONTLIGHT/BULLSEYE/BEACON)</pre>
--changelight token_id|(NONE/WEAPON/TORCH/HOODED/CONTLIGHT/BULLSEYE/BEACON)</pre>
+
===6.Other commands===
===Other commands===
+
<pre>--help<br>
<pre>--help
+
--message [who|][token_id]|title|message<br>
--check-db [ db-name ]
+
--tidy [token_id]|[SILENT]<br>
 +
--config [FANCY-MENUS/SPECIALIST-RULES/SPELL-NUM/ALL-SPELLS] | [TRUE/FALSE]<br>
 +
--check-db [db-name]<br>
 +
--extract-db [db-name]<br>
 +
--handshake from | [cmd]<br>
 +
--hsq from | [cmd]<br>
 +
--hsr from | [cmd] | [TRUE/FALSE]<br>
 
--debug (ON/OFF)</pre>
 
--debug (ON/OFF)</pre>
 
<br>
 
<br>
Line 116: Line 146:
 
<p>If the specified token is not associated with a character that has a spell book of the chosen type, or any granted powers, an error message is displayed.</p>
 
<p>If the specified token is not associated with a character that has a spell book of the chosen type, or any granted powers, an error message is displayed.</p>
 
===Display a menu to memorise spells from the Character's spell book===
 
===Display a menu to memorise spells from the Character's spell book===
<pre>--mem-spell (MU/PR/POWER/MI-MU/MI-PR)|[token_id]</pre>
+
<pre>--mem-spell (MU/PR/POWER/MI-MU/MI-PR)|[token_id]|[mi-name]</pre>
<p>Takes a mandatory spell book type and an optional token ID as arguments. If token ID is not specified, uses the selected token.</p>
+
<p>Takes a mandatory spell book type, an optional token ID, and an optional magic item name as arguments. If token ID is not specified, uses the selected token.</p>
<p>The Character Sheet associated with the token must have spell books specified for the relevant types of spells or powers.  These are lists of spells from the spell macro databases specified by level (powers are all 1 level) and as lists separated by '|'.  E.g. Charm-Person|Light|Sleep.  If the CommandMaster API is installed, the GM can use its menus to set up character spell books and granted powers.  Otherwise refer to the <b>RPGMaster CharSheet Setup</b> handout (created by the API) for how to create these manually.</p>
+
<p>The Character Sheet associated with the token must have spell books specified for the relevant types of spells or powers.  These are lists of spells from the spell macro databases (see Section 7) specified by level (powers are all 1 level) and as lists separated by '|'.  E.g. Charm-Person|Light|Sleep.  If the CommandMaster API is installed, the GM can use its menus to set up character spell books and granted powers.</p>
<p>Initially displays a menu for memorising Level 1 spells (the only level for powers), with a button to choose a spell from the Level 1 spell book on the character sheet, Review the chosen spell, and all the memorising slots the Character has at this level.  Other buttons to memorise or remove spells become available when spells or slots are chosen.  Another button goes to the next available level with slots.  When a granted power is memorised to a slot, a quantity per day can be specified: -1 will grant unlimited uses of the power per day.  Memorising any other type of spell is limited to 1 use per slot.</p>
+
<p>Initially displays a menu for memorising Level 1 spells (the only level for powers), with buttons to: choose a spell from the Level 1 spell book on the character sheet; review the chosen spell; and one for each memorising slot the Character has at this level.  Other buttons to memorise or remove spells become available when spells or slots are chosen.  Another button goes to the next available level with slots.  When a granted power is memorised to a slot, a quantity per day can be specified: -1 will grant unlimited uses of the power per day.  Memorising any other type of spell is limited to 1 use per slot.</p>
<p>MI-MU and MI-PR have a special function: these are used to cast memorised spells into a spell-storing magic item (which should be the last item selected by the Character running the command), such as a Ring of Spell Storing.  Magic Item spells are stored in an unused level of the Character Sheet.  This command displays both all memorised spells and all spell-storing magic item spell slots for the item, and allows a memorised spell to be selected, a slot (for the same spell name) to be selected, and the spell cast from one to the other.  Generally, this command is called from an API button in the Magic Item macro.</p>
+
<p>Depending on the settings on the <b>--config</b> menu, the character will be limited to memorising spells and powers allowed to their character class and level.</p>
 +
<p>MI-MU and MI-PR have a special function: these are used to cast memorised spells into the named spell-storing magic item (if no item is named, the last item selected by the Character running the command will be used instead), such as a Ring-of-Spell-Storing.  Magic Item spells are stored in an unused level of the Character Sheet.  This command displays both all memorised spells and all spell-storing magic item spell slots, and allows a memorised spell to be selected, a slot (for the same spell name) to be selected, and the spell cast from one to the other.  Spells can only be replaced by the same spell that was in the slot previously (unless this is the first time spells have been stored in a blank spell-storing item).</p>
 
===View the memorised spells or granted powers===
 
===View the memorised spells or granted powers===
<pre>--view-spell (MU/PR/POWER/MI-MU/MI-PR/MI-POWER)|[token_id]</pre>
+
<pre>--view-spell (MU/PR/POWER/MI-MU/MI-PR/MI-POWER)|[token_id]|[mi-name]</pre>
<p>Takes a mandatory spell type and an optional token ID. If token ID is not specified, uses the selected token.</p>
+
<p>Takes a mandatory spell type, an optional token ID, and an optional magic item name. If token ID is not specified, uses the selected token.</p>
 
<p>Displays a menu of all levels of memorised spells of the selected type (there is only 1 level of powers).  Spells that have already been cast appear as greyed out buttons, and can't be selected.  Spells that are still available to cast that day can be selected and this runs the spell or power macro from the relevant database without consuming the spell, so that the Player can see the specs.</p>
 
<p>Displays a menu of all levels of memorised spells of the selected type (there is only 1 level of powers).  Spells that have already been cast appear as greyed out buttons, and can't be selected.  Spells that are still available to cast that day can be selected and this runs the spell or power macro from the relevant database without consuming the spell, so that the Player can see the specs.</p>
<p>Adding MI- before any of the types of spell views the spells or powers available for the last Magic Item used by the Character using the command.  Generally this version of the command is only called from API Buttons from the magic item's ability macro.</p>
+
<p>Adding MI- before any of the types of spell views the spells or powers available for the specified magic item, or the last Magic Item used by the Character if no magic item name is provided.  Generally this version of the command is only called from API Buttons from the magic item's ability macro.</p>
 
===Cast a memorised spell or use a granted power===
 
===Cast a memorised spell or use a granted power===
<pre>--cast-spell (MU/PR/POWER/MI)|[token_id]|[casting_level]|[casting_name]|[CHARGED]</pre>
+
<pre>--cast-spell (MU/PR/POWER/MI/MI-POWER)|[token_id]|[casting_level]|[casting_name]|[CHARGED]|[mi-name]</pre>
<p>Takes a mandatory spell type, an optional token ID (if not specified, uses the selected token), an optional casting level, and an optional caster name, and an optional 'CHARGED' command.</p>
+
<p>Takes a mandatory spell type, an optional token ID (if not specified, uses the selected token), an optional casting level, and an optional caster name, an optional 'CHARGED' command, and an optional magic item name.</p>
<p>This displays a menu of all levels of the memorised spells/powers of the relevant type.  MI displays the spell book for spells stored on the last magic item selected by the Character (both MU & PR) and MI-POWER all stored powers in the last selected magic item (this version of the command is generally called using an API Button in the magic item ability macro).  The player can select a spell/power and then a button becomes available to cast it, using up that slot/deducting a power charge until the next long rest.</p>
+
<p>This displays a menu of all levels of the memorised spells/powers of the relevant type.  MI displays the spell book for spells stored on the specified magic item, or the last magic item used or viewed if not specified (both MU & PR), and MI-POWER all stored powers in the specified or last selected magic item, (this version of the command is generally called using an API Button in the magic item ability macro).  The player can select a spell/power and then a button becomes available to cast it, using up that slot/deducting a power charge until the next long rest (or until the item is recharged).</p>
 
<p>If a casting_level is specified, the spell will be cast as if by a caster of that level, and if a casting_name is specified, that name will be displayed in the spell macro information.  These functions are often used for magic items that cast at specific levels of use, or magic artefacts that are named and/or sentient.  If these are not specified, the caster name and relevant class level are used.  In either case, specified or not, the character's Character Sheet Attributes called @{Casting-name} and @{Casting-level} are set to the values used, and can be used in spell, power, or magic item macros.</p>
 
<p>If a casting_level is specified, the spell will be cast as if by a caster of that level, and if a casting_name is specified, that name will be displayed in the spell macro information.  These functions are often used for magic items that cast at specific levels of use, or magic artefacts that are named and/or sentient.  If these are not specified, the caster name and relevant class level are used.  In either case, specified or not, the character's Character Sheet Attributes called @{Casting-name} and @{Casting-level} are set to the values used, and can be used in spell, power, or magic item macros.</p>
<p>If the optional CHARGED parameter is specified (only relevant to spells and powers stored on magic items), this specifies that the Magic Item from which the spell or power is cast is charged, and looses one charge when that cast is made.  This is generally the case when the spell or power is on a Scroll.  When the charge quantity reaches zero (i.e. all the spells on it have been cast), the item will follow the behaviour determined by its charge type (charged, uncharged, rechargeable, recharging, self-charging) - see section 4.1 for more information on charges and charge types.</p>
+
<p>If the optional CHARGED parameter is specified (only relevant to spells and powers stored on magic items), this specifies that the Magic Item from which the spell or power is cast is charged, and looses one charge when that cast is made.  This is generally the case when the spell or power is on a Scroll.  When the charge quantity reaches zero, the item will follow the behaviour determined by its charge type (charged, uncharged, rechargeable, recharging, self-charging) - see section 4.1 for more information on charges and charge types.</p>
 
===Cast the last used spell or power again===
 
===Cast the last used spell or power again===
 
<pre>--cast-again (MU/PR/POWER)|token_id|[spell_name]</pre>
 
<pre>--cast-again (MU/PR/POWER)|token_id|[spell_name]</pre>
 
<p>Takes a mandatory spell type, a mandatory token ID and an optional spell name.</p>
 
<p>Takes a mandatory spell type, a mandatory token ID and an optional spell name.</p>
 
<p>This command is used for certain spells and powers that, once cast, allow continuing effects in the same or subsequent rounds, without using additional charges.  If the optional spell name is not used, the command just casts again the same spell as the last spell cast by the character associated with the selected token, at the same casting level and casting name.  If a spell name is specified, this spell is cast instead as if it were the same spell: this is used where different spell macros are required to specify subsequent spell effects.</p>
 
<p>This command is used for certain spells and powers that, once cast, allow continuing effects in the same or subsequent rounds, without using additional charges.  If the optional spell name is not used, the command just casts again the same spell as the last spell cast by the character associated with the selected token, at the same casting level and casting name.  If a spell name is specified, this spell is cast instead as if it were the same spell: this is used where different spell macros are required to specify subsequent spell effects.</p>
 +
===Memorise All Valid Powers===
 +
<pre>--mem-all-powers token_id</pre>
 +
<p>Takes a mandatory token_id.</p>
 +
<p>Reviews all the Powers currently in the Powers Spellbook, checking for Race, Creature, Class and user-added Powers, and checks them against their respective definitions in the various databases to assess if they can be used at the level of experience/Hit Dice of the character / creature.  Memorises each valid power for the number of uses per day specified in the Race, Class or Creature database definition: user-added powers are memorised at unlimited uses per day unless a default is otherwise specified in the Powers database, on the basis that DMs/Players will either change this by rememorising them individually, or otherwise play to the agreed limits of use.</p>
 
<br>
 
<br>
 
==Magic Item management==
 
==Magic Item management==
Line 142: Line 177:
 
<p>Takes an optional token ID as an argument. If token ID is not specified, uses the selected token.</p>
 
<p>Takes an optional token ID as an argument. If token ID is not specified, uses the selected token.</p>
 
<p>Displays a menu with the following actions: Use a magic item, Search for magic items & treasure, Store magic items in a container, Edit the contents of a character's magic item bag, and View the contents of a character's magic item bag.</p>
 
<p>Displays a menu with the following actions: Use a magic item, Search for magic items & treasure, Store magic items in a container, Edit the contents of a character's magic item bag, and View the contents of a character's magic item bag.</p>
<p>Searching & Storing are explained in section 7.</p>
+
<p>Searching & Storing are explained in section 4.</p>
 
===Edit a Magic Item bag===
 
===Edit a Magic Item bag===
<pre>--edit-mi [token_id]</pre>
+
<pre>--edit-mi [token_id]|[MARTIAL/MAGICAL/ALL]</pre>
<p>Takes an optional token ID as an argument. If token ID is not specified, uses the selected token.</p>
+
<p>Takes an optional token ID, and an optional item type as arguments. If token ID is not specified, uses the selected token. If the item type is not specified, defaults to MAGICAL.</p>
<p>Displays a menu similar to editing memorised spells.  At the top are buttons to choose different types of magic items which have macros in the magic item databases.  The slots available in the bag are shown (with their current contents) and, when magic items and/or slots are chosen buttons become selectable below to store, review, or remove magic items in/from the bag.</p>
+
<p>Displays a menu similar to editing memorised spells.  At the top are buttons to choose different types of magic items which have macros in the magic item databases. If the optional item type is MARTIAL, only weapons, ammo and armour are listed; if ALL is specified, lists of all items are shown; otherwise only non-MARTIAL items are listed.  The slots available in the bag are shown (with their current contents) and, when magic items and/or slots are chosen buttons become selectable below to store, review, or remove magic items in/from the bag.</p>
<p>Storing a magic item will ask for a number - either a quantity or a number of charges.  Magic Items can be of various types: Charged (is used up when reaches 0), Uncharged (a number is a pure quantity that is not consumed), Recharging (regains charges after each long rest), Rechargable (is not used up when reaches 0, stays in bag and can be recharged when the DM allows), Self-charging (recharge at a rate per round determined by the item) and can also be Cursed - more under section 7.</p>
+
<p>Storing a magic item will ask for a number - either a quantity or a number of charges.  Magic Items can be of various types: Charged (is used up when reaches 0), Uncharged (a number is a pure quantity that is not consumed), Recharging (regains charges after each long rest), Rechargable (is not used up when reaches 0, stays in bag and can be recharged when the DM allows), Self-charging (recharge at a rate per round determined by the item) and can also be Cursed - more under section 4.</p>
<p>This menu is generally used when Magic Item & treasure containers (such as Treasure Chests and NPCs/monsters with treasure) have not been set up in a campaign as lootable as a means of giving found magic items to characters, the DM just tells the Player that they have found a magic item, and the Player uses this menu to give an item to the Character.</p>
+
<p>This menu is generally used when Magic Item & treasure containers (such as Treasure Chests and NPCs/monsters with treasure) have not been set up in a campaign as lootable, and provides a means of giving found magic items to characters. The DM just tells the Player that they have found a magic item, and the Player adds it to their Character Sheet using this command (more likely accessed via the Magic Item menu).</p>
===View a Character's Magic Item Bag===
+
===View a character's Magic Item Bag===
 
<pre>--view-mi [token_id]</pre>
 
<pre>--view-mi [token_id]</pre>
 
<p>Takes an optional token ID as an argument. If token ID is not specified, uses the selected token.</p>
 
<p>Takes an optional token ID as an argument. If token ID is not specified, uses the selected token.</p>
Line 156: Line 191:
 
<pre>--use-mi [token_id]</pre>
 
<pre>--use-mi [token_id]</pre>
 
<p>Takes an optional token ID as an argument. If token ID is not specified, uses the selected token.</p>
 
<p>Takes an optional token ID as an argument. If token ID is not specified, uses the selected token.</p>
<p>Displays a similar menu as for viewing the contents of the Magic Item Bag, but when an item is selected, a button is enabled that uses the Magic Item and consumes a charge.  Other buttons specified in the item macro might use additional charges to perform additional effects.</p>
+
<p>Displays a similar menu as for viewing the contents of the Magic Item Bag, but when an item is selected, a button is enabled that uses the Magic Item and consumes a charge.  Other buttons specified in the item macro might use additional charges to perform additional effects.  See section 3.</p>
<p>Items with 0 quantity or charges left are greyed out, and cannot be selected.  When a Charged Item reaches 0 charges left, it is removed from the character's Magic Item Bag automatically.  Recharging, Rechargeable and Self-Charging items remain, even when they reach 0 charges.  Cursed items also remain.</p>
+
<p>Items with 0 quantity or charges left are greyed out and cannot be selected, unless they have abilities to regain charges such as "spell absorbing" items.  When a Charged Item reaches 0 charges left, it is removed from the character's Magic Item Bag automatically.</p>
 
===Add, set or deduct Magic Item charges===
 
===Add, set or deduct Magic Item charges===
<pre>--mi-charges token_id|[+/-]value|[mi_name]|[maximum]</pre>
+
<pre>--mi-charges token_id|[+/-]value|[mi_name]|[maximum]|[charge_override]</pre>
<p>Takes a mandatory token ID, a mandatory value preceeded by an optional + or -, and an optional magic item name and optional maximum value as arguments.</p>
+
<p>Takes a mandatory token ID, a mandatory value preceeded by an optional + or -, an optional magic item name, an optional maximum value, and an optional magic item charge type override as arguments.</p>
 
<p>Does not display anything but alters the number of current or recoverable charges on an item.  By default, alters the last magic item used by the character, or will affect the named magic item.  Warning: a character can have two items of the same name, and there is no guarantee which will be affected if the name is used.</p>
 
<p>Does not display anything but alters the number of current or recoverable charges on an item.  By default, alters the last magic item used by the character, or will affect the named magic item.  Warning: a character can have two items of the same name, and there is no guarantee which will be affected if the name is used.</p>
<p>Remember: using a Charged, Recharging, Rechargeable or Self-Charging Magic Item will automatically use 1 charge on use. This command is not required in order for that to happen.  In addition, that one charge deduction always happens - if an effect of a Magic Item uses 2 charges, only 1 more needs to be deducted.</p>
+
<p>Remember: using a Charged, Recharging, Rechargeable or Self-Charging Magic Item will automatically use 1 charge on use (unless the ItemData specification includes the field <b>c:0</b>, in which case no charges will automatically be deducted on use). If the c: tag is not used, or is anything other than 0, then charges will be deduncted (default 1 charge) on use of the item.  In addition, that one charge deduction always happens - if an effect of a Magic Item uses 2 charges, only 1 more needs to be deducted.</p>
<p><b>Note:</b> '-' reduces <i>current</i> remaining charges, '+' adds to the <i>maximum</i> recoverable charges, and no + or - sets the <i>maximum</i> recoverable charges.  This command <b><i>cannot</i></b> be used to increase the current remaining charges.</p>
+
<p><b>Note:</b> '-' reduces <i>current</i> remaining charges, '+' adds to the <i>maximum</i> recoverable charges, and no + or - sets the <i>maximum</i> recoverable charges.  This command <i>cannot</i> be used to increase the current remaining charges <i>unless</i> the item is of type <i>absorbing</i>.</p>
<p>Using minus '-' before the value will deduct charges from the current quantity/charges: e.g. if using an optional power of the item that uses more than 1 charge.  Using + before the value will add the value to the number of recoverable charges (either overnight or rechargeable), up to any specified maximum (often used for magic items that regain variable numbers of charges overnight).  Just using the value without + or - will just set the number of recoverable charges to the given value.  This command is not required to recharge self-charging items but can be used to change the maximum number of charges they will self-charge up to.</p>
+
<p>Using minus '-' before the value will deduct charges from the current quantity/charges: e.g. if using an optional power of the item that uses more than 1 charge.  Using + before the value will add the value to the number of recoverable charges (overnight or rechargeable to), up to any specified maximum (often used for magic items that regain variable numbers of charges overnight).  Just using the value without + or - will just set the number of recoverable charges to the given value.  This command is not required to recharge self-charging items but can be used to change the maximum number of charges they will self-charge up to.</p>
 +
<p><b>Absorbing items</b> can gain charges in use from other sources, so the <b>--mi-charges</b> command works differently: '-' reduces <i>both current and maximum charges</i> and '+' only increases <i>current charges</i> (but only to maximum and not beyond). Using neither '-' or '+' will set the <i>current</i> charges (but, again, only up to the maximum).</p>
 +
<p>The <i>charge-override</i> can be used to temporarily change the charge behaviour of the magic item. Specifying an override will cause the magic item to behave as if its charging type was that of the override only for this call.  Thus charges could be deducted from an <i>uncharged</i> item by overriding by <i>rechargeable</i> or <i>charged</i>.</p>
 
===Use a Magic Item power===
 
===Use a Magic Item power===
<pre>--mi-power token_id|power_name|mi_name|[casting-level]</pre>
+
<pre>--mi-power token_id|[type-]power_name|mi_name|[casting-level]</pre>
<p>Takes a mandatory token ID, mandatory power name, mandatory magic item name, and an optional casting level as parameters.</p>
+
<p>Takes a mandatory token ID, mandatory power name (optionally prefixed by a power type), mandatory magic item name, and an optional casting level as parameters.</p>
 
<p>Magic Items, especially artefacts, can have their own powers that can be used a specified number of times a day, or at will.  This command can be used in API buttons in the Magic Item macro to call on that power.  The power name and the magic item name must be specified to select the right power.  If a casting level is specified, any relevant impacts on use of the power will be taken into account: it is often the case that magic items use powers at specific levels. If not specified, the item using Character's level is used (user does not need to be a spell caster).</p>
 
<p>Magic Items, especially artefacts, can have their own powers that can be used a specified number of times a day, or at will.  This command can be used in API buttons in the Magic Item macro to call on that power.  The power name and the magic item name must be specified to select the right power.  If a casting level is specified, any relevant impacts on use of the power will be taken into account: it is often the case that magic items use powers at specific levels. If not specified, the item using Character's level is used (user does not need to be a spell caster).</p>
<p>Generally, magic item powers have unique names, though they do not have to.  Such magic items require specific setting up by the DM - see section 11.4.</p>
+
<p>Generally, magic item powers have unique names, though they do not have to.  Such magic items require specific setting up by the DM - see later sections. However, powers can have a prefix that indicates a power type that specifies the power is in fact a Wizard spell (MU-), a Priest spell (PR-), or a Magic Item (MI-) or (for completeness) confirmed as a Power (PW-). Specifying a power type prefix means the appropriate database types will be searched for the named power - thus (for instance) a Wizard or Priest spell can be specified as a Magic Item power without having to program a duplicate in the Powers Databases. If no power type prefix is specified, the system will first search for a matching power in the Powers Databases (both API-supplied and user-supplied), then all Wizard spell databases, then Priest spell databases, then all Magic Item databases, and finally the character sheet of the creature wielding the Magic Item.</p>
===Store spells in a spell-storing Magic Item===
+
===Add spells to a spell-storing Magic Item===
<pre>--mem-spell (MI-MU/MI-PR)|[token_id]</pre>
+
<pre>--store-spells token_id|mi_name</pre>
<p>Takes a mandatory spell type, an optional Token ID for the character, and an optional magic item name.  If token ID is not provided, it uses the selected token.  If the magic item name is not provided, uses the last magic item selected, viewed or used by the character represented by the token.</p>
+
<p>Takes a mandatory token ID and a mandatory magic item name.</p>
<p>MI-MU and MI-PR mem-spell types are used to cast memorised spells into a spell-storing magic item, such as a Ring of Spell Storing.  Magic Item spells are stored in an unused spell level of the Character Sheet (by default Wizard Level 15 spells).  This command displays both all the character's memorised spells and the spell-storing magic item spell slots in the last magic item selected by the Character, and allows a memorised spell to be selected, a slot (for the same spell name - limiting the item to only store certain defined spells) to be selected, and the spell cast from one to the other.</p>
+
<p>This command presents a dialog in the chat window that stores spells or powers in any magic item that has been defined as being able to cast stored spells/powers. The item definition <i>must</i> include somewhere in its definition the command call <code>!magic --cast-spell MI|</code> or <code>!magic --cast-spell MI-POWER|</code>, generally as part of an API button, or spells/powers cannot be stored. If the command is for MI, the dialog defaults to Level 1 Wizard spells, and has buttons to switch level and to Priest spells. If the command is for MI-POWER, the dialog allows powers to be stored, but Wizard and Priest spells can also be stored as powers, and the dialog will prompt for a number of uses per day for each.</p>
 +
<p>Once a spell is cast from a spell-storing item, the spell is spent and does not return on a long or short rest: the spell must be refreshed using the <b>--mem-spell</b> command (see below). If a power is used from a power-storing item, the power will have a number of uses per day (or be "at will"), and <i>will</i> refresh on a long rest.</p>
 +
===Restore spells in a spell-storing Magic Item===
 +
<pre>--mem-spell (MI-MU/MI-PR)[-ADD/-ANY]|[token_id]|[mi-name]</pre>
 +
<p>Takes a mandatory spell type (optionally followed by -ADD or -ANY), an optional Token ID for the character, and an optional magic item name.  If token ID is not provided, it uses the selected token, and if the magic item name is not specified, the last used magic item is assumed.</p>
 +
<p>MI-MU and MI-PR mem-spell types are used to cast memorised spells into a spell-storing magic item, such as a Ring of Spell Storing.  Magic Item spells are stored in an unused spell level of the Character Sheet (by default Wizard Level 15 spells).  This command displays both all the character's memorised spells and the spell-storing magic item spell slots in the specified magic item (or the last one used if not specified), and allows a memorised spell to be selected, a slot to be selected (for the same spell name - limiting the item to only store certain defined spells <i>unless</i> "-ANY" is added to the command), and the spell cast from one to the other.</p>
 +
<p>If either "-ANY" or "-ADD" are added to the spell type string, the player can just select a memorised spell and then immediately cast it into the device without choosing a slot: this will <i>add</i> the spell to the device. If the extension is "-ADD" then existing spells need to be refreshed with an identical spell, the same way as if -ADD was not specified. If "-ANY" is specified, not only can the player extend the spells stored, they can replace expended spell slots with any spell, not just the one previously stored in the slot. Generally, the GM will state that the device used for storing the spells will have a limited capacity of some type - number of spell levels, number of spells, types or spheres of spell, etc. These are not programmatically implemented and the player & GM will need to manage this manually.</p>
 
<p>Unlike some other menus, however, magic item spell slots that are full are greyed out and not selectable - their spell is intact and does not need replacing.  Spell slots that need replenishing are displayed as selectable buttons with the spell name that needs to be cast into the slot.</p>
 
<p>Unlike some other menus, however, magic item spell slots that are full are greyed out and not selectable - their spell is intact and does not need replacing.  Spell slots that need replenishing are displayed as selectable buttons with the spell name that needs to be cast into the slot.</p>
 
<p>The level of the caster at the time of casting the spell into the magic item is stored in the magic item individually for each spell - when it is subsequently cast from the spell-storing magic item it is cast as if by the same level caster who stored it.</p>
 
<p>The level of the caster at the time of casting the spell into the magic item is stored in the magic item individually for each spell - when it is subsequently cast from the spell-storing magic item it is cast as if by the same level caster who stored it.</p>
<p>A spell-storing magic item can hold spells from one or both of Wizard and Priest spells.  The database where the spell is defined is also stored in the magic item with the spell, so the correct one is used when at some point in the future it is cast.  If, when cast, the system can't find the database or the spell in that database (perhaps the character has been moved to a different campaign with different databases) the system will search all databases for a spell with the same name - this does not guarantee that the same spell will be found: the definition used by a different DM could be different - or the DM may not have loaded the database in question into the campaign for some reason.  In this case, an error will occur when the spell is cast.</p>
+
<p>A spell-storing magic item can hold spells from one or both of Wizard and Priest spells.  The database where the spell is defined is also stored in the magic item with the spell, so the correct one is used when at some point in the future it is cast.  A copy of the spell macro is also stored on the Character Sheet of the character that has the spell-storing magic item. If, when cast, the system can't find the database or the spell in that database (perhaps the character has been moved to a different campaign with different databases), and it can't use the copy on its own character sheet for some reason, the system will search all databases for a spell with the same name - this does not guarantee that the same spell will be found: the definition used by a different DM could be different - or the DM may not have loaded the database in question into the campaign for some reason.  In this case, an error will occur when the spell is cast.</p>
<p>See Section 11.4 for how spell-storing magic items are defined.</p>
+
<p>See the Magic Items Database documentation for how spell-storing magic items are defined.</p>
 
===Casting a spell from a spell-storing magic item===
 
===Casting a spell from a spell-storing magic item===
<pre>--cast-spell MI|[token_id]|[casting_level]|[casting_name]|[CHARGED]|[mi-name]</pre>
+
<pre>--cast-spell (MI/MI-POWER)|[token_id]|[casting_level]|[casting_name]|[CHARGED]|[mi-name]</pre>
<p>Takes a mandatory casting type of 'MI', an optional Token ID (if token ID is not provided, it uses the selected token), an optional casting level (which will be ignored in favour of the level of the caster of the spell who cast it into the item), an optional casting name which, if not specified, will be the name of the wielder of the magic item, and an optional magic item name (if not provided, uses name of the last magic item the character selected, viewed or used).</p>
+
<p>Takes a mandatory casting type of 'MI', an optional Token ID (if token ID is not provided, it uses the selected token), an optional casting level (which will be ignored in favour of the level of the caster of the spell who cast it into the item), an optional casting name which, if not specified, will be the name of the wielder of the magic item, an optional 'CHARGED' command, and an optional magic item name (if not provided, uses name of the last magic item the character selected, viewed or used).</p>
<p>This command works in the same way as for casting other spells.  However, spells cast from a spell-storing magic item are not regained by resting - either short or long rests.  The only way to regain spells cast from such an item is to cast them back into the item from the character's own memorised spells: see the -mem-spell command above.  If the character does not have these spells in their spell book or is not of a level able to memorise them, then they will not be able to replace the spells and will have to get another spell caster to cast them into the item (by giving the item to the other Character and asking nicely for it back again) or wait until they can get the spells.</p>
+
<p>This command works in the same way as for casting other spells.  However, spells cast from a spell-storing magic item are not regained by resting - either short or long rests.  The only way to regain spells cast from such an item is to cast them back into the item from the character's own memorised spells: see the <b>--mem-spell</b> command above.  If the character does not have these spells in their spell book or is not of a level able to memorise them, then they will not be able to replace the spells and will have to get another spell caster to cast them into the item (by giving the item to the other Character and asking nicely for it back again) or wait until they can get the spells.</p>
 
<p>If the optional parameter <i>'CHARGED'</i> is used, spells on the magic item are not re-storable.  The spells will be deleted after they are all used up and the magic item will not be able to store any more spells.  This is mainly used for Scrolls with multiple spells.</p>
 
<p>If the optional parameter <i>'CHARGED'</i> is used, spells on the magic item are not re-storable.  The spells will be deleted after they are all used up and the magic item will not be able to store any more spells.  This is mainly used for Scrolls with multiple spells.</p>
 
<br>
 
<br>
 
==Spell, power & magic item effects and resting==
 
==Spell, power & magic item effects and resting==
<p>If this API is used in conjunction with the <b>RoundMaster API</b>, Magic Items, Spells & Powers can all place status markers on tokens, and also cause real Effects to alter token & character sheet attributes and behaviours: when cast; during each round of their duration; and when they expire.  See the RoundMaster documentation for further information, especially on Effects and the Effects Database.</p>
+
<p>If this API is used in conjunction with the RoundMaster API, Magic Items, Spells & Powers can all place status markers on tokens, and also cause real Effects to alter token & character sheet attributes and behaviours: when cast; during each round of their duration; and when they expire.  See the RoundMaster documentation for further information, especially on Effects and the Effects Database.</p>
 
===Target spell effects on a token (with RoundMaster API only)===
 
===Target spell effects on a token (with RoundMaster API only)===
<pre>!rounds --target CASTER|token_id|spell_name|duration|[+/-]increment|[msg]|[marker]<br>
+
<pre>!rounds --target CASTER|caster_token_id|[caster_token_id|]spell_name|duration|[+/-]increment|[msg]|[marker]<br>
!rounds --target (SINGLE/AREA)|token_id|target_token_id|spell_name|duration|increment|[msg]|[marker]</pre>
+
!rounds --target (SINGLE/AREA)|caster_token_id|target_token_id|spell_name|duration|increment|[msg]|[marker]</pre>
 
<p>Takes mandatory CASTER, SINGLE or AREA command, a mandatory caster token ID, for SINGLE/AREA a mandatory target token ID, mandatory spell name, duration & increment (preceeded by an optional +/-), and an optional message and optional token marker name.</p>
 
<p>Takes mandatory CASTER, SINGLE or AREA command, a mandatory caster token ID, for SINGLE/AREA a mandatory target token ID, mandatory spell name, duration & increment (preceeded by an optional +/-), and an optional message and optional token marker name.</p>
 
<p>If using the RoundMaster API, this command targets one, or a sequential set of tokens and applies a token marker to the token for the specified duration number of rounds, with the increment applied each round.  The optional message will be shown below that token's turn announcement each round.  The marker used will either be the one specified or if not specified a menu to choose one will be shown.</p>
 
<p>If using the RoundMaster API, this command targets one, or a sequential set of tokens and applies a token marker to the token for the specified duration number of rounds, with the increment applied each round.  The optional message will be shown below that token's turn announcement each round.  The marker used will either be the one specified or if not specified a menu to choose one will be shown.</p>
Line 194: Line 237:
 
<tr><th scope="row">CASTER</th><td>will just take one Token ID and apply the marker to that token.</td></tr>
 
<tr><th scope="row">CASTER</th><td>will just take one Token ID and apply the marker to that token.</td></tr>
 
<tr><th scope="row">SINGLE</th><td>will take both the Token ID of the caster, and the Token ID of a target of the spell/power/MI.  The marker will be applied to that of the target.</td></tr>
 
<tr><th scope="row">SINGLE</th><td>will take both the Token ID of the caster, and the Token ID of a target of the spell/power/MI.  The marker will be applied to that of the target.</td></tr>
<tr><th scope="row">AREA</th><td>will take the Token ID of the caster, and one Token ID of the first token in the area of effect.  As each token is specified the command will ask the Player to select subsequent tokens in the area of effect.</td></tr>
+
<tr><th scope="row">AREA</th><td>will take the Token ID of the caster, and one Token ID of the first token in the area of effect.  As each token is specified the command will ask the Player to select subsequent tokens in the area of effect. Once all relevant tokens have been selected, just ignore the next prompt.</td></tr>
 
</table>
 
</table>
 
<p>If the Player is not the DM/GM, the system will ask the DM/GM to approve the marker/effect for each token - this allows the DM to make saving throws for monsters/NPCs affected where appropriate.</p>
 
<p>If the Player is not the DM/GM, the system will ask the DM/GM to approve the marker/effect for each token - this allows the DM to make saving throws for monsters/NPCs affected where appropriate.</p>
 
<p>See the RoundMaster API documentation for full details.</p>
 
<p>See the RoundMaster API documentation for full details.</p>
===Cast a spell that requires a “touch” attack roll===
+
===Cast a spell that requires a "touch" attack roll===
 
<pre>--touch token_id|effect-name|duration|per-round|[message]|[marker]</pre>
 
<pre>--touch token_id|effect-name|duration|per-round|[message]|[marker]</pre>
 
<p>Takes mandatory token ID, effect name, duration of the effect, an increment to the duration per round (often -1), an optional message each round for the targeted token, and an optional status marker to use (if not supplied, the DM or user will be asked to select one).</p>
 
<p>Takes mandatory token ID, effect name, duration of the effect, an increment to the duration per round (often -1), an optional message each round for the targeted token, and an optional status marker to use (if not supplied, the DM or user will be asked to select one).</p>
 
<p>Note: this command requires RoundMaster API to also be loaded, but is a !magic command.</p>
 
<p>Note: this command requires RoundMaster API to also be loaded, but is a !magic command.</p>
<p>Sets up the Character represented by the specified token ready for an “Attack Roll” to deliver a touch attack for a spell or power or magic item use that requires an attack.  The parameters are those that will be passed to the !rounds -target command if the attack is successful (see above).</p>
+
<p>Sets up the Character represented by the specified token ready for an "Attack Roll" to deliver a touch attack for a spell or power or magic item use that requires an attack.  The parameters are those that will be passed to the <b>!rounds --target</b> command if the attack is successful (see above).</p>
<p>To use this command, add it as part of a spell, power or MI macro in the appropriate database, before or after the body of the macro text (it does not matter which, as long as it is on a separate line in the macro - the Player will not see the command).  Then include in the macro (in a place the Player will see it and be able to click it) an API Button call [Button name](~Selected|To-Hit-Spell) which will run the Ability “To-Hit-Spell” on the Character's sheet (which has just been newly written there or updated by the -touch command).</p>
+
<p>To use this command, add it as part of a spell, power or MI macro in the appropriate database, before or after the body of the macro text (it does not matter which, as long as it is on a separate line in the macro - the Player will not see the command).  Then include in the macro (in a place the Player will see it and be able to click it) an API Button call [Button name](~Selected|To-Hit-Spell) which will run the Ability "To-Hit-Spell" on the Character's sheet (which has just been newly written there or updated by the <b>--touch</b> command).</p>
 
<p>Thus, when the Player casts the Character's spell, power or MI, they can then press the API Button when the macro runs and the attack roll will be made.  If successful, the Player can then use the button that appears to mark the target token and apply the spell effect to the target.</p>
 
<p>Thus, when the Player casts the Character's spell, power or MI, they can then press the API Button when the macro runs and the attack roll will be made.  If successful, the Player can then use the button that appears to mark the target token and apply the spell effect to the target.</p>
 
<p>See the RoundMaster API documentation for further information on targeting, marking and effects.</p>
 
<p>See the RoundMaster API documentation for further information on targeting, marking and effects.</p>
 +
===Change the Experience Level===
 +
<pre>--level-change [token_id]|[# of levels]</pre>
 +
<p>Takes an optional Token ID (if not specified, uses the selected token), and an optional number of levels (plus or minus: if not specified assumes -1).</p>
 +
<p>Mainly used for attacks and spell-like effects that drain levels from opponents, this command undertakes all the calculations and Character Sheet updates that can automatically be done when a character or creature changes experience level. Saving throw targets are reassessed, weapon attacks per round recalculated, numbers of memorised spells changed, Race & Class powers checked for level appropriateness, etc. Asks for number of hit points to reduce or add to current and maximum values. If the character is multi- or dual-class, asks which class to add/drain levels to/from and the hit points for each.</p>
 +
===Change an Attribute Value===
 +
<pre>--change-attr [token_id]|change|[STRENGTH/DEXTERITY/CONSTITUTION/INTELLIGENCE/WISDOM/CHARISMA]</pre>
 +
<p>Takes an optional Token ID (if not specified, uses the selected token), and a mandatory change value (plus, minus, or zero), and an optional attribute name (defaults to STRENGTH)</p>
 +
<p>Mainly used to support magical effects and creature attacks that drain or add to attributes such as Strength, this command specifically deals with aspects such as Exceptional Strength, remembering if a Character has exceptional strength as a characteristic and taking it into account as the value is changed. Going up or down from the original rolled value and then back the other way will include as a step the exceptional, percentage value.  If the change requested would take the value past the original rolled value, the change will only go as far as the original value, whatever change was requested. However, the change can then continue with subsequent calls to beyond the original value with subsequent calls.</p>
 +
<p><b>Note:</b>Should the rolled value need to change permanently to a new rolled value, the <i>change</i> value of 0 (zero) will reset the remembered original rolled value to the current value of the attribute - this is not needed the first time the command is used on a character sheet, which will trigger this value to be remembered for the first time.</p>
 
===Perform Short or Long Rests===
 
===Perform Short or Long Rests===
 
<pre>--rest [token_id]|[SHORT/LONG]|[MU/PR/MU-PR/POWER/MI/MI-POWER]|[timescale]</pre>
 
<pre>--rest [token_id]|[SHORT/LONG]|[MU/PR/MU-PR/POWER/MI/MI-POWER]|[timescale]</pre>
Line 214: Line 266:
 
<p>A Long rest is considered to be an overnight activity of at least 8 hours (though again this is not a restriction of the system and is up to the DM).  A Long rest allows spell casters to regain all their spells, all character and magic item powers to be regained to full uses per day, and for recharging magic items to regain their charges up to their current maximum.  After a long rest, ammunition that has been used but not recovered can no longer be recovered using the Ammunition Management command (see AttackMaster API documentation): it is assumed that other creatures will have found the ammo, or it has been broken or otherwise lost in the 8 hours of the long rest.</p>
 
<p>A Long rest is considered to be an overnight activity of at least 8 hours (though again this is not a restriction of the system and is up to the DM).  A Long rest allows spell casters to regain all their spells, all character and magic item powers to be regained to full uses per day, and for recharging magic items to regain their charges up to their current maximum.  After a long rest, ammunition that has been used but not recovered can no longer be recovered using the Ammunition Management command (see AttackMaster API documentation): it is assumed that other creatures will have found the ammo, or it has been broken or otherwise lost in the 8 hours of the long rest.</p>
 
<p>A Long rest can only be undertaken if certain conditions are met: either the optional Timescale (in days) must be specified as 1 or more days, or the Character Sheet must have a Roll20 attribute called Timescale, current, set to a value of 1 or more (can be set by <b>InitiativeMaster API --end-of-day</b> command).  An internal date system is incremented: an attribute on the Character Sheet called In-Game-Day is incremented by the Timescale, and Timescale is then set to 0.</p>
 
<p>A Long rest can only be undertaken if certain conditions are met: either the optional Timescale (in days) must be specified as 1 or more days, or the Character Sheet must have a Roll20 attribute called Timescale, current, set to a value of 1 or more (can be set by <b>InitiativeMaster API --end-of-day</b> command).  An internal date system is incremented: an attribute on the Character Sheet called In-Game-Day is incremented by the Timescale, and Timescale is then set to 0.</p>
<p>If the <b>InitMaster API</b> is being used, the system will interact with the “End of Day” command to allow rests to be coordinated with the choice of accommodation (and its cost…!).</p>
+
<p>If the <b>InitiativeMaster API</b> is being used, the system will interact with the "End of Day" command to allow rests to be coordinated with the choice of accommodation (and its cost...!) or with earnings made for the day's adventuring.</p>
 +
===Perform a Single Item Rest===
 +
<pre>--mi-rest [token_id]|mi_name|[charges]|[power_name]</pre>
 +
<p>Takes an optional Token ID (defaults to the selected token), a mandatory magic item name (case insensitive), an optional number of charges to recharge to, and an optional power name (case insensitive).</p>
 +
<p>This command restores the powers for a single magic item, or even a single power of a single magic item. If the optional number of charges is specified, this is the number of charges set for the power, otherwise the power is restored to its original max uses. If a power name is specified, and the item has a power of the same name, only that power will be affected. Otherwise, all powers of the item will be restored.</p>
 
<br>
 
<br>
 
==Treasure & Item container management==
 
==Treasure & Item container management==
Line 220: Line 276:
 
<pre>--gm-edit-mi [token_id]</pre>
 
<pre>--gm-edit-mi [token_id]</pre>
 
<p>Takes an optional token ID. If token ID is not specified, uses the selected token.</p>
 
<p>Takes an optional token ID. If token ID is not specified, uses the selected token.</p>
<p>This command opens a menu showing all the items in the Backpack of the character sheet associated with the specified token.  Unlike the Player version of the command (--edit-mi), this command shows all attributes of every magic item, including those of hidden and cursed items, and also offers an additional list of “DM Only” magic items from the magic item databases.</p>
+
<p>This command opens a menu showing all the items in the Items table of the character sheet associated with the specified token.  Unlike the Player version of the command (--edit-mi), this command shows all attributes of every magic item, including those of hidden and cursed items, and also offers an additional list of "DM Only" magic items from the magic item databases.</p>
 
<p>The following functions are available once both a magic item is selected from the lists, and a slot to store it in are selected:</p>
 
<p>The following functions are available once both a magic item is selected from the lists, and a slot to store it in are selected:</p>
 
<table>
 
<table>
 
<tr><th scope="row">Store item:</th><td>Select a magic item from the databases and store it in a slot - this is the same as the Player version.</td></tr>
 
<tr><th scope="row">Store item:</th><td>Select a magic item from the databases and store it in a slot - this is the same as the Player version.</td></tr>
<tr><th scope="row">Hide item as different item:</th><td>The magic item already in the selected bag slot is given the displayed name of the magic item selected from the databases - the Player will only see the Magic Item selected (Displayed Name), and not the hidden actual name.  The MI will behave exactly like the selected, displayed item until the DM reverts the item to the hidden version using the [Reset Single MI] button.  This is generally used for Cursed items in containers, so that the real nature of the item is hidden until the character discovers the curse.</td></tr>
+
<tr><th scope="row">Hide item as different item:</th><td>The magic item already in the selected bag slot is given the displayed name of the magic item selected from the databases - the Player will only see the Magic Item selected (Displayed Name), and not the hidden actual name.  The MI will behave exactly like the selected, displayed item until the DM reverts the item to the hidden version using the [Reset Single MI] button.  This is generally used for items in containers, especially Cursed items, so that the real nature of the item is hidden until the character uses it or the DM wants them to. Once an item has been marked as hidden, the DM can see the name it will be displayed to the palyer as by selecting that slot - the displayed name will appear on the menu, and other options for hidden items will become selectable.</td></tr>
 +
<tr><th scope="row">Rename MI:</th><td>Allows the DM to change the actual and displayed name of an item. This will create a unique item (existing item names cannot be used) stored on the character's/container's Character Sheet which will work in exactly the same way as the original item. This can be used to resolve duplicate magic items, such as two rings of spell storing can be given different names.  This is different from hiding - the actual name of the item is changed.</td></tr>
 
<tr><th scope="row">Remove MI:</th><td>Blanks the selected Bag slot, removing all details, both displayed & actual.</td></tr>
 
<tr><th scope="row">Remove MI:</th><td>Blanks the selected Bag slot, removing all details, both displayed & actual.</td></tr>
<tr><th scope="row">Change MI Type:</th><td>This allows the type of the item in the selected Bag slot to be changed.  It can be one of the following - Charged, Uncharged, Recharging, Rechargeable, Self-chargeable, Cursed, Cursed-Charged, Cursed-Self-chargeable, Cursed-Recharging (cursed rechargeable items behave in exactly the same way as Cursed-Charged items).  Cursed versions of items cannot be removed from the character's MI Bag, given away, stored or deleted by the Player, even when all their charges are depleted.  Otherwise, they act in the same way as other magic items.</td></tr>
+
<tr><th scope="row">Change MI Type:</th><td>This allows the type of the item in the selected Bag slot to be changed.  It can be one of the following - Charged, Discharging, Uncharged, Recharging, Rechargeable, Self-charging, Absorbing, Cursed, Cursed-Charged, Cursed-Self-charging, Cursed-Recharging, Cursed-Absorbing (cursed rechargeable items behave in exactly the same way as Cursed-Charged items).  Cursed versions of items cannot be removed from the character's MI Bag, given away, stored or deleted by the Player, even when all their charges are depleted.  Otherwise, they act in the same way as other magic items. Charged, Discharging, and Rechargeable items disappear if they reach zero charges, unless preceeded by 'perm-'. Charged, Uncharged and Cursed items can be divided when picked up by Searching or Storing, other types cannot.</td></tr>
<tr><th scope="row">Change Displayed Charges:</th><td>Changes the number of displayed/current charges for the item in the selected Bag slot.  This can be used to set the quantity of Uncharged items, or the current charges of other types.  It also allows charged items in containers to be stored as a single item, for instance single Wands with multiple charges - see the   pickorput command below.</td></tr>
+
<tr><th scope="row">Change Displayed Charges:</th><td>Changes the number of displayed/current charges for the item in the selected Bag slot.  This can be used to set the quantity of Uncharged items, or the current charges of other types.  It also allows charged items in containers to be stored as a single item, for instance single Wands (current/displayed qty = 1) with multiple charges (max qty = n): when picked up the current qty is always set to the actual value - see the <b>--pickorput</b> command below.</td></tr>
 
<tr><th scope="row">Change Actual Charges:</th><td>Setting this allows the actual quantity of Uncharged items in containers to be hidden, or the maximum number of charges to be set for other types.  When the item is picked up from a container, the actual number of charges will be set as the current value.</td></tr>
 
<tr><th scope="row">Change Actual Charges:</th><td>Setting this allows the actual quantity of Uncharged items in containers to be hidden, or the maximum number of charges to be set for other types.  When the item is picked up from a container, the actual number of charges will be set as the current value.</td></tr>
<tr><th scope="row">Store Spells/Powers in MI</th><td>Only enabled for items that can store & cast spells or powers: the item definition must have a call to <code>!magic --cast-spell MI</code> for spell storing, or <code>!magic --cast-spell MI-POWER</code> for powers, associated with an API button.  If this is the case, this option opens a menu to select Wizard or Priest spells, or powers as appropriate.</td></tr>
+
<tr><th scope="row">Store Spells/Powers in MI</th><td>Only enabled for items that can store & cast spells or powers: the item definition must have a call to <code>!magic --cast-spell MI</code> for spell storing, or <code>!magic --cast-spell MI-POWER</code> for powers, associated with an API button.  If this is the case, this option opens a menu to select Wizard or Priest spells, or powers as appropriate. A blank Ring-of-Spell-Storing and a blank Scroll-of-Spells are both included in the databases, allowing GMs to build their own unique items and then give them a unique new name using the Rename function described above.</td></tr>
 
<tr><th scope="row">Change Item Cost:</th><td>Items can have a cost in GP (fractions allowed which get converted to SP & CP).  When an item is picked up from a container, the cost will be multiplied by the quantity picked up and the Player will be asked if they want the character to pay the cost.  If confirmed, the cost will be deducted from the money values on the character sheet.  0 and negative values are allowed.  This supports merchants and shops to be created in the campaign.</td></tr>
 
<tr><th scope="row">Change Item Cost:</th><td>Items can have a cost in GP (fractions allowed which get converted to SP & CP).  When an item is picked up from a container, the cost will be multiplied by the quantity picked up and the Player will be asked if they want the character to pay the cost.  If confirmed, the cost will be deducted from the money values on the character sheet.  0 and negative values are allowed.  This supports merchants and shops to be created in the campaign.</td></tr>
<tr><th scope="row">Reset Single MI:</th><td>Allows the DM to reset the item in the selected Bag slot to the actual values, revealing any hidden name, and resetting the displayed quantity to be the actual quantity.  From that point on, the item will behave as the revealed item.  This is mostly used to reveal cursed items.</td></tr>
+
<tr><th scope="row">Reset Qty to Max:</th><td>Allows the DM to reset the quantity of the selected Bag slot to the actual (max) values.</td></tr>
 +
<tr><th scope="row">Reveal Now:</th><td>Only available when a hidden item is selected. Reveals the item, setting the displayed name to the actual name, which will function as the revealed item from that point on.</td></tr>
 +
  <tr><th scope="row">Reveal MI</th><td>Allows selection of when a hidden item is revealed: MANUALLY by DM (the default) using the Reveal Now button; on VIEWING the item; or on USING the item. From the point the item is revealed onwards, the item will behave as the revealed item.</td></tr>
 
<tr><th scope="row">Edit Treasure:</th><td>Mainly for use on Magic Item containers, such as Treasure Chests, but also useful for NPCs and Monsters.  Allows the DM to add text only treasure descriptions to the container.  The displayed menu allows [Add], [Edit], and [Delete] functions to manage multiple lines/rows of treasure description.</td></tr>
 
<tr><th scope="row">Edit Treasure:</th><td>Mainly for use on Magic Item containers, such as Treasure Chests, but also useful for NPCs and Monsters.  Allows the DM to add text only treasure descriptions to the container.  The displayed menu allows [Add], [Edit], and [Delete] functions to manage multiple lines/rows of treasure description.</td></tr>
<tr><th scope="row">Container Type:</th><td>Sets the type of the Magic Item container or Bag.  Available choices are: Empty Inanimate object, Inanimate object with stuff, Sentient Being with empty Bag, Sentient Being with items, Trapped container. If searched,  Inanimate objects can be looted without penalty;  Sentient beings require a Pick Pockets check; Trapped containers call a Trap ability macro on the container's character sheet to determine the effect.  See -search command below.</td></tr>
+
<tr><th scope="row">Container Type:</th><td>Sets the type of the Magic Item container or Bag.  Available choices are: Empty Inanimate object, Inanimate object with stuff, Sentient Being with empty Bag, Sentient Being with items, Trapped container. If searched,  Inanimate objects can be looted without penalty;  Sentient beings require a Pick Pockets check; Trapped containers call a Trap ability macro on the container's character sheet to determine the effect.  See the <b>--search</b> command below.</td></tr>
 
<tr><th scope="row">Container Size:</th><td>Sets the maximum number of items that can be stored in the selected Character's/containers bag.  The default is 18 items, though identical items can be stacked.</td></tr>
 
<tr><th scope="row">Container Size:</th><td>Sets the maximum number of items that can be stored in the selected Character's/containers bag.  The default is 18 items, though identical items can be stacked.</td></tr>
 +
<tr><th scope="row">Show As:</th><td>Sets what level of item description a Player sees when looting a container. Either "Show as Item Types" (e.g. potion, scroll, melee weapon, etc), or "Show as Item Names" (default) which shows the display names of the items. Once picked up from the container, will always show their display names.</td></tr>
 
</table>
 
</table>
 
===Search tokens for Magic Items and Treasure===
 
===Search tokens for Magic Items and Treasure===
 
<pre>--search token_id|pick_id|put_id</pre>
 
<pre>--search token_id|pick_id|put_id</pre>
<p>Takes a mandatory token ID, mandatory token ID of the token to search and pick up items from, mandatory token ID of the token to put picked up items in.</p>
+
<p>Takes a mandatory token ID of the character's token, mandatory token ID of the token to search and pick up items from, mandatory token ID of the token to put picked up items in.</p>
<p>This command can be used to pick the pockets of an NPC or even another Player Character, as well as to loot magic item and treasure containers such as Chests and dead bodies.  It can also be used for putting stuff away, storing items from the character's Magic Item Bag into a container, for instance if the MI Bag is getting too full (it is limited to the number of items specified via the --gm-edit-mi menu, though similar items can be stacked). The effect of this command when looting (i.e. the Character's token_id is also the put_id) depends on the Container Type of the searched token set by the DM using the -gm-edit-mi command menu:</p>
+
<p>This command can be used to pick the pockets of an NPC or even another Player Character, as well as to loot magic item and treasure containers such as Chests and dead bodies.  It can also be used for putting stuff away, storing items from the character's Magic Item Bag into a container, for instance if the MI Bag is getting too full (it is limited to the number of items specified via the --gm-edit-mi menu, though similar items can be stacked). The effect of this command when looting (i.e. the Character's token_id is also the put_id) depends on the Container Type of the searched token set by the DM using the --gm-edit-mi command menu:</p>
 
<table>
 
<table>
 
<tr><th scope="row">Inanimate without items:</th><td>a message is shown to the Player saying the container is empty or, if there are no Magic Items but there is text describing contained treasure, this will be displayed.</td></tr>
 
<tr><th scope="row">Inanimate without items:</th><td>a message is shown to the Player saying the container is empty or, if there are no Magic Items but there is text describing contained treasure, this will be displayed.</td></tr>
Line 245: Line 305:
 
<tr><th scope="row">Sentient being without items:</th><td>a Pick Pockets check is undertaken - the Player is asked to roll a dice and enter the result (or Roll20 can do it for them), which is compared to the Pick Pockets score on their character sheet.  If successful, a message is displayed in the same way as an Inanimate object.  If unsuccessful, a further check is made against the level of the being targeted to see if they notice, and the DM is informed either way.  The DM can then take whatever action they believe is needed.</td></tr>
 
<tr><th scope="row">Sentient being without items:</th><td>a Pick Pockets check is undertaken - the Player is asked to roll a dice and enter the result (or Roll20 can do it for them), which is compared to the Pick Pockets score on their character sheet.  If successful, a message is displayed in the same way as an Inanimate object.  If unsuccessful, a further check is made against the level of the being targeted to see if they notice, and the DM is informed either way.  The DM can then take whatever action they believe is needed.</td></tr>
 
<tr><th scope="row">Sentient being with items:</th><td>the Pick Pockets check is done the same way as above, but if successful, the items in the target's Magic Item Bag are displayed and the Player can pick them up and store them in their character's Magic Item Bag.</td></tr>
 
<tr><th scope="row">Sentient being with items:</th><td>the Pick Pockets check is done the same way as above, but if successful, the items in the target's Magic Item Bag are displayed and the Player can pick them up and store them in their character's Magic Item Bag.</td></tr>
<tr><th scope="row">Trapped container:</th><td>Traps can be as simple or as complex as the DM desires.  Traps may be nothing more than a lock that requires a Player to say they have a specific key, or a combination that has to be chosen from a list, and nothing happens if it is wrong other than the items in the container not being displayed.  Or setting it off can have damaging consequences for the character searching or the whole party.  It can just be a /whisper gm message to let the DM know that the trapped container has been searched.  Searching a trapped container with this command calls an ability macro called “Trap-@{container_name|version}on the container's character sheet: if this does not exist, it calls an ability macro just called “Trap”.  The first version allows the Trap macro to change the behaviour on subsequent calls to the Trap functionality (if using the ChatSetAttr API to change the version attribute), for instance to allow the chest to open normally once the trap has been defused or expended.  This functionality requires confidence in Roll20 macro programming.<br><b>Important Note:</b> all Character Sheets representing Trapped containers <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>.  Otherwise, Players will not be able to run the macros contained in them that operate the trap!</td></tr>
+
<tr><th scope="row">Trapped container:</th><td>Traps can be as simple or as complex as the DM desires.  Traps may be nothing more than a lock that requires a Player to say they have a specific key, or a combination that has to be chosen from a list, and nothing happens if it is wrong other than the items in the container not being displayed.  Or setting it off can have damaging consequences for the character searching or the whole party.  It can just be a /whisper gm message to let the DM know that the trapped container has been searched.  Searching a trapped container with this command calls an ability macro called "Trap-@{container_name|version}" on the container's character sheet: if this does not exist, it calls an ability macro just called "Trap".  The first version allows the Trap macro to change the behaviour on subsequent calls to the Trap functionality (if using the ChatSetAttr API to change the version attribute), for instance to allow the chest to open normally once the trap has been defused or expended.  This functionality requires confidence in Roll20 macro programming.<br><b>Important Note:</b> all Character Sheets representing Trapped containers <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>.  Otherwise, Players will not be able to run the macros contained in them that operate the trap!</td></tr>
 
</table>
 
</table>
 
===Looting without searching, and storing items in a container===
 
===Looting without searching, and storing items in a container===
 
<pre>--pickorput token_id|pick_id|put_id|[SHORT/LONG]</pre>
 
<pre>--pickorput token_id|pick_id|put_id|[SHORT/LONG]</pre>
 
<p>Takes a mandatory token ID for the Player's character, a mandatory token ID for the token to pick items from, a mandatory token ID for the token to put items in to, and an optional argument specifying whether to use a long or a short menu.</p>
 
<p>Takes a mandatory token ID for the Player's character, a mandatory token ID for the token to pick items from, a mandatory token ID for the token to put items in to, and an optional argument specifying whether to use a long or a short menu.</p>
<p>This command displays a menu from which items in the Backpack Bag on the character sheet associated with the Pick token can be selected to put in the Bag of the character sheet associated with the Put token.  The Player's character's token can be either the Put token (if picking up items from a container) or the Pick token (if storing items from their Bag into the container).  The other token can be another Player Character (useful for one character giving a magic item to another character) or any other selectable token with a character sheet.  No traps or sentient being checks are made by this command - this allows the DM to allow Players to bypass the searching functionality when looting a container or storing items in it.  Note: the Player's Magic Item menu (accessed via the -mimenu command) does not have an option to loot without searching, but the Store function on that menu does not use Search.</p>
+
<p>This command displays a menu from which items on the character sheet associated with the Pick token can be selected to put in the character sheet associated with the Put token.  The Player's character's token can be either the Put token (if picking up items from a container) or the Pick token (if storing items from their sheet into the container).  The other token can be another Player Character (useful for one character giving a magic item to another character) or any other selectable token with a character sheet.  No traps or sentient being checks are made by this command - this allows the DM to allow Players to bypass the searching functionality when looting a container or storing items in it.  Note: the Player's Magic Item menu (accessed via the <b>--mimenu</b> command) does not have an option to loot without searching, but the Store function on that menu does use this command.</p>
<p>There are two forms of this menu - the Long form displays all items in the container as individual buttons for the Player to select from, and a single button to store the item: this is generally OK when looting containers with not much in them.  The Short form of the menu shows only two buttons: one button which, when clicked, brings up a pick list of all the items in the Pick container, and another button to store the item in the Put container: this is generally best for when a character is storing something from their MI Bag into a chest or other container, or giving an MI to another character, as a character's MI Bag often has many items in it which can make a Long menu very long.  Each type of menu has a button on it to switch to the other type of menu without re-issuing the command.  If not specified in the command, the type of menu the Player last used in this campaign is remembered and used by the system.</p>
+
<p>There are two forms of this menu - the Long form displays all items in the container as individual buttons for the Player to select from, and a single button to store the item: this is generally OK when looting containers with not much in them.  The Short form of the menu shows only two buttons: one button which, when clicked, brings up a pick list of all the items in the Pick container, and another button to store the item in the Put container: this is generally best for when a character is storing something from their character sheet items into a chest or other container, or giving an MI to another character, as a character's sheet often has many items in it which can make a Long menu very long.  Each type of menu has a button on it to switch to the other type of menu without re-issuing the command.  If not specified in the command, the type of menu the Player last used in this campaign is remembered and used by the system.</p>
 
<br>
 
<br>
 
==Light source management==
 
==Light source management==
<p>These functions use Roll20 Dynamic Lighting to provide a token with a light source.  If your campaign does not use Dynamic Lighting, they will not function.  They can also be accessed through the menu displayed by the AttackMaster API -other-menu command.</p>
+
<p>These functions use Roll20 Dynamic Lighting to provide a token with a light source.  If your campaign does not use Dynamic Lighting, they will not function.  They can also be accessed through the menu displayed by the AttackMaster API <b>!attk --other-menu</b> command.</p>
===Show a menu of Light Sources to select from===
+
===how a menu of Light Sources to select from===
 
<pre>--lightsources [token_id]</pre>
 
<pre>--lightsources [token_id]</pre>
 
<p>Takes an optional token ID as an argument. If token ID is not specified, uses the selected token.</p>
 
<p>Takes an optional token ID as an argument. If token ID is not specified, uses the selected token.</p>
Line 269: Line 329:
 
<p>The menu shows [ON] and [OFF] buttons for each type.  Only one type can be ON for each Token: selecting an ON button for any light source turns OFF the others for that Token.  Turning the current light source off will turn off all lighting effects on the identified token.</p>
 
<p>The menu shows [ON] and [OFF] buttons for each type.  Only one type can be ON for each Token: selecting an ON button for any light source turns OFF the others for that Token.  Turning the current light source off will turn off all lighting effects on the identified token.</p>
 
===Set a lightsource for a token===
 
===Set a lightsource for a token===
<pre>--changelight token_id|(NONE/WEAPON/TORCH/HOODED/CONTLIGHT/BULLSEYE/BEACON)</pre>
+
<pre>--light token_id|(NONE/WEAPON/TORCH/HOODED/CONTLIGHT/BULLSEYE/BEACON)</pre>
 
<p>Takes a mandatory token ID, and a mandatory type of light source.</p>
 
<p>Takes a mandatory token ID, and a mandatory type of light source.</p>
<p>This command sets the light source type that the identified token is using, and changes the Roll20 Dynamic Lighting settings of the token to the relevant value shown under the previous section, or turn off all lighting effects for the selected token if NONE is specified.</p>
+
<p>This command sets the light source type that the identified token is using, and changes the Roll20 Dynamic Lighting settings of the token to the relevant value shown under section 5.1, or turn off all lighting effects for the selected token if NONE is specified.</p>
 
<br>
 
<br>
 
==Other commands==
 
==Other commands==
Line 277: Line 337:
 
<pre>--help</pre>
 
<pre>--help</pre>
 
<p>This command does not take any arguments.  It displays the mandatory and optional arguments, and a brief description of each command.</p>
 
<p>This command does not take any arguments.  It displays the mandatory and optional arguments, and a brief description of each command.</p>
 +
===Display a formatted message in chat===
 +
<pre>--message [who|][token_id]|title|message</pre>
 +
<p>This command takes an optional parameter stating who to send the message to, which defaults to depending on who owns the character represented by the token, an optional token_id which defaults to a selected token, a title for the message which can be an empty string, and the message to display.</p>
 +
<p>The "who" parameter can be one of:</p>
 +
<table>
 +
<tr><th scope="row">gm</th><td>Send only to the GM</td></tr>
 +
<tr><th scope="row">whisper</th><td>Send only to the players that control the character represented by the token</td></tr>
 +
<tr><th scope="row">w</th><td>Short for "whisper" and does the same</td></tr>
 +
<tr><th scope="row">public</th><td>Send to all players and the GM</td></tr>
 +
<tr><th scope="row">standard</th><td>Check which players/GMs control the character represented by the token. If the GM controls, or no-one, or the controlling player is not on-line, or the token does not represent a character, send to the GM; otherise make public.</td></tr>
 +
<tr><th scope="row">Anything else</th><td>Same as Standard</td></tr>
 +
</table>
 +
===Tidy one or more character sheets===
 +
<pre>--tidy [token_id]</pre>
 +
<p>This command takes an optional token_id. If not specified, the command will act on the character sheets represented by all currently selected tokens.</p>
 +
<p>This command tidies up the character sheet, removing Spell and Magic Item attribute and ability objects that are no longer for items held, and for spells no longer in any spell book.  Attack ability objects will also all be removed.  All of these will be recreated as and when these items, spells or attacks are again picked up, added to spell books, or used for attacks. This simplifies and speeds up the system, removing redundant processing and memory usage.</p>
 +
<p><b>Note:</b> this command is automatically run whenever the DM moves the "Player Ribbon" to a new map page, for every token on that map page that represents a character sheet, and also whenever a character token is dragged onto the active Player page. This continually tidies the system while not imposing a heavy overhead on processing.</p>
 
===Configure API behavior===
 
===Configure API behavior===
<pre>--config [PROF/ALL-WEAPS/WEAP-CLASS/ALL-ARMOUR/MASTER-RANGE/SPECIALIST-RULES/SPELL-NUM] | [TRUE/FALSE]</pre>
+
<pre>--config [FANCY-MENUS/SPECIALIST-RULES/SPELL-NUM/ALL-SPELLS] | [TRUE/FALSE]</pre>
 
<p>Takes two optional arguments, the first a switchable flag name, and the second TRUE or FALSE.</p>
 
<p>Takes two optional arguments, the first a switchable flag name, and the second TRUE or FALSE.</p>
 
<p>Allows configuration of several API behaviors.  If no arguments given, displays menu for DM to select configuration.  Parameters have the following effects:</p>
 
<p>Allows configuration of several API behaviors.  If no arguments given, displays menu for DM to select configuration.  Parameters have the following effects:</p>
{| class="wikitable"
+
<table>
|+
+
<thead><tr><th>Flag</th><th>True</th><th>False</th></tr></thead>
|-
+
<tr><th scope="row">FANCY-MENUS</th><td>Use chat menus with a textured background</td><td>Use chat menus with a plain background</td></tr>
! Flag !! True !! False
+
<tr><th scope="row">SPECIALIST-RULES</th><td>Only Specialist Wizards specified in the PHB get an extra spell per spell level</td><td>Any non-Standard Wizard gets an extra spell per spell level</td></tr>
|-
+
<tr><th scope="row">SPELL-NUM</th><td>Spellcaster spells per level restricted to PHB rules</td><td>Spellcaster spells per level alterable using Misc Spells button</td></tr>
! scope="row" | PROF
+
<tr><th scope="row">ALL-SPELLS</th><td>Spellcaster spell schools are unrestricted</td><td>Spellcaster spell schools are restricted by class rules</td></tr>
|| Strictly apply non-proficient weapon penalties as per PHB || Use the non-proficient weapon penalty displayed on the Character Sheet
+
</table>
|-
+
! scope="row" | ALL-WEAPS
+
|| Allow any character of any class to use and become proficient in any weapon. || Restrict the use of weapons by class to some degree set by WEAP-CLASS
+
|-
+
! scope="row" | WEAP-CLASS
+
|| Weapons not allowed to a class get a penalty of -100 || Weapons not allowed to a class get double non-proficient penalty
+
|-
+
! scope="row" | ALL-ARMOUR
+
|| All armour types allowed for all classes || Armour not allowed to a class not included in AC calculations
+
|-
+
! scope="row" | MASTER-RANGE
+
|| Ranged weapon Mastery gives double damage at Point Blank range || Ranged weapon Mastery not allowed, as per PHB
+
|-
+
! scope="row" | SPECIALIST-RULES
+
|| Only Specialist Wizards specified in the PHB get an extra spell per spell level || Any non-Standard Wizard gets an extra spell per spell level
+
|-
+
! scope="row" | SPELL-NUM
+
|| Spellcaster spells per level restricted to PHB rules || Spellcaster spells per level alterable using Misc Spells button
+
|}
+
 
===Check database completeness & integrity (GM only)===
 
===Check database completeness & integrity (GM only)===
 
<pre>--check-db [ db-name ]</pre>
 
<pre>--check-db [ db-name ]</pre>
 
<p>Takes an optional database name or part of a database name: if a partial name, checks all character sheets with the provided text in their name that also have '-db' as part of their name.  If omitted, checks all character sheets with '-db' in the name.  Not case sensitive.  Can only be used by the GM.</p>
 
<p>Takes an optional database name or part of a database name: if a partial name, checks all character sheets with the provided text in their name that also have '-db' as part of their name.  If omitted, checks all character sheets with '-db' in the name.  Not case sensitive.  Can only be used by the GM.</p>
 
<p>This command finds all databases that match the name or partial name provided (not case sensitive), and checks them for completeness and integrity.  The command does not alter any ability macros, but ensures that the casting time ('ct-') attributes are correctly created, that the item lists are sorted and complete, and that any item-specific power & spell specifications are correctly built and saved.</p>
 
<p>This command finds all databases that match the name or partial name provided (not case sensitive), and checks them for completeness and integrity.  The command does not alter any ability macros, but ensures that the casting time ('ct-') attributes are correctly created, that the item lists are sorted and complete, and that any item-specific power & spell specifications are correctly built and saved.</p>
<p>This command is very useful to run after creating/adding new items as ability macros to the databases (see section 11 below).  It does not check if the ability macro definition itself is valid, but if it is then it ensures all other aspects of the database consistently reflect the new ability(s).</p>
+
<p>This command is very useful to run after creating/adding new items as ability macros to the databases (see specific database documentation).  It does not check if the ability macro definition itself is valid, but if it is then it ensures all other aspects of the database consistently reflect the new ability(s).</p>
 +
===Extract database for Editing===
 +
<pre>--extract-db [db-name]</pre>
 +
<p>Takes an optional database name or part of a database name: if a partial name, extracts all character sheets with the provided text in their name that also have '-db' as part of their name.  If omitted, checks all character sheets with '-db' in the name.  Not case sensitive.  Can only be used by the GM.</p>
 +
<p>Extracts a named database or all provided databases from the loaded RPGMaster Library, and builds the database(s) in a Character Sheet format: see the Database specific help handouts for further details of this format.  This allows editing of the standard items in the databases, adding additional items to the databases, or for items to be copied into the GM's own databases.  Unlike with previous versions of the Master Series APIs, these extracted databases will not be overwritten automatically by the system. <b>However:</b> using extracted databases will slow the system down - the use of the internal API databases held in memory is much faster. The best use for these extracts is to examine how various items have been programmed so that the GM can create variations of the standard items in their own databases by copying and making small alterations to the definitions, and then the extracted databases can be deleted.</p>
 +
<p><b>Important:</b> Once a Character Sheet database is changed or deleted, run the <b>!magic --check-db</b> command against any database (especially a changed one) to prompt the APIs to re-index the objects in all databases.</p>
 +
===Handshake with other APIs===
 +
<pre>-hsq from|[command]<br>
 +
-handshake from|[command]</pre>
 +
<p>Either form performs a handshake with another API, whose call (without the '!') is specified as <i>from</i> in the command parameters (the response is always an <b>-hsr</b> command).  The command calls the <i>from</i> API command responding with its own command to confirm that this API is loaded and running: e.g. </p>
 +
<dl><dt>Received:</dt><dd><i>!magic -hsq init</i></dd>
 +
<dt>Response:</dt><dd><i>!init -hsr magic</i></dd></dl>
 +
<p>Optionally, a command query can be made to see if the command is supported by MagicMaster if the <i>command</i> string parameter is added, where <i>command</i> is the MagicMaster command (the '--' text without the '--').  This will respond with a <i>true/false</i> response: e.g.</p>
 +
<dl><dt>Received:</dt><dd><i>!magic -handshake init|menu</i></dd>
 +
<dt>Response:</dt><dd><i>!init -hsr magic|menu|true</i></dd></dl>
 
===Switch on or off Debug mode===
 
===Switch on or off Debug mode===
 
<pre>--debug (ON/OFF)</pre>
 
<pre>--debug (ON/OFF)</pre>
 
<p>Takes one mandatory argument which should be ON or OFF.</p>
 
<p>Takes one mandatory argument which should be ON or OFF.</p>
 
<p>The command turns on a verbose diagnostic mode for the API which will trace what commands are being processed, including internal commands, what attributes are being set and changed, and more detail about any errors that are occurring.  The command can be used by the DM or any Player - so the DM or a technical advisor can play as a Player and see the debugging messages.</p>
 
<p>The command turns on a verbose diagnostic mode for the API which will trace what commands are being processed, including internal commands, what attributes are being set and changed, and more detail about any errors that are occurring.  The command can be used by the DM or any Player - so the DM or a technical advisor can play as a Player and see the debugging messages.</p>
===Forcing a database reset to the API version===
 
<p>A database can be rebuilt as the version that came with the current version of the API if you have accidentally altered one of the Ability macros or an attribute and caused functions not to work as expected.  The easiest way to achieve this is to find the offending database Character Sheet and delete it, then exist the campaign and re-enter.  If and only if the database Character Sheet is one of the following, it will be automatically re-written as the version distributed with the API:</p>
 
<p><i>MI-DB, MI-DB-Weapons, MI-DB-Ammo, MI-DB-Armour, MI-DB-Potions, MI-DB-Scrolls-Books, MI-DB-Wands-Staves-Rods, MI-DB-Rings, MI-DB-Light, MU-Spells-DB, PR-Spells-DB, Powers-DB.</i></p>
 
<br>
 
==Using Character Sheet Ability/Action buttons==
 
<p>The most common approach for the Player to run these commands is to use Ability macros on their Character Sheets which are flagged to appear as Token Action Buttons: Ability macros & Token Action Buttons are standard Roll20 functionality, refer to the Roll20 Help Centre for information on creating and using these.</p>
 
<p>In fact, the simplest configuration is to provide only Token Action Buttons for the menu commands: --spellmenu and  mimenu.  From these, most other commands can be accessed.</p>
 
<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 attacks 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 attacks 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.<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 AttackMaster API, as with all the other RPGMaster series APIs, use Roll20 Roll Templates extensively.  This 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.  AttackMaster 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 attack systems and calculations.  If you use another system, future developments might support additional approaches.  Contact the author for information and to pass on ideas (see the link in the sidebar at the top).<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>
 
In order to change the field that the API uses on the character sheet for a different one, you can change the ''sheet_field_name'' and/or ''field_attribute'' for the one you want to use.  <u>'''However, the ''Internal_api_name'' and the other values should not be changed'''</u> as otherwise the system will not work.<br>
 
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_table'' 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, spells 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, spells in the repeating_spells 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 AttackMaster 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.  They '''do not''' also need an entry under a spellcaster column.<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 !! Psion Classes
 
|-
 
| Warrior || Wizard || Priest || Rogue || Psion
 
|-
 
| 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 relevant 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 caster.  Just 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 relevant spells  menus.  Do 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 AttackMaster 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 commands ''--edit-weapons'' (to load from the database) and ''--weapon'' (to take weapons ''in-hand''), 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 actions to be selected.<br>
 
<br>
 
==Character Sheet data fields==
 
<p>The Character Sheet field mapping to the API script can be altered using the definition of the fields object, the definition for which can be found at the top of 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>
 
<br>
 
 
=MagicMaster Databases=
 
==General Database information==
 
<p>The MagicMaster API uses a number of Character Sheets as databases to hold Ability Macros defining spells, powers and magic items and their effects.  The API is distributed with many spell, power & magic item definitions, and checks for, creates and updates these Character Sheet databases on start-up.  DMs can add their own weapons, ammo and armour to additional databases, but the databases provided are totally rewritten when new updates are released so the DM must add their own database sheets.  If the provided databases are accidentally deleted, they will be automatically recreated the next time the Campaign is opened. Additional databases should be named as follows:</p>
 
<table>
 
<tr><th scope="row">Wizard Spells:</th><td>additional databases: MU-Spells-DB-<i>[added name]</i> where <i>[added name]</i> can be replaced with anything you want.</td></tr>
 
<tr><th scope="row">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>
 
<tr><th scope="row">Powers:</th><td>additional databases: Powers-DB-<i>[added name]</i> where <i>[added name]</i> can be replaced with anything you want.</td></tr>
 
<tr><th scope="row">Magic Items:</th><td>additional databases: MI-DB-<i>[added name]</i> where <i>[added name]</i> can be replaced with anything you want.</td></tr>
 
</table>
 
<p><b>However:</b> the system will ignore any database with a name that includes a version number of the form “v#.#” where # can be any number or group of numbers e.g. MI-DB v2.13 will be ignored.  This is so that the DM can version control their databases, with only the current one (without a version number) being live.</p>
 
<p>There can be as many additional databases as you want. Other Master series APIs come with additional databases, some of which overlap - this does not cause a problem as version control and merging unique macros is managed by the APIs.</p>
 
<p><b>Important Note:</b> all Character Sheet databases <b><u><i>must</i></u></b> have their <i>'ControlledBy'</i> value (found under the [Edit] button at the top right of each sheet) set to <i>'All Players'</i>.  This must be for all databases, both those provided (set by the API) and any user-defined ones.  Otherwise, Players will not be able to run the macros contained in them.</p>
 
<p>Each database has a similar structure, with:</p>
 
<ul>
 
<li>Ability Macros named as the spell, power or magic item specified, and used to describe and provide effects for spells, powers and magic items using the commands in the Magic Master API;</li>
 
<li>Custom Attributes with the attribute name “ct-ability-macro-name”, one per Ability Macro, which defines the casting time and casting cost for spells & powers, and speed and MI type for magic items;</li>
 
<li>An entry in a list on the character sheet in the spell book of the relevant Character Sheet tab (Spell Level of the spell defined, Powers tab, or various spell books for different Magic Items - see MI entry below).</li>
 
</ul>
 
<p>Ability Macros can be whatever the DM wants and can be as simple or as complex as desired. Roll Templates are very useful when defining spell, power and magic item ability macros.  When a Player or an NPC or Monster views or casts a spell, power or uses a magic item the Magic Master API runs the relevant Ability Macro from the databases as if it had been run by the Player from the chat window.  All Roll20 functions for macros are available.</p>
 
===Replacing Spells & Items===
 
<p>If you want to replace any spell or item provided in any of the databases, you can do so simply by creating an Ability Macro in one of your own databases with exactly the same name as the provided item to be replaced.  The API gives preference to Ability Macros in user-defined databases, so yours will be selected in preference to the one provided with the APIs.</p>
 
<br>
 
==Spells and Powers Databases==
 
<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, each spell or power definition has 3 parts in the database (see Section 11.1): an Ability Macro with a name that is unique and matches the spell or power, an Attribute with the name of the Ability Macro preceded by “ct-“, and a listing in the database character sheet of the ability macro name separated by '|' along with others of the same level in the spell book of the level of the spell or power.  The quickest way to understand these entries is to examine existing entries.  Do 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>--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>
 
===Sleep===
 
<p style="display: inline-block; background-color: lightgrey; border: 1px solid black; padding: 4px; color: black;">/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; background-color=white">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; background-color=white">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, or none and just plain text.  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.</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:0.01,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">st:</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>
 
===Turn Undead===
 
<p style="display: inline-block; background-color: lightgrey; border: 1px solid black; padding: 4px; color: black">/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=[Turn It](</nowiki><span style="color:red">!rounds --target area|@{selected|token_id}|&#64;{target|Select undead|token_id}|Turned|99|0|Turned undead, flee if free-willed, stand aside if controlled|screaming</span><nowiki>)}}</nowiki><span style="color:blue">SpellData=[w:Turn Undead, sp:10, cs:VS]</span><nowiki>{{</nowiki>effects=<b>Remember that Paladins turn as a Priest of 2 levels lower.</b><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.<nowiki>}}{{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>
 
==Magic Item Databases==
 
<p>Magic Item databases are all character sheets that have names such as</p>
 
<p> <b>Magic Items:</b> MI-DB-[added name]</p>
 
<p>And can have anything put at the end, though those with version numbers of the form v#.# as part of the name will be ignored.</p>
 
<p>As previously stated and as for other magic, each magic item definition has 3 parts in the database (see Section 11.1): an Ability Macro with a name that is unique and identifies the magic item, an Attribute with the name of the Ability Macro preceded by “ct-“, and a listing in the database character sheet of the ability macro name separated by '|' along with others of the same magic item type, which is one of: Potion, Scroll, Rod/Stave/Wand, Weapon, Armour, Ring, Miscellaneous, and also DM Only magic items.  The quickest way to understand these entries is to examine existing entries.  Do go to the root database 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>--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> may look something like this:</p>
 
===Oil-of-Etherealness===
 
<p style="display: inline-block; background-color: lightgrey; border: 1px solid black; padding: 4px; color: black">/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>)}}{{</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>
 
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.<nowiki>}}{{materials=Oil}}</nowiki></p>
 
<p>You might notice that the structure of this macro is extremely similar to that of a spell: indeed, it uses the same Roll Template.  As this is an Oil that achieves the same effect as a spell, this is not surprising.</p>
 
<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>
 
</table>
 
<p>All magic items have a recharging/curse type: for details, see the <b>--gm-edit-mi</b> command in the MagicMaster API help documentation, section 7.1.  If not supplied for a magic item definition, it defaults to uncharged.  Generally, items in the database are not cursed-, but can have their type changed to cursed or some recharging cursed type when the DM stores them in a container or gives them to a Character using the <b>--gm-edit-mi</b> command.</p>
 
<p>Other magic items might use different structures, and be more complex:</p>
 
===Bead-of-Force===
 
<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:2Edefault}{{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>)}}{{</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>
 
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>}}</nowiki></p>
 
<p>The Bead of Force ability macro uses a Default Roll Template, which means the only mandatory field is the <nowiki>{{name=}}</nowiki> field, and the DM can define any other fields they want to describe and enact the magic item.  Here, an API button exists to do a saving throw with documented outcomes, and another API button can target an area with multiple tokens in to entrap them (if the DM rejects or confirms as they make or fail each saving throw).</p>
 
<br>
 
==Magic Items with Powers or Spell-Storing==
 
<p>Some magic items, especially artefacts and sentient items, can store spells and/or have powers similar to characters.  MagicMaster supports magic items of this type to a degree, although there are inevitably exceptions that the DM will have to get creative in their development!  These items use API buttons that call various MagicMaster commands to deliver their capabilities.</p>
 
<p>First to note is that <b>items that have powers and spells use spell slots in the owning character's character sheet</b>.  These spell slots should not be used by characters in your campaign.  If they are, errors might occur.  By default, on the AD&D2E character sheet the system uses Wizard Level 14 spell slots for magic item powers, and Wizard Level 15 spell slots for spell-storing magic items.  As standard AD&D2E only has spells up to level 9 this generally works without causing problems.</p>
 
<p>Next, in addition to the three standard elements of the Ability Macro, the 'ct-' attribute and the listing, these items require a 4th element which specifies their powers and spells.  These are:</p>
 
<table>
 
<tr><th scope="row">mi-muspells-[item-name]:</th><td>Wizard spells able to be stored in the magic item</td></tr>
 
<tr><th scope="row">mi-prspells-[item-name]:</th><td>Priest spells able to be stored in the magic item</td></tr>
 
<tr><th scope="row">mi-powers-[item-name]:</th><td>Powers able to be used by the magic item</td></tr>
 
</table>
 
<p>In each case the <i>[item-name]</i> is replaced by the Ability macro name (which is not case sensitive).</p>
 
<p><b>Note:</b> The DM creating new spell storing or power wielding magic items does not need to worry about anything other than the Ability Macro in the database, as running the command <b><i>--check-db</i></b> will update all other aspects of the database appropriately for all databases, as long as the Specs and Data fields are correctly defined. Use the name of the particular database as a parameter to check and update just that database.  Running the command <b><i>--check-db</i></b> with no parameters will check and update all databases.</p>
 
<p>When a spell-storing or power wielding magic item is added to a magic item bag or container using --edit-mi or --gm-edit-mi, these attributes are 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.</p>
 
<p>Here is an example of a power wielding magic item:</p>
 
===Ring-of-Shooting-Stars===
 
<p style="display: inline-block; background-color: lightgrey; border: 1px solid black; padding: 4px; color: dimgrey; font-weight: extra-light;"><span style="color:red">!setattr --silent --sel --casting-level|1 --casting-name|@{selected|token_name}'s Ring of Shooting Stars</span><br>
 
/w "@{selected|character_name}" <nowiki>&{template:2Edefault}{{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}} {{</nowiki>desc=This ring has two modes of operation—at night and underground—both of which work only in relative darkness.<br>
 
<i>During night hours, under the open sky</i>, the shooting stars ring will perform the following functions:<br>
 
• [*Dancing lights*](<span style="color:red">!magic --mi-power @{selected|token_id}|RoSS-Dancing-Lights|Ring-of-Shooting-Stars|1</span>) as spell (once per hour).<br>
 
• [*Light*](<span style="color:red">!magic --mi-power @{selected|token_id}|RoSS-Light|Ring-of-Shooting-Stars|1</span>), as spell (twice per night), 120-foot range.<br>
 
• [*Ball lightning*](<span style="color:red">!magic --mi-power @{selected|token_id}|RoSS-Ball-Lightning|Ring-of-Shooting-Stars|1</span>), as power (once per night).<br>
 
• [*Shooting stars*](<span style="color:red">!magic --mi-power @{selected|token_id}|RoSS-Shooting-Stars|Ring-of-Shooting-Stars|1</span>), as power (special).<br>
 
<i>Indoors at night, or underground</i>, the ring of shooting stars has the following properties:<br>
 
[*Faerie fire*](<span style="color:red">!magic --mi-power @{selected|token_id}|RoSS-Faerie-Fire|Ring-of-Shooting-Stars|1</span>) (twice per day) as spell<br>
 
[*Spark shower*](<span style="color:red">!magic --mi-power @{selected|token_id}|RoSS-Spark-Shower|Ring-of-Shooting-Stars|1</span>) (once per day) as power<br>
 
Range, duration, and area of effect of functions are the minimum for the comparable spell unless otherwise stated. Casting time is 5<nowiki>}}</nowiki></p>
 
<p>Note that the ability macro starts with a call to the <b>ChatSetAttr API</b> to set the <i>casting-level</i> to 1 and the name of the caster to be <i><Character-name>'s Ring of Shooting Stars</i>.  Not strictly necessary, but a nice cosmetic.</p>
 
<p>The data section now includes repeating data sets, one for each of the powers that the item has:</p>
 
<pre>RingData=[w:Ring of Shooting Stars,sp:5,rc:charged,ns:6], [cl:PW,w:RoSS-Dancing-Lights,sp:5,pd:12], … </pre>
 
<p>The first data set is very similar to the standard magic item data, with the addition of the <b>ns:</b> field, and is then followed by a number of repeated data sets specifying each of the powers:</p>
 
<table>
 
<tr><th scope="row">ns:</th><td>&lt;#&gt;</td><td>The number of powers (or spells) that the item can wield or store</td></tr>
 
<tr><th scope="row">cl:</th><td>&lt;MU/PR/PW&gt;</td><td>The type of the power/spell specification: PW=power, MU=wizard spell, PR=priest spell</td></tr>
 
<tr><th scope="row">w:</th><td>&lt;text&gt;</td><td>The name of the power/spell - must be exactly the same as the database name (case ignored)</td></tr>
 
<tr><th scope="row">sp:</th><td>&lt;[-/+]# / dice roll spec&gt;</td><td>The speed or casting time of the power/spell in segments</td></tr>
 
<tr><th scope="row">pd:</th><td>&lt;-1/#&gt;</td><td>The available casts per day, or -1 for <i>'at will'</i></td></tr>
 
</table>
 
<p>By running the <b>--check-db</b> command (see section 9 and the note above) these data sets are used to correctly set up the database with the powers wielded, so that when a Character receives this item, the Character also gains the powers to use through the item.</p>
 
<p><b>Note:</b> if a Character picks up two Power-wielding items with exactly the same item name (i.e. two copies of the same item) the results are unpredictable.  This is best avoided.</p>
 
<p>Feel free to just copy the specification for a Ring-of-Shooting-Stars in the Rings database and save it to a new Ability Macro with a different name, and then alter the power names, speeds, and uses per day, as well as the API Button <b>--mi-power</b> commands and the other text, to form new power-wielding magic items.  Also, the Ring does not have to have 6 powers - just remove or add one or more repeating data sets to reduce or increase the number of powers.</p>
 
<p>Here is an example of a spell-storing magic item:</p>
 
===Ring-of-Spell-Storing-HHSLS===
 
<p style="display: inline-block; background-color: lightgrey; border: 1px solid black; padding: 4px; color: dimgrey; font-weight: extra-light;">/w "@{selected|character_name}" <nowiki>&{template:2Edefault}{{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>)<br>
 
[Store Wizard Spell](<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>) or [Cast](<span style="color:red">!magic --cast-spell MI|@{selected|token_id}</span><nowiki>) spells}}{{</nowiki>desc=A ring of spell storing contains 1d4+1 spells which the wearer can employ as if he were a spellcaster of the level required to use the stored spells. The class of spells contained within the ring is determined in the same fashion as the spells on scrolls (see "Scrolls"). The level of each spell is determined by rolling 1d6 (for priests) or 1d8 (for wizards). The number rolled is the level of the spell, as follows:<br>
 
Priest: 1d6, if 6 is rolled, roll 1d4 instead.<br>
 
Wizard: 1d8, if 8 is rolled, roll 1d6 instead.<br>
 
Which spell type of any given level is contained by the ring is also randomly determined.<br>
 
The ring empathically imparts to the wearer the names of its spells. Once spell class, level, and type are determined, the properties of the ring are fixed and unchangeable. Once a spell is cast from the ring, it can be restored only by a character of appropriate class and level of experience (i.e., a 12th-level wizard is needed to restore a 6th-level magical spell to the ring). Stored spells have a casting time of [[5]].<nowiki>}}</nowiki></p>
 
<p>This is a specific version of a Ring of Spell Storing.  As the spells stored are specified in the macro, if you want there to be multiple rings of spell storing in your campaign they each need to be individually programmed (easy cut & paste job) & named differently.</p>
 
<p>The only new field in these data sets is:</p>
 
<table>
 
<tr><th scope="row">lv:</th><td>&lt;#&gt;</td><td>The level of the caster who cast the spell into the ring.  The spell will have effects as if cast at this level when cast from the ring.</td></tr>
 
</table>
 
<p>The <b>lv:</b> field only specifies the level of the initial spell caster when the item is first found.  Once owned and used, the level of the spell caster is recorded each time a spell is refreshed by casting into the item.  As the item is then passed from one Character to another, or stored in a container and recovered later, the levels at which the spells were cast is retained.  However, if the item is reloaded from the databases, or a duplicate of the item is placed by the DM and found by another character, that version of the item will have the spell caster levels from the database definitions.  Note that if a single Character picks up two versions of exactly the same spell storing item (i.e. with the same item name) the results are unpredicable...</p>
 
<p>Feel free to just copy the specification for a Ring-of-Spell-Storing in the Rings database and save it to a new Ability Macro with a different name, and then alter the spell names and casting levels as desired, to form new Rings of Spell Storing or other magic items.  Also, the Ring does not have to have 5 spells - just remove or add one or more repeating data sets to reduce or increase the number of stored spells (though the official definition of a Ring of Spell Storing states a maximum of 5 spells).</p>
 
<br>
 
==Weapons (if using AttackMaster API)==
 
<p>Weapons, magical or not, are special types of items in the Magic Items databases.  If coded properly (in the same way as those in the MI-DB-Weapons database), they can be used with the <b>AttackMaster API</b> to implement fully automatic weapon management, the ability to hold weapons “in-hand” or sheathed, to have automatic ammo and range management for ranged weapons, automatic entry of weapons into the melee and/or ranged weapons tables, ready to make attacks with magical plusses and other specifications all set up, and support for dancing weapons (ones that can attack without being held by the Character), creatures with more than 2 hands, and 1-handed weapons, 2-handed weapons, and even weapons that need more than 2 hands!</p>
 
<p>See the <b>Weapon & Armour Database Help</b> handout and AttackMaster API documentation for how Weapon definitions should be structured for use with the AttackMaster API, which are just a few additions to the standard definition of an item.</p>
 
<br>
 
==Armour & Shields==
 
<p>Like weapons, armour and shields of all types (including magical armour like magical Bracers and Rings of Protection) can be coded to be used with the <b>AttackMaster API</b> to automatically calculate the appropriate AC for various scenarios (such as with & without Shield, from the back, if surprised, etc).  This will take into account if the armour is valid for the character class, determine which is the best armour combination that the character has, if various armour elements can or can't work together, and add in Dexterity bonuses or impairments.  It will also allow magical effects cast on the character to take effect or be adjusted via the token “circles” and highlight when such an effect is in place by showing the relevant token bar (only when there is a difference between the token AC and calculated AC).</p>
 
<p>See the <b>Weapon & Armour Database Help</b> handout and AttackMaster API documentation for how Armour & Shield definitions should be structured for use with the AttackMaster API, which are just a few additions to the standard definition of an item.</p>
 
<p>Also, see the <b>RoundMaster API</b> documentation for how magical effects can be placed on and affect tokens and characters.</p>
 
<br>
 
==Specs & Data field values==
 
<p>Below are lists of the current possible values for the item database Ability macro sections.</p>
 
===Specs sections===
 
<pre>Specs=[Type, Item-Class, Handedness, Group-Type]</pre>
 
<p>There are no default settings for any of the Specs data fields.  All must be explicitly specified.</p>
 
====Spell Types====
 
<p>There is an infinite list of spell types: generally the type is the spell name.</p>
 
====Spell Item-Classes====
 
<table>
 
<tr><th scope="row">MUSpellL< 1-9 ></th><td>A Wizard spell with the Level specified as a number from 1 to 9</td></tr>
 
<tr><th scope="row">PRSpellL< 1-9 ></th><td>A Priest spell with the Level specified as a number from 1 to 9</td></tr>
 
<tr><th scope="row">Power</th><td>A Power</td></tr>
 
</table>
 
====Spell Handedness====
 
<p><b>0H</b> A spell/power that does not take a hand (there is no Somatic component)<br>
 
<b>1H</b> A spell/power that requires only 1 hand to cast (most spells are like this)<br>
 
<b>2H</b> A spell/power that requires 2 hands to cast (perhaps a scroll must be held)<br>
 
<b>3H</b> A spell/power that takes 3 hands… perhaps more than 1 caster together?<br>
 
<b>4H</b> Etc  No currently programmed spells use more than 2 hands<br>
 
<b>…</b> …</p>
 
====Spell/Power Schools====
 
<p>Spell Schools are not currently checked by the system, but are required for future expansion for whether it can be used by a Character of a specific class, or if there are magical situations that suppress various spell types.  Those implemented so far for the Spells databases are:</p>
 
<p><i>Abjuration, Alteration, Conjuration-Summoning, Enchantment-Charm, Divination, Illusion-Phantasm, Invocation-Evocation, Necromancy.</i></p>
 
<p>Note that the '/' in School names in the AD&D2e PHB have been replaced by hyphens.  It is also allowed to use just one half of any hyphenated school name where appropriate. If a spell or power is of more than one school, separate each with a vertical bar character '|'</p>
 
<br>
 
====Magic Item Types====
 
<p>There is an infinite list of magic item types: generally the type is the magic item name.  A magic item can have more than one type, with each separated by a vertical bar character '|'</p>
 
====Magic Item Classes====
 
<table>
 
<tr><th scope="row">Weapon</th><td>Weapons that are not Melee or Ranged weapons or any other class</td></tr>
 
<tr><th scope="row">Melee</th><td>Melee weapons that are used in hand-to-hand combat</td></tr>
 
<tr><th scope="row">Innate-Melee</th><td>Melee weapons that do not require proficiency to wield</td></tr>
 
<tr><th scope="row">Ranged</th><td>Ranged weapons that are either thrown or fire ammunition</td></tr>
 
<tr><th scope="row">Innate-Ranged</th><td>Ranged weapons that do not require proficiency to wield</td></tr>
 
<tr><th scope="row">Ammo</th><td>All types of ammunition that is used by Ranged weapons</td></tr>
 
<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>
 
<tr><th scope="row">Potion</th><td>Any type of potion, oil, pill or similar that is consumed or rubbed on</td></tr>
 
<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>
 
<tr><th scope="row">Staff</th><td>Quarterstaffs and similar large bludgeoning items that can also have spell-like abilities</td></tr>
 
<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>
 
<tr><th scope="row">Protection-Ring</th><td>Rings that protects and are counted as a type of Armour</td></tr>
 
<tr><th scope="row">Protection-Robe</th><td>A Robe that protect and are counted as a type of Armour</td></tr>
 
<tr><th scope="row">Light</th><td>All types of lantern, torch, and other illumination</td></tr>
 
<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>
 
</table>
 
====Armour Handedness====
 
<p><b>0H</b> Items that do not require to be held to work (e.g. a Ring, Buckler or a Helm)<br>
 
<b>1H</b> An item that must be held in one hand to work, such as a Wand<br>
 
<b>2H</b> Items that need two hands to wield, like a Staff<br>
 
<b>3H</b> Items that need three hands to use, perhaps by two characters… (not yet implemented)<br>
 
<b>…</b> etc.</p>
 
====Item Schools====
 
<p>Currently, all Magic Items other than Weapons and Armour use the same set of magical schools as for Spells & Powers, as they mostly perform spell-like effects.  See section 11.7.1.4 for the list.</p>
 
===Data Sections===
 
<p>Definitions for Data Section field types for Weapons & Armour can be found in the AttackMaster API documentation.  Below are the definitions for Spell, Power & other Magical Item types.</p>
 
<p><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>
 
<table>
 
<thead>
 
<tr>
 
<th scope="col" rowspan="2">Field</th>
 
<th scope="col" rowspan="2">Format</th>
 
<th scope="col" rowspan="2">Default Value</th>
 
<th scope="col" rowspan="2">Description</th>
 
<th scope="col" colspan="8">Can be used in</th>
 
</tr>
 
<tr>
 
<th scope="col">Spell<br>Data</th>
 
<th scope="col">Potion<br>Data</th>
 
<th scope="col">Scroll<br>Data</th>
 
<th scope="col">Wand<br>Data</th>
 
<th scope="col">Staff<br>Data</th>
 
<th scope="col">Rod<br>Data</th>
 
<th scope="col">Ring<br>Data</th>
 
<th scope="col">Misc<br>Data</th>
 
</tr>
 
</thead>
 
<tr><th scope="row">w:</th><td>< text ></td><td>'-'</td><td>Name to be displayed</td><td> </td><td>X</td><td>X</td><td>X</td><td>X</td><td>X</td><td>X</td><td>X</td></tr>
 
<tr><th scope="row">w:</th><td>< text ></td><td>''</td><td>Name of spell or power (Not case sensitive)</td><td>X</td><td> </td><td> </td><td> </td><td> </td><td> </td><td> </td><td> </td></tr>
 
<tr><th scope="row">+:</th><td>[ + / - ] #</td><td>0</td><td>Magical adjustment</td><td> </td><td> </td><td> </td><td>X</td><td>X</td><td>X</td><td>X</td></tr>
 
<tr><th scope="row">n:</th><td># [ / # ]</td><td>1</td><td>Attacks per round</td><td> </td><td> </td><td> </td><td>X</td><td>X</td><td>X</td><td> </td><td>X</td></tr>
 
<tr><th scope="row">sz:</th><td>[ t / s / m / l / h ]</td><td>''</td><td>Size of item</td><td> </td><td> </td><td> </td><td>X</td><td>X</td><td>X</td><td>X</td><td>X</td></tr>
 
<tr><th scope="row">sp:</th><td>[-]# or Dice Roll spec</td><td>0</td><td>Speed in segments (1/10 round)</td><td>X</td><td>X</td><td>X</td><td>X</td><td>X</td><td>X</td><td>X</td><td>X</td></tr>
 
<tr><th scope="row">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>
 
<tr><th scope="row">cl:</th><td>MU / PR / PW</td><td>''</td><td>Type of stored spell or power</td><td> </td><td> </td><td>X</td><td>X</td><td>X</td><td>X</td><td>X</td><td>X</td></tr>
 
<tr><th scope="row">lv:</th><td>#</td><td>1</td><td>Level at which spell/power is cast</td><td> </td><td> </td><td> </td><td>X</td><td>X</td><td>X</td><td>X</td><td>X</td></tr>
 
<tr><th scope="row">pd:</th><td>-1 / #</td><td>1</td><td>Number per day (power only)</td><td> </td><td> </td><td> </td><td>X</td><td>X</td><td>X</td><td>X</td><td>X</td></tr>
 
<tr><th scope="row">rc:</th><td>Charged / Uncharged / Rechargeable / Recharging / Self-chargeable / Cursed / Charged-Cursed / Recharging-Cursed / Self-chargeable-Cursed</td><td>Uncharged</td><td>Initial charged and Cursed status of item when found (Can be changed by DM using -gm-only-mi command once added to Character Sheet) Not case sensitive</td><td> </td><td>X</td><td>X</td><td>X</td><td>X</td><td>X</td><td>X</td><td>X</td></tr>
 
</table>
 
<br>
 
 
= Changelog =
 
{{changelog version|1.047|2022-02-02|* Added --config command and menu for DM to alter some API behavior.
 
* Fixed Shocking Bracers LB error & enhanced Rage power
 
* Multiple weapon and magic item definition updates}}
 
{{changelog version|1.046|2022-01-23|* Fixed illegal characters not rendered by One-Click installation
 
* Corrected definitions of Spear and Lightning-Bolt
 
* Added menu for adding Spells & Powers to magic items}}
 
{{changelog version|1.045|2022-01-14|* Fixes to multiclass spell level calculation and non-MU/non-Priest spellcaster spell numbers
 
* Force container type to "Holds items" when adding items.}}
 
{{changelog version|1.044|2022-01-09|* First version for public release}}
 
 
[[Category:AD&D 2E]]
 
[[Category:API:RPGMaster]]
 

Latest revision as of 21:10, 10 June 2023

Main Page: API:Script Index

API ScriptAuthor: Richard E
Version: 1.5.02
Last Modified: 2023-05-24
Code: MagicMaster
Dependencies: ChatSetAttr,TokenMod, RoundMaster, InitMaster, AttackMaster, CommandMaster, RPGMlibrary AD+D2e
Conflicts: None

MagicMaster API provides functions for AD&D-2E (though 5e and other spells could be added) to manage all types of magic, including Wizard & Priest spell use and effects; Character, NPC & Monster Powers; and discovery, looting, use and cursing of Magic Items. It's a part of the RPGMaster suite of APIs.

Note: This API requires that a RPGMaster Library API is loaded, which provides RPG version-specific and Roll20 Character Sheet version-specific data, rulesets and processing (as well as other goodies!).

All magical aspects can work with the RoundMaster API to implement token markers that show and measure durations, and produce actual effects that can change character sheet attributes temporarily for the duration of the spell or permanently if so desired. They can also work with the InitiativeMaster API to provide menus of initiative choices and correctly adjust individual initiative rolls, including effects of Haste and Slow and similar spells. Spells can summon weapons to hand via the AttackMaster API and change bonuses on attacks and damage, by weapon or for one or more party members. This API can also interact with the MoneyMaster API (under development) to factor in the passing of time, the cost of spell material use, the cost of accommodation for resting, and the cost of training for leveling up as a spell caster (Wizard, Priest or any other).

Specification for spells, magic items, weapons, armour & shields are implemented as ability macros in specific database character sheets. This API comes with a wide selection of such specifications, held in databases that are created and updated automatically when the API is run. The GM can add to the provided items in the databases using standard Roll20 Character Sheet editing, following the instructions provided in the relevant database wiki pages.

Contents

[edit] Forum

RPGMaster Forum

[edit] MagicMaster Database Help

RPGMaster Magic Spells & Items DB - RPGMaster Spells & Magic Items databases Wiki page

[edit] Configuring Character Sheets

RPGMaster Character Sheet setup - RPGMaster Character Sheet setup Wiki page

[edit] What MagicMaster does

Race, Class, Item, Spell and Power databases

MagicMaster uses a large range of items held in databases. The current versions of these databases are distributed with the game-version-specific RPGMaster Library, updated as new versions are released via Roll20. The provided databases are held in memory, but can be extracted to ability macros in database character sheets using the !magic --extract-db command. These macros can do anything that can be programmed in Roll20 using ability macros and calls to APIs, and are found (either in the Character Sheet database or the internal database in memory) and called by the MagicMaster API when the Player selects them using the menus provided by the MagicMaster functions. The GM can add to the provided items in the databases using standard Roll20 Character Sheet editing, following the instructions provided in the Magic Database Handout.

Races & Classes

The definitions for character Races & Classes held in the Race-DB and Class-DB databases include a description of the race and class and its capabilities, the powers/non-weapon proficiencies that it comes with, any restrictions on weapons, armour and spells that it is subject to, and other class-specific aspects such as alignments and races. As you might expect, these are not just descriptions, but restrict the player character to the characteristics defined (alterable by using the !magic --config command). The Class & Race Database handout provides information on the structure of the race & class specifications and how the GM / game creator can add their own races and classes and alter those provided.

Spells and Powers

The Ability Macros for spells and powers include descriptions of the spell they represent (limited, I'm afraid, to avoid copyright issues), and also can optionally have API Buttons embedded in them which, if selected by the Player, can enact the actions of the spell or power. The API Buttons call one or more of the API commands listed in this document, or commands provided by other APIs. This is most powerful when combined with the RoundMaster API to implement token statuses and status markers with durations and effect macros, enabling the spells & powers to make temporary (or permanent, if desired) changes to the targeted creature's token and character sheet attributes.

The best way to learn about these capabilities is to look at example spell definitions in the databases and use those spells or powers to see what they do.

Types of Item Provided

The Item database is currently split into nine parts: Weapons, Ammunition, Armour, Lights, Potions, Scrolls & Spellbooks, Wands Staves & Rods, Rings, and Miscellaneous. More might be added in future releases, and any DM can add more databases with their own items.

Many magic items have actions that they can perform in the same way as Spells & Powers, using API Buttons in their macros that call MagicMaster API commands, or commands from other APIs. As with spells & powers, this is most powerful when combined with the capabilities of the RoundMaster API.

Items can have stored spells (like Rings of Spell Storing) and the spells can be cast from them, and/or can have powers that can be consumed and are refreshed each day. Again, using the RoundMaster API, the spells and powers can have temporary or permanent effects on Tokens and Character Sheets, if desired.

Adding Items to the Character

Classes are set using the CommandMaster API or via the AttackMaster !attk --other-menu menu (or can be set manually on the Character Sheet). Classes can be those provided in the Class-DB, or any other class. Class names that are not in the database will adopt the attributes of the standard classes depending on the character sheet field the class name and level are entered into: Warrior, Wizard, Priest, Rogue, and Psion. Depending on the settings selected by the GM under the --config menu, the choise of class will restrict or grant the character's ability to use certain items and cast certain spells.

The MagicMaster API provides commands to perform menu-driven addition of items to the Character Sheet. Using these commands will set up all the necessary fields so that the Player can use the items with the other APIs - if using MagicMaster then items should not be added directly to the Character Sheet.

Items can also be acquired by finding them in chests or on tables (simply tokens with images of chests or tables that represent Character Sheets with items added to them) that can be looted, or even dead bodies of NPCs that have been killed in battle. MagicMaster provides commands that support a menu-driven way to perform looting. Characters, especially Rogues, can even try to Pick Pockets to take items from NPCs (or even other Characters...), though failure may alert the DM (or other Player) to the attempt. Containers can even be trapped, with magical consequences if the trap goes off! On the other hand, Characters can also put items away into chests or onto tables or other storage places, or give them to other Characters or NPCs.

Adding Spells & Powers to the Character

Spells need to be added in two steps: 1. adding to a Character's or NPC's spell book; and 2. Memorising the spells each day.

The simplest way to add spells to a Character's spell books is to use the CommandMaster API functions that set up Character Sheets from scratch. However, spells can be added to the Character Sheet manually: see the RPGMaster Character Sheet setup handout for details of how to do this. Either approach results in the Character having a list of spells at each spell level they can use that they have available to memorise.

Spells can be memorised using the MagicMaster menus or via the !magic --mem-spell MagicMaster command. This limits the number of spells memorised at each level to the number that is valid for the Character, with their specific characteristics, class, level and other valid adjustments (though it is possible to add a "fudge factor" if needed). Once memorised, they can be rememorised or changed at any time, though the DM usually limits this in game play to once each in-game day. If a Player is happy with the spells a Character has, the Character just needs to rest at the end of the day to regain their spells (and powers, and recharging magic item charges).

Powers are added in exactly the same way as Spells. The difference between the two is that Powers are granted to a Character, either as a function of the class they have adopted, or from being granted powers in game-play. Of course, NPCs and creatures also have many various powers. Some Powers can be used more than once a day, or even 'at will' (an example is Priests turning undead).

Using Items

Items possessed by the Character can be used to perform their functions, using MagicMaster menus. When used with the InitiativeMaster API, the action for the next round can be the use of a specific item the Character has on them, with the speed of that item. This may use charges or consume quantities of the item, and these charges may or may not be regained overnight, or through other means. The items use Roll20 ability macros that can be as simple as putting text in the chat window explaining what the item does, through to much more complex targeting of effects on the user, a single other target, or all tokens in a defined area. When used with the RoundMaster API, targeted tokens can have a status marker applied with a pre-determined duration and associated effects at the start, each round and when it finishes. Items that are totally consumed will automatically disappear from the Character Sheet.

Casting spells and using powers

Spells memorised by the Character can be cast using MagicMaster menus. As with items, when used with the InitiativeMaster API with Group or Individual initiative, the action for the next round can be the casting of a specific spell with the speed of the Casting Time. Casting a spell will remove it from memory for the rest of the day, but a rest will bring it back. Like items, spells use Roll20 ability macros and thus can perform any function a macro or an API call can achieve. The same capability to affect tokens and Character Sheets is available if used with the RoundMaster API.

Dynamic lighting for tokens

MagicMaster API provides commands to change the lighting settings of the token to reflect illumination, as if holding various light sources. This includes both radiant light sources such as hooded lanterns, torches, continual light gems, magic items and magic armour, and also directed light sources such as beacon lanterns and bullseye lanterns which only illuminate in beams.

DM tools

The DM is provided with tools to be able to add items to chests, NPCs, Characters etc. These tools allow the DM to also change certain aspects of the items, including the displayed name and the cursed status of the item. Items that are cursed are not obvious to Characters and Players, and such items can be 'hidden' and appear to be other items until revealed as the cursed item by the DM.

The tools also allow the DM to increase or restrict the number of items Characters can have on their person: it is then possible to give each Character a 'backpack' token/character sheet, which the Character can store items to and get items from - of course, retrieving an item from the backpack takes a round (at the DM's discression - the system does not impose this).

DMs can also add their own items, spells and powers to additional databases (the provided databases should not be added to, but entries can be replaced by new entries in your own databases - updates will not replace your own databases - see the RPGMaster Magic Spells & Items Database handout). This requires some knowledge of Roll20 macro programming and use of APIs. See the Roll20 Help Centre for information.


[edit] How to use MagicMaster

Installation and Configuration

Copy the script's code, available either via the Roll20 One-Click Install system, or from the menu on the right and stored at Roll20's API GitHub Repository and paste the code into a new script in your campaign's API Script Editor. Save the new script and it will be available inside your campaign. It will install several new Character Sheets and Handouts: The handout MagicMaster Help provides a full manual of how to use MagicMaster. The handout RPGMaster CharSheet Setup provides information on setting up a character sheet for use with MagicMaster and the rest of the RPGMaster API series. The handout Magic Database Help provides information on use and adding to the Magic Item, Spell & Power databases.

Script Use

After installing the script, refer the the handout MagicMaster Help for full information on use. Below is a copy of the contents of that handout.

Syntax

The MagicMaster API is called using !magic (or the legacy command !mibag).

!magic --help

Commands to be sent to the MagicMaster API must be preceded by two hyphens '--' as above for the --help command. Parameters to these commands are separated by vertical bars '|', for example:

!magic --mi-power token_id|power_name|mi_name|[casting-level]

If optional parameters are not to be included, but subsequent parameters are needed, use two vertical bars together with nothing between them, e.g.

!magic --cast-spell MI|[token_id]||[casting_name]

Commands can be stacked in the call, for example:

!magic --spellmenu [token_id]|[MU/PR/POWER] --mimenu [token_id]

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


[edit] Roll Query Extension

The syntax of the Roll20 Roll Query has been extended within the RPGMaster MagicMaster API to support !magic API commands with Roll Queries that the GM is forced to answer, rather than the player regardless of who issued the command. The standard syntax and the extended syntax is shown below:

Standard Syntax: ?{Query text|option1|option2|...}<br>
Extended syntax: gm{Query text|option1|option2|...}

When used in a !magic API command, the extended Roll Query will prompt the GM with a button in the Chat Window for the GM to answer the question posed by the query text. The result will be fed into the action taken by the API command. This allows the GM to be involved when, for instance, a Staff of the Magi absorbs levels of spells cast at a character that the character & player can't know.


[edit] Using Character Sheet Ability/Action buttons

The most common approach for the Player to run these commands is to use Ability macros on their Character Sheets which are flagged to appear as Token Action Buttons: Ability macros & Token Action Buttons are standard Roll20 functionality, refer to the Roll20 Help Centre for information on creating and using these.

In fact, the simplest configuration is to provide only Token Action Buttons for the menu commands: --spellmenu and --mimenu. From these, most other commands can be accessed. If using the CommandMaster API, its character sheet setup functions can be used to add the necessary Ability Macros and Token Action Buttons to any Character Sheet.


[edit] Command Index

[edit] 1.Spell and Power management

--spellmenu [token_id]|[MU/PR/POWER]<br>
--mem-spell (MU/PR/POWER)|[token_id]<br>
--view-spell (MU/PR/POWER)|[token_id]<br>
--cast-spell (MU/PR/POWER/MI)|[token_id]|[casting_level]|[casting_name]<br>
--cast-again (MU/PR/POWER)|token_id|[spell_name]<br>
--mem-all-powers token_id

[edit] 2.Magic Item management

--mimenu [token_id]<br>
--edit-mi [token_id]<br>
--view-mi [token_id]<br>
--use-mi [token_id]<br>
--mi-charges token_id|value|[mi_name]|[maximum]|[charge_override]<br>
--mi-power token_id|power_name|mi_name|[casting-level]<br>
--store-spells token_id|mi-name<br>
--mem-spell (MI-MU/MI-PR)[-ANY]|[token_id]|[mi-name]<br>
--view-spell (MI/MI-MU/MI-PR/MI-POWER)|[token_id]|[mi-name]<br>
--cast-spell (MI/MI-POWER)|[token_id]|[casting_level]|[casting_name]|[CHARGED]|[mi-name]

[edit] 3.Spell, power & magic item effects and resting

!rounds --target CASTER|caster_token_id|caster_token_id|spell_name|duration|increment|[msg]|[marker]<br>
!rounds --target (SINGLE/AREA)|caster_token_id|target_token_id|spell_name|duration|increment|[msg]|[marker]<br>
--touch token_id|effect-name|duration|per-round|message|marker<br>
--level-change [token_id]|[# of levels]<br>
--change-attr [token_id]|change|[field]|[SILENT]<br>
--rest [token_id]|[SHORT/LONG]|[MU/PR/MU-PR/POWER/MI/MI-POWER]|[timescale]<br>
--mi-rest [token_id]|mi_name|[charges]|[power_name]

[edit] 4.Treasure & Item container management

--gm-edit-mi [token_id]<br>
--search token_id|pick_id|put_id<br>
--pickorput token_id|pick_id|put_id|[SHORT/LONG]

[edit] 5.Light source management

--lightsources [token_id]<br>
--light token_id|(NONE/WEAPON/TORCH/HOODED/CONTLIGHT/BULLSEYE/BEACON)

[edit] 6.Other commands

--help<br>
--message [who|][token_id]|title|message<br>
--tidy [token_id]|[SILENT]<br>
--config [FANCY-MENUS/SPECIALIST-RULES/SPELL-NUM/ALL-SPELLS] | [TRUE/FALSE]<br>
--check-db [db-name]<br>
--extract-db [db-name]<br>
--handshake from | [cmd]<br>
--hsq from | [cmd]<br>
--hsr from | [cmd] | [TRUE/FALSE]<br>
--debug (ON/OFF)


[edit] Spell management

[edit] Display a menu to do actions with spells

--spellmenu [token_id]|[MU/PR/POWER]

Takes an optional token ID and an optional menu type as arguments. If token ID is not specified, uses the selected token.

MU:displays buttons for Magic User/Wizard spells for casting, resting (short or long), memorising spells from the character's spell book, or viewing the memorised spells.
PR:displays buttons for Priest spells for casting, resting (short or long), memorising spells from the character's spell book, or viewing the memorised spells.
POWER:displays buttons for using powers, doing a long rest, changing/resetting powers from the character's granted powers, or viewing the granted powers.
None of the above:the system will check the class(es) of the character and display the appropriate menu, or if a multi-class character including both a Wizard and a Priest, ask if the player wants to display Magic User or Priest menus.

If the specified token is not associated with a character that has a spell book of the chosen type, or any granted powers, an error message is displayed.

[edit] Display a menu to memorise spells from the Character's spell book

--mem-spell (MU/PR/POWER/MI-MU/MI-PR)|[token_id]|[mi-name]

Takes a mandatory spell book type, an optional token ID, and an optional magic item name as arguments. If token ID is not specified, uses the selected token.

The Character Sheet associated with the token must have spell books specified for the relevant types of spells or powers. These are lists of spells from the spell macro databases (see Section 7) specified by level (powers are all 1 level) and as lists separated by '|'. E.g. Charm-Person|Light|Sleep. If the CommandMaster API is installed, the GM can use its menus to set up character spell books and granted powers.

Initially displays a menu for memorising Level 1 spells (the only level for powers), with buttons to: choose a spell from the Level 1 spell book on the character sheet; review the chosen spell; and one for each memorising slot the Character has at this level. Other buttons to memorise or remove spells become available when spells or slots are chosen. Another button goes to the next available level with slots. When a granted power is memorised to a slot, a quantity per day can be specified: -1 will grant unlimited uses of the power per day. Memorising any other type of spell is limited to 1 use per slot.

Depending on the settings on the --config menu, the character will be limited to memorising spells and powers allowed to their character class and level.

MI-MU and MI-PR have a special function: these are used to cast memorised spells into the named spell-storing magic item (if no item is named, the last item selected by the Character running the command will be used instead), such as a Ring-of-Spell-Storing. Magic Item spells are stored in an unused level of the Character Sheet. This command displays both all memorised spells and all spell-storing magic item spell slots, and allows a memorised spell to be selected, a slot (for the same spell name) to be selected, and the spell cast from one to the other. Spells can only be replaced by the same spell that was in the slot previously (unless this is the first time spells have been stored in a blank spell-storing item).

[edit] View the memorised spells or granted powers

--view-spell (MU/PR/POWER/MI-MU/MI-PR/MI-POWER)|[token_id]|[mi-name]

Takes a mandatory spell type, an optional token ID, and an optional magic item name. If token ID is not specified, uses the selected token.

Displays a menu of all levels of memorised spells of the selected type (there is only 1 level of powers). Spells that have already been cast appear as greyed out buttons, and can't be selected. Spells that are still available to cast that day can be selected and this runs the spell or power macro from the relevant database without consuming the spell, so that the Player can see the specs.

Adding MI- before any of the types of spell views the spells or powers available for the specified magic item, or the last Magic Item used by the Character if no magic item name is provided. Generally this version of the command is only called from API Buttons from the magic item's ability macro.

[edit] Cast a memorised spell or use a granted power

--cast-spell (MU/PR/POWER/MI/MI-POWER)|[token_id]|[casting_level]|[casting_name]|[CHARGED]|[mi-name]

Takes a mandatory spell type, an optional token ID (if not specified, uses the selected token), an optional casting level, and an optional caster name, an optional 'CHARGED' command, and an optional magic item name.

This displays a menu of all levels of the memorised spells/powers of the relevant type. MI displays the spell book for spells stored on the specified magic item, or the last magic item used or viewed if not specified (both MU & PR), and MI-POWER all stored powers in the specified or last selected magic item, (this version of the command is generally called using an API Button in the magic item ability macro). The player can select a spell/power and then a button becomes available to cast it, using up that slot/deducting a power charge until the next long rest (or until the item is recharged).

If a casting_level is specified, the spell will be cast as if by a caster of that level, and if a casting_name is specified, that name will be displayed in the spell macro information. These functions are often used for magic items that cast at specific levels of use, or magic artefacts that are named and/or sentient. If these are not specified, the caster name and relevant class level are used. In either case, specified or not, the character's Character Sheet Attributes called @{Casting-name} and @{Casting-level} are set to the values used, and can be used in spell, power, or magic item macros.

If the optional CHARGED parameter is specified (only relevant to spells and powers stored on magic items), this specifies that the Magic Item from which the spell or power is cast is charged, and looses one charge when that cast is made. This is generally the case when the spell or power is on a Scroll. When the charge quantity reaches zero, the item will follow the behaviour determined by its charge type (charged, uncharged, rechargeable, recharging, self-charging) - see section 4.1 for more information on charges and charge types.

[edit] Cast the last used spell or power again

--cast-again (MU/PR/POWER)|token_id|[spell_name]

Takes a mandatory spell type, a mandatory token ID and an optional spell name.

This command is used for certain spells and powers that, once cast, allow continuing effects in the same or subsequent rounds, without using additional charges. If the optional spell name is not used, the command just casts again the same spell as the last spell cast by the character associated with the selected token, at the same casting level and casting name. If a spell name is specified, this spell is cast instead as if it were the same spell: this is used where different spell macros are required to specify subsequent spell effects.

[edit] Memorise All Valid Powers

--mem-all-powers token_id

Takes a mandatory token_id.

Reviews all the Powers currently in the Powers Spellbook, checking for Race, Creature, Class and user-added Powers, and checks them against their respective definitions in the various databases to assess if they can be used at the level of experience/Hit Dice of the character / creature. Memorises each valid power for the number of uses per day specified in the Race, Class or Creature database definition: user-added powers are memorised at unlimited uses per day unless a default is otherwise specified in the Powers database, on the basis that DMs/Players will either change this by rememorising them individually, or otherwise play to the agreed limits of use.


[edit] Magic Item management

[edit] Display a menu of possible Magic Item actions

--mimenu [token_id]

Takes an optional token ID as an argument. If token ID is not specified, uses the selected token.

Displays a menu with the following actions: Use a magic item, Search for magic items & treasure, Store magic items in a container, Edit the contents of a character's magic item bag, and View the contents of a character's magic item bag.

Searching & Storing are explained in section 4.

[edit] Edit a Magic Item bag

--edit-mi [token_id]|[MARTIAL/MAGICAL/ALL]

Takes an optional token ID, and an optional item type as arguments. If token ID is not specified, uses the selected token. If the item type is not specified, defaults to MAGICAL.

Displays a menu similar to editing memorised spells. At the top are buttons to choose different types of magic items which have macros in the magic item databases. If the optional item type is MARTIAL, only weapons, ammo and armour are listed; if ALL is specified, lists of all items are shown; otherwise only non-MARTIAL items are listed. The slots available in the bag are shown (with their current contents) and, when magic items and/or slots are chosen buttons become selectable below to store, review, or remove magic items in/from the bag.

Storing a magic item will ask for a number - either a quantity or a number of charges. Magic Items can be of various types: Charged (is used up when reaches 0), Uncharged (a number is a pure quantity that is not consumed), Recharging (regains charges after each long rest), Rechargable (is not used up when reaches 0, stays in bag and can be recharged when the DM allows), Self-charging (recharge at a rate per round determined by the item) and can also be Cursed - more under section 4.

This menu is generally used when Magic Item & treasure containers (such as Treasure Chests and NPCs/monsters with treasure) have not been set up in a campaign as lootable, and provides a means of giving found magic items to characters. The DM just tells the Player that they have found a magic item, and the Player adds it to their Character Sheet using this command (more likely accessed via the Magic Item menu).

[edit] View a character's Magic Item Bag

--view-mi [token_id]

Takes an optional token ID as an argument. If token ID is not specified, uses the selected token.

Displays a menu of items in the character's magic item bag, with the quantity possessed or the number of charges. Pressing a button displays the named Magic Item specs without using any charges so that the Player can review the specifications of that item. Items for which all charges have been consumed are greyed out, and cannot be viewed as the character can no longer use them. They will become viewable again if they gain charges.

[edit] Use a Magic Item from the bag

--use-mi [token_id]

Takes an optional token ID as an argument. If token ID is not specified, uses the selected token.

Displays a similar menu as for viewing the contents of the Magic Item Bag, but when an item is selected, a button is enabled that uses the Magic Item and consumes a charge. Other buttons specified in the item macro might use additional charges to perform additional effects. See section 3.

Items with 0 quantity or charges left are greyed out and cannot be selected, unless they have abilities to regain charges such as "spell absorbing" items. When a Charged Item reaches 0 charges left, it is removed from the character's Magic Item Bag automatically.

[edit] Add, set or deduct Magic Item charges

--mi-charges token_id|[+/-]value|[mi_name]|[maximum]|[charge_override]

Takes a mandatory token ID, a mandatory value preceeded by an optional + or -, an optional magic item name, an optional maximum value, and an optional magic item charge type override as arguments.

Does not display anything but alters the number of current or recoverable charges on an item. By default, alters the last magic item used by the character, or will affect the named magic item. Warning: a character can have two items of the same name, and there is no guarantee which will be affected if the name is used.

Remember: using a Charged, Recharging, Rechargeable or Self-Charging Magic Item will automatically use 1 charge on use (unless the ItemData specification includes the field c:0, in which case no charges will automatically be deducted on use). If the c: tag is not used, or is anything other than 0, then charges will be deduncted (default 1 charge) on use of the item. In addition, that one charge deduction always happens - if an effect of a Magic Item uses 2 charges, only 1 more needs to be deducted.

Note: '-' reduces current remaining charges, '+' adds to the maximum recoverable charges, and no + or - sets the maximum recoverable charges. This command cannot be used to increase the current remaining charges unless the item is of type absorbing.

Using minus '-' before the value will deduct charges from the current quantity/charges: e.g. if using an optional power of the item that uses more than 1 charge. Using + before the value will add the value to the number of recoverable charges (overnight or rechargeable to), up to any specified maximum (often used for magic items that regain variable numbers of charges overnight). Just using the value without + or - will just set the number of recoverable charges to the given value. This command is not required to recharge self-charging items but can be used to change the maximum number of charges they will self-charge up to.

Absorbing items can gain charges in use from other sources, so the --mi-charges command works differently: '-' reduces both current and maximum charges and '+' only increases current charges (but only to maximum and not beyond). Using neither '-' or '+' will set the current charges (but, again, only up to the maximum).

The charge-override can be used to temporarily change the charge behaviour of the magic item. Specifying an override will cause the magic item to behave as if its charging type was that of the override only for this call. Thus charges could be deducted from an uncharged item by overriding by rechargeable or charged.

[edit] Use a Magic Item power

--mi-power token_id|[type-]power_name|mi_name|[casting-level]

Takes a mandatory token ID, mandatory power name (optionally prefixed by a power type), mandatory magic item name, and an optional casting level as parameters.

Magic Items, especially artefacts, can have their own powers that can be used a specified number of times a day, or at will. This command can be used in API buttons in the Magic Item macro to call on that power. The power name and the magic item name must be specified to select the right power. If a casting level is specified, any relevant impacts on use of the power will be taken into account: it is often the case that magic items use powers at specific levels. If not specified, the item using Character's level is used (user does not need to be a spell caster).

Generally, magic item powers have unique names, though they do not have to. Such magic items require specific setting up by the DM - see later sections. However, powers can have a prefix that indicates a power type that specifies the power is in fact a Wizard spell (MU-), a Priest spell (PR-), or a Magic Item (MI-) or (for completeness) confirmed as a Power (PW-). Specifying a power type prefix means the appropriate database types will be searched for the named power - thus (for instance) a Wizard or Priest spell can be specified as a Magic Item power without having to program a duplicate in the Powers Databases. If no power type prefix is specified, the system will first search for a matching power in the Powers Databases (both API-supplied and user-supplied), then all Wizard spell databases, then Priest spell databases, then all Magic Item databases, and finally the character sheet of the creature wielding the Magic Item.

[edit] Add spells to a spell-storing Magic Item

--store-spells token_id|mi_name

Takes a mandatory token ID and a mandatory magic item name.

This command presents a dialog in the chat window that stores spells or powers in any magic item that has been defined as being able to cast stored spells/powers. The item definition must include somewhere in its definition the command call !magic --cast-spell MI| or !magic --cast-spell MI-POWER|, generally as part of an API button, or spells/powers cannot be stored. If the command is for MI, the dialog defaults to Level 1 Wizard spells, and has buttons to switch level and to Priest spells. If the command is for MI-POWER, the dialog allows powers to be stored, but Wizard and Priest spells can also be stored as powers, and the dialog will prompt for a number of uses per day for each.

Once a spell is cast from a spell-storing item, the spell is spent and does not return on a long or short rest: the spell must be refreshed using the --mem-spell command (see below). If a power is used from a power-storing item, the power will have a number of uses per day (or be "at will"), and will refresh on a long rest.

[edit] Restore spells in a spell-storing Magic Item

--mem-spell (MI-MU/MI-PR)[-ADD/-ANY]|[token_id]|[mi-name]

Takes a mandatory spell type (optionally followed by -ADD or -ANY), an optional Token ID for the character, and an optional magic item name. If token ID is not provided, it uses the selected token, and if the magic item name is not specified, the last used magic item is assumed.

MI-MU and MI-PR mem-spell types are used to cast memorised spells into a spell-storing magic item, such as a Ring of Spell Storing. Magic Item spells are stored in an unused spell level of the Character Sheet (by default Wizard Level 15 spells). This command displays both all the character's memorised spells and the spell-storing magic item spell slots in the specified magic item (or the last one used if not specified), and allows a memorised spell to be selected, a slot to be selected (for the same spell name - limiting the item to only store certain defined spells unless "-ANY" is added to the command), and the spell cast from one to the other.

If either "-ANY" or "-ADD" are added to the spell type string, the player can just select a memorised spell and then immediately cast it into the device without choosing a slot: this will add the spell to the device. If the extension is "-ADD" then existing spells need to be refreshed with an identical spell, the same way as if -ADD was not specified. If "-ANY" is specified, not only can the player extend the spells stored, they can replace expended spell slots with any spell, not just the one previously stored in the slot. Generally, the GM will state that the device used for storing the spells will have a limited capacity of some type - number of spell levels, number of spells, types or spheres of spell, etc. These are not programmatically implemented and the player & GM will need to manage this manually.

Unlike some other menus, however, magic item spell slots that are full are greyed out and not selectable - their spell is intact and does not need replacing. Spell slots that need replenishing are displayed as selectable buttons with the spell name that needs to be cast into the slot.

The level of the caster at the time of casting the spell into the magic item is stored in the magic item individually for each spell - when it is subsequently cast from the spell-storing magic item it is cast as if by the same level caster who stored it.

A spell-storing magic item can hold spells from one or both of Wizard and Priest spells. The database where the spell is defined is also stored in the magic item with the spell, so the correct one is used when at some point in the future it is cast. A copy of the spell macro is also stored on the Character Sheet of the character that has the spell-storing magic item. If, when cast, the system can't find the database or the spell in that database (perhaps the character has been moved to a different campaign with different databases), and it can't use the copy on its own character sheet for some reason, the system will search all databases for a spell with the same name - this does not guarantee that the same spell will be found: the definition used by a different DM could be different - or the DM may not have loaded the database in question into the campaign for some reason. In this case, an error will occur when the spell is cast.

See the Magic Items Database documentation for how spell-storing magic items are defined.

[edit] Casting a spell from a spell-storing magic item

--cast-spell (MI/MI-POWER)|[token_id]|[casting_level]|[casting_name]|[CHARGED]|[mi-name]

Takes a mandatory casting type of 'MI', an optional Token ID (if token ID is not provided, it uses the selected token), an optional casting level (which will be ignored in favour of the level of the caster of the spell who cast it into the item), an optional casting name which, if not specified, will be the name of the wielder of the magic item, an optional 'CHARGED' command, and an optional magic item name (if not provided, uses name of the last magic item the character selected, viewed or used).

This command works in the same way as for casting other spells. However, spells cast from a spell-storing magic item are not regained by resting - either short or long rests. The only way to regain spells cast from such an item is to cast them back into the item from the character's own memorised spells: see the --mem-spell command above. If the character does not have these spells in their spell book or is not of a level able to memorise them, then they will not be able to replace the spells and will have to get another spell caster to cast them into the item (by giving the item to the other Character and asking nicely for it back again) or wait until they can get the spells.

If the optional parameter 'CHARGED' is used, spells on the magic item are not re-storable. The spells will be deleted after they are all used up and the magic item will not be able to store any more spells. This is mainly used for Scrolls with multiple spells.


[edit] Spell, power & magic item effects and resting

If this API is used in conjunction with the RoundMaster API, Magic Items, Spells & Powers can all place status markers on tokens, and also cause real Effects to alter token & character sheet attributes and behaviours: when cast; during each round of their duration; and when they expire. See the RoundMaster documentation for further information, especially on Effects and the Effects Database.

[edit] Target spell effects on a token (with RoundMaster API only)

!rounds --target CASTER|caster_token_id|[caster_token_id|]spell_name|duration|[+/-]increment|[msg]|[marker]<br>
!rounds --target (SINGLE/AREA)|caster_token_id|target_token_id|spell_name|duration|increment|[msg]|[marker]

Takes mandatory CASTER, SINGLE or AREA command, a mandatory caster token ID, for SINGLE/AREA a mandatory target token ID, mandatory spell name, duration & increment (preceeded by an optional +/-), and an optional message and optional token marker name.

If using the RoundMaster API, this command targets one, or a sequential set of tokens and applies a token marker to the token for the specified duration number of rounds, with the increment applied each round. The optional message will be shown below that token's turn announcement each round. The marker used will either be the one specified or if not specified a menu to choose one will be shown.

CASTERwill just take one Token ID and apply the marker to that token.
SINGLEwill take both the Token ID of the caster, and the Token ID of a target of the spell/power/MI. The marker will be applied to that of the target.
AREAwill take the Token ID of the caster, and one Token ID of the first token in the area of effect. As each token is specified the command will ask the Player to select subsequent tokens in the area of effect. Once all relevant tokens have been selected, just ignore the next prompt.

If the Player is not the DM/GM, the system will ask the DM/GM to approve the marker/effect for each token - this allows the DM to make saving throws for monsters/NPCs affected where appropriate.

See the RoundMaster API documentation for full details.

[edit] Cast a spell that requires a "touch" attack roll

--touch token_id|effect-name|duration|per-round|[message]|[marker]

Takes mandatory token ID, effect name, duration of the effect, an increment to the duration per round (often -1), an optional message each round for the targeted token, and an optional status marker to use (if not supplied, the DM or user will be asked to select one).

Note: this command requires RoundMaster API to also be loaded, but is a !magic command.

Sets up the Character represented by the specified token ready for an "Attack Roll" to deliver a touch attack for a spell or power or magic item use that requires an attack. The parameters are those that will be passed to the !rounds --target command if the attack is successful (see above).

To use this command, add it as part of a spell, power or MI macro in the appropriate database, before or after the body of the macro text (it does not matter which, as long as it is on a separate line in the macro - the Player will not see the command). Then include in the macro (in a place the Player will see it and be able to click it) an API Button call [Button name](~Selected|To-Hit-Spell) which will run the Ability "To-Hit-Spell" on the Character's sheet (which has just been newly written there or updated by the --touch command).

Thus, when the Player casts the Character's spell, power or MI, they can then press the API Button when the macro runs and the attack roll will be made. If successful, the Player can then use the button that appears to mark the target token and apply the spell effect to the target.

See the RoundMaster API documentation for further information on targeting, marking and effects.

[edit] Change the Experience Level

--level-change [token_id]|[# of levels]

Takes an optional Token ID (if not specified, uses the selected token), and an optional number of levels (plus or minus: if not specified assumes -1).

Mainly used for attacks and spell-like effects that drain levels from opponents, this command undertakes all the calculations and Character Sheet updates that can automatically be done when a character or creature changes experience level. Saving throw targets are reassessed, weapon attacks per round recalculated, numbers of memorised spells changed, Race & Class powers checked for level appropriateness, etc. Asks for number of hit points to reduce or add to current and maximum values. If the character is multi- or dual-class, asks which class to add/drain levels to/from and the hit points for each.

[edit] Change an Attribute Value

--change-attr [token_id]|change|[STRENGTH/DEXTERITY/CONSTITUTION/INTELLIGENCE/WISDOM/CHARISMA]

Takes an optional Token ID (if not specified, uses the selected token), and a mandatory change value (plus, minus, or zero), and an optional attribute name (defaults to STRENGTH)

Mainly used to support magical effects and creature attacks that drain or add to attributes such as Strength, this command specifically deals with aspects such as Exceptional Strength, remembering if a Character has exceptional strength as a characteristic and taking it into account as the value is changed. Going up or down from the original rolled value and then back the other way will include as a step the exceptional, percentage value. If the change requested would take the value past the original rolled value, the change will only go as far as the original value, whatever change was requested. However, the change can then continue with subsequent calls to beyond the original value with subsequent calls.

Note:Should the rolled value need to change permanently to a new rolled value, the change value of 0 (zero) will reset the remembered original rolled value to the current value of the attribute - this is not needed the first time the command is used on a character sheet, which will trigger this value to be remembered for the first time.

[edit] Perform Short or Long Rests

--rest [token_id]|[SHORT/LONG]|[MU/PR/MU-PR/POWER/MI/MI-POWER]|[timescale]

Takes an optional token ID (if not specified, uses the selected token), an optional rest type, short or long, an optional magic type to regain charges for, and an optional timescale for days passing.

Most magic requires the character to rest periodically to study spell books, rememorise spells, and regain powers and charges of magic items. This command implements both Short and Long rests.

The type of rest (short or long) can be specified or, if not specified, the system will ask the Player what type of rest is to be undertaken - though Long Rests will be disabled if the Timescale (either the optional value or the character sheet attribute) is not 1 or more days (see below). The type of magic to be affected can also be specified or, if not specified, all types of magic are affected.

A Short rest is deemed to be for 1 hour (though this is not a restriction of the system and is up to the DM), and allows spell casters (such as Wizards and Priests, as well as others) to regain their 1st level spells only. This can happen as often as the DM allows.

A Long rest is considered to be an overnight activity of at least 8 hours (though again this is not a restriction of the system and is up to the DM). A Long rest allows spell casters to regain all their spells, all character and magic item powers to be regained to full uses per day, and for recharging magic items to regain their charges up to their current maximum. After a long rest, ammunition that has been used but not recovered can no longer be recovered using the Ammunition Management command (see AttackMaster API documentation): it is assumed that other creatures will have found the ammo, or it has been broken or otherwise lost in the 8 hours of the long rest.

A Long rest can only be undertaken if certain conditions are met: either the optional Timescale (in days) must be specified as 1 or more days, or the Character Sheet must have a Roll20 attribute called Timescale, current, set to a value of 1 or more (can be set by InitiativeMaster API --end-of-day command). An internal date system is incremented: an attribute on the Character Sheet called In-Game-Day is incremented by the Timescale, and Timescale is then set to 0.

If the InitiativeMaster API is being used, the system will interact with the "End of Day" command to allow rests to be coordinated with the choice of accommodation (and its cost...!) or with earnings made for the day's adventuring.

[edit] Perform a Single Item Rest

--mi-rest [token_id]|mi_name|[charges]|[power_name]

Takes an optional Token ID (defaults to the selected token), a mandatory magic item name (case insensitive), an optional number of charges to recharge to, and an optional power name (case insensitive).

This command restores the powers for a single magic item, or even a single power of a single magic item. If the optional number of charges is specified, this is the number of charges set for the power, otherwise the power is restored to its original max uses. If a power name is specified, and the item has a power of the same name, only that power will be affected. Otherwise, all powers of the item will be restored.


[edit] Treasure & Item container management

[edit] DM/GM version of Magic Item management

--gm-edit-mi [token_id]

Takes an optional token ID. If token ID is not specified, uses the selected token.

This command opens a menu showing all the items in the Items table of the character sheet associated with the specified token. Unlike the Player version of the command (--edit-mi), this command shows all attributes of every magic item, including those of hidden and cursed items, and also offers an additional list of "DM Only" magic items from the magic item databases.

The following functions are available once both a magic item is selected from the lists, and a slot to store it in are selected:

Store item:Select a magic item from the databases and store it in a slot - this is the same as the Player version.
Hide item as different item:The magic item already in the selected bag slot is given the displayed name of the magic item selected from the databases - the Player will only see the Magic Item selected (Displayed Name), and not the hidden actual name. The MI will behave exactly like the selected, displayed item until the DM reverts the item to the hidden version using the [Reset Single MI] button. This is generally used for items in containers, especially Cursed items, so that the real nature of the item is hidden until the character uses it or the DM wants them to. Once an item has been marked as hidden, the DM can see the name it will be displayed to the palyer as by selecting that slot - the displayed name will appear on the menu, and other options for hidden items will become selectable.
Rename MI:Allows the DM to change the actual and displayed name of an item. This will create a unique item (existing item names cannot be used) stored on the character's/container's Character Sheet which will work in exactly the same way as the original item. This can be used to resolve duplicate magic items, such as two rings of spell storing can be given different names. This is different from hiding - the actual name of the item is changed.
Remove MI:Blanks the selected Bag slot, removing all details, both displayed & actual.
Change MI Type:This allows the type of the item in the selected Bag slot to be changed. It can be one of the following - Charged, Discharging, Uncharged, Recharging, Rechargeable, Self-charging, Absorbing, Cursed, Cursed-Charged, Cursed-Self-charging, Cursed-Recharging, Cursed-Absorbing (cursed rechargeable items behave in exactly the same way as Cursed-Charged items). Cursed versions of items cannot be removed from the character's MI Bag, given away, stored or deleted by the Player, even when all their charges are depleted. Otherwise, they act in the same way as other magic items. Charged, Discharging, and Rechargeable items disappear if they reach zero charges, unless preceeded by 'perm-'. Charged, Uncharged and Cursed items can be divided when picked up by Searching or Storing, other types cannot.
Change Displayed Charges:Changes the number of displayed/current charges for the item in the selected Bag slot. This can be used to set the quantity of Uncharged items, or the current charges of other types. It also allows charged items in containers to be stored as a single item, for instance single Wands (current/displayed qty = 1) with multiple charges (max qty = n): when picked up the current qty is always set to the actual value - see the --pickorput command below.
Change Actual Charges:Setting this allows the actual quantity of Uncharged items in containers to be hidden, or the maximum number of charges to be set for other types. When the item is picked up from a container, the actual number of charges will be set as the current value.
Store Spells/Powers in MIOnly enabled for items that can store & cast spells or powers: the item definition must have a call to !magic --cast-spell MI for spell storing, or !magic --cast-spell MI-POWER for powers, associated with an API button. If this is the case, this option opens a menu to select Wizard or Priest spells, or powers as appropriate. A blank Ring-of-Spell-Storing and a blank Scroll-of-Spells are both included in the databases, allowing GMs to build their own unique items and then give them a unique new name using the Rename function described above.
Change Item Cost:Items can have a cost in GP (fractions allowed which get converted to SP & CP). When an item is picked up from a container, the cost will be multiplied by the quantity picked up and the Player will be asked if they want the character to pay the cost. If confirmed, the cost will be deducted from the money values on the character sheet. 0 and negative values are allowed. This supports merchants and shops to be created in the campaign.
Reset Qty to Max:Allows the DM to reset the quantity of the selected Bag slot to the actual (max) values.
Reveal Now:Only available when a hidden item is selected. Reveals the item, setting the displayed name to the actual name, which will function as the revealed item from that point on.
Reveal MIAllows selection of when a hidden item is revealed: MANUALLY by DM (the default) using the Reveal Now button; on VIEWING the item; or on USING the item. From the point the item is revealed onwards, the item will behave as the revealed item.
Edit Treasure:Mainly for use on Magic Item containers, such as Treasure Chests, but also useful for NPCs and Monsters. Allows the DM to add text only treasure descriptions to the container. The displayed menu allows [Add], [Edit], and [Delete] functions to manage multiple lines/rows of treasure description.
Container Type:Sets the type of the Magic Item container or Bag. Available choices are: Empty Inanimate object, Inanimate object with stuff, Sentient Being with empty Bag, Sentient Being with items, Trapped container. If searched, Inanimate objects can be looted without penalty; Sentient beings require a Pick Pockets check; Trapped containers call a Trap ability macro on the container's character sheet to determine the effect. See the --search command below.
Container Size:Sets the maximum number of items that can be stored in the selected Character's/containers bag. The default is 18 items, though identical items can be stacked.
Show As:Sets what level of item description a Player sees when looting a container. Either "Show as Item Types" (e.g. potion, scroll, melee weapon, etc), or "Show as Item Names" (default) which shows the display names of the items. Once picked up from the container, will always show their display names.

[edit] Search tokens for Magic Items and Treasure

--search token_id|pick_id|put_id

Takes a mandatory token ID of the character's token, mandatory token ID of the token to search and pick up items from, mandatory token ID of the token to put picked up items in.

This command can be used to pick the pockets of an NPC or even another Player Character, as well as to loot magic item and treasure containers such as Chests and dead bodies. It can also be used for putting stuff away, storing items from the character's Magic Item Bag into a container, for instance if the MI Bag is getting too full (it is limited to the number of items specified via the --gm-edit-mi menu, though similar items can be stacked). The effect of this command when looting (i.e. the Character's token_id is also the put_id) depends on the Container Type of the searched token set by the DM using the --gm-edit-mi command menu:

Inanimate without items:a message is shown to the Player saying the container is empty or, if there are no Magic Items but there is text describing contained treasure, this will be displayed.
Inanimate with items:the items in the container are displayed, and the character doing the search (associated with the put_id token ID) can pick them up and store them in their own Magic Item Bag.
Sentient being without items:a Pick Pockets check is undertaken - the Player is asked to roll a dice and enter the result (or Roll20 can do it for them), which is compared to the Pick Pockets score on their character sheet. If successful, a message is displayed in the same way as an Inanimate object. If unsuccessful, a further check is made against the level of the being targeted to see if they notice, and the DM is informed either way. The DM can then take whatever action they believe is needed.
Sentient being with items:the Pick Pockets check is done the same way as above, but if successful, the items in the target's Magic Item Bag are displayed and the Player can pick them up and store them in their character's Magic Item Bag.
Trapped container:Traps can be as simple or as complex as the DM desires. Traps may be nothing more than a lock that requires a Player to say they have a specific key, or a combination that has to be chosen from a list, and nothing happens if it is wrong other than the items in the container not being displayed. Or setting it off can have damaging consequences for the character searching or the whole party. It can just be a /whisper gm message to let the DM know that the trapped container has been searched. Searching a trapped container with this command calls an ability macro called "Trap-@{container_name|version}" on the container's character sheet: if this does not exist, it calls an ability macro just called "Trap". The first version allows the Trap macro to change the behaviour on subsequent calls to the Trap functionality (if using the ChatSetAttr API to change the version attribute), for instance to allow the chest to open normally once the trap has been defused or expended. This functionality requires confidence in Roll20 macro programming.
Important Note: all Character Sheets representing Trapped containers must have their 'ControlledBy' value (found under the [Edit] button at the top right of each sheet) set to 'All Players'. Otherwise, Players will not be able to run the macros contained in them that operate the trap!

[edit] Looting without searching, and storing items in a container

--pickorput token_id|pick_id|put_id|[SHORT/LONG]

Takes a mandatory token ID for the Player's character, a mandatory token ID for the token to pick items from, a mandatory token ID for the token to put items in to, and an optional argument specifying whether to use a long or a short menu.

This command displays a menu from which items on the character sheet associated with the Pick token can be selected to put in the character sheet associated with the Put token. The Player's character's token can be either the Put token (if picking up items from a container) or the Pick token (if storing items from their sheet into the container). The other token can be another Player Character (useful for one character giving a magic item to another character) or any other selectable token with a character sheet. No traps or sentient being checks are made by this command - this allows the DM to allow Players to bypass the searching functionality when looting a container or storing items in it. Note: the Player's Magic Item menu (accessed via the --mimenu command) does not have an option to loot without searching, but the Store function on that menu does use this command.

There are two forms of this menu - the Long form displays all items in the container as individual buttons for the Player to select from, and a single button to store the item: this is generally OK when looting containers with not much in them. The Short form of the menu shows only two buttons: one button which, when clicked, brings up a pick list of all the items in the Pick container, and another button to store the item in the Put container: this is generally best for when a character is storing something from their character sheet items into a chest or other container, or giving an MI to another character, as a character's sheet often has many items in it which can make a Long menu very long. Each type of menu has a button on it to switch to the other type of menu without re-issuing the command. If not specified in the command, the type of menu the Player last used in this campaign is remembered and used by the system.


[edit] Light source management

These functions use Roll20 Dynamic Lighting to provide a token with a light source. If your campaign does not use Dynamic Lighting, they will not function. They can also be accessed through the menu displayed by the AttackMaster API !attk --other-menu command.

[edit] how a menu of Light Sources to select from

--lightsources [token_id]

Takes an optional token ID as an argument. If token ID is not specified, uses the selected token.

This command brings up a menu showing a selection of various light sources that a character can use. Selecting one will change the Roll20 Dynamic Lighting values on the Token identified to provide this lighting effect. These are:

  • Magic Weapon or Magical Armour (5ft radius circle),
  • Torch (15ft radius circle),
  • Hooded Lantern (30ft radius circle),
  • Continual Light lantern (60ft radius circle),
  • Bullseye Lantern (cone of light, 20 degrees wide and 60ft long),
  • Beacon Lantern (cone of light, 20 degrees wide and 240ft long).

The menu shows [ON] and [OFF] buttons for each type. Only one type can be ON for each Token: selecting an ON button for any light source turns OFF the others for that Token. Turning the current light source off will turn off all lighting effects on the identified token.

[edit] Set a lightsource for a token

--light token_id|(NONE/WEAPON/TORCH/HOODED/CONTLIGHT/BULLSEYE/BEACON)

Takes a mandatory token ID, and a mandatory type of light source.

This command sets the light source type that the identified token is using, and changes the Roll20 Dynamic Lighting settings of the token to the relevant value shown under section 5.1, or turn off all lighting effects for the selected token if NONE is specified.


[edit] Other commands

[edit] Display help on these commands

--help

This command does not take any arguments. It displays the mandatory and optional arguments, and a brief description of each command.

[edit] Display a formatted message in chat

--message [who|][token_id]|title|message

This command takes an optional parameter stating who to send the message to, which defaults to depending on who owns the character represented by the token, an optional token_id which defaults to a selected token, a title for the message which can be an empty string, and the message to display.

The "who" parameter can be one of:

gmSend only to the GM
whisperSend only to the players that control the character represented by the token
wShort for "whisper" and does the same
publicSend to all players and the GM
standardCheck which players/GMs control the character represented by the token. If the GM controls, or no-one, or the controlling player is not on-line, or the token does not represent a character, send to the GM; otherise make public.
Anything elseSame as Standard

[edit] Tidy one or more character sheets

--tidy [token_id]

This command takes an optional token_id. If not specified, the command will act on the character sheets represented by all currently selected tokens.

This command tidies up the character sheet, removing Spell and Magic Item attribute and ability objects that are no longer for items held, and for spells no longer in any spell book. Attack ability objects will also all be removed. All of these will be recreated as and when these items, spells or attacks are again picked up, added to spell books, or used for attacks. This simplifies and speeds up the system, removing redundant processing and memory usage.

Note: this command is automatically run whenever the DM moves the "Player Ribbon" to a new map page, for every token on that map page that represents a character sheet, and also whenever a character token is dragged onto the active Player page. This continually tidies the system while not imposing a heavy overhead on processing.

[edit] Configure API behavior

--config [FANCY-MENUS/SPECIALIST-RULES/SPELL-NUM/ALL-SPELLS] | [TRUE/FALSE]

Takes two optional arguments, the first a switchable flag name, and the second TRUE or FALSE.

Allows configuration of several API behaviors. If no arguments given, displays menu for DM to select configuration. Parameters have the following effects:

<thead></thead>
FlagTrueFalse
FANCY-MENUSUse chat menus with a textured backgroundUse chat menus with a plain background
SPECIALIST-RULESOnly Specialist Wizards specified in the PHB get an extra spell per spell levelAny non-Standard Wizard gets an extra spell per spell level
SPELL-NUMSpellcaster spells per level restricted to PHB rulesSpellcaster spells per level alterable using Misc Spells button
ALL-SPELLSSpellcaster spell schools are unrestrictedSpellcaster spell schools are restricted by class rules

[edit] Check database completeness & integrity (GM only)

--check-db [ db-name ]

Takes an optional database name or part of a database name: if a partial name, checks all character sheets with the provided text in their name that also have '-db' as part of their name. If omitted, checks all character sheets with '-db' in the name. Not case sensitive. Can only be used by the GM.

This command finds all databases that match the name or partial name provided (not case sensitive), and checks them for completeness and integrity. The command does not alter any ability macros, but ensures that the casting time ('ct-') attributes are correctly created, that the item lists are sorted and complete, and that any item-specific power & spell specifications are correctly built and saved.

This command is very useful to run after creating/adding new items as ability macros to the databases (see specific database documentation). It does not check if the ability macro definition itself is valid, but if it is then it ensures all other aspects of the database consistently reflect the new ability(s).

[edit] Extract database for Editing

--extract-db [db-name]

Takes an optional database name or part of a database name: if a partial name, extracts all character sheets with the provided text in their name that also have '-db' as part of their name. If omitted, checks all character sheets with '-db' in the name. Not case sensitive. Can only be used by the GM.

Extracts a named database or all provided databases from the loaded RPGMaster Library, and builds the database(s) in a Character Sheet format: see the Database specific help handouts for further details of this format. This allows editing of the standard items in the databases, adding additional items to the databases, or for items to be copied into the GM's own databases. Unlike with previous versions of the Master Series APIs, these extracted databases will not be overwritten automatically by the system. However: using extracted databases will slow the system down - the use of the internal API databases held in memory is much faster. The best use for these extracts is to examine how various items have been programmed so that the GM can create variations of the standard items in their own databases by copying and making small alterations to the definitions, and then the extracted databases can be deleted.

Important: Once a Character Sheet database is changed or deleted, run the !magic --check-db command against any database (especially a changed one) to prompt the APIs to re-index the objects in all databases.

[edit] Handshake with other APIs

-hsq from|[command]<br>
-handshake from|[command]

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 command calls the from API command responding with its own command to confirm that this API is loaded and running: e.g.

Received:</dt>
!magic -hsq init</dd>
Response:</dt>
!init -hsr magic</dd>

Optionally, a command query can be made to see if the command is supported by MagicMaster if the command string parameter is added, where command is the MagicMaster command (the '--' text without the '--'). This will respond with a true/false response: e.g.

Received:</dt>
!magic -handshake init|menu</dd>
Response:</dt>
!init -hsr magic|menu|true</dd>

[edit] Switch on or off Debug mode

--debug (ON/OFF)

Takes one mandatory argument which should be ON or OFF.

The command turns on a verbose diagnostic mode for the API which will trace what commands are being processed, including internal commands, what attributes are being set and changed, and more detail about any errors that are occurring. The command can be used by the DM or any Player - so the DM or a technical advisor can play as a Player and see the debugging messages.