MapTool Preferences

Note: Screenshots in this article are shown with the default settings, which might not necessarily be the recommended settings for your use.

BEGINNER
THIS IS A BEGINNER ARTICLE

Interactions Tab

File:prefs tab interactions.png

Interactions Tab on the Preferences Dialog

Maps

Maps Section

• New maps have Fog of War

Determines if new maps should have Fog of War enabled when created. If you use Fog of War, it might seem obvious to have this ✓checked; however, when creating multiple maps for a new campaign, it is often useful to to disable this feature to assist with rapid map creation since even as a GM you will be unable to clearly view a map covered in Fog of War. After completing a map, it is a simple process to re-enable Fog of War.

• New maps visible to players

Determines if new maps should be set as Player Visible when created. Although there are exceptions, typically having this ✓unchecked is the optimal setting; that way you won't unintentionally leave a map visible to players.

• New Map Grid Type
  • Square File:gridSquare.png
  • Horizontal Hex File:gridHorizontalHex.png
  • Vertical Hex File:gridVerticalHex.png
  • Isometric File:gridIsometric.png

Determines the default grid type of new maps when created. You are free to create maps without a grid type, and also a grid type different than the one specified here, but you can not set the Default Grid Type to none.

• New Map Grid Size

Represents the default amount of pixels you want MapTool to use drawing each grid cell at full resolution. The default setting of 100 pixels is adequate for most computers, but more capable computers can handle 100 pixels or even 200 pixels computers. There is no requirement that you use specific sizes, but 50 pixels and 100 pixels are commonly used. This setting will also determine how large an image appears when placed on a map layer when 'Start Freesize' is not checked for that layer.

• New Map Units Per Cell

Sets the amount of units that each grid cell represents. The ambiguous "unit" is used in this case because you decide what "unit" means. If you want each grid cell to represent 5 feet, this would be set to 5. If you want each grid cell to represent 4 kilometers, this would be set to 4. This is often referred to as Distance Per Cell. As of v1.5.1 MapTool supports a floating point number for this value.

• New Map Vision Distance

The maximum distance that PC Tokens can expose Fog of War after Lights, Sights, and Vision Blocking Layers are taken into account. It is important to note that this setting is measured in Distance Per Cell.

• New Map Light

The light setting for new maps. Choose from Off, Day and Night. (As of MT v1.5.11)

• Movement metric
  • ONE_TWO_ONE specifies that every second diagonal movement will calculate as twice the Distance Per Cell.
  • ONE_ONE_ONE specifies that diagonal movement will calculate the same as non-diagonal movement.
  • MANHATTAN specifies that every diagonal movement will calculate as twice the Distance Per Cell.
  • NO DIAGONALS specifies that Tokens can only move non-diagonally.

Determines how movement should be calculated when a Token moves diagonally on maps using a Square or Isometric grid. This affects the total distance displayed beneath a Token when it is moving, or when its previous path is displayed; it is calculated based on Distance Per Cell. Maps with Hex grid types ignore this setting and instead calculate movement in any direction using the Distance Per Cell.

Tokens

Tokens Section

• Start Snap to Grid

Determines if Tokens will default to having Snap to Grid ✓checked. Having this setting ✓checked is optimal for maps that use a grid, but even on such maps there are cases when you might want to temporarily disable this setting(e.g. when placing a lot of "prop" Tokens on the Object layer while drawing a map).

• New tokens visible to players

Determines if new Tokens have the Visible option ✓checked upon creation. The optimal setting for this really depends on your play style; if you have a lot of random encounters and build them during play, you may find it useful to have this setting disabled.

• Warn when tokens are deleted

When ✓checked MapTool asks for confirmation whenever deleting a Token.

• Duplicate Token Numbering
  • Increment
  • Random

Will automatically generate numbers for Tokens with duplicate names upon creation to distinguish them. Increment will leave the first token unnumbered, but will number each duplicate after that starting with the number 1 (e.g. Troll, Troll 1, Troll 2). Random will create a random two-digit or greater number for the token, even if there are no duplicates on the map yet. Random might be considered the optimal setting, as it gives your players no indication of how many copies of that Token can be expected to exist.

