Introduction to Tables

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
-135	Down & Left/Southwest	-179 - -90	Southwest facing image	-179 - -135	West facing image (Row 1 of 2)
-90	Down/South			-134 - -45	South facing image
-45	Down & Right/Southeast	-89 - 0	Southeast facing image
0	Right/East			-44 - 45	East facing image
45	Up & Right/Northeast	1 - 90	Northeast facing image
90	Up/North			46 - 135	North facing image
135	Up & Left/Northwest	91 - 180	Northwest facing image
180	Left/West			136 - 180	West 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

• setTablePickOnce()
• getTablePickOnce()
• resetTablePicks()
• getTablePicksLeft()

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.