HowTo Guide for the MapTool Launcher

The MapTool Launcher (or just "MTL") is a standalone Java application whose purpose is to control the execution environment for the RPTools "MapTool" application. That application has a number of settings and options that make it cumbersome to manage manually. Hence this graphical application was written to make things easier for end users.

If you're interested in reviewing or modifying the source code for this application, see our project home page at SourceForge.net, specifically the project named Launcher under the SVN toolbar menu.

Visit our forums and ask any questions you may have regarding MTL in the Tools > MapTool forum. Be sure to state which version of the program you're using (it'll be in the titlebar of the MTL window as well as embedded in the name of the application itself). Also note the string that appears in the window title of any dialog that pops up on the screen. That string of text uniquely identifies the error message and makes it easier for us to track down the problem.

The rest of this guide will discuss the individual parts of the application with a focus towards describing common use cases.

Unpack the Launcher ZIP file

This step is done for you if you have downloaded and unpacked the MapTool ZIP archive since v1.3.b90. You may skip to the next section in this case.

Be sure to unpack the ZIP file with the Preserve Directories option enabled. MTL uses subdirectories to hold some configuration files and if you unpack the ZIP file without those directories MTL will not work correctly (if at all!).

When executed, MTL will determine what directory it is being executed from and will look for its configuration files there. A common place to put MTL would be in the same directory as your MapTool application (which is the default for MapTool starting with v1.3.b90), but this is not required.

MTL will create a configuration file called mt.cfg and will write to that file when changes are made to the configuration and MapTool is launched. Be aware of this if you put MTL somewhere with slow writes or a limited number of writes. Note that you must launch MapTool or the file won't be written!

There are also some subdirectories created. The first is doc, which you looked inside to find this document! Other files are here also: the open source license, for example. When you unpack a new version of MTL, be sure to check here to see if anything is new.

The next subdirectory is translations. You can probably guess what this is! If you have a new translation, please send us a copy of the file so that we can distribute it to others. We may create a repository of these on our wiki at some point. Follow the naming convention you see in the directory. Always start from the English translation, the i18n_en.properties file, because that one will always be the most accurate and most complete.

The last subdirectory is logging. You will likely never need the files in here. They cause MapTool to generate extensive logging as it executes. They are included because MTL can provide a checkbox for each one and then automatically copy the files to the right directory and install them for MapTool to use. Every time you launch MapTool, any changes in the logging configuration will cause the mt.cfg file to be rewritten.

Activate the Launcher

On most systems you can simply double-click on MTL's JAR file to activate it. Other systems might have other techniques for executing Java applications -- use whatever method your operating system dictates.

As a last resort you can always open a command line window, navigate to the directory containing MTL, and type the command below followed by the Enter or Return key:

    java -jar launcher-YYMMDDx.VV.jar

(Specify the correct date string and build number for your version of MTL, of course.)

This is also a great way to see error messages generated by the Java runtime and not by MTL itself. You may be asked to perform this step as part of the diagnostics process if you post MTL-related questions on our forum. For more details see Select Launcher logging detail.

Operation of the Launcher

This section covers the various tabs in MTL and reviews individual settings.

Basic tab