• Show Numbering on
  • Name
  • GM Name
  • Both

Specifies where the number that derived from Duplicate Token Numbering is applied. Name appends the number after the name (derived from New Token Naming). GM Name places the number within the GM Name field of the Token options. Both appends the number after the name, and places it within the GM Name field of the Token options.

Note: It is generally recommended that you set this preference to Name or Both, and not GM Name. Any Macros which refer to tokens by name rather than by token ID will break/behave unpredictably when a map has multiple tokens with the same name.

• New Token Naming
  • Use Filename
  • Use "Creature"

Determines what the name will be when creating a new Token, or what the Name field will be pre-filled with in a new Token dialog. Use Filename specifies that the name will be derived from the name of the file that was added to your Resource Library (e.g. if you add the file uglytroll.jpg to your Resource Library, tokens created from that image will begin with the name uglytroll). Use "Creature" defaults all new Tokens to being named "Creature" (without quotes).

• Start Freesize

If you are using a map with a grid, Tokens typically default to the size of one grid cell upon creation. Having this setting ✓checked allows you to have them default to the image's Native Size. Native Size tokens moved to another layer become Freesize, which can be resized by dragging a handle in their lower right corner.

• Show Dialog on New Token

When this setting is ✓checked, a New Token dialog will open when you drag an image onto the map, allowing you to set some options prior to creation. If you disable this setting, all new tokens will be created with the default settings derived from previous settings in this section.

• Stat Sheet Portrait Size (Set to 0 to disable portaits)

Sets the width (in pixels) of the portrait that is displayed in the lower left corner of the map when mousing over certain Tokens; the image is resized proportionately. A portrait is displayed under a few different circumstances; if the Token has properties that are set to display on the stat sheet, and those properties have values, the portrait will display the token image. If the Token has a portrait image set, it will display with or without a stat sheet. Why might you want to set this to 0? Besides the obvious reason of not displaying the portrait, you might want to use a stat sheet, but not want a portrait displayed with it; or perhaps you don't want to use a stat sheet or a portrait, but would like to have the portrait image 'slot' usable for other purposes, like inside a Dialog or Frame.

• Show Portrait on mouseover

When ✓checked, displays the token's Portrait image in the lower left corner when the cursor is hovered over the token.

• Show stat sheet on mouseover

When ✓checked, displays the token's stat sheet in the lower left corner (to the right of the portrait) when the cursor is hovered over the token.

• Stat sheet requires Shift key

Requires the Shift key be held down when the cursor is hovered over the token in order to display the stat sheet when ✓checked. Has no effect if Show stat sheet on mouseover is unchecked. MapTool only checks if the Shift key is depressed when the cursor first passes over a token and then either displays or suppresses the stat sheet, meaning you cannot use this setting to 'toggle' the statsheet on and off with the shift key without also moving the cursor.

• Force Token Facing Arrow

Displays a yellow facing arrow on all tokens with a facing value when ✓checked, even on top-down tokens which normally omit them.

• Snap Token while dragging

Tokens will snap to the grid as they are dragged when ✓checked. When unchecked, the token's path and destination are still highlighted.

• Hide Mouse Pointer while dragging

MapTool hides the cursor arrow while dragging tokens within the map view when ✓checked.

Chat

Chat autosave settings now reside in the 'Application' tab of the Preferences window.

File:prefs interactions chat.png

Chat Section

• Show Avatar per line

The image for the impersonated token is shown next to any chat output it creates, when this is ✓checked. This is a client-side setting and does not effect any other clients connected to the same game.

• Insert Smilies

Replaces common smiley(emoticon) character sequences with graphical smilies when this is ✓checked. If you use a lot of macros, it is recommended that you turn this off, as it could cause some complications if any of your macro code is interpreted as a smiley.

• Use ToolTips for Inline Rolls

Sets the default display (Display Roll Option) for rolls in the chat panel. Will use [tooltip:] if this is ✓checked, otherwise it will default to [expanded:].

• Suppress ToolTips for MacroLinks

