Introduction to Tables: Difference between revisions

From RPTools Wiki
Jump to navigation Jump to search
(Add Categories)
No edit summary
 
(10 intermediate revisions by 4 users not shown)
Line 1: Line 1:
{{Beginner}}
MapTool Tables make it easy to randomly select an image or a line of text from a list of options. Basic uses for tables include graphical dice rolls, simulating drawing from a decks of cards, generating random treasure, and rolling for random encounters.  
MapTool Tables make it easy to randomly select an image or a line of text from a list of options. Basic uses for tables include graphical dice rolls, simulating drawing from a decks of cards, generating random treasure, and rolling for random encounters.  


Tables can be used with MapTool's macro scripting language using [[:Category:Table_Function|Table Macro Functions]]. MapTool also recognizes tables formatted in a certain way as 'facing' images intended for tokens on an isometric grid.
Tables have some advanced features such as token image tables, pick once tables, and can be used with MapTool's macro scripting language using [[:Category:Table_Function|Table Macro Functions]].


The loaded campaign's tables can be viewed in the {{ui_location|Tables panel}}, toggled from the menu at {{ui_location|Window > Tables}}.
The loaded campaign's tables can be viewed in the {{ui_location|Tables panel}}, toggled from the menu at {{ui_location|Window > Tables}}.
Line 41: Line 42:
* Removing/deleting a table is permanent and '''can't be undone'''!
* Removing/deleting a table is permanent and '''can't be undone'''!
* Duplicating a table will immediately open the New Table dialog populated with the source table's data and the name ''Copy Of (the name of your source table)''.
* Duplicating a table will immediately open the New Table dialog populated with the source table's data and the name ''Copy Of (the name of your source table)''.
== Token Image Tables ==
{{Intermediate}}
In a token's properties, there is an [[Introduction_to_Tokens#Image_Table|Image Table]] setting with lets you specify a table of 'facing' images intended for tokens on an isometric grid.
Image Tables work by keying the 'facing' value of a token to an image. Facing values are in degrees from -179 to 180, starting with 0 in the east/right side of the screen and increasing counter-clockwise around the token (it loops from 180 to -179 on the left/west side of the token). To properly work, image tables need their ''Range'' values to fully include all the possible facing values from -179 to 180.
To create an image table with 4 images, you need to break the circle up in 90 degree chunks around your desired directions. Following is a table of eight cardinal directions in degrees and sample values for a table to display 4 edge-facing token on isometric and square grids.
<table cellspacing=0 cellpadding=4 style="border-collapse: collapse; border: 1px silver solid">
<tr>
<th colspan=2>Cardinal Directions</th>
<th colspan=2>Ranges for Isometric Grid</th>
<th colspan=2>Ranges for Square Grid</th>
</tr>
<tr>
<th style="border:1px solid #afafaf">Degrees</th>
<th style="border:1px solid #afafaf">Direction</th>
<th style="border:1px solid #afafaf">Range</th>
<th style="border:1px solid #afafaf">Value / Image</th>
<th style="border:1px solid #afafaf">Range</th>
<th style="border:1px solid #afafaf">Value / Image</th>
</tr>
<tr>
  <td style="border:1px solid #afafaf">-135</td><td style="border:1px solid #afafaf">Down & Left/Southwest</td>
  <td style="border:1px solid #afafaf" rowspan=2>-179 - -90</td><td style="border:1px solid #afafaf" rowspan=2>Southwest facing image</td>
  <td style="border:1px solid #afafaf">-179 - -135</td><td style="border:1px solid #afafaf">West facing image (Row 1 of 2)</td></tr>
<tr>
  <td style="border:1px solid #afafaf">-90</td><td style="border:1px solid #afafaf">Down/South</td>
  <!-- td colspan="3"> - </td -->
  <td style="border:1px solid #afafaf" rowspan=2>-134 - -45</td><td style="border:1px solid #afafaf" rowspan=2>South facing image</td></tr>
