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.
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.
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.
This section covers the various tabs in MTL and reviews individual settings.
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.
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!
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!
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.
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.)
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.
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.
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.
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.
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.
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.
This tab has options that we hope you'll never need to use. ;)
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:
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.
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.
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. :)
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.
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.
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.)
This document was prepared for MapToolLauncher 130829.01.
For questions or comments, please visit our forums and post in the Tools > MapTool forum.