MacroLinks normally show tooltips that state information about the link target as an anti-cheating device. When ✓checked, these tooltips are disabled.

• Typing Notification Duration Seconds

The number of seconds before typing notifications in the top left of the Map View disappear after a player's last keystroke.

• Typing Notification Color

Color of the text for typing notifications.

• Show Chat Notification Background

When ✓checked shows a graphic behind typing notifications. Can be helpful to provide consistently contrasting background for the notifications.

• Trusted Prefix Background

Sets a custom background for macro output that comes from a Trusted Macro.

• Trusted Prefix Foreground

Sets a custom foreground (text color) for macro output that comes from a Trusted Macro.

Macro Editor

Macro Editor Section

• Style Theme

Select from a variety of themes for macro editor windows.

Objects

Objects Section

• Start Snap to Grid

Tokens created on map's Object layer will automatically be set to Snap to Grid if this is ✓checked.

• Start Freesize

Tokens created on a map's Object layer will automatically be set to Freesize if this is ✓checked.

Backgrounds

Backgrounds Section

• Start Snap to Grid

Images dropped on a map's Background layer will automatically be set to Snap to Grid, if this is ✓checked.

• Start Freesize

Images dropped on a map's Background layer will automatically be set to Freesize, if this is ✓checked.

Facing

Facing Section

• On Edges

A token's facing will snap to the edges when ✓checked. Edges are the lines that make up a grid cell.

• On Vertices

A token's facing will snap to the vertices when ✓checked. Vertices are the points that connect the lines that make up a grid cell.

Accessibility Tab

File:prefs tab accessibility.png

Accessibility Tab on the Preferences Dialog

• Chat Font Size

The default size of the font in the chat panel; measured in points.

• ToolTip Initial Delay

The time it takes for a tooltip to display when hovering the mouse over an element that possesses a tooltip; measured in miliseconds.

• ToolTip Dismiss Delay

The time it takes for a tooltip to disappear when hovering the mouse over an element that possesses a tooltip; measured in miliseconds.

Application Tab

File:prefs tab application.png

Application Tab on the Preferences Dialog

Save

File:prefs application save.png

Save Section

• Campaign autosave every [ ] min

Saves an autosave copy of your campaign in the interval specified in %{appHome}/autosave. This will not overwrite your campaign file, but rather create a file which is updated every time it automatically saves. Autosave is only a temporary file, useful in case MapTool crashes. When MapTool is properly closed, the Autosave file is deleted. Note the interval is the time between the last save completing and the start of the next one.

As a troubleshooting aid, the AutoSaveManager will switch from measuring the autosave interval in minutes to seconds when the log level for that package is set to “DEBUG”.

• Save reminder on close

Displays a dialog when attempting to close the program with unsaved changes to your campaign when ✓checked.

• Time between chat log autosaves

The amount of time in minutes between the autosaving of the chat log.

• Autosave chat log filename

The filename that will be used when automatically saving your chat log. Unless it has been changed on the #Startup_Tab, the directory containing the file will be ~/.maptool-rptools

• File Sync Directory

Specify a path to a local cloud-synced directory to determine relative path external files such as Hero Lab portfolios. (This appears to be used only when relative pathnames appear as icons, images, or other references within Hero Lab portfolio files.)

• 1.3b50 Compatability Mode

This setting has been removed. You can use File > Export Campaign As... to save campaigns for MapTool versions as far back as 1.4.0.

Due to some changes in how certain data is stored in the campaign file in versions after 1.3b50, they might not be compatible with version 1.3b50 and earlier. If this is ✓checked your campaign will be saved in the older format, allowing it to be opened in older versions, but losing some of the new features.

Map Visuals

Map Visuals Section

• Halo line width

Controls the width of the Halo border when it is displayed on a Token.

• Use halo color for vision

When this setting is ✓checked, hovering over a token with Vision overlays the token's visible area with the token's Halo color. This overlay is a translucent layer controlled by the Halo opacity setting.

• Halo opacity

Controls the opacity of the optional overlay enabled by the Use halo color for vision setting. This does not control the actual Halo's outline opacity, which is always completely opaque. This value can be a number from 0 (transparent) to 255 (opaque).

