MapTool 1.8.3 Released

Dear MapTool users,

This is a long post but worth the read. It contains some vital information regarding a new version of MapTool you’ll want to read. It also has the usual list of enhancements and bug fixes available in this release.

Recently, two severe exploits from a third-party library have been brought to our attention. MapTool versions 1.7 and earlier are vulnerable to this exploit which can be used to access your files and run programs on a computer running a server even if you have a password set. The latest version of MapTool 1.8 has fixed these exploitsWE ADVISE EVERYONE TO UPGRADE AS SOON AS POSSIBLE. 


Below we address what we expect to be the main three topics regarding an upgrade to the latest:

If you really don’t want to change
If you insist on using an older version, you can do things to help protect your MapTool server:

  • You can use the Direct Connect option; this is still risky since hackers scan for vulnerable IP addresses all the time. You can mitigate the risk by creating a whitelist through the router that allows only certain IP addresses to connect. Not all routers will support this option.
  • You can disconnect from the internet or block all incoming internet traffic and use your personal LAN (connect via the LAN tab).
  • You can create a VPN for your server and the other clients (also connecting via the LAN tab).

Despite these precautions, anyone allowed to connect to your server will still have access to abuse these exploits in the older versions of MapTool!

If you’re running into issues
We expect some macros may run into trouble when used in the new version. If you run into issues due to this upgrade:

  • paste a link to a downloadable version of the framework (either to a Discord post or a forum post), and
  • give clear instructions on what is needed to recreate the issue and with which MT version it does work.