<tr>
  <td style="border:1px solid #afafaf">-45</td><td style="border:1px solid #afafaf">Down & Right/Southeast</td>
  <td style="border:1px solid #afafaf" rowspan=2>-89 - 0</td><td style="border:1px solid #afafaf" rowspan=2>Southeast facing image</td>
  <!-- td colspan="2"> - </td -->
<tr>
  <td style="border:1px solid #afafaf">0</td><td style="border:1px solid #afafaf">Right/East</td>
  <!-- td colspan="3"> - </td -->
  <td style="border:1px solid #afafaf" rowspan=2>-44 - 45</td><td style="border:1px solid #afafaf" rowspan=2>East facing image</td></tr>
<tr>
  <td style="border:1px solid #afafaf">45</td><td style="border:1px solid #afafaf">Up & Right/Northeast</td>
  <td style="border:1px solid #afafaf" rowspan=2>1 - 90</td><td style="border:1px solid #afafaf" rowspan=2>Northeast facing image</td>
  <!-- td colspan="2"> - </td -->
<tr>
  <td style="border:1px solid #afafaf">90</td><td style="border:1px solid #afafaf">Up/North</td>
  <!-- td colspan="3"> - </td -->
  <td style="border:1px solid #afafaf" rowspan=2>46 - 135</td><td style="border:1px solid #afafaf" rowspan=2>North facing image</td></tr>
<tr>
  <td style="border:1px solid #afafaf">135</td><td style="border:1px solid #afafaf">Up & Left/Northwest</td>
  <td style="border:1px solid #afafaf" rowspan=2>91 - 180</td><td style="border:1px solid #afafaf" rowspan=2>Northwest facing image</td> 
  <!-- td colspan="2"> - </td -->
<tr>
  <td style="border:1px solid #afafaf">180</td><td style="border:1px solid #afafaf">Left/West</td>
  <!-- td colspan="3"> - </td -->
  <td style="border:1px solid #afafaf">136 - 180</td><td style="border:1px solid #afafaf">West facing image (Row 2 of 2)</td></tr>
</table>
''Note 1:'' The Square Grid needs 2 rows with the West facing image, since a 90 degree range facing west includes both the upper (180) and lower (-179) limits of the facing value.
''Note 2:'' MapTool can understand hyphenated ranges with negative numbers, so {{code|-179--90}} will be understood correctly even if it looks odd to the reader.
== Pick Once Tables ==
{{Advanced}}
This is a new feature added with v1.6.0.
The individual entries in a Pick Once table can only be randomly chosen once until the table is reset with the resetTablePicks() function. This can be used to simulate a deck of cards where a card picked is no longer available for future picks until the deck is re-shuffled.
Currently, setting a table as Pick Once can only be done via the {{func|setTablePickOnce}} macro function.  Once a table has been set as Pick Once it will remain that way until changed via the same function.
'''Pick Once Functions'''
* {{func|setTablePickOnce}}
* {{func|getTablePickOnce}}
* {{func|resetTablePicks}}
* {{func|getTablePicksLeft}}
=== Poker Deck Example ===
A basic example of using a Pick Once deck.
'''Make a Poker Deck'''
# Add Default Tables to your campaign if not there already.
# Make a duplicate of the Standard card deck table and name it ''Poker''
# Execute the following macro command in the chat window to make it a Pick Once table:
<syntaxhighlight lang="mtmacro" line>
[h: setTablePickOnce("Poker", 1)]
</syntaxhighlight>
'''Deal a Hand'''
# Add a macro to the Campaign macro panel and name it ''Deal Hand''.
# Put in the following macro code.
<syntaxhighlight lang="mtmacro" line>
[h: picks = getTablePicksLeft("Poker")]
[r, if(picks < 5), code:{
Shuffling...<br>
[h: resetTablePicks("Poker")]
};{}]
<image src='[r: tblImage("Poker")]' width=80></image>
<image src='[r: tblImage("Poker")]' width=80></image>
<image src='[r: tblImage("Poker")]' width=80></image>
<image src='[r: tblImage("Poker")]' width=80></image>
<image src='[r: tblImage("Poker")]' width=80></image>
</syntaxhighlight>
Every time you click on the Deal Hand macro button you'll get 5 card images in the chat window.
[[File:PokerHandExample.png]]
The macro will automatically shuffle the deck ({{func|resetTablePicks}}) when fewer than 5 cards remain.