• Aura opacity

Controls the opacity of color overlays provided by Auras enabled on tokens. This value can be a number from 0 (transparent) to 255 (opaque).

• Light opacity

Controls the opacity of color overlays provided by Light Sources enabled on tokens. This also affects 'personal' lights defined in a token's Vision setting. This value can be a number from 0 (transparent) to 255 (opaque).

• Fog opacity

Controls the opacity of the black layer of 'Soft Fog' that is left in previously explored areas when Fog of War is enabled. This value can be a number from 0 (transparent) to 255 (opaque).

• Auto-expose fog on token movement (GM Only)

Will automatically expose Fog of War after moving a Token if ✓checked. This setting is intended to help test Fog of War and VBL when not hosting a game. When running a server, this setting is ignored in favor of the settings in the 'Start Server' dialog.

Performance

Performance Section

• Fill selection box

When ✓checked, the selection box which appears when dragging to select tokens in the Map View will contain a translucent blue fill. Less powerful devices running MapTool may see a small performance gain from unchecking this setting.

• Frame Rate Cap New in MapTool 1.5.7

Sets the maximum frame rate for the map renderer. Less powerful devices running MapTool may see a performance gain by lowering this setting.

Initiative Defaults

Initiative Section

• Hide NPCs from players on new maps

When ✓checked, automatically enables 'Hide NPCs' in the Initiative Panel on new maps. This setting doesn't show connected players NPC Tokens on the Initiative Panel.

• Give Owners Permission in new campaigns

This automatically enables the 'Owner Permissions' setting in the Initiative Panel on new maps when ✓checked. The setting mainly lets players with token ownership add their tokens to or remove their tokens from the initiative list and advance the initiative when it is their token's turn.

• Lock Player Movement in new campaigns

When ✓checked, new maps will have 'Lock Player Movement' automatically enabled in the Initiative Panel. This setting prevents players who do not own the token with initiative from moving any tokens.

• Show Initiative Gain Message

When initiative advances to a PC Token token and this is ✓checked, a simple 'Token Name has received initiative' message is displayed for all players in chat. This is ignored for NPC Tokens.

Client

Client Section

• Fit GM View

When ✓checked and the GM uses 'Center Players on Current View', the Map View will zoom out as necessary to accommodate the entire GM view. If unchecked, the zoom level will be set to match the GM's Map View, which will occlude part of the map if your Map View areas are different sizes.

• Default Username

Use to set the Default Username that appears in the MapTool title bar when a personal server is running. Defaults to Anonymous User. (Added MapTool v1.9.0.)

Macro Panels

Macro Panels Section

• Default: Allow Players to Edit Macros

In order for a macro to be considered a Trusted Macro, players must not be able to edit it. This setting determines if a new macro should default to allowing players to edit if ✓checked. Disabling this setting can be very useful if you intend to create a lot of macros that you intend to be trusted.

UPnP

UPnP Section

• Discovery Timeout

The timeout period in milliseconds MapTool will wait when searching for UPnP gateways before giving up.

Macro Permissions

Macro Permissions Section

• Enable External Macro Access

When ✓checked, Macros may call functions that access your drive and http services. Some examples (not a complete list) of functions which will be enabled are REST Functions, exportData, and getEnvironmentVariable.

Note about security: This option is off by default and exposes you to some risk when enabled. For instance, a malicious macro could communicate with an external server and store data on your local computer. Only enable this option if all the macros and libraries in your campaign files were written by you or directly from authors you trust.

Sounds Tab

File:prefs tab sounds.png

Sounds Tab on the Preferences Dialog

• Play system sounds

When ✓checked, MapTool will play a sound when new content is sent to the chat panel.

• Play streams

When ✓checked, streams started with playStream will be allowed to play.

• Only when window not focused

When ✓checked, the sound that MapTool plays when new content is sent to the chat panel will only play if MapTool is not the application that has focus.

• Turn on Syrinscape Integration

When clicking syrinscape-fantasy: links in MapTool, the Syrinscape Fantasy Player will be allowed to automatically open when this setting is ✓checked. This has no effect on Syrinscape Integration using the REST API and Online Player.