We’ve opened up a channel in Discord ( just for this purpose: mt-1-8-3-framework-issues

Why now, why this
We are aware that this will force you and your players to upgrade (if you’re using the registry) which will bring its own hassle and we are sincerely sorry for that, but we don’t see any other way. You might wonder why now and why so rigorous: all complex software contains exploitable parts, if the software is properly written and managed then the risk of someone finding and abusing this, is very small (to give you an idea: this potential exploit remained 10 years undiscovered). HOWEVER, as soon as the exploit is found and fixed in open source software (which is the case for MapTool), anyone can check what has been changed in the code and immediately identify the exploit and use it!! So it automatically becomes a huge risk. Hence, it becomes our responsibility to mitigate this risk as much as possible, leading to this course of action.

Maptool 1.8 Changes

Now for the better news.

MapTool now uses Java 14 from AdoptOpenJDK.

Lots of enhancements, bug fixes, and performance improvements to the code base.

Many thanks to community developers merudo, selquest, nmeier, euank, ebudai, grimreaper, Phi1010, Irarara, irisiflimsi, dluga93, MeloDub, dat-adi, sum_catnip for their work on this release. Also, big thanks to the translators building up the language support and the wiki editors for improving/growing the documentation.


  • Critical Security Fixes – see Discord or Website for more details.
  • Significant improvements in macro run times giving a 4x to 10x (and sometimes more) reduction in run times.
  • Chat output formatting refactored to produce a more consistent output and make future changes easier/cleaner.
  • Macro errors now produce a call stack showing the macro calls leading to the error.Function "setTokenDrawOrder" requires at least 1 parameters; 0 were provided. Error trace : m3@Campaign <<< m2@Campaign <<< m1@campaign
  • ISO-8859-1 character support. Can now use accented characters in Token Properties and macros.
  • Several Export Screenshot bugs fixed.
  • Annoying bug in Resource Library where scroll bar coulnd’t go down far enough fixed.
  • A number of Initiative improvements/enhancement: #987#1458#1479#1845#2097


  • #2345 /ooc chat command now displays Player name instead of current impersonation.
  • #2314 Output formatting refactored to use CSS classes and moved to a new MessageUtil class.
  • #2283 Basic support for SVG images added.
  • #2271 Improved readability for output of chat commands /emote & /say to bring them inline with normal macro output.
  • #2256 Support for data: URIs in HTML5 windows (overlay, dialog5, html5).
  • #2237 MapTool Builds now include package for ArchLinux.
  • #2230 getInfo("client") function now includes details about Dialogs, Frames and Overlays.
  • #2229 New delim parameter for herolab.XPath() function allows for returning a string list or JSON Array to address issues with content having commas in it.
  • #2205 Improved efficiency of onTokenMove event handler with multiple tokens selected.
  • #2199 Updated Dicelib 1.7.0 adds support for Shadowrun 5 dice rolls: sr5(n)sr5(n,g)sr5e(n)sr5(n,g)
  • #2188 New macro function removeDrawing(MapName, DrawingID) to remove drawings from map.
  • #2157 Macro function resetTablePicks() can now be used to reset specific entries in table. I.e. return drawn cards to a deck.
  • #2149 Improved performance of Fog of War checks for a noticeable improvement on complex maps.
  • #2097 Initiative can now be set to ascending or descending order with descending as default.
  • #2032 Added various Preferences settings to output of getInfo("client"). Added personal server status to getInfo("server").
  • #1986 Stat sheets and token notes now appear above Overlays.
  • #1958 Moving a token into a unreachable location adds a fail key/value pair to the last object in the array of location objects returned by getLastPath() or to onTokenMove.
  • #1898 A number of improvements to macro performance resulting in as much as 10x or more reduction in run time.
  • #1890 Map name parameter added to removeToken() function. copyToken() function cleaned up internally.
  • #1882 NullPointerException messages now include more information about why the error occured.
  • #1861 Macro errors now produce a call stack showing the macro calls leading to the error.
  • #1845 Initiative Panel restyled to make it more obvious when a token isn’t visible to players.
  • #1726 Lumens value added to Personal Lights in Sight definitions. This allows Sight definitions that will see into areas of darkness.
  • #1482 Can now export Macro Groups instead of an entire macro panel with right-click Export Macro Group option.
  • #1479 New macro function prevInitiative() allows stepping back one initiative advance.
  • #1458 New Initiative panel menu option to disable Next/Previous functions.
  • #1362 New macro function to run JavaScript functions defined in frames, dialogs and overlays: runJsFunction(name, type, func, thisArg, argsArray)
  • #987 New events for initiative: onInitiativeChangeonInitiativeChangeRequest. New system variable init.denyChange.

Bug Fixes

  • #2343 Trusted Prefix preference colors weren’t being correctly saved nor used in chat output. Fixed.
  • #2335 Using cp: protocol with invalid resource could freeze client. Fixed.
  • #2321 With Individual Views option OFF, players could not see owned NPC tokens. Fixed.
  • #2313 Switching to Player View with an Object flagged as VoFoW could cause an NPE. Fixed by fix for #2242
  • #2311 movedOverToken() throwing exception in beta. Fixed.
  • #2287 Export screenshot broken in beta. Fixed.
  • #2270 Control for restricting impersonation of tokens by players was working opposite of indicated state. Fixed.
  • #2223 onCampaignLoad macros were no longer suppressing output when executed on load. Fixed.
  • #2221 Beta builds had OpenJDK icon instead of MT icon in menus for linux. Fixed.
  • #2220 MapTool beta 2 was creating a folder in user home for logs instead of using .maptool-rptools\logs. Fixed.
  • #2215 Some previously working URIs were failing for playStream/Clip in beta. Fixed.
  • #2242 NullPointerException: Cannot invoke “java.awt.geom.Area.intersects(java.awt.geom.Rectangle2D)” because “fog” is null. Fixed.
  • #2211 Function isNumber() returning incorrect response on anything not a positive integer. Fixed.
  • #2192 Using function movedOverDrawing() with a template would throw an NPE. Fixed.
  • #2184 Initiative panel Lock Movement toggle was also changing Owner Permissions. Fixed.
  • #2178 Token opacity was broken in develop. Fixed.
  • #2177 Output of macroLinks was not being formatted properly. Fixed.
  • #2174 Ability to save startup settings broken by Java/packaging changes. Restored. Startup tab now has more explanation.
  • #2152 Function isNumber() was returning true for empty strings. Fixed.
  • #2151 Function isNumber() was returning true for empty strings. Fixed.
  • #2119 Excessive processing of roll options was making macro execution slow. Changes improved speed by 10x or more.
  • #2118 Importing large macrosets was very slow and used a lot of memory. Changes improved speed by 10:1 up to 150:1 for macro buttons with images.
  • #2116 Failing to load a campaign incorrectly reported “Could not save campaign.” Fixed.
  • #2092 Spurious on change selection events were occuring and caused infinite loops under 1.7.0. Fixed.
  • #2081 Universal VTT map import wasn’t applying portal closed flag to enable/disable VBL on portals. Fixed.
  • #2078 Event onChangeToken was being generated multiple times even when token wasn’t changed. Was repeating indefinitely on impersonated tokens. Fixed.
  • #2074 Updating overlay wasn’t removing event handlers, e.g.onChangeSelection. Fixed.
  • #2069 Tokens partially out of line-of-sight were fully shown on player clients. Fixed.
  • #2057 Token properties with a single element JSON array returned bad results when accessed. Not in published code. Fixed.
  • #2056 Form submit for dialogs, frames and overlays was on wrong thread leading to inconsistent results from macro functions such as getToken(). Fixed.
  • #2046 Cancelling out of Rename Macro Group would cause an NPE. Fixed.
  • #2041 A number of macro functions if called with the wrong case such as getplayername() instead of getPlayerName(), would either call the wrong function internally or return the wrong result. A parser exception will now be thrown instead. See issue for more details.
  • #2040 Vision of player-owned NPC tokens were not visible when no PC tokens were on map. Fixed.
  • #2037 Clicking on Move Up/Down buttons with only a Single bar defined was throwing an exception. Fixed.
  • #2023 Moving a token on a map with FoW and triggering an onTokenMove event that moved the token to a different map would cause an NPE. Fixed.
  • #2021 Double-clicking on token in Initiative List wasn’t updating Selected panel. Fixed.
  • #2006 Some themes still had some UI elements using fonts lacking CJK support. Fixed.
  • #1996 Error message for missing remote repository was missing closing quote. Fixed.
  • #1995 Function capitalize() would always treat numbers and symbols as word boundaries. New parameter allows for turning off.
  • #1988 Audio funciton playClip() was hogging the JavaFX application thread. Fixed.
  • #1976 Calling overlay() with new content was not erasing previous content. Fixed.
  • #1974 Disabling deterministic expression building was causing NPEs. Not in released builds. Fixed.
  • #1972 Using listGet() on lists where elements had spaces in the name would fail. Fixed.
  • #1962 Selecting colors in Drawing tool color palette could fail if mouse is moved between click and release. Fixed.
  • #1950 Calling getname() instead of getName() was calling `setName() instead. Fixed.
  • #1948 Multiple fixes to Exporting Screenshots.
    • Uninitialized variables if attempting to do an Entire Map export would cause NPE. Fixed.
    • Exposed FoW areas not included in exported image. Fixed.
    • Entire Map exports were not getting correct extents. Fixed.
  • #1938 Macros created via createaMacro() or already present on a droped in token were getting set to Player Editable as they should be. Fixed.
  • #1935 Players calling macros via a frame macrolink would not have permission to use trusted functions. Fixed.
  • #1926 Updates to Hot Key display checkbox and macro Commonality were only applied on first edit. Fixed.
  • #1921 Rapidly changing Token facing in vision range of of multiple lights would degrade performance. Fixed.
  • #1896 Light sources with a lumens value of 100 weren’t revealing for tokens with personal light. Fixed.
  • #1894 Trusted functions called from a frame opened from a GM panel macro lacked permission to run. Fixed.
  • #1893 Several bugs related to personal lights fixed.
    • Areas exposed by personal lights would be “overridden” by dim light sources.
    • Superfluous calls to flush(token) and exposeFoW() were removed.
    • Light caches no longer accumulate duplicates.
  • #1889 Macro function copyToken() wasn’t preserving Shape setting of token. Fixed.
  • #1888 Clicking on or hovering over a macro link in a campaign with no maps was producing an NPE. Fixed.
  • #1886 Error message dialog not being display correctly. Fixed. Not in released code.
  • #1884 Overlay transparency broken with Java 14. Fixed. Not in released code.
  • #1880 Attempting to create an overlay when there are no maps caused an NPE. Fixed.
  • #1878 HTML5 button formAction was ignored. Fixed.
  • #1876 Spurious quote symbols no longer created in chat by [if(), code:{}] blocks lacking the else block.
  • #1874 Macro function getMacroProps() was returning a misnamed property (toolapplyToSelected). Fixed.
  • #1867 Macro links to macros with no output would produce an empty line in chat. Fixed.
  • #1863 HTML5 form submit was not allowed at document load. Fixed.
  • #1737 Some CMYK JPEGs would appear as all black. Fixed.
  • #1736 Variable names can now start with trutruefalfals, and false.
  • #1733 Embedded double quotes in JSON objects not handled correctly. Fixed.
  • #1705 Map functions getCurrentMapName(), getMapVisible() and setMapVisible() would throw NPEs if campaign had no maps. Fixed.
  • [#1562][i1562] Accessing certain data from HeroLab files in the Edit Token dialog could thrown an exception. Fixed.
  • #1560 Default property settings using assigment expressions, i.e.{prop2 = prop1}, would fail. Fixed.
  • #1359 Map coordinates were appearing over token notes. Fixed.
  • #755 Scroll bar in Resource Library window wouldn’t always go far enough to see all content. Fixed.
  • #715 Bad or missing remote repository would produce a Null Pointer Exception in the log but not inform the user. Fixed.


  • #2280 Update to for clarity of current processes. Fixed.
  • #2279 CampaignDialog unit test failing under DE locale. Fixed.
  • #2244 Too much network debug output when using gradlew run. Fixed.
  • #2197 Build changes caused release builds to barf if release tags contained alpha chars(i.e. beta). Fixed.
  • #2135 Code cleanup: removed redundant null checks, tests that were always true/false, replaced anonymous inner classes with lambdas, etc.
  • #2109 Build.gradle update to pull version from tag. Fixed. Dev only.
  • #2102 jpackage created Windows installers weren’t installing/updating with existing installs. Fixed. Dev only.
  • #2049 Removed a number of classes that were obsolete/unused.
  • #2047 Code cleanup. Removed obsolete Java version checks.
  • #2019 Updated to Parse 1.8.0 which added support for logical operators to Expression.format()/InlineTreeFormatter..
  • #1992 Code cleanup of I18NManager.
  • #1947 MapTool credits updated with recent (and long time) contributors.
  • #1943 Updated to Parse 1.7.1 which adds ISO-8859-1 character support. Can now use accented characters in Token Properties and macros.
  • #1907 Dicelib updated to 1.6.2 for fixes to getRolled() and getNewRolls().

You can download available versions of MapTool from GitHub.

All users running versions prior to 1.8.3 are strongly encouraged to update. See this announcement post on our forum.

A JAR file version may be downloaded as well but is only recommended for developers or other advanced users.

Mac Users are encouraged to use the PKG version of the install. Windows users are encouraged to use the MSI.

If you need interactive help, please join our Discord Server. Or visit our wiki for complete walk-throughs of how to use the tool. Our Community page has more links; see the toolbar at the top of the page.

This Post Has 3 Comments

  1. RPTools Bard

    Yes, I know the version number of 1.8.3 might surprise a few people who didn’t see 1.8.0, 1.8.1, and 1.8.2. This is just a technical glitch on the part of GitHub and auto-incrementing version numbers. “There’s nothing to see here. Move along.”

  2. Darin

    1.8.4 is broken.
    unable to register your server. JsonReader.setLenient(true) to accept malformed JSON at line 2 column 2 path $

Leave a Reply

This site uses Akismet to reduce spam. Learn how your comment data is processed.