[[Category:Feature Guide]]
[[Category:Feature Guide]]
[[Category:Beginner]]
[[Category:Beginner]]
[[Category:Tutorial]]
[[Category:Tutorial]]

Latest revision as of 20:24, 15 March 2023

BEGINNER
THIS IS A BEGINNER ARTICLE

MapTool Tables make it easy to randomly select an image or a line of text from a list of options. Basic uses for tables include graphical dice rolls, simulating drawing from a decks of cards, generating random treasure, and rolling for random encounters.

Tables have some advanced features such as token image tables, pick once tables, and can be used with MapTool's macro scripting language using Table Macro Functions.

The loaded campaign's tables can be viewed in the Tables panel, toggled from the menu at Window > Tables.

Default Tables

Every install of MapTool includes an option to add a set of default tables to your campaign from the menus by selecting Help > Add Default Tables.... These tables are both useful and an excellent starting place to learn about basic table use. They include:

  • 6 dice image tables for rolling a D4, D6, D8, D10, D12, and D20,
  • 2 standard card deck tables, one with jokers and one without.

Using Tables

There are 3 ways to roll a simple result for a table:

  1. Using the mouse. Double-click the table from the Tables panel. If an image is present for the roll result, it will be shown in chat. If not, the 'Value' will be shown instead.
  2. Using chat commands. Enter /table table_name or /tbl table_name in chat to roll the table. Table names are case-sensitive, and if the name has a space enclose it in single or double quotes. If an image is present for the roll result, it will be shown in chat. If not, the 'Value' will be shown instead.
  3. Using macro script.
    1. The table() function will display only the value of a random or specific row.
    2. The tableImage() function will display only the Image asset value of a random or specific row. This can be then used as the 'src' attribute in HTML image tags.

Creating Tables

New tables can be added by clicking the green plus symbol in the top left of the Tables panel (Tables can also be created using the createTable() macro function). When creating a table, the following fields are available to you:

  • Name: Your table's name. This name is case sensitive and will be used for chat commands and macros so short, descriptive names are recommended. If you include a space in your table's name you will have to enclose the name in quotes when rolling it with a chat command.
  • Roll: A dice code in XdY+Z format. If left blank, MapTool will automatically determine a roll from the the lowest and highest values in the Range column of your table. For ranges that use multiple dice, always enter the Roll yourself. For instance, if your table has a total range from 2 to 12, MapTool will create a roll of 1d11+1 when you probably want to enter 2d6.
  • Table Image: This is an image from the Resource Library to visually represent your table in the
  • Show Table to Players: When checked, will allow connected players to see the table in the Tables panel.
  • Allow Lookup by Players: When checked, will allow connected players to use the table by double-clicking it in the Table Panels (if visible) or by using chat commands.
  • Table Rows: Tables themselves are essentially lists where each row has three columns. Here is where you define your table's rows.
    • Range: Either a single integer value or a hyphenated range (such as 5-10). If not set explicitly, the table's Roll is determined by taking the minimum and maximum numbers among your table's Range values.
    • Value: A text value for the row. When activated with the mouse or via a chat command, the value will be shown only if no image is present.
    • Image: An image from the Resource Library. When activated with the mouse or via a chat command, the row's image will be shown if present.

Note about Ranges: MapTool expects your table ranges to be continuous, i.e. without numerical gaps. A table that has three rows with the ranges 1, 2, and 4 will generate a roll of d4 and produce an error whenever '3' is rolled, because there is no corresponding Range value in any of the table's rows.