The first tab holds the basic configuration information: minimum and maximum amount of memory to provide to MapTool, maximum size of the stack area for each thread created by MapTool, whether to prompt when MTL is executed next time, and a button to choose which MapTool JAR file will be stored in the configuration file and started by this application.

  1. Memory sizes for MapTool

    The memory sizes are dictated by how you plan to use MapTool. If you expect to have large maps with a lot of imported graphics at very high resolutions, then you'll want a larger memory size so that MapTool has room to maintain all of that information. (Note that the memory requirements should be set for the largest desired map size; only the map currently in use consumes memory while MapTool is running. There is a small amount of memory used simply to keep track of overhead information for maps, but it's so small as to be negligible.)

    The stack size is special. It places a maximum upper limit on how much recursion can be performed by threads that MapTool may spawn to accomplish tasks. The most common situation where this is important is with macro programming using MTscript. (MTscript is a built-in, custom programming language that allows users to automate tasks.) In general you should choose the smallest possible stack size that will work for the set of macros you're using, since otherwise you're simply consuming memory that could be used for maps!

  2. Selecting the MapTool JAR file to launch

    In order for MTL to start MapTool it has to know where it is! This button will bring up a file chooser and you can navigate to where you unpacked the MapTool download. Once there, select the JAR file that corresponds to the application and accept the selection. You'll see the basename of the file show up where the button prompt used to be. This indicates the selection has been accepted. In addition, the command line at the bottom of the window will update and show an actual command line.

    Mac Users: The application bundle is configured to start MTL since MapTool v1.3.b90. The default mt.cfg will come preconfigured to know where the MapTool JAR file is located.

    Expert Hint: If you want to run multiple versions of MapTool, execute MTL from different directories each time and it will put its configuration file into that directory. This allows you to return to one particular directory and execute MTL there to start that MapTool. Clearly the simplest way to do this is to put MTL in each of the MapTool directories. (The default since v1.3.b90 is for MTL to be in the MapTool directory.)

    Expert Hint: On the Advanced tab is a checkbox for using relative pathnames for directories. If you select that checkbox, the configuration file will hold directory names relative to where MTL was executed. This would allow the MapTool application, the data directory used by MapTool, and even a Java runtime environment to all be stored on removable media! You'd be able to pack up your entire environment and move it from machine to machine with ease!

  3. The bottom of the Basic panel

    Here you'll find the button that launches the selected MapTool version, but there's also a checkbox that will keep MTL open. This is helpful if you want to run multiple instances of MapTool, possibly with different values each time.

    Each time you click the Launch button, you get a new instance of MapTool. This can be used to test your maps. Start MapTool the first time and start a server as the GM. Then start MapTool a second time and connect to the server as a Player. Now you will literally see (on the Player instance) exactly what the players will see. This is important because the GM is (essentially) an owner of all map resources and can always see certain things (even in Show as Player mode).

    At the very bottom of the panel is the command line as it will be executed. Hovering over the command line field will bring a tooltip that identifies what the current directory is and what the full command line contains. If the Relative pathnames for directories option is on, you'll see the relative paths for any directories chosen, except for the current directory (we have to start somewhere, right?).

    By default, MapTool creates a directory called .maptool under your home directory and places there all of its configuration files, image cache, autosave backups, repository caches, and so forth. This directory is referred to generically as MAPTOOL_DATADIR. There is no way to change this location through MTL; it can only be changed by editing the configuration file directly. The reason is simple: changing this location can have drastic effects on how MapTool executes. (In general you won't want to change this value.)

    Mac Users: The concept of multiple instances works great on OS X as well, even though this isn't the normal mode of operation on OS X.

    Expert Hint: The mt.cfg configuration file is rewritten each time the Launch MapTool button is activated. That means the last set of values entered into MTL will be stored and previous settings will be overwritten. Keep that in mind if you plan to use the Keep launcher open checkbox.

Language tab

This is where you choose the language for MapTool (and for MTL itself).

When you start MTL it will scan the translations directory. It will make a list of each filename (each one is a different translation) and it will look inside the file for a line that contains # LANGUAGE= and use the rest of that line as the language name. There are currently three languages, English (the original), German, and French.

Select the language you want MapTool to use. That setting will be stored in the mt.cfg file and used when MapTool is launched. However, it'll also be used the next time you start MTL. If you choose a language and decide that was a bad idea (!) you can select the None option, delete the mt.cfg file and start over, or just edit mt.cfg and delete the LOCALE field to reset it back to English (the default).

Expert Users and Translators: Have a look at the files if you like. You'll note that Java uses a Unicode value for letters outside the ASCII range. You can edit the file using any editor you wish, but please use UTF-8 encoding. When you submit the translation to us we will process the file with the native2ascii command so that the file appears as you see it in this directory with all the \u#### sequences. (Not all editors and operating systems do a good job with other languages so this format is used because it's portable.)

