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:RPGMaster Library"

From Roll20 Wiki

Jump to: navigation, search
m
 
(One intermediate revision by one user not shown)
Line 3: Line 3:
 
|name=RPGMaster Library
 
|name=RPGMaster Library
 
|author=[[Richard E]]
 
|author=[[Richard E]]
|version=1.3.01
+
|version=1.5.01
|lastmodified=2022-10-10
+
|lastmodified=2023-05-17
 
|code=RPGMlibrary AD+D2e
 
|code=RPGMlibrary AD+D2e
 
|dependencies=None
 
|dependencies=None
Line 13: Line 13:
 
Some of the APIs can be used with other sheets.
 
Some of the APIs can be used with other sheets.
 
===Forum===
 
===Forum===
[https://app.roll20.net/forum/post/10607093/script-rpgmaster-apis-for-ad-and-d-2e RPGMaster APIs for AD&D 2E] - old frozen forum thread
 
 
[https://app.roll20.net/forum/post/11115777/script-rpgmaster-apis-for-ad-and-d-2e RPGMaster APIs for AD&D 2E] - main forum thread
 
[https://app.roll20.net/forum/post/11115777/script-rpgmaster-apis-for-ad-and-d-2e RPGMaster APIs for AD&D 2E] - main forum thread
  
Line 25: Line 24:
 
==General RPGMaster Library information==
 
==General RPGMaster Library information==
 
<p>The RPGMaster Library API provides the data and rule-set processing for a specific RPG version and Roll20 Character Sheet for the RPGMaster series of APIs. This particular Library supports the Advanced Dungeons and Dragons v2e RPG, and the Advanced D&D 2e Character Sheet by Peter B.</p>
 
<p>The RPGMaster Library API provides the data and rule-set processing for a specific RPG version and Roll20 Character Sheet for the RPGMaster series of APIs. This particular Library supports the Advanced Dungeons and Dragons v2e RPG, and the Advanced D&D 2e Character Sheet by Peter B.</p>
<p>The functions and data in the Library cannot be accessed directly by the GM or Players (with the exception of the RPGMaster Roll Templates). It does not support any API commands directly, but supports the functioning of the API commands provided by other RPGMaster APIs: <b>[[Script:InitiativeMaster]], [[Script:AttackMaster]], [[Script:MagicMaster]]</b> and <b>[[Script:CommandMaster]]</b>, to the extent that these APIs will not function without the Library being loaded. <b>Note:</b> RoundMaster does not have any RPG-version specific aspects, is independent of the Library, and does not require a RPGMaster Library to be loaded to function.</p>
+
<p>The functions and data in the Library cannot be accessed directly by the GM or Players (with the exception of the RPGMaster Roll Templates). It does not support any API commands directly, but supports the functioning of the API commands provided by other RPGMaster APIs: <b>InitiativeMaster, AttackMaster, MagicMaster</b> and <b>CommandMaster</b>, to the extent that these APIs will not function without the Library being loaded. <b>Note:</b> RoundMaster does not have any RPG-version specific aspects, is independent of the Library, and does not require a RPGMaster Library to be loaded to function.</p>
 
<p>The Library does Roll Template processing for RPGMaster-defined Roll Templates. These can be used by GMs to create their own Chat menus and displays.  See the descriptions in Section 2 for how to access and use these templates.</p>
 
<p>The Library does Roll Template processing for RPGMaster-defined Roll Templates. These can be used by GMs to create their own Chat menus and displays.  See the descriptions in Section 2 for how to access and use these templates.</p>
 
<p>The Library also provides a number of objects and functions that can be called from other APIs. These include an extensive Character Sheet table management suite described in Section 3 below, for table structures defined by The Aaron in various standard Roll20 Character Sheets, such as the Advanced D&D 2e character sheet by Peter B. There are a number of other useful functions, which are described in Section 3.</p>
 
<p>The Library also provides a number of objects and functions that can be called from other APIs. These include an extensive Character Sheet table management suite described in Section 3 below, for table structures defined by The Aaron in various standard Roll20 Character Sheets, such as the Advanced D&D 2e character sheet by Peter B. There are a number of other useful functions, which are described in Section 3.</p>
<br>
 
  
 
==RPGMaster Roll Templates==
 
==RPGMaster Roll Templates==
Line 52: Line 50:
 
<p>The templates are built upon four base templates: <i>RPGMattack, RPGMspell, RPGMmessage,</i> and <i>RPGMdefault</i>. However, each individual template can have different colour swatches and background images. It is also possible for the GM to use special template field tags to change the colours and background images of various parts of the templates, as described below.</p>
 
<p>The templates are built upon four base templates: <i>RPGMattack, RPGMspell, RPGMmessage,</i> and <i>RPGMdefault</i>. However, each individual template can have different colour swatches and background images. It is also possible for the GM to use special template field tags to change the colours and background images of various parts of the templates, as described below.</p>
 
===User-Selectable Template Display Options===
 
===User-Selectable Template Display Options===
[[File:RPGM Player Template options.jpeg|thumb|289px|right|Player-selectable template display options]]
 
 
<p>In the API configuration menu, opened using <b>!attk --config</b> or <b>!magic --config</b>, the GM can choose whether the default display of RPGMaster Roll Templates for everyone is <i>Fancy</i>, meaning the system uses background textures and images to make the chat templates look interesting, or <i>Plain</i>, which means the default display is of coloured templates but without textures or images.</p>
 
<p>In the API configuration menu, opened using <b>!attk --config</b> or <b>!magic --config</b>, the GM can choose whether the default display of RPGMaster Roll Templates for everyone is <i>Fancy</i>, meaning the system uses background textures and images to make the chat templates look interesting, or <i>Plain</i>, which means the default display is of coloured templates but without textures or images.</p>
<p>In addition, each Player can choose their own options: at the right of the Title of every menu or message displayed in the chat using a RPGMaster Template is a cog wheel {{gear}}. Clicking this cog wheel will display an options dialog for the Player with three options - Menus with Images, Plain Menus, and Dark Mode Menus. The Player can select one of the options, and the current and all future menus and messages using RPGMaster Roll Templates will be displayed for that particular Player using this new option. The option persists for that Player between gameplay sessions.</p>
+
<p>In addition, each Player can choose their own options: at the top right of every menu or message displayed in the chat using a RPGMaster Template is a cog wheel. Clicking this cog wheel will display an options dialog for the Player with three options - Menus with Images, Plain Menus, and Dark Mode Menus. The Player can select one of the options, and the current and all future menus and messages using RPGMaster Roll Templates will be displayed for that particular Player using this new option. The option persists for that Player between gameplay sessions.</p>
 
<p><b>Note:</b> if use of a template includes any of the colour or image field tags (<i>outer image, title image</i> or <i>body image</i>) these images will always appear regardless of which option the Player chooses. The field tags always override the original template definition.</p>
 
<p><b>Note:</b> if use of a template includes any of the colour or image field tags (<i>outer image, title image</i> or <i>body image</i>) these images will always appear regardless of which option the Player chooses. The field tags always override the original template definition.</p>
<br><br><br><br><br><br><br><br><br>
 
 
 
===Colour, Padding and Image Override Field Tags===
 
===Colour, Padding and Image Override Field Tags===
 
<p>All RPGMaster templates can use the following field tags (with some exceptions as noted). The field tags are used in this way:</p>
 
<p>All RPGMaster templates can use the following field tags (with some exceptions as noted). The field tags are used in this way:</p>
 
<pre>{{field tag=... whatever you want to be in this field ...}}</pre>
 
<pre>{{field tag=... whatever you want to be in this field ...}}</pre>
<p>However, the field tags in this table do not display data, but take the content of the field after the "=" as data for a CSS command to change the behavior of the template.</p>
+
<p>However, the fields in this table do not display data, but take the content of the field after the "=" as data for a CSS command to change the behavior of the template.</p>
[[File:RPGM Oil Flask Attack Template.jpeg|thumb|289px|right|RPGMattack Roll Template using custom "title image" field-tag]]
+
 
<table>
 
<table>
 
<tr><th scope="row">shadow</th><td>drop shadow spec</td><td>The specification of the Template drop shadow for the outer box in any form of CSS units</td></tr>
 
<tr><th scope="row">shadow</th><td>drop shadow spec</td><td>The specification of the Template drop shadow for the outer box in any form of CSS units</td></tr>
Line 83: Line 77:
 
</table>
 
</table>
 
<p>The data passed with these field tags is one of four types: <i>color, padding spec, shadow spec</i> or <i>image URL</i>. Note, the CSS keyword is not needed in each case, just the data specification that would follow the keyword.</p>
 
<p>The data passed with these field tags is one of four types: <i>color, padding spec, shadow spec</i> or <i>image URL</i>. Note, the CSS keyword is not needed in each case, just the data specification that would follow the keyword.</p>
<p><b>Tip:</b> <i>In fact, you can sneak additional CSS keywords into the data - e.g. the <b>title text</b> colour could be <code>title text=white; text-shadow: 1px 1px 1px gray</code> which would sneak a drop-shadow onto the title text of the Template. This will not always work, but is worth trying.</i></p>
+
<p><b>Tip:</b> <i>In fact, you can sneak additional CSS keywords into the data - e.g. the <b>title text</b> colour could be '{{title text=white; text-shadow: 1px 1px 1px gray}}' which would sneak a drop-shadow onto the title text of the Template. This will not always work, but is worth trying.</i></p>
 
<table>
 
<table>
 
<tr><th scope="row">color</th><td>Can be any valid < color > specification that can be placed after a CSS < color > command: a named color, a RGB specification, a HSL specification, or any other valid syntax.</td></tr>
 
<tr><th scope="row">color</th><td>Can be any valid < color > specification that can be placed after a CSS < color > command: a named color, a RGB specification, a HSL specification, or any other valid syntax.</td></tr>
Line 90: Line 84:
 
<tr><th scope="row">Image URL</th><td>Must be a valid URL of a thumbnail image already loaded to the Roll20 image library - either your own or one you are provided with.</td></tr>
 
<tr><th scope="row">Image URL</th><td>Must be a valid URL of a thumbnail image already loaded to the Roll20 image library - either your own or one you are provided with.</td></tr>
 
</table>
 
</table>
<br>
 
 
 
===Template Definitions===
 
===Template Definitions===
<h3>RPGMattack</h3>
+
====RPGMattack====
 
<p>As with any template, the text in any of the fields can be anything allowed by Roll20 in a macro or template, except where noted otherwise. If to be used with a RPGMaster API database, the <i>Specs</i> and <i>Data</i> fields must be configured in line with the relevant database documentation and placed <i>between</i> the template fields so as not to be seen by the Players when the Roll Template is displayed. This is a highly graphical template (even in Plain Mode) and the Field Tags are generally not displayed.</p>
 
<p>As with any template, the text in any of the fields can be anything allowed by Roll20 in a macro or template, except where noted otherwise. If to be used with a RPGMaster API database, the <i>Specs</i> and <i>Data</i> fields must be configured in line with the relevant database documentation and placed <i>between</i> the template fields so as not to be seen by the Players when the Roll Template is displayed. This is a highly graphical template (even in Plain Mode) and the Field Tags are generally not displayed.</p>
[[File:RPGM Std Attack Template.jpeg|thumb|289px|left|RPGMattack Roll Template]] [[File:RPGM Targeted Attack Template.jpeg|thumb|289px|left|Targeted RPGMattack Roll Template]]
 
 
<table>
 
<table>
 
<tr><th scope="row">Title / Name</th><td>Mandatory</td><td>The title text for the attack template. Either field tag can be used, and the tag is not displayed.</td></tr>
 
<tr><th scope="row">Title / Name</th><td>Mandatory</td><td>The title text for the attack template. Either field tag can be used, and the tag is not displayed.</td></tr>
Line 112: Line 103:
 
<tr><th scope="row">Target MaxHP</th><td>Optional</td><td>The maximum Hit Points of the targeted opponent. Must result in a numeric value.</td></tr>
 
<tr><th scope="row">Target MaxHP</th><td>Optional</td><td>The maximum Hit Points of the targeted opponent. Must result in a numeric value.</td></tr>
 
<tr><th scope="row">Result</th><td>Optional</td><td>A comparison function between any two other field tags, which are usually AC_Hit and Target_AC (note the underscores added). Can use any test from: = < > <= >= <> != e.g. AC_Hit<=Target_AC if true will give a green Success bar, if false will give a red Failure.</td></tr>
 
<tr><th scope="row">Result</th><td>Optional</td><td>A comparison function between any two other field tags, which are usually AC_Hit and Target_AC (note the underscores added). Can use any test from: = < > <= >= <> != e.g. AC_Hit<=Target_AC if true will give a green Success bar, if false will give a red Failure.</td></tr>
 +
<tr><th scope="row">SuccessCmd</th><td>Optional</td><td>The text provided will not be displayed but will be sent to the chat window if the <i>Result</i> comparison indicates success. Normally used to send an API command on a successful attack result</td></tr>
 +
<tr><th scope="row">FailCmd</th><td>Optional</td><td>The text provided will not be displayed but will be sent to the chat window if the <i>Result</i> comparison indicates failure. Normally used to send an API command on a failed attack result</td></tr>
 
<tr><th scope="row">Crit Roll</th><td>Optional</td><td>Data must result in a numeric value which is compared to the Dice Roll value tagged in the AC Hit field. If Crit_roll<=Dice Roll, displays a green "Critical Hit!" bar.</td></tr>
 
<tr><th scope="row">Crit Roll</th><td>Optional</td><td>Data must result in a numeric value which is compared to the Dice Roll value tagged in the AC Hit field. If Crit_roll<=Dice Roll, displays a green "Critical Hit!" bar.</td></tr>
 
<tr><th scope="row">Fumble Roll</th><td>Optional</td><td>Data must result in a numeric value which is compared to the Dice Roll value tagged in the AC Hit field. If Fumble_roll>=Dice Roll, displays a red "Fumbled!" bar.</td></tr>
 
<tr><th scope="row">Fumble Roll</th><td>Optional</td><td>Data must result in a numeric value which is compared to the Dice Roll value tagged in the AC Hit field. If Fumble_roll>=Dice Roll, displays a red "Fumbled!" bar.</td></tr>
 
<tr><th scope="row">Desc / Desc(1-9)</th><td>Optional</td><td>Up to 10 description fields can be added to the bottom of any RPGMaster attack template. The field tag is not displayed. These can, for example, hold reminders of special outcomes of the attack depending on the weapon or creature wielding it, or the roll achieved.</td></tr>
 
<tr><th scope="row">Desc / Desc(1-9)</th><td>Optional</td><td>Up to 10 description fields can be added to the bottom of any RPGMaster attack template. The field tag is not displayed. These can, for example, hold reminders of special outcomes of the attack depending on the weapon or creature wielding it, or the roll achieved.</td></tr>
 
</table>
 
</table>
<br>
+
====RPGMspell, RPGMpotion & RPGMscroll====
<h3>RPGMspell, RPGMpotion & RPGMscroll</h3>
+
<p>As with any template, the text in any of the fields can be anything allowed by Roll20 in a macro or template, except where noted otherwise. For spell, potion and scroll descriptions especially it is quite often useful to include API Buttons in some of the fields to run certain RPGMaster API commands: this is especially the case if using the <b>RoundMaster API</b> and the commands <b>!rounds --target</b> to set status markers and timers and target spell effects, and/or <b>!rounds --aoe</b> to display ranges and areas of effect. If to be used with a RPGMaster API database, the <i>Specs</i> and <i>Data</i> fields must be configured in line with the relevant database documentation and placed <i>between</i> the template fields so as not to be seen by the Players when the Roll Template is displayed.</p>
[[File:RPGM Spell Template.jpeg|thumb|280px|left|RPGMspell Roll Template]] [[File:RPGM Potion Template.jpeg|thumb|280px|left|RPGMpotion Roll Template]]
+
<p>As with any template, the text in any of the fields can be anything allowed by Roll20 in a macro or template, except where noted otherwise. For spell, potion and scroll descriptions especially it is quite often useful to include API Buttons in some of the fields to run certain RPGMaster API commands: this is especially the case if using the <b>[[Script:RoundMaster]] API</b> and the commands <b>!rounds --target</b> to set status markers and timers and target spell effects, and/or <b>!rounds --aoe</b> to display ranges and areas of effect. If to be used with a RPGMaster API database, the <i>Specs</i> and <i>Data</i> fields must be configured in line with the relevant database documentation and placed <i>between</i> the template fields so as not to be seen by the Players when the Roll Template is displayed.</p>
+
 
<table>
 
<table>
 
<tr><th scope="row">Title / Name</th><td>Mandatory</td><td>The title text for the template. Either field tag can be used, and is not displayed.</td></tr>
 
<tr><th scope="row">Title / Name</th><td>Mandatory</td><td>The title text for the template. Either field tag can be used, and is not displayed.</td></tr>
Line 135: Line 126:
 
<tr><th scope="row">Reference</th><td>Optional</td><td>A reference to where more information can be found about the spell or spell-like effect.</td></tr>
 
<tr><th scope="row">Reference</th><td>Optional</td><td>A reference to where more information can be found about the spell or spell-like effect.</td></tr>
 
<tr><th scope="row">Materials</th><td>Optional</td><td>The material components required to cast the spell or spell-like effect.</td></tr>
 
<tr><th scope="row">Materials</th><td>Optional</td><td>The material components required to cast the spell or spell-like effect.</td></tr>
 +
<tr><th scope="row">Looks Like</th><td>Optional</td><td>A description of what the item looks like (for potions & scrolls), especially useful for <i>hidden</i> items.</td></tr>
 
<tr><th scope="row">Effects</th><td>Optional</td><td>A description of the effects of the spell or spell-like effect.</td></tr>
 
<tr><th scope="row">Effects</th><td>Optional</td><td>A description of the effects of the spell or spell-like effect.</td></tr>
 
<tr><th scope="row">Use</th><td>Optional</td><td>Instructions for how to use the spell or spell-like effect. Especially useful for complex spells that require actions to occur in a particular sequence, have different means of achieving different effects in different circumstances, or have long-lasting effects.</td></tr>
 
<tr><th scope="row">Use</th><td>Optional</td><td>Instructions for how to use the spell or spell-like effect. Especially useful for complex spells that require actions to occur in a particular sequence, have different means of achieving different effects in different circumstances, or have long-lasting effects.</td></tr>
 +
<tr><th scope="row">GM Info</th><td>Optional</td><td>Only appears if the message is for the GM (though other players included in the same message will also see it). Instructions for the GM on how to use the spell or spell-like effect, such as how to tailor for your own campaigns.</td></tr>
 
<tr><th scope="row">Desc / Desc(1-9)</th><td>Optional</td><td>Up to 10 description fields can be added to the bottom of any RPGMaster spell, potion or scroll template. The field tag is not displayed. These can, for example, hold reminders of special outcomes of the spell depending on the creature targeted, or anything else the GM thinks useful but does not fit in any other field.</td></tr>
 
<tr><th scope="row">Desc / Desc(1-9)</th><td>Optional</td><td>Up to 10 description fields can be added to the bottom of any RPGMaster spell, potion or scroll template. The field tag is not displayed. These can, for example, hold reminders of special outcomes of the spell depending on the creature targeted, or anything else the GM thinks useful but does not fit in any other field.</td></tr>
 
</table>
 
</table>
<br>
+
====RPGMmessage====
<h3>RPGMmessage</h3>
+
 
<p>This template is mostly used internally by the RPGMaster APIs to send messages to the GM and Players. It provides a very simple template with a minimum of overhead. As with any template, the text in any of the fields can be anything allowed by Roll20 in a macro or template, except where noted otherwise. If to be used with a RPGMaster API database, the <i>Specs</i> and <i>Data</i> fields must be configured in line with the relevant database documentation and placed <i>between</i> the template fields so as not to be seen by the Players when the Roll Template is displayed.</p>
 
<p>This template is mostly used internally by the RPGMaster APIs to send messages to the GM and Players. It provides a very simple template with a minimum of overhead. As with any template, the text in any of the fields can be anything allowed by Roll20 in a macro or template, except where noted otherwise. If to be used with a RPGMaster API database, the <i>Specs</i> and <i>Data</i> fields must be configured in line with the relevant database documentation and placed <i>between</i> the template fields so as not to be seen by the Players when the Roll Template is displayed.</p>
 
<table>
 
<table>
Line 146: Line 138:
 
<tr><th scope="row">Desc / Desc(1-9)</th><td>Optional</td><td>Up to 10 description fields can be defined, though usually it is just the one, which will contain the message. The field tag is not displayed.</td></tr>
 
<tr><th scope="row">Desc / Desc(1-9)</th><td>Optional</td><td>Up to 10 description fields can be defined, though usually it is just the one, which will contain the message. The field tag is not displayed.</td></tr>
 
</table>
 
</table>
<br><br><br>
+
====RPGMdefault====
<h3>RPGMdefault</h3>
+
[[File:RPGM Weapon Template.jpeg|thumb|280px|left|RPGMweapon Roll Template]] [[File:RPGM Default Template.jpeg|thumb|280px|right|RPGMdefault Roll Template]]
+
 
<p>All template definitions other than those described above use the base RPGMdefault template structure, with different colour swatches, textures and images. This template type is the most flexible, and will display pretty much any field tag that is added. Only a few are predefined, which provide the ability to structure the template. As with any template, the text in any of the fields can be anything allowed by Roll20 in a macro or template, except where noted otherwise. If to be used with a RPGMaster API database, the <i>Specs</i> and <i>Data</i> fields must be configured in line with the relevant database documentation and placed <i>between</i> the template fields so as not to be seen by the Players when the Roll Template is displayed.</p>
 
<p>All template definitions other than those described above use the base RPGMdefault template structure, with different colour swatches, textures and images. This template type is the most flexible, and will display pretty much any field tag that is added. Only a few are predefined, which provide the ability to structure the template. As with any template, the text in any of the fields can be anything allowed by Roll20 in a macro or template, except where noted otherwise. If to be used with a RPGMaster API database, the <i>Specs</i> and <i>Data</i> fields must be configured in line with the relevant database documentation and placed <i>between</i> the template fields so as not to be seen by the Players when the Roll Template is displayed.</p>
 
<table>
 
<table>
Line 155: Line 145:
 
<tr><th scope="row">Section / Section(1-9)</th><td>Optional</td><td>A section header, separating other user-defined field tags (not the Desc description field tags, which always appear at the bottom of the template). The field tag is not displayed, and the contents are centred in the row.</td></tr>
 
<tr><th scope="row">Section / Section(1-9)</th><td>Optional</td><td>A section header, separating other user-defined field tags (not the Desc description field tags, which always appear at the bottom of the template). The field tag is not displayed, and the contents are centred in the row.</td></tr>
 
<tr><th scope="row">Any User-defined tag</th><td>Optional</td><td>As many different user-defined field tags as are desired, using A-Z a-z - _ 0-9 and Space but always starting with an Alpha.</td></tr>
 
<tr><th scope="row">Any User-defined tag</th><td>Optional</td><td>As many different user-defined field tags as are desired, using A-Z a-z - _ 0-9 and Space but always starting with an Alpha.</td></tr>
<tr><th scope="row">Result</th><td>Optional</td><td>A comparison function between any two other field tags which have numeric data or calculations and attribute look-ups that result in numeric data. The field tag names to be compared should have underscores \'_\' instead of spaces. Can use any test from: = < > <= >= <> != e.g. AC_Hit<=Target_AC if true will give a green Success bar, if false will give a red Failure.</td></tr>
+
<tr><th scope="row">Result</th><td>Optional</td><td>A comparison function between any two other field tags which have numeric data or calculations and attribute look-ups that result in numeric data. The field tag names to be compared should have underscores '_' instead of spaces. Can use any test from: = < > <= >= <> != e.g. AC_Hit<=Target_AC if true will give a green Success bar, if false will give a red Failure.</td></tr>
 +
<tr><th scope="row">SuccessCmd</th><td>Optional</td><td>The text provided will not be displayed but will be sent to the chat window if the <i>Result</i> comparison indicates success. Normally used to send an API command on a successful attack result</td></tr>
 +
<tr><th scope="row">FailCmd</th><td>Optional</td><td>The text provided will not be displayed but will be sent to the chat window if the <i>Result</i> comparison indicates failure. Normally used to send an API command on a failed attack result</td></tr>
 +
<tr><th scope="row">GM Info</th><td>Optional</td><td>Only appears if the message is for the GM (though other players included in the same message will also see it). Instructions for the GM on whatever the roll template is about, such as how to tailor a magic item for your own campaigns.</td></tr>
 +
<tr><th scope="row">Looks Like</th><td>Optional</td><td>A description of what the item looks like, especially useful for <i>hidden</i> items.</td></tr>
 
<tr><th scope="row">Desc / Desc(1-9)</th><td>Optional</td><td>Up to 10 description fields can be defined, which will all be displayed at the bottom of the template in numeric order. The field tags are not displayed.</td></tr>
 
<tr><th scope="row">Desc / Desc(1-9)</th><td>Optional</td><td>Up to 10 description fields can be defined, which will all be displayed at the bottom of the template in numeric order. The field tags are not displayed.</td></tr>
 
</table>
 
</table>
<br>
 
 
 
==API Library Accessible Functions==
 
==API Library Accessible Functions==
 
<p>In addition to the RPGM Templates described in Section 2, the RPGMaster Library provides a number of functions, objects and methods that might be of use to API authors, independantly of the RPGMaster series of APIs. These are described in this section. To access these, the functions can be accessed using the following syntax from other APIs:</p>
 
<p>In addition to the RPGM Templates described in Section 2, the RPGMaster Library provides a number of functions, objects and methods that might be of use to API authors, independantly of the RPGMaster series of APIs. These are described in this section. To access these, the functions can be accessed using the following syntax from other APIs:</p>
Line 172: Line 164:
 
<p>This function does not take any parameters, but returns an array of two object references:</p>
 
<p>This function does not take any parameters, but returns an array of two object references:</p>
 
<ul>
 
<ul>
<li><b>fields:</b> A reference for the object mapping standard internal API field names to the definitions for those fields on the supported Character Sheet. Using this field map means the programming of the API does not need to change for each Character Sheet. Each field definition has the structure<br>
+
<li><b>fields:</b> A reference for the object mapping standard internal API field names to the definitions for those fields on the supported Character Sheet. Using this field map means the programming of the API does not need to change for each Character Sheet. Each field definition has the structure<br>
<pre>api_field_name: [char_sheet_field_name,property,defaultValue,sheetWorkerFlag]</pre>
+
<pre>api_field_name: [char_sheet_field_name,property,<defaultValue>,<sheetWorkerFlag>]</pre>
where property is <i>current</i> or <i>max</i> and sheetWorkerFlag (optional) is true if the field is to be set with the Roll20 setWithSheetWorker() method or false if the Roll20 set() method is to be used (default false).</li>
+
where property is <i>current</i> or <i>max</i>, an optional <i>defaultValue</i> can be provided which is used if the field is <i>undefined</i> when read, and the sheetWorkerFlag (optional) is true if the field is to be set with the Roll20 setWithSheetWorker() method or false if the Roll20 set() method is to be used (default false).<br></li>
<li><b>RPGMap:</b> a reference to an object with handles to each of the global data items available in the Library. The contents of these data items are specific to the versions of the RPG and Character Sheet supported by the Library. The data is as in the table below:</li>
+
<li><b>RPGMap:</b> a reference to an object with handles to each of the global data items available in the Library. The contents of these data items are specific to the versions of the RPG and Character Sheet supported by the Library. The data is as in the table below:</li>
 
</ul>
 
</ul>
 
<table>
 
<table>
<tr><th scope="row">dbNames</th><td>An array of the database objects of the standard, RPGMaster provided databases, indexed by name.</td></tr>
+
<tr><th scope="row">dbNames</th><td>An array of the database objects of the standard, RPGMaster provided databases, indexed by name.</td></tr>
<tr><th scope="row">fieldGroups</th><td>An object defining the groups of fields held in repeating tables on the Character Sheet and named in the <i>fields</i> object</td></tr>
+
<tr><th scope="row">fieldGroups</th><td>An object defining the groups of fields held in repeating tables on the Character Sheet and named in the <i>fields</i> object</td></tr>
<tr><th scope="row">spellsPerLevel</th><td>An object specifying the number of spells that can be memorised at each level by each class of spellcaster</td></tr>
+
<tr><th scope="row">spellsPerLevel</th><td>An object specifying the number of spells that can be memorised at each level by each class of spellcaster</td></tr>
<tr><th scope="row">specMU</th><td>An array of strings naming the standard specialist wizard classes for this RPG version</td></tr>
+
<tr><th scope="row">specMU</th><td>An array of strings naming the standard specialist wizard classes for this RPG version</td></tr>
<tr><th scope="row">ordMU</th><td>An array of strings naming the standard ordinary wizard classes for this RPG version</td></tr>
+
<tr><th scope="row">ordMU</th><td>An array of strings naming the standard ordinary wizard classes for this RPG version</td></tr>
<tr><th scope="row">wisdomSpells</th><td>An array holding the additional spell slots or points per level for high wisdom scores</td></tr>
+
<tr><th scope="row">wisdomSpells</th><td>An array holding the additional spell slots or points per level for high wisdom scores</td></tr>
<tr><th scope="row">raceToHitMods</th><td>An object of race toHit modifiers with various weapon types and super-types</td></tr>
+
<tr><th scope="row">raceToHitMods</th><td>An object of race toHit modifiers with various weapon types and super-types</td></tr>
<tr><th scope="row">rangedWeapMods</th><td>The standard range mods to the toHit roll for firing ranged weapons at <i>Near, Point Blank, Short, Medium, Long</i> and <i>Far</i> ranges for this RPG version</td></tr>
+
<tr><th scope="row">rangedWeapMods</th><td>The standard range mods to the toHit roll for firing ranged weapons at <i>Near, Point Blank, Short, Medium, Long</i> and <i>Far</i> ranges for this RPG version</td></tr>
<tr><th scope="row">saveLevels</th><td>An object mapping class levels to the <i>baseSaves</i> table saving throw entries</td></tr>
+
<tr><th scope="row">saveLevels</th><td>An object mapping class levels to the <i>baseSaves</i> table saving throw entries</td></tr>
<tr><th scope="row">baseSaves</th><td>An object holding for each base class an array of base saving throws with improvement by level progression mapped by <i>saveLevels</i></td></tr>
+
<tr><th scope="row">baseSaves</th><td>An object holding for each base class an array of base saving throws with improvement by level progression mapped by <i>saveLevels</i></td></tr>
<tr><th scope="row">classSaveMods</th><td>An object of class modifiers to the base saving throws</td></tr>
+
<tr><th scope="row">classSaveMods</th><td>An object of class modifiers to the base saving throws</td></tr>
<tr><th scope="row">raceSaveMods</th><td>An object of race modifiers to the base saving throws</td></tr>
+
<tr><th scope="row">raceSaveMods</th><td>An object of race modifiers to the base saving throws</td></tr>
 
</table>
 
</table>
 +
<p>Please contact the author if you wish more in-depth specifications for any of these data elements.</p>
 
<br>
 
<br>
 
 
===Manage Character Sheet Tables===
 
===Manage Character Sheet Tables===
 
<p>Some data on Character Sheets is best represented in tables, made up of multiple rows of multiple fields. Some tables can also have multiple columns of rows, each column containing rows which in turn have multiple fields (in fact, each column is considered a table in itself). Having a structured set of functions to add to, find, read, update, and remove data in these tables is a useful function to have. the <b>ChatSetAttr API</b> from The Aaron provides an amount of such functionality, but the RPGMaster Library provides a full suite of management functions, based on the definition of a standard Table Object, with associated Methods. The mechanics of the Character Sheet table are then hidden from the author of the API, who can concentrate on other functionality.</p>
 
<p>Some data on Character Sheets is best represented in tables, made up of multiple rows of multiple fields. Some tables can also have multiple columns of rows, each column containing rows which in turn have multiple fields (in fact, each column is considered a table in itself). Having a structured set of functions to add to, find, read, update, and remove data in these tables is a useful function to have. the <b>ChatSetAttr API</b> from The Aaron provides an amount of such functionality, but the RPGMaster Library provides a full suite of management functions, based on the definition of a standard Table Object, with associated Methods. The mechanics of the Character Sheet table are then hidden from the author of the API, who can concentrate on other functionality.</p>
 
<p>The Library consists of the Table Object, and the Methods. The mechanics of the Table Object are hidden from the API (but can be exposed & used if you know what you are doing and understand the structure of Character Sheet tables fully). The important aspects to know are the functions to get the table object from the character sheet, and the methods to manipulate the table object.</p>
 
<p>The Library consists of the Table Object, and the Methods. The mechanics of the Table Object are hidden from the API (but can be exposed & used if you know what you are doing and understand the structure of Character Sheet tables fully). The important aspects to know are the functions to get the table object from the character sheet, and the methods to manipulate the table object.</p>
<br>
+
====Table Management Functions====
<h3>Table Management Functions</h3>
+
<pre>tableObject = getTable(character,fieldGroupDef,<column>,<tableObject>,<caseSensitive>)</pre>
<pre>tableObject = getTable(character,fieldGroupDef,column,tableObject,caseSensitive)</pre>
+
<p>Gets a complete table object from a character sheet. Also discovers all the valid default values for the table fields from the <i>fields</i> object. Takes the following parameters:</p>
<p>Gets a complete table object from a character sheet. Also discovers all the valid default values for the table fields from the <i>fields</i> object. Takes the following parameters:</p>
+
<ul>
<ul>
+
<li><b>character:</b> the character sheet object for the character sheet from which to get the table</li>
<li><b>character:</b> the character sheet object for the character sheet from which to get the table</li>
+
<li><b>fieldGroupDef:</b> an entry from the <i>fieldGroups</i> object (obtained in the RPGMap with <i>getRPGMap()</i> - see Section 3.1). One of fieldGroup.MELEE .DMG .RANGED .AMMO .WPROF .MI .MAGIC .SPELLS .POWERS .INHAND .QUIVER .STYLES .GEAR .STORED .DUSTS .SCROLLS .MONWEAP .ALTWIZ .ALTPRI</li>
<li><b>fieldGroupDef:</b> an entry from the <i>fieldGroups</i> object (obtained in the RPGMap with <i>[https://wiki.roll20.net/index.php?title=API:RPGMaster_Library#Get_Character_Sheet_Field_Map_and_Global_Data getRPGMap()]</i>). One of fieldGroup.MELEE .DMG .RANGED .AMMO .WPROF .MI .SPELLS .POWERS .INHAND .QUIVER</li>
+
<li><b><i>column:</i></b> (optional) for tables that have multiple columns, this is the column number to obtain. Each column is recovered as a complete table in itself</li>
<li><b><i>column:</i></b> (optional) for tables that have multiple columns, this is the column number to obtain. Each column is recovered as a complete table in itself</li>
+
<li><b><i>tableObj:</i></b> (optional) an existing table object that will be overwritten with the complete table obtained by this command</li>
<li><b><i>tableObj</i></b> (optional) an existing table object that will be overwritten with the complete table obtained by this command</li>
+
<li><b><i>caseSensitive:</i></b> (optional) a true/false flag which, if true, makes all matches with table and field names in the table case sensitive (default is false, i.e. not case sensitive)</li>
<li><b><i>caseSensitive</i></b> (optional) a true/false flag which, if true, makes all matches with table and field names in the table case sensitive (default is false, i.e. not case sensitive)</li>
+
</ul><br>
</ul><br>
+
<pre>tableObject = getTableField(character,tableObject,tableDef,attributeDef,<column>,<defaultVal>,<caseSensitive>)</pre>
<pre>tableObject = getTableField(character,tableObject,tableDef,attributeDef,column,defaultVal,caseSensitive)</pre>
+
<p>Gets all rows for one field of a table. Adds that to the table object passed as a parameter. Faster than obtaining the full table with getTable(), but should only be used for finding and reading data and not for writing or adding new data and especially not adding rows with the .addTableRow() method. Takes the following parameters:</p>
<p>Gets all rows for one field of a table. Adds that to the table object passed as a parameter. Faster than obtaining the full table with getTable(), but should only be used for finding and reading data and not for writing or adding new data and especially not adding rows with the .addTableRow() method. Takes the following parameters:</p>
+
<ul>
<ul>
+
<li><b>character:</b> the character sheet object for the character sheet from which to get the table</li>
<li><b>character:</b> the character sheet object for the character sheet from which to get the table</li>
+
<li><b>tableObject:</b> an existing table object to add the field to, or an empty object '{}' to create a new table object with just this one field</li>
<li><b>tableObject:</b> an existing table object to add the field to, or an empty object '{}' to create a new table object with just this one field</li>
+
<li><b>tableDef:</b> the table definition from the <i>fields</i> object obtained with the getRPGMap() function (see Section 3.1). This will be the entry <i>'fields.xxx_table'</i> that defines the character sheet repeating table name and the first row index for the table</li>
<li><b>tableDef:</b> the table definition from the <i>fields</i> object obtained with the [https://wiki.roll20.net/index.php?title=API:RPGMaster_Library#Get_Character_Sheet_Field_Map_and_Global_Data getRPGMap()] function. This will be the entry <i>"fields.xxx_table"</i> that defines the character sheet repeating table name and the first row index for the table</li>
+
<li><b>attributeDef:</b> the table field definition from the <i>fields</i> object obtained with the getRPGMap() function (see Section 3.1). E.g. The entry for <i>fieldName</i> will be <i>'fields.xxx_fieldName'</i> that defines the character sheet table field name and property (<i>current</i> or <i>max</i>)</li>
<li><b>attributeDef:</b> the table field definition from the <i>fields</i> object obtained with the getRPGMap() function. E.g. The entry for <i>fieldName</i> will be <i>"fields.xxx_fieldName"</i> that defines the character sheet table field name and property (<i>current</i> or <i>max</i>)</li>
+
<li><b><i>column:</i></b> (optional) for tables that have multiple columns, this is the column number to obtain. Each column is recovered as a complete table in itself</li>
<li><b><i>column:</i></b> (optional) for tables that have multiple columns, this is the column number to obtain. Each column is recovered as a complete table in itself</li>
+
<li><b><i>defaultVal:</i></b> (optional) the default value to be given to this field if a row is blanked, or created without a value specified for this field. If not provided, it itself is defaulted to the default value provided for the field in the <i>fields</i> object obtained with getRPGMap()</li>
<li><b><i>defaultVal:</i></b> (optional) the default value to be given to this field if a row is blanked, or created without a value specified for this field. If not provided, it itself is defaulted to the default value provided for the field in the <i>fields</i> object obtained with getRPGMap()</li>
+
<li><b><i>caseSensitive:</i></b> (optional) a true/false flag which, if true, makes all matches with table and field names in the table case sensitive (default is false, i.e. not case sensitive)</li>
<li><b><i>caseSensitive</i></b> (optional) a true/false flag which, if true, makes all matches with table and field names in the table case sensitive (default is false, i.e. not case sensitive)</li>
+
</ul><br>
</ul><br>
+
<pre>defaultValues = initValues(fieldGroupDef)</pre>
<pre>defaultValues = initValues(fieldGroupDef)</pre>
+
<p>Gets a new default values object for the table defined by the provided field group definition from the <i>fieldGroup</i> object from the RPGMap obtained with getRPGMap() (see Section 3.1). The default values are those set for the table fields in the <i>fields</i> object. The structure of the values object is values[field_name][field_property]. Takes the following parameter:</p>
<p>Gets a new default values object for the table defined by the provided field group definition from the <i>fieldGroup</i> object from the RPGMap obtained with [https://wiki.roll20.net/index.php?title=API:RPGMaster_Library#Get_Character_Sheet_Field_Map_and_Global_Data getRPGMap()]. The default values are those set for the table fields in the <i>fields</i> object. The structure of the values object is values[field_name][field_property]. Takes the following parameter:</p>
+
<ul>
<ul>
+
<li><b>fieldGroupDef:</b> an entry from the <i>fieldGroups</i> object (obtained in the RPGMap, see <i>getRPGMap() in Section 3.1</i>). One of fieldGroup.MELEE .DMG .RANGED .AMMO .WPROF .MI .MAGIC .SPELLS .POWERS .INHAND .QUIVER .STYLES .GEAR .STORED .DUSTS .SCROLLS .MONWEAP .ALTWIZ .ALTPRI</li>
<li><b>fieldGroupDef:</b> an entry from the <i>fieldGroups</i> object (obtained in the RPGMap, see <i>[https://wiki.roll20.net/index.php?title=API:RPGMaster_Library#Get_Character_Sheet_Field_Map_and_Global_Data getRPGMap()]</i>). One of fieldGroup.MELEE .DMG .RANGED .AMMO .WPROF .MI .SPELLS .POWERS .INHAND .QUIVER</li>
+
</ul><br>
<li><b>defaultValues:</b> a <i>values</i> object with the structure<br>
+
====Table Object Methods====
<pre>{fieldName:{property:value,property:value,...},<br>
+
<pre>value = tableObject.tableLookup(attributeDef,row,<defaultValue>,<returnObj>)</pre>
fieldName:{property:value,...},<br>
+
<p>Looks up the value stored in a specified field in the specified row of the table object. Can take an optional default value (which will override the default value for the field stored in the table object itself), and an optional returnObj parameter to determine what is returned (value or object). Takes the following parameters:</p>
fieldName:{property:value,...},<br>
+
<ul>
...}</pre>
+
<li><b>attributeDef:</b> the table field definition from the <i>fields</i> object obtained with the <i>getRPGMap()</i> function (see Section 3.1). For field <i>fieldName</i>,This will be the entry <i>'fields.xxx_fieldName'</i> that defines the character sheet table field name and property (<i>current</i> or <i>max</i>)</li>
</ul><br>
+
<li><b>row:</b> the row number of the row to get the field value from. If the row number is beyond the current end of the table, will return a default value or < undefined >, depending on the value of the <i>defaultValue</i> parameter</li>
<h3>Table Object Methods</h3>
+
<li><b><i>defaultValue:</i></b> a value or true or false (absolute boolian values). Defaults to true. If the field requested does not exist or does not have a value: <b>true</b> (or not provided) returns the default value stored for that field in the table object; <b>false</b> returns < undefined >; <b>any other value</b> is returned instead of the default value stored for that field in the table object</li>
<pre>value = tableObject.tableLookup(attributeDef,row,defaultValue,returnObj)</pre>
+
<li><b><i>returnObj:</i></b> an attributeDef or true or false (absolute boolean values). Defaults to false. <b>false</b> (or not provided) returns the value or default value of the requested field; <b>true</b> returns the <i>field object</i> from the table instead of the value; an <b>attributeDef</b> specifies a different <i>property</i> to return, e.g. <i>current</i> or <i>max</i> (uses only the property field of the attributeDef)</li>
<p>Looks up the value stored in a specified field in the specified row of the table object. Can take an optional default value (which will override the default value for the field stored in the table object itself), and an optional returnObj parameter to determine what is returned (value or object). Takes the following parameters:</p>
+
</ul><br>
<ul>
+
<pre>tableObject = tableObject.tableSet(attributeDef,row,value,<caseSensitive>)</pre>
<li><b>attributeDef:</b> the table field definition from the <i>fields</i> object obtained with the <i>[https://wiki.roll20.net/index.php?title=API:RPGMaster_Library#Get_Character_Sheet_Field_Map_and_Global_Data getRPGMap()]</i> function. For field <i>fieldName</i>,This will be the entry <i>"fields.xxx_fieldName"</i> that defines the character sheet table field name and property (<i>current</i> or <i>max</i>)</li>
+
<p>Sets the value of the specified table field in the specified row to be the value provided. tableObject is changed in-place. Takes the following parameters:</p>
<li><b>row:</b> the row number of the row to get the field value from. If the row number is beyond the current end of the table, will return a default value or < undefined > depending on the value of the <i>defaultValue</i> parameter</li>
+
<ul>
<li><b><i>defaultValue:</i></b> a value or true or false (absolute boolian values). Defaults to true. If the field requested does not exist or does not have a value: <b>true</b> (or not provided) returns the default value stored for that field in the table object; <b>false</b> returns < undefined >; <b>any other value</b> is returned instead of the default value stored for that field in the table object</li>
+
<li><b>attributeDef:</b> the table field definition from the <i>fields</i> object obtained with the <i>getRPGMap()</i> function (see Section 3.1). For field <i>fieldName</i>, this will be the entry <i>'fields.xxx_fieldName'</i> that defines the character sheet table field name and property (<i>current</i> or <i>max</i>)</li>
<li><b><i>returnObj:</i></b> an attributeDef or true or false (absolute boolean values). Defaults to false. <b>false</b> (or not provided) returns the value or default value of the requested field; <b>true</b> returns the <i>field object</i> from the table instead of the value; an <b>attributeDef</b> specifies a different <i>property</i> to return, e.g. <i>current</i> or <i>max</i> (uses only the property field of the attributeDef)</li>
+
<li><b>row:</b> the row number of the row to set the field value in. If the row number is beyond the current end of the table, will create a new object for that field and the row specified: <b>WARNING: creating a new field in a row this way can have unpredictable results. It is better to use the <i>addTableRow()</i> method to add complete new rows or to define all the fields in an existing row</b></li>
</ul><br>
+
<li><b>value:</b> the value to store in the specified field in the specified row of the table</li>
<pre>tableObject = tableObject.tableSet(attributeDef,row,value,caseSensitive)</pre>
+
<li><b><i>caseSensitive</i></b> (optional) a true/false flag which, if true, makes all matches with table and field names in the table case sensitive (default is false, i.e. not case sensitive)</li>
<p>Sets the value of the specified table field in the specified row to be the value provided. tableObject is changed in-place. Takes the following parameters:</p>
+
</ul>
<ul>
+
<pre>tableObject = tableObject.addTableRow(row,<values>)</pre>
<li><b>attributeDef:</b> the table field definition from the <i>fields</i> object obtained with the <i>[https://wiki.roll20.net/index.php?title=API:RPGMaster_Library#Get_Character_Sheet_Field_Map_and_Global_Data getRPGMap()]</i> function. For field <i>fieldName</i>, this will be the entry <i>"fields.xxx_fieldName"</i> that defines the character sheet table field name and property (<i>current</i> or <i>max</i>)</li>
+
<p>Either add a new row to a table object with the provided or default values, or replace a current row with the provided or default values. tableObject is changed in-place. Takes the following parameters:</p>
<li><b>row:</b> the row number of the row to set the field value in. If the row number is beyond the current end of the table, will create a new object for that field and the row specified: <b>WARNING: creating a new field in a row this way can have unpredictable results. It is better to use the <i>addTableRow()</i> method to add complete new rows or to define all the fields in an existing row</b></li>
+
<ul>
<li><b>value:</b> the value to store in the specified field in the specified row of the table</li>
+
<li><b>row:</b> the row number of the row to write the values to. If the row number is beyond the current end of the table, will create all the fields in a new row of the Table Object, either with the values provided, or the default values</li>
<li><b><i>caseSensitive</i></b> (optional) a true/false flag which, if true, makes all matches with table and field names in the table case sensitive (default is false, i.e. not case sensitive)</li>
+
<li><b><i>values:</i></b> a <i>values</i> object (optional), created using the <i>initValues()</i> table function, and modified as required with new values for the fields. If not provided, defaults to the default values for the table fields held by the Table Object itself (effectively blanking the row). See the description of the <i>initValues()</i> function for the structure of the <i>values</i> object</li>
</ul>
+
</ul>
<pre>tableObject = tableObject.addTableRow(row,values)</pre>
+
<p>Either add a new row to a table object with the provided or default values, or replace a current row with the provided or default values. tableObject is changed in-place. Takes the following parameters:</p>
+
<ul>
+
<li><b>row:</b> the row number of the row to set the field values in. If the row number is beyond the current end of the table, will create all the fields in the Table Object, either with the values provided, or the default values</li>
+
<li><b><i>values:</i></b> a <i>values</i> object (optional), created using the <i>initValues()</i> table function, and modified as required with new values for the fields. If not provided, defaults to the default values for the table fields held by the Table Object itself (effectively blanking the row). See the description of the <i>initValues()</i> function for the structure of the <i>values</i> object</li>
+
</ul>
+
 
<pre>row = tableObject.tableFind(attributeDef,valToFind)</pre>
 
<pre>row = tableObject.tableFind(attributeDef,valToFind)</pre>
<p>Find the first row in the Table Object with an entry in the field defined by the <i>attributeDef</i> with the value of <i>valToFind</i>. If found, <i>row</i> will be a valid table row number; otherwise the method returns < undefined >. Takes the following parameters:</p>
+
<p>Find the first row in the Table Object with an entry in the field defined by the <i>attributeDef</i> with the value of <i>valToFind</i>. If found, <i>row</i> will be a valid table row number; otherwise the method returns < undefined >. Takes the following parameters:</p>
<ul>
+
<ul>
<li><b>attributeDef:</b> the table field definition from the <i>fields</i> object obtained with the [https://wiki.roll20.net/index.php?title=API:RPGMaster_Library#Get_Character_Sheet_Field_Map_and_Global_Data getRPGMap()] function. For the field <i>fieldName</i>, this will be the entry <i>"fields.xxx_fieldName"</i> that defines the character sheet table field name and property (<i>current</i> or <i>max</i>) to search</li>
+
<li><b>attributeDef:</b> the table field definition from the <i>fields</i> object obtained with the getRPGMap() function (see Section 3.1). For the field <i>fieldName</i>, this will be the entry <i>'fields.xxx_fieldName'</i> that defines the character sheet table field name and property (<i>current</i> or <i>max</i>) to search</li>
<li><b>valToFind:</b> the value to be searched for in the attributeDef field</li>
+
<li><b>valToFind:</b> the value to be searched for in the attributeDef field</li>
<li><b>row:</b> the row number of the first row on which a match occurs, or < undefined > if no match was found</li>
+
<li><b>row:</b> the row number of the first row on which a match occurs, or < undefined > if no match was found</li>
</ul>
+
</ul>
<br>
+
 
+
 
===Attribute Management===
 
===Attribute Management===
 
<p>Two functions that get and set attribute values on the character sheet:</p>
 
<p>Two functions that get and set attribute values on the character sheet:</p>
<pre>value = attrLookup( character, attributeDef, tableDef, row, column, caseSensitive, defaultValue );</pre>
+
<pre>value = attrLookup( character, attributeDef, <tableDef>, <row>, <column>, <caseSensitive>, <defaultValue> );</pre>
<p>A function that can get the value of an attribute from a character sheet, either from a standard attribute, or from a repeating table. <b>However:</b> for table field values using the [https://wiki.roll20.net/API:RPGMaster_Library#Table_Management_Functions Table Management] functions, objects and methods is prefered and may suffer from fewer issues in future. Takes the following parameters:</p>
+
<p>A function that can get the value of an attribute from a character sheet, either from a standard attribute, or from a repeating table. <b>However:</b> for table field values using the Table Management functions, objects and methods is preferred and may suffer from fewer issues in future. Takes the following parameters:</p>
 
<ul>
 
<ul>
<li><b>character:</b> the character sheet object for the character sheet from which to get the value</li>
+
<li><b>character:</b> the character sheet object for the character sheet from which to get the value</li>
<li><b>attributeDef:</b> the attribute field definition from the <i>fields</i> object obtained with the [https://wiki.roll20.net/index.php?title=API:RPGMaster_Library#Get_Character_Sheet_Field_Map_and_Global_Data getRPGMap()] function. For a field <i>fieldName</i> this will be the entry <i>"fields.fieldName"</i> that defines the character sheet attribute field name and property (<i>current</i> or <i>max</i>)</li>
+
<li><b>attributeDef:</b> the attribute field definition from the <i>fields</i> object obtained with the getRPGMap() function (see Section 3.1). For a field <i>fieldName</i> this will be the entry <i>'fields.fieldName'</i> that defines the character sheet attribute field name and property (<i>current</i> or <i>max</i>)</li>
<li><b><i>tableDef:</i></b> (optional) the table definition from the <i>fields</i> object obtained with the getRPGMap() function. This will be the entry <i>"fields.xxx_table"</i> that defines the character sheet repeating table name and the first row index for the table</li>
+
<li><b><i>tableDef:</i></b> (optional) the table definition from the <i>fields</i> object obtained with the getRPGMap() function (see Section 3.1). This will be the entry <i>'fields.xxx_table'</i> that defines the character sheet repeating table name and the first row index for the table</li>
<li><b><i>row:</i></b> (optional) the row number of the row to get the field value from. If the row number is beyond the current end of the table, will return a default value or < undefined >, depending on the value of the <i>defaultValue</i> parameter</li>
+
<li><b><i>row:</i></b> (optional) the row number of the row to get the field value from. If the row number is beyond the current end of the table, will return a default value or < undefined >, depending on the value of the <i>defaultValue</i> parameter</li>
<li><b><i>column:</i></b> (optional) for tables that have multiple columns, this is the column number from which to obtain the field value.</li>
+
<li><b><i>column:</i></b> (optional) for tables that have multiple columns, this is the column number from which to obtain the field value.</li>
<li><b><i>caseSensitive</i></b> (optional) a true/false flag which, if true, makes all matches with table and field names case sensitive (default is false, i.e. not case sensitive)</li>
+
<li><b><i>caseSensitive</i></b> (optional) a true/false flag which, if true, makes all matches with table and field names case sensitive (default is false, i.e. not case sensitive)</li>
<li><b><i>defaultValue:</i></b> (optional) a value or true or false (absolute boolian values). Defaults to true. If the field requested does not exist or does not have a value: <b>true</b> (or not provided) returns the default value stored for that field in the table object; <b>false</b> returns < undefined >; any other value is returned instead of the default value stored for that field in the <i>fields</i> object</li>
+
<li><b><i>defaultValue:</i></b> (optional) a value or true or false (absolute boolian values). Defaults to true. If the field requested does not exist or does not have a value: <b>true</b> (or not provided) returns the default value stored for that field in the <i>fields</i> object; <b>false</b> returns < undefined >; any other value is returned instead of the default value stored for that field in the <i>fields</i> object</li>
 
</ul><br>
 
</ul><br>
<pre>attributeObj = setAttr( character, attributeDef, value, tableDef, row, column, caseSensitive );</pre>
+
<pre>attributeObj = setAttr( character, attributeDef, value, <tableDef>, <row>, <column>, <caseSensitive> );</pre>
<p>A function that sets the value held by an attribute on a character sheet. Can also set values in repeating tables on the character sheet. <b>However:</b> for table attributes it is highly recommended that the [https://wiki.roll20.net/API:RPGMaster_Library#Table_Management_Functions Table Management] functions, objects and methods are used to get and set repeating table field values, as this might suffer from fewer issues in the future. Takes for following parameters:</p>
+
<p>A function that sets the value held by an attribute on a character sheet. Can also set values in repeating tables on the character sheet. <b>However:</b> for table attributes it is highly recommended that the Table Management functions, objects and methods (see Section 3.2) are used to get and set repeating table field values, as this might suffer from fewer issues in the future. Takes for following parameters:</p>
 
<ul>
 
<ul>
<li><b>character:</b> the character sheet object for the character sheet on which to set the value</li>
+
<li><b>character:</b> the character sheet object for the character sheet on which to set the value</li>
<li><b>attributeDef:</b> the attribute field definition from the <i>fields</i> object obtained with the [https://wiki.roll20.net/index.php?title=API:RPGMaster_Library#Get_Character_Sheet_Field_Map_and_Global_Data getRPGMap()] function. For field <i>fieldName</i> this will be the entry <i>"fields.fieldName"</i> that defines the character sheet attribute field name and property (<i>current</i> or <i>max</i>). If the attribute object does not exist on the character sheet (and is not a table field) it will be created</li>
+
<li><b>attributeDef:</b> the attribute field definition from the <i>fields</i> object obtained with the getRPGMap() function (see Section 3.1). For field <i>fieldName</i> this will be the entry <i>'fields.fieldName'</i> that defines the character sheet attribute field name and property (<i>current</i> or <i>max</i>). If the attribute object does not exist on the character sheet (and is not a table field) it will be created</li>
<li><b>value:</b> the value to store in the specified attribute of the specified character sheet</li>
+
<li><b>value:</b> the value to store in the specified attribute of the specified character sheet</li>
<li><b><i>tableDef:</i></b> (optional) the table definition from the <i>fields</i> object obtained with the getRPGMap() function. This will be the entry <i>"fields.xxx_table"</i> that defines the character sheet repeating table name and the first row index for the table</li>
+
<li><b><i>tableDef:</i></b> (optional) the table definition from the <i>fields</i> object obtained with the getRPGMap() function (see Section 3.1). This will be the entry <i>'fields.xxx_table'</i> that defines the character sheet repeating table name and the first row index for the table</li>
<li><b><i>row:</i></b> (optional) the row number of the row to set the field value in. If the row number is beyond the current end of the table, the function will attempt to create the new row, and put the value in it</li>
+
<li><b><i>row:</i></b> (optional) the row number of the row to set the field value in. If the row number is beyond the current end of the table, the function will attempt to create the new row, and put the value in it</li>
<li><b><i>column:</i></b> (optional) for tables that have multiple columns, this is the column number in which to set the field value. If the column does not exist, the function will return < undefined ></li>
+
<li><b><i>column:</i></b> (optional) for tables that have multiple columns, this is the column number in which to set the field value. If the column does not exist, the function will return < undefined ></li>
<li><b><i>caseSensitive</i></b> (optional) a true/false flag which, if true, makes all matches with table and field names case sensitive (default is false, i.e. not case sensitive)</li>
+
<li><b><i>caseSensitive</i></b> (optional) a true/false flag which, if true, makes all matches with table and field names case sensitive (default is false, i.e. not case sensitive)</li>
<li><b>attributeObj:</b> the function returns the attribute object found and in which the value has been set, or < undefined > if a table field or row does not exist</li>
+
<li><b>attributeObj:</b> the function returns the attribute object found and in which the value has been set, or < undefined > if a table field or row does not exist</li>
 
</ul><br>
 
</ul><br>
 
 
===Database Management===
 
===Database Management===
 
<p>The RPGMaster series of APIs use a number of databases holding data about spells, powers, magic items, character classes, attack macros, and other aspects. These are held as objects within the game-version and character sheet-version specific RPGMaster Library, and can be supplemented by GM provided additional databases held in Roll20 character sheets. See the database help handouts distributed with the RPGMaster APIs for more information on each type of database.</p>
 
<p>The RPGMaster series of APIs use a number of databases holding data about spells, powers, magic items, character classes, attack macros, and other aspects. These are held as objects within the game-version and character sheet-version specific RPGMaster Library, and can be supplemented by GM provided additional databases held in Roll20 character sheets. See the database help handouts distributed with the RPGMaster APIs for more information on each type of database.</p>
 
<p>The RPGMaster Library provides a number of database management functions which can be used by APIs to manage the provided databases. These functions are described here.</p>
 
<p>The RPGMaster Library provides a number of database management functions which can be used by APIs to manage the provided databases. These functions are described here.</p>
<pre>DBindex = getDBindex( forceUpdate )</pre>
+
<pre>DBindex = getDBindex( <forceUpdate> )</pre>
 
<p>A function to build or get and return an index to all entries in the RPGMaster databases. This function <b><i>must</i></b> be called before any items in the databases are queried or acted upon with the other database management functions. Having this index (which is globally held in the system) speeds up database access considerably over relying on the Roll20 object management functions, and allows the APIs to seamlessly access items that might be in either internal object databases or held in external character sheet databases, and supports the prioritisation of user-defined database items over Library defined items. Takes one optional parameter:</p>
 
<p>A function to build or get and return an index to all entries in the RPGMaster databases. This function <b><i>must</i></b> be called before any items in the databases are queried or acted upon with the other database management functions. Having this index (which is globally held in the system) speeds up database access considerably over relying on the Roll20 object management functions, and allows the APIs to seamlessly access items that might be in either internal object databases or held in external character sheet databases, and supports the prioritisation of user-defined database items over Library defined items. Takes one optional parameter:</p>
 
<ul>
 
<ul>
<li><b><i>forceUpdate:</i></b> (optional) A boolean flag: if true, forces the global database index to be recreated from scratch. If false or not provided, only builds the index if it does not already exist (e.g. when the game session has just started and the APIs initialise)</li>
+
<li><b><i>forceUpdate:</i></b> (optional) A boolean flag: if true, forces the global database index to be recreated from scratch. If false or not provided, only builds the index if it does not already exist (e.g. when the game session has just started and the APIs initialise)</li>
 
</ul><br>
 
</ul><br>
<pre>dbItemObject = abilityLookup( rootDB, dbItemName, character, silent, default );</pre>
+
<pre>dbItemObject = abilityLookup( rootDB, dbItemName, <character>, <silent>, <default> );</pre>
 
<p>A function to get an entry from a database. Uses the global DBindex internally to access the correct database entry directly, eliminating the speed of a Roll20 object search. The building of the index using getDBindex() will determine the priority order of the potential sources for database items: see that function description for details. However, if the item does not have an entry in the DBindex (i.e. is not in any currently loaded database), and if a character sheet object is passed as a parameter, this abilityLookup() function will also search the character sheet for a copy of the database item which might have previously been placed there by a getAbility() function call. This allows characters to have items that come from user-defined databases in one campaign that are carried with them to other campaigns which perhaps don't have the same user-defined databases loaded.</p>
 
<p>A function to get an entry from a database. Uses the global DBindex internally to access the correct database entry directly, eliminating the speed of a Roll20 object search. The building of the index using getDBindex() will determine the priority order of the potential sources for database items: see that function description for details. However, if the item does not have an entry in the DBindex (i.e. is not in any currently loaded database), and if a character sheet object is passed as a parameter, this abilityLookup() function will also search the character sheet for a copy of the database item which might have previously been placed there by a getAbility() function call. This allows characters to have items that come from user-defined databases in one campaign that are carried with them to other campaigns which perhaps don't have the same user-defined databases loaded.</p>
 
<p>Takes the following parameters:</p>
 
<p>Takes the following parameters:</p>
 
<ul>
 
<ul>
<li><b>rootDB:</b> The root database name for the type of item being recovered. Will access indexes from any database name that starts with the rootDB name. Can be one of <i>MU-Spells-DB, PR-Spells-DB, Powers-DB, MI-DB, Attacks-DB, Class-DB</i></li>
+
<li><b>rootDB:</b> The root database name for the type of item being recovered. Will access indexes from any database name that starts with the rootDB name. Can be one of <i>MU-Spells-DB, PR-Spells-DB, Powers-DB, MI-DB, Attacks-DB, Class-DB</i></li>
<li><b>dbItemName:</b> The name of the item being searched for. The following characters are ignored: '-' ''(hyphen)'', '_' ''(underscore)'', 'space'.</li>
+
<li><b>dbItemName:</b> The name of the item being searched for. The following characters are ignored: '-', '_', 'space'.</li>
<li><b><i>character:</i></b> (optional) the character sheet object for the character sheet for which the item is relevant, and which might hold any orphaned item that is not available in current databases.</li>
+
<li><b><i>character:</i></b> (optional) the character sheet object for the character sheet for which the item is relevant, and which might hold any orphaned item that is not available in current databases.</li>
<li><b><i>silent:</i></b> (optional) a boolean value which, if true, will surpress any error message if the rootDB is invalid or the item cannot be found. False or not provided will result in error messages being returned.</li>
+
<li><b><i>silent:</i></b> (optional) a boolean value which, if true, will surpress any error message if the rootDB is invalid or the item cannot be found. False or not provided will result in error messages being returned.</li>
<li><b><i>default:</i></b> (optional) a boolean value which, if false, returns < undefined > for any database item object if the item is not found or other errors occur, or if true or not defined returns a default item with the following structure:<br>
+
<li><b><i>default:</i></b> (optional) a boolean value which, if false, returns < undefined > for any database item object if the item is not found or other errors occur, or if true or not defined returns a default item with the following structure:<br>
<pre>{
+
<pre>{name:'-',type:'',ct:'0',charge:'uncharged',cost:'0',body:'This is a blank slot. Go search out something new to fill it up!'}</pre></li>
dB:rootDB,
+
<li><b>dbItemObject</b> A database item object, of class AbilityObj, with structure:
obj:[undefined,{name:'-',type:'',ct:'0',charge:'uncharged',cost:'0',body:'This is a blank slot. Go search out something new to fill it up!'}],
+
<pre> class AbilityObj {<br>
ct:[undefined,0],
+
constructor( dBname, abilityObj, ctObj, source ) {<br>
source:'apiDB',
+
this.dB = dBname;<br>
api:undefined
+
this.obj = abilityObj;<br>
}</pre></li>
+
this.ct = ctObj;<br>
<li><b>dbItemObject</b> A database item object, of class AbilityObj, with structure:
+
this.source = source;<br>
<pre>class AbilityObj {
+
this.api = (abilityObj && abilityObj[1]) ? (abilityObj[1].body.trim()[0] == '!') : false;<br>
constructor( dBname, abilityObj, ctObj, source ) {
+
}</pre></li>
this.dB = dBname;
+
this.obj = abilityObj;
+
this.ct = ctObj;
+
this.source = source;
+
this.api = (abilityObj && abilityObj[1]) ? (abilityObj[1].body.trim()[0] == '!') : false;
+
}</pre></li>
+
 
</ul><br>
 
</ul><br>
<pre>dbItemObject = getAbility( rootDB, dbItemName, character, silent )</pre>
+
<pre>dbItemObject = getAbility( rootDB, dbItemName, character, <silent> )</pre>
<p>A special version of <i>abilityLookup()</i> that not only gets the requested database item from the databases, but also saves that item to the stated character sheet for later reference. All parameters are defined the same as those for <i>AbilityLookup()</i> above. The returned <i>dbItemObject.dB</i> object attribute always holds the name of the character sheet, so that after a call to <i>getAbility()</i>, the standard Roll20 syntax of `%{${dbItemObject.dB}|${dbItemName}}` will work to display the database item in the chat window, but the original source database information will be lost.</p>
+
<p>A special version of <i>abilityLookup()</i> that not only gets the requested database item from the databases, but also saves that item to the stated character sheet for later reference. All parameters are defined the same as those for <i>AbilityLookup()</i> above. The returned <i>dbItemObject.dB</i> object attribute always holds the name of the character sheet, so that after a call to <i>getAbility()</i>, the standard Roll20 syntax of `%{${dbItemObject.dB}|${dbItemName}}` will work to display the database item in the chat window.</p>
 
<br>
 
<br>
<pre>itemObject = setAbility( character, itemName, itemBody, actionBar )</pre>
+
<pre>itemObject = setAbility( character, itemName, itemBody, <actionBar> )</pre>
 
<p>A function to set or update a database item or an ability macro in a character sheet (database items are stored as ability macros on a character sheet). <b>Note:</b> the API in-memory databases cannot be updated in this way. Only items and ability macros on character sheets can be created and updated. Takes the following parameters:</p>
 
<p>A function to set or update a database item or an ability macro in a character sheet (database items are stored as ability macros on a character sheet). <b>Note:</b> the API in-memory databases cannot be updated in this way. Only items and ability macros on character sheets can be created and updated. Takes the following parameters:</p>
 
<ul>
 
<ul>
<li><b>character:</b> the character sheet object of the character sheet on which the item is to be stored or updated.</li>
+
<li><b>character:</b> the character sheet object of the character sheet on which the item is to be stored or updated.</li>
<li><b>itemName:</b> The name of the item being set. The case of the name and the following characters will be saved as part of the name, but are ignored for indexing and matching of the item name to those already stored on the character sheet: '-', '_', 'space'.</li>
+
<li><b>dbItemName:</b> The name of the item being set. The case of the name and the following characters will be saved as part of the name, but are ignored for indexing and matching of the item name to those already stored on the character sheet: '-', '_', 'space'.</li>
<li><b>itemBody:</b> The content to store as the data item, which will be stored as a character sheet Ability Macro body. Can consist of any text that can be stored in an Ability Macro body</li>
+
<li><b>dbItemBody:</b> The content to store as the data item, which will be stored as a character sheet Ability Macro body. Can consist of any text that can be stored in an Ability Macro body</li>
<li><b><i>actionBar:</i></b> (optional) a boolean value which, if true, will set the "Show as Token Action" flag for the Ability Macro that represents the item. Default is false</li>
+
<li><b><i>actionBar:</i></b> (optional) a boolean value which, if true, will set the "Show as Token Action" flag for the Ability Macro that represents the item. Default is false</li>
<li><b>itemObject:</b> the returned item object which represents the item just set. Has the same definition as <i>dbItemObject</i> defined for the abilityObject() function</li>
+
<li><b>itemObject:</b> the returned item object which represents the item just set. Has the same definition as <i>dbItemObject</i> defined for the abilityObject() function</li>
 
</ul><br>
 
</ul><br>
<pre>errFlag = buildCSdb( dbFullName, dbObj, typeList, silent )</pre>
+
<pre>errFlag = buildCSdb( dbFullName, dbObj, typeList, <silent> )</pre>
 
<p>A function to extract an API databse from memory into a Character Sheet Database representation, so that the GM can examine the standard items stored there. <b>Note:</b> the function does not re-index the databases, so the Character Sheet database representation so created will not actually be used to recover data from by the system. If use of the Character Sheet database is required, it will be necessary to run a <i>getDBindex( true )</i> function to force an index update. Takes the following parameters:</p>
 
<p>A function to extract an API databse from memory into a Character Sheet Database representation, so that the GM can examine the standard items stored there. <b>Note:</b> the function does not re-index the databases, so the Character Sheet database representation so created will not actually be used to recover data from by the system. If use of the Character Sheet database is required, it will be necessary to run a <i>getDBindex( true )</i> function to force an index update. Takes the following parameters:</p>
 
<ul>
 
<ul>
<li><b>dbFullName:</b> the name of the database to be built, which should be one of the databases named in the <i>dbNames</i> object returned by the [https://wiki.roll20.net/index.php?title=API:RPGMaster_Library#Get_Character_Sheet_Field_Map_and_Global_Data getRPGMap()] function, but does not have to be</li>
+
<li><b>dbFullName:</b> the name of the database to be built, which should be one of the databases named in the <i>dbNames</i> object returned by the getRPGMap() function (see Section 3.1), but does not have to be</li>
<li><b>dbObj:</b> the database object in <i>dbNames</i> that is to be extracted to the Character Sheet database named <i>dbFullName</i></li>
+
<li><b>dbObj:</b> the database object in <i>dbNames</i> that is to be extracted to the Character Sheet database named <i>dbFullName</i></li>
<li><b>typeList:</b> one of <i>clTypeLists</i> (for character classes), <i>spTypeLists</i> (for all types of spell or power), or <i>miTypeLists</i> (for all other items), which have been obtained using <i>getRPGMap()</i></li>
+
<li><b>typeList:</b> one of <i>clTypeLists</i> (for character classes), <i>spTypeLists</i> (for all types of spell or power), or <i>miTypeLists</i> (for all other items), which have been obtained using <i>getRPGMap()</i> (see Section 3.1)</li>
<li><b><i>silent:</i></b> (optional) a boolean value which, if true, will surpress any error messages. False or not provided will result in error messages being sent to chat. An error flag is always returned</li>
+
<li><b><i>silent:</i></b> (optional) a boolean value which, if true, will surpress any error messages. False or not provided will result in error messages being sent to chat. An error flag is always returned</li>
<li><b>errFlag:</b> a boolean value indicating if an error occurred.</li>
+
<li><b>errFlag:</b> a boolean value indicating if an error occurred.</li>
 
</ul><br>
 
</ul><br>
<pre>checkCSdb( dbName );</pre>
+
<pre>checkCSdb( <dbName> );</pre>
 
<p>A function to check any character sheet database for completeness and accuracy. If the body texts of the item Ability Macros have been set up in accordance with the relevant database documentation handout, this function will ensure that all other attributes, lists and fields are set up to match the database item Ability Macros. Takes the following parameter:</p>
 
<p>A function to check any character sheet database for completeness and accuracy. If the body texts of the item Ability Macros have been set up in accordance with the relevant database documentation handout, this function will ensure that all other attributes, lists and fields are set up to match the database item Ability Macros. Takes the following parameter:</p>
 
<ul>
 
<ul>
<li><b><i>dbName</i></b> (optional) the name of the character sheet database to check. If not provided, or dbName = '-db', all character sheet databases will be checked</li>
+
<li><b><i>dbName</i></b> (optional) the name of the character sheet database to check. If not provided, or dbName = '-db', all character sheet databases will be checked</li>
 
</ul>
 
</ul>
 +
 +
= Changelog =
 +
{{changelog version|1.3.00|2022-09-21|* First release to GitHub.
 +
* Updated to delete old versions of standard character sheet databases.}}
 +
{{changelog version|1.3.01|2022-10-01|* Fix issue with database lookup if a character has a name that includes "spell" or "power" in their name.
 +
* Added support for direct access to MU & PR spells, and/or other Magic Items as powers for characters and magic items.}}
 +
{{changelog version|1.3.02|2022-10-10|* Fixed errors in the coding of spells that requite a To-Hit roll but do damage rather than targeted magic.
 +
* Changed initiative modifier char sheet field from comreact to custom field init-mod.
 +
* Added spell as weapon flag to spell tables. }}
 +
{{changelog version|1.3.03|2022-10-22|* Support for the Race Database.}}
 +
{{changelog version|1.3.04|2022-11-15|* Allow handleCheckSaves() to work in silent mode.
 +
* Added support for the Creatures database.}}
 +
{{changelog version|1.4.01|2022-11-28|* Support for the Fighting Styles database & creature setup.
 +
* Allowalphabetically indexed lists.
 +
* Support %{DB|abilityMacro} in certain database definitions (e.g. Race/Creature).
 +
* ShapeSpellbook() moved to library.
 +
* Extended String prototype with dbName() method.
 +
* Updated Attacks-DB with Throat Leech attacks.
 +
* Added more creatures.
 +
* Adds and fixes to other database entries.
 +
* Added deeper inheritance chaining for race and class definitions.}}
 +
{{changelog version|1.4.02|2022-12-16|* More creature definitions, and supporting powers.
 +
* Add ability to specify weapons and armour for creatures with probability of different sets.
 +
* Also added ammo reuse type 2: becomes only possible ammo of several for that weapon e.g. spitting snake venom, and type 3: reduces in qty by 1, and all other ammo for same weapon increases qty b 1.}}
 +
{{changelog version|1.4.03|2023-01-16|* Added Attack messages (similar to damage messages) using Ranged weapons notes field.
 +
* Added ability for creature innate attacks to have damage roll before attack name so they work with CS buttons.
 +
* Fixed issue with abilityLookup() if ability name undefined.
 +
* Fixed issue with resolveData() if not defaulting values & ns: attribute not specified.}}
 +
{{changelog version|1.4.04|2022-01-16|* Added creature attkmsg & dmgmsg attributes to support messages to display with attack and damage rolls respectively.
 +
* Added table & function to return calculated base Thac0.
 +
* Made attrLookup() and getTokenValue() more robust vs. Character Sheet errors.
 +
* Added support in getTokenValue() for redefined default token bars.
 +
* Added support for Character Sheet conversion.
 +
* Gave Ammo its own lookup table capability.}}
 +
{{changelog version|1.4.04|2023-02-02|* Added code necessary to support new Rods, Staves & Wands, the new Magic item class, and charges expended on successful hit.
 +
* Fixed DB entries that incorrectly use parentheses.
 +
* Modified tableFind() to compare field values using dbName().
 +
* Decouple AttackMaster and MagicMaster config values from parseOutput().
 +
* Better error handling for several library functions.
 +
* Moved caster level parsing to the library.}}
 +
{{changelog version|1.4.05|2023-04-09|* Updated MI database and Magic Database Help to add ability for bags to automatically create item-holding character sheet, and optionally for it to auto-populate initial items in the bag.
 +
* Added "GM Info" as a possible line tag for RPGMspell & RPGMdefault Roll Templates, that is shown only if the GM is one of the recipients for the message.}}
 +
{{changelog version|1.4.07|2023-04-15|* Added more miscellaneous magic items.
 +
* Updated Magic DB help.
 +
* Added creatures for Bag of Tricks.
 +
* Added new "discharging" MI type = charged but cannot be split on pick or put.
 +
* Added ItemQty field to hold current qty of currently selected MI, held in MIct|max attribute on character sheet.}}
 +
{{changelog version|1.4.08|2023-04-20|* Updated MI database items to compress using %{...|...} syntax.
 +
* Added new magic items.}}
 +
{{changelog version|1.5.01|2023-05-17|* Fixed db reData parsing to only recover relevant text.
 +
* Fixed reDataCharge parsing to accept + as a valid character.
 +
* Fixed db Specs field parsing to only recover relevant data.
 +
* Added string trueCompare(txt) prototype.
 +
* Added the dispName() string prototype to replace hyphens with spaces in names to display.
 +
* Added improved handling of hidden magic items.
 +
* Added "Looks Like" special template tag which will auto-hide an item and display only what it looks like until revealed.
 +
* Default unknown magic item classes to be the same as "miscellaneous".
 +
* Allow character_ids to be substituted for token_ids in calls to getCharacter().
 +
* Added the ability to alphabetise lists.
 +
* Allow 'PW' to substitute 'POWER' in calls to caster() and related functions.}}
 +
 +
[[Category:AD&D 2E]]
 +
[[Category:API:RPGMaster]]

Latest revision as of 07:36, 12 June 2023

Main Page: API:Script Index

API ScriptAuthor: Richard E
Version: 1.5.01
Last Modified: 2023-05-17
Code: RPGMlibrary AD+D2e
Dependencies: None
Conflicts: None

[edit] RPGMaster Scripts

The RPGMaster suite of APIs is a set of APIs created primarily for enhancing AD&D 2E gameplay, made by Richard E. The APIs are compatible with the Advanced 2nd Edition character sheet.

Some of the APIs can be used with other sheets.

[edit] Forum

RPGMaster APIs for AD&D 2E - main forum thread

Contents


[edit] RPGMaster Library

The RPGMaster series of APIs has been designed to work with multiple RPG systems and rulesets (although only AD&D2e is actually currently supported, as that is what the Author mostly plays!). In releases later than v1.3.00 (01/10/2022), all RPG version-specific data, rulesets and processing has been extracted from the APIs and moved into an RPGMaster Library API that must be loaded alongside the RPGMaster APIs you wish to use (except Script:RoundMaster which is RPG version independent). Which version of the RPGMaster Library is loaded will determine the RPG version and Roll20 Character Sheet version that is supported by the APIs: as of now, only the following versions exist:

  • RPGMaster Library AD+D2e - supports Advanced Dungeon & Dragons V2e and the Advanced AD&D2e Character Sheet by Peter B.

[edit] General RPGMaster Library information

The RPGMaster Library API provides the data and rule-set processing for a specific RPG version and Roll20 Character Sheet for the RPGMaster series of APIs. This particular Library supports the Advanced Dungeons and Dragons v2e RPG, and the Advanced D&D 2e Character Sheet by Peter B.

The functions and data in the Library cannot be accessed directly by the GM or Players (with the exception of the RPGMaster Roll Templates). It does not support any API commands directly, but supports the functioning of the API commands provided by other RPGMaster APIs: InitiativeMaster, AttackMaster, MagicMaster and CommandMaster, to the extent that these APIs will not function without the Library being loaded. Note: RoundMaster does not have any RPG-version specific aspects, is independent of the Library, and does not require a RPGMaster Library to be loaded to function.

The Library does Roll Template processing for RPGMaster-defined Roll Templates. These can be used by GMs to create their own Chat menus and displays. See the descriptions in Section 2 for how to access and use these templates.

The Library also provides a number of objects and functions that can be called from other APIs. These include an extensive Character Sheet table management suite described in Section 3 below, for table structures defined by The Aaron in various standard Roll20 Character Sheets, such as the Advanced D&D 2e character sheet by Peter B. There are a number of other useful functions, which are described in Section 3.

[edit] RPGMaster Roll Templates

Roll Templates are standard Roll20 functionality, often provided by various Character Sheet versions. The RPGMaster Library provides RPGMaster-specific versions of Roll Templates to support gameplay using the RPGMaster series of APIs. Of course, they can also be used for other purposes by the GM to support their design for gameplay, and by other APIs that might be loaded alongside the RPGMaster Library API. The list of those provided is:

TemplateBased onDescription
RPGMattackRPGMattackFormat the results of attacks, Melee or Ranged
RPGMpotionRPGMspellDisplay the details of a potion, oil or other consumable liquid
RPGMspellRPGMspellDisplay the specification of a spell or power
RPGMscollRPGMspellDisplay the details of a scroll or book
RPGMmessageRPGMmessageDisplay a formatted message
RPGMwarningRPGMdefaultDisplay a warning message in a bold format
RPGMweaponRPGMdefaultDisplay the specification of a weapon of any type
RPGMammoRPGMdefaultDisplay the specification of ammunition for a Ranged weapon
RPGMarmourRPGMdefaultDisplay the specifications of any form of armour
RPGMringRPGMdefaultDisplay the specifications of a ring
RPGMwandRPGMdefaultDosplay the specifications of a wand, stave or rod
RPGMitemRPGMdefaultDisplay the specifications of any magic item
RPGMclassRPGMdefaultDisplay the details of a character class
RPGMmenuRPGMdefaultDisplay a menu of actions that a Player or GM can perform
RPGMdefaultRPGMdefaultA default template that can display any form of information

The templates are built upon four base templates: RPGMattack, RPGMspell, RPGMmessage, and RPGMdefault. However, each individual template can have different colour swatches and background images. It is also possible for the GM to use special template field tags to change the colours and background images of various parts of the templates, as described below.

[edit] User-Selectable Template Display Options

In the API configuration menu, opened using !attk --config or !magic --config, the GM can choose whether the default display of RPGMaster Roll Templates for everyone is Fancy, meaning the system uses background textures and images to make the chat templates look interesting, or Plain, which means the default display is of coloured templates but without textures or images.

In addition, each Player can choose their own options: at the top right of every menu or message displayed in the chat using a RPGMaster Template is a cog wheel. Clicking this cog wheel will display an options dialog for the Player with three options - Menus with Images, Plain Menus, and Dark Mode Menus. The Player can select one of the options, and the current and all future menus and messages using RPGMaster Roll Templates will be displayed for that particular Player using this new option. The option persists for that Player between gameplay sessions.

Note: if use of a template includes any of the colour or image field tags (outer image, title image or body image) these images will always appear regardless of which option the Player chooses. The field tags always override the original template definition.

[edit] Colour, Padding and Image Override Field Tags

All RPGMaster templates can use the following field tags (with some exceptions as noted). The field tags are used in this way:

{{field tag=... whatever you want to be in this field ...}}

However, the fields in this table do not display data, but take the content of the field after the "=" as data for a CSS command to change the behavior of the template.

shadowdrop shadow specThe specification of the Template drop shadow for the outer box in any form of CSS units
outercolorThe colour of the outer box of the template
title boxcolorThe fill colour of the title box
title textcolorThe colour of the title text
body boxcolorThe fill colour of the body box
row boxcolorThe colour of the outline of each row box
row lightcolorThe fill colour of alternate row boxs (light / dark / light / dark ...)
row light textcolorThe colour of alternate row text (light / dark / light / dark ...)
row darkcolorThe fill colour of alternate row boxs (light / dark / light / dark ...)
row dark textcolorThe colour of alternate row text (light / dark / light / dark ...)
outer padpadding specThe padding of the outer box specified using any form of CSS measurements
title padpadding specThe padding of the title box specified using any form of CSS measurements
body padpadding specThe padding of the body box specified using any form of CSS measurements
row padpadding specThe padding of each row box specified using any form of CSS measurements
outer imageImage URLThe URL to an image in Roll20 which will be drawn behind the whole Template
title imageImage URLThe URL to an image in Roll20 which will be drawn behind the title box
body imageImage URLThe URL to an image in Roll20 which will be drawn behind the body of the Template

The data passed with these field tags is one of four types: color, padding spec, shadow spec or image URL. Note, the CSS keyword is not needed in each case, just the data specification that would follow the keyword.

Tip: In fact, you can sneak additional CSS keywords into the data - e.g. the title text colour could be 'Template:Title text=white; text-shadow: 1px 1px 1px gray' which would sneak a drop-shadow onto the title text of the Template. This will not always work, but is worth trying.

colorCan be any valid < color > specification that can be placed after a CSS < color > command: a named color, a RGB specification, a HSL specification, or any other valid syntax.
padding specCan be any valid padding < length > specification that can be placed after a CSS < padding > command: relative units such as 'em' or 'small' or percentages, or can be absolute units such as 'px' or 'cm'.
shadow specCan be any valid shadow < length > and < color > specification that can be placed after a CSS < box-shadow > command: relative units such as 'em' or 'small' or percentages, absolute units such as 'px' or 'cm'; and a named color, a RGB specification, an HSL specification, or any other valid <color> syntax.
Image URLMust be a valid URL of a thumbnail image already loaded to the Roll20 image library - either your own or one you are provided with.

[edit] Template Definitions

[edit] RPGMattack

As with any template, the text in any of the fields can be anything allowed by Roll20 in a macro or template, except where noted otherwise. If to be used with a RPGMaster API database, the Specs and Data fields must be configured in line with the relevant database documentation and placed between the template fields so as not to be seen by the Players when the Roll Template is displayed. This is a highly graphical template (even in Plain Mode) and the Field Tags are generally not displayed.

Title / NameMandatoryThe title text for the attack template. Either field tag can be used, and the tag is not displayed.
SubtitleOptionalThe subtitle text for the attack template. The tag is not displayed.
AC hitMandatoryThe value of the Armour Class that has been successfully hit by the attack. Can be a Roll20 calculation and/or dice roll specification. If the "Crit Roll" and "Fumble Roll" field tags are to function correctly, the AC hit tag must include one Roll20 calculation field tagged as the Dice Roll e.g. matches ##[Dice roll].
Attk typeOptionalThe type of damage done by the attack: S, P, B, or any combination of these.
Dmg S LabelOptionalThe label / title to display for the Dmg S field on the template. If not provided, it defaults to "S / M". Useful if using the template for attacks that result in some outcome other than damage to the opponent.
Dmg SMandatoryThe specification to display for damage to Small & Medium opponents. Can be numeric, a Roll20 calculation, dice roll specification, or even an API button specification.
Dmg L LabelOptionalThe label / title to display for the Dmg L field on the template. If not provided, it defaults to "L". Useful if using the template for attacks that result in some outcome other than damage to the opponent.
Dmg LMandatoryThe specification to display for damage to Large and larger opponents. Can be numeric, a Roll20 calculation, dice roll specification, or even an API button specification.
Target ACOptionalThe Armour Class value of the targeted opponent. Only used for targeted attacks. Can be a Roll20 "@{target..." command, numeric value, calculation etc.
Target SACOptionalThe Armour Class value of the targeted opponent vs. Slashing attacks. Only used for targeted attacks. Can be a Roll20 "@{target..." command, numeric value, calculation etc.
Target PACOptionalThe Armour Class value of the targeted opponent vs. Piercing attacks. Only used for targeted attacks. Can be a Roll20 "@{target..." command, numeric value, calculation etc.
Target BACOptionalThe Armour Class value of the targeted opponent vs. Bludgeoning attacks. Only used for targeted attacks. Can be a Roll20 "@{target..." command, numeric value, calculation etc.
Target HPOptionalThe current Hit Points of the targeted opponent. Must result in a numeric value.
Target MaxHPOptionalThe maximum Hit Points of the targeted opponent. Must result in a numeric value.
ResultOptionalA comparison function between any two other field tags, which are usually AC_Hit and Target_AC (note the underscores added). Can use any test from: = < > <= >= <> != e.g. AC_Hit<=Target_AC if true will give a green Success bar, if false will give a red Failure.
SuccessCmdOptionalThe text provided will not be displayed but will be sent to the chat window if the Result comparison indicates success. Normally used to send an API command on a successful attack result
FailCmdOptionalThe text provided will not be displayed but will be sent to the chat window if the Result comparison indicates failure. Normally used to send an API command on a failed attack result
Crit RollOptionalData must result in a numeric value which is compared to the Dice Roll value tagged in the AC Hit field. If Crit_roll<=Dice Roll, displays a green "Critical Hit!" bar.
Fumble RollOptionalData must result in a numeric value which is compared to the Dice Roll value tagged in the AC Hit field. If Fumble_roll>=Dice Roll, displays a red "Fumbled!" bar.
Desc / Desc(1-9)OptionalUp to 10 description fields can be added to the bottom of any RPGMaster attack template. The field tag is not displayed. These can, for example, hold reminders of special outcomes of the attack depending on the weapon or creature wielding it, or the roll achieved.

[edit] RPGMspell, RPGMpotion & RPGMscroll

As with any template, the text in any of the fields can be anything allowed by Roll20 in a macro or template, except where noted otherwise. For spell, potion and scroll descriptions especially it is quite often useful to include API Buttons in some of the fields to run certain RPGMaster API commands: this is especially the case if using the RoundMaster API and the commands !rounds --target to set status markers and timers and target spell effects, and/or !rounds --aoe to display ranges and areas of effect. If to be used with a RPGMaster API database, the Specs and Data fields must be configured in line with the relevant database documentation and placed between the template fields so as not to be seen by the Players when the Roll Template is displayed.

Title / NameMandatoryThe title text for the template. Either field tag can be used, and is not displayed.
SPlevelOptionalThe level of the spell being cast. No need to provide for potions or scrolls.
SchoolOptionalThe school of the spell or spell-like effect.
RangeMandatoryThe range of the spell or spell-like effect.
ComponentsMandatoryThe components of the spell or spell-like effect. Often represented by a combination of the letters VSM.
DurationMandatoryThe duration of the spell or spell-like effect.
RangeMandatoryThe range of the spell or spell-like effect.
TimeMandatoryThe casting time or time until effect occurs of the spell or spell-like effect.
AoEMandatoryThe Area of Effect of the spell or spell-like effect.
SaveMandatoryThe validity and outcome of any saving throw or other mitigating factors to the spell or spell-like effect.
HealingOptionalThe healing or other beneficial effect of the spell or spell-like effect.
DamageOptionalThe damage or other maleficent effect of the spell or spell-like effect.
ReferenceOptionalA reference to where more information can be found about the spell or spell-like effect.
MaterialsOptionalThe material components required to cast the spell or spell-like effect.
Looks LikeOptionalA description of what the item looks like (for potions & scrolls), especially useful for hidden items.
EffectsOptionalA description of the effects of the spell or spell-like effect.
UseOptionalInstructions for how to use the spell or spell-like effect. Especially useful for complex spells that require actions to occur in a particular sequence, have different means of achieving different effects in different circumstances, or have long-lasting effects.
GM InfoOptionalOnly appears if the message is for the GM (though other players included in the same message will also see it). Instructions for the GM on how to use the spell or spell-like effect, such as how to tailor for your own campaigns.
Desc / Desc(1-9)OptionalUp to 10 description fields can be added to the bottom of any RPGMaster spell, potion or scroll template. The field tag is not displayed. These can, for example, hold reminders of special outcomes of the spell depending on the creature targeted, or anything else the GM thinks useful but does not fit in any other field.

[edit] RPGMmessage

This template is mostly used internally by the RPGMaster APIs to send messages to the GM and Players. It provides a very simple template with a minimum of overhead. As with any template, the text in any of the fields can be anything allowed by Roll20 in a macro or template, except where noted otherwise. If to be used with a RPGMaster API database, the Specs and Data fields must be configured in line with the relevant database documentation and placed between the template fields so as not to be seen by the Players when the Roll Template is displayed.

Title / NameOptionalThe title text for the template. In a Message Template, the title/name is optional and a message can appear without a title if so desired. Either field tag can be used, and is not displayed.
Desc / Desc(1-9)OptionalUp to 10 description fields can be defined, though usually it is just the one, which will contain the message. The field tag is not displayed.

[edit] RPGMdefault

All template definitions other than those described above use the base RPGMdefault template structure, with different colour swatches, textures and images. This template type is the most flexible, and will display pretty much any field tag that is added. Only a few are predefined, which provide the ability to structure the template. As with any template, the text in any of the fields can be anything allowed by Roll20 in a macro or template, except where noted otherwise. If to be used with a RPGMaster API database, the Specs and Data fields must be configured in line with the relevant database documentation and placed between the template fields so as not to be seen by the Players when the Roll Template is displayed.

Title / NameMandatoryThe title text for the template. Either field tag can be used, and the tag is not displayed.
SubtitleOptionalThe subtitle text for the template. The tag is not displayed.
Section / Section(1-9)OptionalA section header, separating other user-defined field tags (not the Desc description field tags, which always appear at the bottom of the template). The field tag is not displayed, and the contents are centred in the row.
Any User-defined tagOptionalAs many different user-defined field tags as are desired, using A-Z a-z - _ 0-9 and Space but always starting with an Alpha.
ResultOptionalA comparison function between any two other field tags which have numeric data or calculations and attribute look-ups that result in numeric data. The field tag names to be compared should have underscores '_' instead of spaces. Can use any test from: = < > <= >= <> != e.g. AC_Hit<=Target_AC if true will give a green Success bar, if false will give a red Failure.
SuccessCmdOptionalThe text provided will not be displayed but will be sent to the chat window if the Result comparison indicates success. Normally used to send an API command on a successful attack result
FailCmdOptionalThe text provided will not be displayed but will be sent to the chat window if the Result comparison indicates failure. Normally used to send an API command on a failed attack result
GM InfoOptionalOnly appears if the message is for the GM (though other players included in the same message will also see it). Instructions for the GM on whatever the roll template is about, such as how to tailor a magic item for your own campaigns.
Looks LikeOptionalA description of what the item looks like, especially useful for hidden items.
Desc / Desc(1-9)OptionalUp to 10 description fields can be defined, which will all be displayed at the bottom of the template in numeric order. The field tags are not displayed.

[edit] API Library Accessible Functions

In addition to the RPGM Templates described in Section 2, the RPGMaster Library provides a number of functions, objects and methods that might be of use to API authors, independantly of the RPGMaster series of APIs. These are described in this section. To access these, the functions can be accessed using the following syntax from other APIs:

LibRPGMaster.function( parameters )

Alternatively, so as not to need to reference the Library, and/or to facilitate an easily alterable and maintainable reference that can be changed in one place, the Library reference can be made within a function mapping, like this:

const localFunctionName = (...a) => libRPGMaster.functionName(...a);

The Library function can then be accessed using the localFunctionName in the API as required and, should the Library function call change, the change can be made in just one place.

The rest of this Section describes the accessible functions, objects and methods.

[edit] Get Character Sheet Field Map and Global Data

The RPGMaster Library holds RPG-version-specific data which other APIs can access, and a map of the important fields on the Roll20 Character Sheet version supported. References to each of these data items can be acquired using the getRPGMap() function:

[fields,RPGMap] = getRPGMap()

This function does not take any parameters, but returns an array of two object references:

  • fields: A reference for the object mapping standard internal API field names to the definitions for those fields on the supported Character Sheet. Using this field map means the programming of the API does not need to change for each Character Sheet. Each field definition has the structure
    api_field_name: [char_sheet_field_name,property,<defaultValue>,<sheetWorkerFlag>]
    where property is current or max, an optional defaultValue can be provided which is used if the field is undefined when read, and the sheetWorkerFlag (optional) is true if the field is to be set with the Roll20 setWithSheetWorker() method or false if the Roll20 set() method is to be used (default false).
  • RPGMap: a reference to an object with handles to each of the global data items available in the Library. The contents of these data items are specific to the versions of the RPG and Character Sheet supported by the Library. The data is as in the table below:
dbNamesAn array of the database objects of the standard, RPGMaster provided databases, indexed by name.
fieldGroupsAn object defining the groups of fields held in repeating tables on the Character Sheet and named in the fields object
spellsPerLevelAn object specifying the number of spells that can be memorised at each level by each class of spellcaster
specMUAn array of strings naming the standard specialist wizard classes for this RPG version
ordMUAn array of strings naming the standard ordinary wizard classes for this RPG version
wisdomSpellsAn array holding the additional spell slots or points per level for high wisdom scores
raceToHitModsAn object of race toHit modifiers with various weapon types and super-types
rangedWeapModsThe standard range mods to the toHit roll for firing ranged weapons at Near, Point Blank, Short, Medium, Long and Far ranges for this RPG version
saveLevelsAn object mapping class levels to the baseSaves table saving throw entries
baseSavesAn object holding for each base class an array of base saving throws with improvement by level progression mapped by saveLevels
classSaveModsAn object of class modifiers to the base saving throws
raceSaveModsAn object of race modifiers to the base saving throws

Please contact the author if you wish more in-depth specifications for any of these data elements.


[edit] Manage Character Sheet Tables

Some data on Character Sheets is best represented in tables, made up of multiple rows of multiple fields. Some tables can also have multiple columns of rows, each column containing rows which in turn have multiple fields (in fact, each column is considered a table in itself). Having a structured set of functions to add to, find, read, update, and remove data in these tables is a useful function to have. the ChatSetAttr API from The Aaron provides an amount of such functionality, but the RPGMaster Library provides a full suite of management functions, based on the definition of a standard Table Object, with associated Methods. The mechanics of the Character Sheet table are then hidden from the author of the API, who can concentrate on other functionality.

The Library consists of the Table Object, and the Methods. The mechanics of the Table Object are hidden from the API (but can be exposed & used if you know what you are doing and understand the structure of Character Sheet tables fully). The important aspects to know are the functions to get the table object from the character sheet, and the methods to manipulate the table object.

[edit] Table Management Functions

tableObject = getTable(character,fieldGroupDef,<column>,<tableObject>,<caseSensitive>)

Gets a complete table object from a character sheet. Also discovers all the valid default values for the table fields from the fields object. Takes the following parameters:

  • character: the character sheet object for the character sheet from which to get the table
  • fieldGroupDef: an entry from the fieldGroups object (obtained in the RPGMap with getRPGMap() - see Section 3.1). One of fieldGroup.MELEE .DMG .RANGED .AMMO .WPROF .MI .MAGIC .SPELLS .POWERS .INHAND .QUIVER .STYLES .GEAR .STORED .DUSTS .SCROLLS .MONWEAP .ALTWIZ .ALTPRI
  • column: (optional) for tables that have multiple columns, this is the column number to obtain. Each column is recovered as a complete table in itself
  • tableObj: (optional) an existing table object that will be overwritten with the complete table obtained by this command
  • caseSensitive: (optional) a true/false flag which, if true, makes all matches with table and field names in the table case sensitive (default is false, i.e. not case sensitive)

tableObject = getTableField(character,tableObject,tableDef,attributeDef,<column>,<defaultVal>,<caseSensitive>)

Gets all rows for one field of a table. Adds that to the table object passed as a parameter. Faster than obtaining the full table with getTable(), but should only be used for finding and reading data and not for writing or adding new data and especially not adding rows with the .addTableRow() method. Takes the following parameters:

  • character: the character sheet object for the character sheet from which to get the table
  • tableObject: an existing table object to add the field to, or an empty object '{}' to create a new table object with just this one field
  • tableDef: the table definition from the fields object obtained with the getRPGMap() function (see Section 3.1). This will be the entry 'fields.xxx_table' that defines the character sheet repeating table name and the first row index for the table
  • attributeDef: the table field definition from the fields object obtained with the getRPGMap() function (see Section 3.1). E.g. The entry for fieldName will be 'fields.xxx_fieldName' that defines the character sheet table field name and property (current or max)
  • column: (optional) for tables that have multiple columns, this is the column number to obtain. Each column is recovered as a complete table in itself
  • defaultVal: (optional) the default value to be given to this field if a row is blanked, or created without a value specified for this field. If not provided, it itself is defaulted to the default value provided for the field in the fields object obtained with getRPGMap()
  • caseSensitive: (optional) a true/false flag which, if true, makes all matches with table and field names in the table case sensitive (default is false, i.e. not case sensitive)

defaultValues = initValues(fieldGroupDef)

Gets a new default values object for the table defined by the provided field group definition from the fieldGroup object from the RPGMap obtained with getRPGMap() (see Section 3.1). The default values are those set for the table fields in the fields object. The structure of the values object is values[field_name][field_property]. Takes the following parameter:

  • fieldGroupDef: an entry from the fieldGroups object (obtained in the RPGMap, see getRPGMap() in Section 3.1). One of fieldGroup.MELEE .DMG .RANGED .AMMO .WPROF .MI .MAGIC .SPELLS .POWERS .INHAND .QUIVER .STYLES .GEAR .STORED .DUSTS .SCROLLS .MONWEAP .ALTWIZ .ALTPRI

[edit] Table Object Methods

value = tableObject.tableLookup(attributeDef,row,<defaultValue>,<returnObj>)

Looks up the value stored in a specified field in the specified row of the table object. Can take an optional default value (which will override the default value for the field stored in the table object itself), and an optional returnObj parameter to determine what is returned (value or object). Takes the following parameters:

  • attributeDef: the table field definition from the fields object obtained with the getRPGMap() function (see Section 3.1). For field fieldName,This will be the entry 'fields.xxx_fieldName' that defines the character sheet table field name and property (current or max)
  • row: the row number of the row to get the field value from. If the row number is beyond the current end of the table, will return a default value or < undefined >, depending on the value of the defaultValue parameter
  • defaultValue: a value or true or false (absolute boolian values). Defaults to true. If the field requested does not exist or does not have a value: true (or not provided) returns the default value stored for that field in the table object; false returns < undefined >; any other value is returned instead of the default value stored for that field in the table object
  • returnObj: an attributeDef or true or false (absolute boolean values). Defaults to false. false (or not provided) returns the value or default value of the requested field; true returns the field object from the table instead of the value; an attributeDef specifies a different property to return, e.g. current or max (uses only the property field of the attributeDef)

tableObject = tableObject.tableSet(attributeDef,row,value,<caseSensitive>)

Sets the value of the specified table field in the specified row to be the value provided. tableObject is changed in-place. Takes the following parameters:

  • attributeDef: the table field definition from the fields object obtained with the getRPGMap() function (see Section 3.1). For field fieldName, this will be the entry 'fields.xxx_fieldName' that defines the character sheet table field name and property (current or max)
  • row: the row number of the row to set the field value in. If the row number is beyond the current end of the table, will create a new object for that field and the row specified: WARNING: creating a new field in a row this way can have unpredictable results. It is better to use the addTableRow() method to add complete new rows or to define all the fields in an existing row
  • value: the value to store in the specified field in the specified row of the table
  • caseSensitive (optional) a true/false flag which, if true, makes all matches with table and field names in the table case sensitive (default is false, i.e. not case sensitive)
tableObject = tableObject.addTableRow(row,<values>)

Either add a new row to a table object with the provided or default values, or replace a current row with the provided or default values. tableObject is changed in-place. Takes the following parameters:

  • row: the row number of the row to write the values to. If the row number is beyond the current end of the table, will create all the fields in a new row of the Table Object, either with the values provided, or the default values
  • values: a values object (optional), created using the initValues() table function, and modified as required with new values for the fields. If not provided, defaults to the default values for the table fields held by the Table Object itself (effectively blanking the row). See the description of the initValues() function for the structure of the values object
row = tableObject.tableFind(attributeDef,valToFind)

Find the first row in the Table Object with an entry in the field defined by the attributeDef with the value of valToFind. If found, row will be a valid table row number; otherwise the method returns < undefined >. Takes the following parameters:

  • attributeDef: the table field definition from the fields object obtained with the getRPGMap() function (see Section 3.1). For the field fieldName, this will be the entry 'fields.xxx_fieldName' that defines the character sheet table field name and property (current or max) to search
  • valToFind: the value to be searched for in the attributeDef field
  • row: the row number of the first row on which a match occurs, or < undefined > if no match was found

[edit] Attribute Management

Two functions that get and set attribute values on the character sheet:

value = attrLookup( character, attributeDef, <tableDef>, <row>, <column>, <caseSensitive>, <defaultValue> );

A function that can get the value of an attribute from a character sheet, either from a standard attribute, or from a repeating table. However: for table field values using the Table Management functions, objects and methods is preferred and may suffer from fewer issues in future. Takes the following parameters:

  • character: the character sheet object for the character sheet from which to get the value
  • attributeDef: the attribute field definition from the fields object obtained with the getRPGMap() function (see Section 3.1). For a field fieldName this will be the entry 'fields.fieldName' that defines the character sheet attribute field name and property (current or max)
  • tableDef: (optional) the table definition from the fields object obtained with the getRPGMap() function (see Section 3.1). This will be the entry 'fields.xxx_table' that defines the character sheet repeating table name and the first row index for the table
  • row: (optional) the row number of the row to get the field value from. If the row number is beyond the current end of the table, will return a default value or < undefined >, depending on the value of the defaultValue parameter
  • column: (optional) for tables that have multiple columns, this is the column number from which to obtain the field value.
  • caseSensitive (optional) a true/false flag which, if true, makes all matches with table and field names case sensitive (default is false, i.e. not case sensitive)
  • defaultValue: (optional) a value or true or false (absolute boolian values). Defaults to true. If the field requested does not exist or does not have a value: true (or not provided) returns the default value stored for that field in the fields object; false returns < undefined >; any other value is returned instead of the default value stored for that field in the fields object

attributeObj = setAttr( character, attributeDef, value, <tableDef>, <row>, <column>, <caseSensitive> );

A function that sets the value held by an attribute on a character sheet. Can also set values in repeating tables on the character sheet. However: for table attributes it is highly recommended that the Table Management functions, objects and methods (see Section 3.2) are used to get and set repeating table field values, as this might suffer from fewer issues in the future. Takes for following parameters:

  • character: the character sheet object for the character sheet on which to set the value
  • attributeDef: the attribute field definition from the fields object obtained with the getRPGMap() function (see Section 3.1). For field fieldName this will be the entry 'fields.fieldName' that defines the character sheet attribute field name and property (current or max). If the attribute object does not exist on the character sheet (and is not a table field) it will be created
  • value: the value to store in the specified attribute of the specified character sheet
  • tableDef: (optional) the table definition from the fields object obtained with the getRPGMap() function (see Section 3.1). This will be the entry 'fields.xxx_table' that defines the character sheet repeating table name and the first row index for the table
  • row: (optional) the row number of the row to set the field value in. If the row number is beyond the current end of the table, the function will attempt to create the new row, and put the value in it
  • column: (optional) for tables that have multiple columns, this is the column number in which to set the field value. If the column does not exist, the function will return < undefined >
  • caseSensitive (optional) a true/false flag which, if true, makes all matches with table and field names case sensitive (default is false, i.e. not case sensitive)
  • attributeObj: the function returns the attribute object found and in which the value has been set, or < undefined > if a table field or row does not exist

[edit] Database Management

The RPGMaster series of APIs use a number of databases holding data about spells, powers, magic items, character classes, attack macros, and other aspects. These are held as objects within the game-version and character sheet-version specific RPGMaster Library, and can be supplemented by GM provided additional databases held in Roll20 character sheets. See the database help handouts distributed with the RPGMaster APIs for more information on each type of database.

The RPGMaster Library provides a number of database management functions which can be used by APIs to manage the provided databases. These functions are described here.

DBindex = getDBindex( <forceUpdate> )

A function to build or get and return an index to all entries in the RPGMaster databases. This function must be called before any items in the databases are queried or acted upon with the other database management functions. Having this index (which is globally held in the system) speeds up database access considerably over relying on the Roll20 object management functions, and allows the APIs to seamlessly access items that might be in either internal object databases or held in external character sheet databases, and supports the prioritisation of user-defined database items over Library defined items. Takes one optional parameter:

  • forceUpdate: (optional) A boolean flag: if true, forces the global database index to be recreated from scratch. If false or not provided, only builds the index if it does not already exist (e.g. when the game session has just started and the APIs initialise)

dbItemObject = abilityLookup( rootDB, dbItemName, <character>, <silent>, <default> );

A function to get an entry from a database. Uses the global DBindex internally to access the correct database entry directly, eliminating the speed of a Roll20 object search. The building of the index using getDBindex() will determine the priority order of the potential sources for database items: see that function description for details. However, if the item does not have an entry in the DBindex (i.e. is not in any currently loaded database), and if a character sheet object is passed as a parameter, this abilityLookup() function will also search the character sheet for a copy of the database item which might have previously been placed there by a getAbility() function call. This allows characters to have items that come from user-defined databases in one campaign that are carried with them to other campaigns which perhaps don't have the same user-defined databases loaded.

Takes the following parameters:

  • rootDB: The root database name for the type of item being recovered. Will access indexes from any database name that starts with the rootDB name. Can be one of MU-Spells-DB, PR-Spells-DB, Powers-DB, MI-DB, Attacks-DB, Class-DB
  • dbItemName: The name of the item being searched for. The following characters are ignored: '-', '_', 'space'.
  • character: (optional) the character sheet object for the character sheet for which the item is relevant, and which might hold any orphaned item that is not available in current databases.
  • silent: (optional) a boolean value which, if true, will surpress any error message if the rootDB is invalid or the item cannot be found. False or not provided will result in error messages being returned.
  • default: (optional) a boolean value which, if false, returns < undefined > for any database item object if the item is not found or other errors occur, or if true or not defined returns a default item with the following structure:
    {name:'-',type:'',ct:'0',charge:'uncharged',cost:'0',body:'This is a blank slot. Go search out something new to fill it up!'}
  • dbItemObject A database item object, of class AbilityObj, with structure:
    	class AbilityObj {<br>
    		constructor( dBname, abilityObj, ctObj, source ) {<br>
    			this.dB = dBname;<br>
    			this.obj = abilityObj;<br>
    			this.ct = ctObj;<br>
    			this.source = source;<br>
    			this.api = (abilityObj && abilityObj[1]) ? (abilityObj[1].body.trim()[0] == '!') : false;<br>
    		}

dbItemObject = getAbility( rootDB, dbItemName, character, <silent> )

A special version of abilityLookup() that not only gets the requested database item from the databases, but also saves that item to the stated character sheet for later reference. All parameters are defined the same as those for AbilityLookup() above. The returned dbItemObject.dB object attribute always holds the name of the character sheet, so that after a call to getAbility(), the standard Roll20 syntax of `%{${dbItemObject.dB}|${dbItemName}}` will work to display the database item in the chat window.


itemObject = setAbility( character, itemName, itemBody, <actionBar> )

A function to set or update a database item or an ability macro in a character sheet (database items are stored as ability macros on a character sheet). Note: the API in-memory databases cannot be updated in this way. Only items and ability macros on character sheets can be created and updated. Takes the following parameters:

  • character: the character sheet object of the character sheet on which the item is to be stored or updated.
  • dbItemName: The name of the item being set. The case of the name and the following characters will be saved as part of the name, but are ignored for indexing and matching of the item name to those already stored on the character sheet: '-', '_', 'space'.
  • dbItemBody: The content to store as the data item, which will be stored as a character sheet Ability Macro body. Can consist of any text that can be stored in an Ability Macro body
  • actionBar: (optional) a boolean value which, if true, will set the "Show as Token Action" flag for the Ability Macro that represents the item. Default is false
  • itemObject: the returned item object which represents the item just set. Has the same definition as dbItemObject defined for the abilityObject() function

errFlag = buildCSdb( dbFullName, dbObj, typeList, <silent> )

A function to extract an API databse from memory into a Character Sheet Database representation, so that the GM can examine the standard items stored there. Note: the function does not re-index the databases, so the Character Sheet database representation so created will not actually be used to recover data from by the system. If use of the Character Sheet database is required, it will be necessary to run a getDBindex( true ) function to force an index update. Takes the following parameters:

  • dbFullName: the name of the database to be built, which should be one of the databases named in the dbNames object returned by the getRPGMap() function (see Section 3.1), but does not have to be
  • dbObj: the database object in dbNames that is to be extracted to the Character Sheet database named dbFullName
  • typeList: one of clTypeLists (for character classes), spTypeLists (for all types of spell or power), or miTypeLists (for all other items), which have been obtained using getRPGMap() (see Section 3.1)
  • silent: (optional) a boolean value which, if true, will surpress any error messages. False or not provided will result in error messages being sent to chat. An error flag is always returned
  • errFlag: a boolean value indicating if an error occurred.

checkCSdb( <dbName> );

A function to check any character sheet database for completeness and accuracy. If the body texts of the item Ability Macros have been set up in accordance with the relevant database documentation handout, this function will ensure that all other attributes, lists and fields are set up to match the database item Ability Macros. Takes the following parameter:

  • dbName (optional) the name of the character sheet database to check. If not provided, or dbName = '-db', all character sheet databases will be checked

[edit] Changelog

v1.3.00 (2022-09-21)

  • First release to GitHub.
  • Updated to delete old versions of standard character sheet databases.


v1.3.01 (2022-10-01)

  • Fix issue with database lookup if a character has a name that includes "spell" or "power" in their name.
  • Added support for direct access to MU & PR spells, and/or other Magic Items as powers for characters and magic items.


v1.3.02 (2022-10-10)

  • Fixed errors in the coding of spells that requite a To-Hit roll but do damage rather than targeted magic.
  • Changed initiative modifier char sheet field from comreact to custom field init-mod.
  • Added spell as weapon flag to spell tables.


v1.3.03 (2022-10-22)

  • Support for the Race Database.


v1.3.04 (2022-11-15)

  • Allow handleCheckSaves() to work in silent mode.
  • Added support for the Creatures database.


v1.4.01 (2022-11-28)

  • Support for the Fighting Styles database & creature setup.
  • Allowalphabetically indexed lists.
  • Support %{DB


v1.4.02 (2022-12-16)

  • More creature definitions, and supporting powers.
  • Add ability to specify weapons and armour for creatures with probability of different sets.
  • Also added ammo reuse type 2: becomes only possible ammo of several for that weapon e.g. spitting snake venom, and type 3: reduces in qty by 1, and all other ammo for same weapon increases qty b 1.


v1.4.03 (2023-01-16)

  • Added Attack messages (similar to damage messages) using Ranged weapons notes field.
  • Added ability for creature innate attacks to have damage roll before attack name so they work with CS buttons.
  • Fixed issue with abilityLookup() if ability name undefined.
  • Fixed issue with resolveData() if not defaulting values & ns: attribute not specified.


v1.4.04 (2022-01-16)

  • Added creature attkmsg & dmgmsg attributes to support messages to display with attack and damage rolls respectively.
  • Added table & function to return calculated base Thac0.
  • Made attrLookup() and getTokenValue() more robust vs. Character Sheet errors.
  • Added support in getTokenValue() for redefined default token bars.
  • Added support for Character Sheet conversion.
  • Gave Ammo its own lookup table capability.


v1.4.04 (2023-02-02)

  • Added code necessary to support new Rods, Staves & Wands, the new Magic item class, and charges expended on successful hit.
  • Fixed DB entries that incorrectly use parentheses.
  • Modified tableFind() to compare field values using dbName().
  • Decouple AttackMaster and MagicMaster config values from parseOutput().
  • Better error handling for several library functions.
  • Moved caster level parsing to the library.


v1.4.05 (2023-04-09)

  • Updated MI database and Magic Database Help to add ability for bags to automatically create item-holding character sheet, and optionally for it to auto-populate initial items in the bag.
  • Added "GM Info" as a possible line tag for RPGMspell & RPGMdefault Roll Templates, that is shown only if the GM is one of the recipients for the message.


v1.4.07 (2023-04-15) max attribute on character sheet.


v1.4.08 (2023-04-20)

  • Updated MI database items to compress using %{...


v1.5.01 (2023-05-17)

  • Fixed db reData parsing to only recover relevant text.
  • Fixed reDataCharge parsing to accept + as a valid character.
  • Fixed db Specs field parsing to only recover relevant data.
  • Added string trueCompare(txt) prototype.
  • Added the dispName() string prototype to replace hyphens with spaces in names to display.
  • Added improved handling of hidden magic items.
  • Added "Looks Like" special template tag which will auto-hide an item and display only what it looks like until revealed.
  • Default unknown magic item classes to be the same as "miscellaneous".
  • Allow character_ids to be substituted for token_ids in calls to getCharacter().
  • Added the ability to alphabetise lists.
  • Allow 'PW' to substitute 'POWER' in calls to caster() and related functions.