Editing, Removing, and Duplicating Tables

In the Tables panel, select a table and click on the pencil icon to edit it, the red minus icon to remove it, or the double file icon to duplicate it. Tables can also be updated using a variety Table Macro Functions, though for most uses of tables the UI will be much more convenient. Here are notes about these table functions:

  • When editing a table, remember to update the Roll so it matches your updated table. If you remove the Roll entirely and save the table, MapTool will recalculate a single dice roll for your table's range.
  • Removing/deleting a table is permanent and can't be undone!
  • Duplicating a table will immediately open the New Table dialog populated with the source table's data and the name Copy Of (the name of your source table).

Token Image Tables

INTERMEDIATE
THIS IS AN INTERMEDIATE ARTICLE

In a token's properties, there is an Image Table setting with lets you specify a table of 'facing' images intended for tokens on an isometric grid.

Image Tables work by keying the 'facing' value of a token to an image. Facing values are in degrees from -179 to 180, starting with 0 in the east/right side of the screen and increasing counter-clockwise around the token (it loops from 180 to -179 on the left/west side of the token). To properly work, image tables need their Range values to fully include all the possible facing values from -179 to 180.

To create an image table with 4 images, you need to break the circle up in 90 degree chunks around your desired directions. Following is a table of eight cardinal directions in degrees and sample values for a table to display 4 edge-facing token on isometric and square grids.

Cardinal Directions Ranges for Isometric Grid Ranges for Square Grid
Degrees Direction Range Value / Image Range Value / Image
-135Down & Left/Southwest -179 - -90Southwest facing image -179 - -135West facing image (Row 1 of 2)
-90Down/South -134 - -45South facing image
-45Down & Right/Southeast -89 - 0Southeast facing image
0Right/East -44 - 45East facing image
45Up & Right/Northeast 1 - 90Northeast facing image
90Up/North 46 - 135North facing image
135Up & Left/Northwest 91 - 180Northwest facing image
180Left/West 136 - 180West facing image (Row 2 of 2)

Note 1: The Square Grid needs 2 rows with the West facing image, since a 90 degree range facing west includes both the upper (180) and lower (-179) limits of the facing value.

Note 2: MapTool can understand hyphenated ranges with negative numbers, so -179--90 will be understood correctly even if it looks odd to the reader.

Pick Once Tables

ADVANCED
THIS IS AN ADVANCED ARTICLE

This is a new feature added with v1.6.0.

The individual entries in a Pick Once table can only be randomly chosen once until the table is reset with the resetTablePicks() function. This can be used to simulate a deck of cards where a card picked is no longer available for future picks until the deck is re-shuffled.

Currently, setting a table as Pick Once can only be done via the setTablePickOnce() macro function. Once a table has been set as Pick Once it will remain that way until changed via the same function.

Pick Once Functions

Poker Deck Example

A basic example of using a Pick Once deck.

Make a Poker Deck

  1. Add Default Tables to your campaign if not there already.
  2. Make a duplicate of the Standard card deck table and name it Poker
  3. Execute the following macro command in the chat window to make it a Pick Once table:
[h: setTablePickOnce("Poker", 1)]

Deal a Hand

  1. Add a macro to the Campaign macro panel and name it Deal Hand.
  2. Put in the following macro code.
[h: picks = getTablePicksLeft("Poker")]
[r, if(picks < 5), code:{
	Shuffling...<br>
	[h: resetTablePicks("Poker")]
};{}]

<image src='[r: tblImage("Poker")]' width=80></image>
<image src='[r: tblImage("Poker")]' width=80></image>
<image src='[r: tblImage("Poker")]' width=80></image>
<image src='[r: tblImage("Poker")]' width=80></image>
<image src='[r: tblImage("Poker")]' width=80></image>

Every time you click on the Deal Hand macro button you'll get 5 card images in the chat window.

The macro will automatically shuffle the deck (resetTablePicks()) when fewer than 5 cards remain.