Latest revision as of 21:10, 10 June 2023

Page Updated:   2023-06-10

Main Page: API:Script Index

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.

[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

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

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.

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:

[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:

[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:

[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:

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