Startup Tab

Startup Tab of Preferences Dialog

JVM Settings

JVM Memory Section

These preferences are somewhat advanced. To better understand how MapTool uses memory settings, read about Stack Size. If you are having Stack Overflow errors and need to modify these settings for more reliable performance, read about Avoiding Stack Overflow. If you need help resetting MapTool memory settings, check out Resetting MapTool JVM Settings on the RPTools blog.

The packaging tool provided with Java 14+ has eliminated our ability to have MapTool configure its memory settings for you. For the time being, these options are greyed out and the user must edit the configuration file directly using a normal text editor. This text is taken from a Discord post by Phergus and replicated on our forum. This is not likely to change until Java 17 is released at the earliest, and possibly later if the Java developers don't correct it by then.

Startup Config for MT 1.8.x
Locate and edit the maptool.cfg file under the application folder in your MapTool install directory. In most cases, you shouldn't need to change ANY of them, excepting user.language for those in different locales.

Under [JavaOptions] you can add/set the following (example values are shown):

-Xmx4G - set max heap to 4G

-Xms1G - set min heap to 1G

-Xss10M - set stack size to 10M

-Dsun.java2d.d3d=false - disabled Direct3D

-Dsun.java2d.opengl=true - enable OpenGL

-Djavafx.macosx.embedded=false - initialize AWT before JFX (MacOS only)

-Duser.language=en - set MT local to English

-Dawt.useSystemAAFontSettings=on - turn on text antialiasing (for Linux)

Startup Config for MT 1.9.x and later
The format changed slightly for MT 1.9.x. Each line should now start with java-options= and then the options listed for MT 1.8.x.

These three settings are memory sizes in bytes. The letter at the end can be K, M, or G signifying Kilobytes, Megabytes, or Gigabytes. Changes to these settings take effect upon restarting MapTool.

• Maximum heap size (-Xmx)

The maximum amount of total memory (RAM) MapTool can use at once, usually entered in Gigabytes (G). For heavy frameworks with many assets, you may have to raise this value. 4G is a generous default value for nearly all users with at least 8GB of RAM.

• Initial & minimum heap size (-Xms)

The minimum amount of memory (RAM) which MapTool will always reserve for use, usually entered in Gigabytes (G). Oracle recommends this setting be the same as the Maximum heap size. Doing so may provide performance gains by reducing garbage collection operations. This value should not be higher than the Maximum heap size.

• Thread stack size (-Xss)

The memory each particular Java thread has reserved for its use, usually entered in Megabytes (M). Raising this value may allow more complex macros to be run, but it should generally be kept as low as possible. 4M is a generous default value that allows most macros to work just fine. To help understand this value, a simple campaign using short macros or no macros may be able to run successfully with a value as low as 256K, while a campaign containing extremely large macros may need 5M or 6M to avoid stack overflow.

Advanced Options

Advanced Options Section

These options are used for development and troubleshooting. Changes to these settings take effect upon restarting MapTool.

• Enable assertions

Developers often test MapTool with this option ✓checked to enable additional Java checks so they can find additional warnings or errors. This setting is not recommended for normal users as it lowers performance.

• Disable Direct3d Pipeline

When ✓checked, MapTool will not use Direct3D. This is mainly used by developers, but if you are having visual issues you can try using this setting to see if your problem is resolved. If so, it may indicate you need new drivers from your video card manufacturer. As of MapTool 1.11 Direct3D use will be disabled by default.

• Enable OpenGL Pipeline

This option may help resolve visual issues when ✓checked by enabling OpenGL rendering. You do not need to check 'Disable Direct3d Pipeline' in order to use this setting.

• Initialize AWT before JavaFX

Developers can use this.

Language Override

Language Override Section

• Language

Select the user interface language for MapTool. Changes to this setting take effect upon restarting MapTool.

Additional Options

Additional Options Section

• Data Directory

The local directory where MapTool saves asset cache data, autosaves, backups, configuration files, and more. Changes to this setting take effect upon restarting MapTool.