Advanced tab

This tab is broken into four parts: logging controls at the top, a text field where arbitrary text can be added to the command line, two checkboxes to control MTL, and a button to reset the directory chosen for an alternate version of Java.

  1. Select logging type

    When MTL starts it will scan the current directory (the directory containing MTL's JAR file) and look for a subdirectory named logging. It will read all XML files from that directory and present a list of options at the top of the Advanced tab. These are extended logging features available in MapTool. Selecting a checkbox will cause the contents of the corresponding XML file to be added to the logging.xml that is in MAPTOOL_DATADIR when MapTool is started.

    MapTool itself will load the logging.xml file and configure its logging facilities appropriately. The logging configuration options are not used by MTL at all.

    This technique of looking in a subdirectory for individual XML files will make it easier for the developers to add new ones in the future. Users can just drop the new file into the directory and the next time they run MTL they'll see a new checkbox on the Advanced tab! At some point we may even incorporate an option for automatically downloading new logging configurations from our web site.

    Expert Hint: Every time MTL is used to start MapTool, the logging.xml will be recreated if there have been any changes in the logging configuration. In addition, the individual XML files are copied to the MAPTOOL_DATADIR at the same time (in case you should choose to delete MTL, the XML files will still be available for MapTool). The XML files are only copied if they are newer than the ones already there, or are newer than the configuration file itself. You can examine the XML files to see how to change the description (and tooltip) that appears in the Advanced tab, if you wish. Note that these two strings cannot currently be translated.

  2. Additional Java arguments

    It's unlikely you'll need to use this field. It allows you to specify additional command line options to add when executing MapTool.

    However, there have been occasions where it has been useful. The first deals with internationalization: you may want to run MapTool using a particular language configuration even if your operating system is not set to that language. For example, the following lines configure MapTool to use its German translation and its Turkish translation, respectively:

        -Duser.language=de -Duser.country=DE
        -Duser.language=tr -Duser.country=TR

    There are nine supported translations in MapTool (as of July 25th, 2013). They are English, Spanish, Italian, French, German, Polish, Japanese, Russian, and Chinese. (Hm, I thought we had a Turkish translation. I remember posts on our forum about how some parts of MapTool didn't work in Turkish because uppercase to lowercase can't be done automatically and I had to modify the code to compensate. I guess the translation file was never submitted though, and so isn't included in MapTool. That's a shame.)

    You only need to use the above options if MTL doesn't have that language as a choice (because MTL's language options are propagated to MapTool automatically). At some point we may add support for MTL to query the MapTool application and find out what languages it has.

    The other common use for this field is when Windows video drivers don't work. (Yes, I know this is a topic for jokes, but believe me -- we run into this a lot!) In this case, you might try turning off certain features of the video support in Java in an attempt to work around bugs in the driver. Here's how to turn off all DirectDraw support (necessary if the driver has bugs in its implementation):

        -Dsun.java2d.noddraw=true

    If you only want to turn off Direct3D, use this instead:

        -Dsun.java2d.d3d=false

    If one of those works, you need to get updated video drivers. And not from Microsoft or your OEM manufacturer, but from the video card vendor themselves -- Microsoft and the OEMs typically have woefully out of date drivers.

  3. Relative pathnames for directories

    In order to support self-contained distributions of MapTool (such as placing Java, MapTool, and all of MapTool's data onto a flash drive) this option was added. It causes the directory that contains the MapTool JAR file to be considered the "base directory" and both the MapTool data directory (MAPTOOL_DATADIR) and the path to the alternate Java version (JAVA_DIRECTORY) will be written to the configuration file as relative paths.

    There is another directory that will be written as a relative name: the directory where the MapTool JAR file is stored (called MAPTOOL_DIRECTORY in the configuration file). You might wonder how it can be written to the configuration file if that's the directory used as a base for the others... For that single option, the base is the location of MTL itself! So the location of the launcher is used to locate the MapTool JAR, then that becomes the base for everything else. The goal is to allow multiple launchers to be placed in multiple different directories, each with their own configuration file. Which launcher you use determines how MapTool is executed, but no changes to the MapTool directory are required at all.

    Recent experience has shown that it may be useful for this option to be split into two pieces, one to indicate whether data directories should be relative and one to indicate whether command directories should be relative.

  4. Launch with console

    This opens up a typical command line window and executes MapTool from inside that window. In an ideal world every possible error message that MapTool might generate would be caught and stored into the log.txt file that is in the MAPTOOL_DATADIR directory. But there are some errors generated by Java and not by MapTool that cannot be caught. In order to see those error messages, the console is needed.

    This option will default to off and will likely always stay that way. But if you have a problem that is hard to diagnose you may find the community on the forum asking you to turn this option on and then reporting any messages that appear in the command line window.

  5. Set Java Version (select directory)
  6. Reset to default Java version

    The text on this button will change depending on its state.

    Initially it will display the first message. Activating it will bring up a file chooser and allow you to select the directory that contains your operating system's java command. This is useful if you want to try a different version of Java for running MapTool.

    If you have selected such a directory, the button text will indicate that activating it again will reset the directory (ie. clear it out) so that the alternate version will not be used. You'll be back to your system's default version of Java.

    Expert Hint: There have been updates made to Java that stop MapTool from working or that produce warnings or errors. If that should happen in the future, you can use this button to specify a particular (older) version and avoid the messages.

Troubleshoot tab

This tab has options that we hope you'll never need to use. ;)

  1. Select Launcher logging detail

    This setting is not saved in the mt.cfg configuration file.

    If the launcher starts but doesn't seem to be functioning properly, the community on the forum may ask you to change the detail to INFO. This will cause MTL to generate a lot of detail log messages. However, they will only appear on the console. In order to execute the launcher in a console window, follow these general steps:

    1. Open the application that produces a console window

      On Windows this is CMD, on OS X it is Terminal, and on Linux it depends on the desktop environment but gnome-terminal and konsole are good possibilities.

    2. Navigate to the directory containing MTL

      You can use the CD change directory command and follow it with the directory containing MTL. However, most GUI environments will let you drag/drop a folder to the console window and will insert that folder name onto the command line. Therefore, you can try typing CD follow by a space, then dragging the folder name into the console window. If a directory name appears you're done -- just hit Enter or Return. (OS X and Linux have case-sensitive command lines, so be sure to use lowercase cd!)

      If a directory name doesn't appear, you'll need to navigate there yourself by typing the path name to the directory.

    3. Execute MTL using the java command

      Once you're in the proper directory you can execute MTL with a single command:

      java -jar launcher-YYMMDD.VV.jar

      Type that command and press Enter or Return to execute it. Replace the YYMMDD.VV with the version information for your MTL. In many console windows you can type the first few letters (such as lau) and hit the Tab key to invoke the filename autocompletion feature. If that doesn't work though, you'll need to type it out yourself. :)

    4. Check the console window for messages

      You should go to the Troubleshoot tab and select INFO to turn on all possible messages, then keep an eye on the console window for errors.

  2. Enable assertions

    In most cases (99 out of 100) you will never need to enable this checkbox. The developers will often test MapTool with that option enabled because it makes Java much more picky about borderline cases that could cause warnings or errors. Because of all the extra checks, it also slows down the application.

Other Operations

You may copy the mt.cfg file to other directories if you wish, but be aware of the Relative pathnames for directories option.

MTL is now part of the MapTool ZIP archive starting with MapTool v1.3.b90. You can update MTL without updating MapTool, if you wish. For example, you might have an older version of MapTool and be interested in using MTL. Just download and unpack the latest MTL as described above under Unpack the Launcher ZIP file. If you unpack it into MapTool's main directory you'll have a self-contained setup and you can move or copy MapTool to other locations, taking MTL with it. (Just be sure to keep the previous comment in mind about copying mt.cfg.)

Publication Information

This document was prepared for MapToolLauncher 130829.01.

For questions or comments, please visit our forums and post in the Tools > MapTool forum.