Startup Properties

Startup Properties

During the startup sequence of MapTool several properties can be defined on different places. This guide tries to make it a little bit more clear, which can be set where and how.

Definitions of Startup Properties

Startup Properties are properties, you can set only during the startup phase of the application. If you change same, you have to restart the application. There are several reasons for this behavior:

JVM property: They are for the java virtual machine in where the application is running. Best examples are the memory properties to define the memory usage of the JVM.
Only on startup relevant: E.g. which campaign is loaded during startup is only relevant during startup
Complicate to change later: E.g. changing the location of files (e.g. MAPTOOL_DATADIR) during a session is complicated and normally not necessary.

Locations To Set Values

First of all, try to use the startup tab on the option window in the maptool UI. The application will try to save your changes in the correct location.
But not all settings are changeable over the UI and if the UI tells you, to do the change by yourself, it is god to know some backgrounds.

You can set the value of a property on several locations. Since there are no guaranties, that the value of a property is set on only one location or that it has the same value on all locations, there is a clear hierarchy for the priority of a location.

The locations and there priority from high (overwrite) to low (will be overwritten) by higher locations first:

MapTool Command Line Option
- When you start the MapTool application, you can start it with optional parameters
- With -h you can get a list of the current command line options of MapTool
- E.g. maptool.exe -D=“data dictionary” to tell MapTool where the data dictionary is (should be)
Startup Property File
- The standard location & name of this file is startup.properties in the configure subdirectory of the data dictionary of MapTool. E.g. {user.home}/.maptool/config/startup.properties
- There is an startupExample.properties file with instructions and a list of the currently supported properties at the default location
- A property is a key value text pair with a '=' or ':' between them
- E.g. MAPTOOL_DATADIR=“data dictionary”
- More details about the format of a properties file are on this WIki page
JVM Command Line Parameters (-D, -X, …)
- MapTool uses launchers generated with jpackage, which does not allow users to use JVM command line parameters
- Use the section [JavaOptions] in MapTool.cfg to change JVM parameters.
MapTool.cfg (-D, -X, …)
- The configuration file of MapTool is in the app subdirectory of the application home directory, e.g. {application home]/app/MapTool.cfg
- This file is overwritten during an update and holds user specific parameters and inherent application specific parameters together
- Use the startup property file for user specific parameters
- This location should only be used if the application has problems to change general setups of the application.
- It has 3 sections:
  - [Application]
    Only developers will change here sometimes something
  - [JavaOptions]
    With the startup properties, you should no longer have to change things here, unless you have runtime troubles with MapTool.
  - [ArgOptions]
    In this section you can set command line options with a lower priority as the direct command line but with a higher priority then the startup properties.
    This is used by MapTool to set the correct version.
    With the startup properties, a user should no longer change things here.
Default System Properties
- Most default system properties are dependent values from the operating system (OS) and are set by the JVM
- e.g. user.home get his value (path&name) of the OS specific home directory of the current user in the OS who starts the application
- The non standard system properties will get there default value from the application
Default Values
- This values are defined inside the MapTool application to define a fallback value, if needed.

Property Overview

This table should give you an overview about all properties during the startup process.

KEY	Default Value	System	Startup	Command Line		Set By	Description
				short	long
os.name	os dependent						Name of the operating system
user.home	os dependent						Home directory of the os user
MAPTOOL_DATADIR	.maptool	+	(+)	D	datadir	user	Main directory for runtime data (under user home) Will be ignored in Startup, if MAPTOOL_STARTUP_FILE is relative to the data directory.
MAPTOOL_LOGDIR	logs	+	+			user	Directory for logging data (under datadir)
CONFIG_SUBDIR_NAME	config						Subdirectory under datadir for configuration data
TEMP_SUBDIR_NAME	tmp						Subdirectory under datadir for temporary data
CMD_OPTIONS_HELP				h	help	user	Command options incl. description to log and information frame
DEBUG_FLAG	false (not set)	-		d	debug	adv.	Set log level to debug and turn on system.out enhanced debug output
VERSION_OVERWRITE	current version	-		v	version	dev.	Overwrites the MapTool version. ONLY FOR DEVELOPMENT. Some MapTool functions will break if the version is not set correct! This can corrupt your data!
FULLSCREEN_FLAG	false (not set)	-	+	f	fullscreen	user	Maximize the MapTool window on startup
MONITOR_TO USE	-1 (not overwrite)	-		g	monitor	adv.	Sets which monitor (graphical device) to use.
WINDOW_WIDTH	-1 (not overwrite)	-		w	width	adv.	Override MapTool window width. Only usable together with monitor and height
WINDOW_HEIGHT	-1 (not overwrite)	-		h	height	adv.	Override MapTool window height. Only usable together with monitor and width
WINDOW_XPOS	-1 (not overwrite)	-		x	xpos	adv.	Override MapTool window starting x coordinate. Only usable together with monitor and ypos
WINDOW_YPOS	-1 (not overwrite)	-		y	ypos	adv.	Override MapTool window starting y coordinate. Only usable together with monitor and xpos
LIST_MACRO_FLAG	false (not set)			m	macros	adv.	Writes a list of the defined macro functions into the log
RESET_FLAG	false (not set)			r	reset	adv.	Reset startup options to defaults
DEPRECATED_LOAD_CAMPAIGN_NAME		-		F	file		Load campaign from file on startup. Deprecated: Please use LOAD_CAMPAIGN_NAME (C or campaign)
LOAD_CAMPAIGN_NAME		-	+	C	campaign	user	Load campaign on startup. Arg.: Full file path and name of the campaign
LOAD_SERVER_FLAG	false (not set)	-	+	S	server	user	Start server on startup. Using server parameters from user preferences (last server start dialog)
LOAD_SERVER_DELAY	0	-	+	s	server-delay	user	Delay the start of the server for x seconds, e.g. network needs more time to be ready
LOAD_AUTOSAVE_FILE	ask	-	+	A	autosave	user	If there is a newer autosave file then the campaign to load, should the app load it (yes), not load it (no) or ask (ask) for the decision (default is ask)
MAPTOOL_STARTUP_FILE	startup.properties under config dir.	-		P	props-file	user	Override name (& path) of the startup properties file
SKIP_AUTO_UPDATE_FLAG	false (not set)		+			user	Skips the auto update process. There is also a user preference to do this.
user.language	default from OS	+	+			user	Sets the (default) language for the MapTool UI. Fallback will be en (English).
user.region	default from OS	+	+			user	Sets the (default) region (country) for the MapTool UI. E.g. how date or numbers are shown.
MAX_MEM		+				adv.
MIN_MEM		+				adv.
STACK_SIZE		+				adv.
ASSERTION		+				adv.
JAVA2D_D3D		+				adv.
JAVA2D_OPENGL_OPTION		+				adv.
MACOSX_EMBEDDED_OPTION		+				adv.

Legend / Notes

Legend	Description
KEY	identification of the value
Default Value	The value, which is used if the value of the key is not set explicitly
System	Can be set in the MapTool.cfg or by the JVM command line parameters, if there is a + in the key row Can be set in the MapTool.cfg using the command line option key with a '-' as prefix in the[ArgOptions] section, if there is a - in the key row.
Startup	Can be set in the startup properties file, if there is a + in the key row. (+) has side conditions, see description in the row of the key
Command Line Short	A single letter to use with a '-' as prefix in the command line of the application call to select the key
Command Line Long	A single word to use with a '-' as prefix in the command line of the application call to select the key
Set By	Normally set by a normal user (user) or an advanced user (adv.) or a developer (dev.)
Description	Description to the key meaning and usage

Note for	Note
Keys ending with FLAG	This keys have a boolean value, true or false. There default value is false and if they are set somewhere, they will be true, no matter what value was used to set the key. (E.g. If you set SKIP_AUTO_UPDATE_FLAG=“false” the value will be true!!! It can never be set back to false) Command line has no argument. (E.g. -f or -fullscreen and not -f=“true”)

user.language

ISO 639 alpha-2 (-1) or alpha-3 (-2) language code, or registered language subtags up to 8 alpha letters (for future enhancements). When a language has both an alpha-2 code and an alpha-3 code, the alpha-2 code must be used.ISO 639 alpha-2 or alpha-3 language code, or registered language subtags up to 8 alpha letters (for future enhancements). When a language has both an alpha-2 code and an alpha-3 code, the alpha-2 code must be used.

MapTool has currently translations for the following languages:

Code	Language (en)
en	English (Default - Fallback)
ach	Acoli
cs	Czech
da	Danish
de	German
es	Spanish; Castilian
fr	French
it	Italian
ja	Japanese
nl	Dutch; Flemish
pl	Polish
pt	Portuguese
ru	Russian
sv	Swedish
uk	Ukrainian
zh	Chinese

If the translation is not there (completely or just for a specific text), the fallback language is English.

How to Support Translations

Quote from MapTools Discord:
MapTool UI translations are crowd sourced on Crowdin. If the language you'd like to help with is not listed, ask in Discord MapTool#internationalisation-and-localisation and the dev team will set it up.
If it is, create an account and join the effort. Requests to join the translation team will be reviewed at the project manager(s) earliest opportunity.

user.region

ISO 3166 alpha-2 country code or UN M.49 numeric-3 area code.

Recommendation

First try to change the values over the startup tab on the option window. On some OS the MapTool.cfg file is not writeable, so you can not change everything what you can see.
Specially the command line options have to be set directly by yourself.

If you need your own dictionary location(s), best practice would be to set the -P command line option to tell MapTool, what the path & name of the startup property file is and define anything else in that file.
(The data dictionary directory can only be set in the startup properties file, if the startup properties file will be located independent from the data dictionary!)

If your MapTool application seems to be instable and your OS does not allow the setting of new values over the startup tab on the option window, then go and try to manipulate the MapTool.cfg file.

Try to avoid changes in the MapTool.cfg file, because the file will be overwritten by the next update.

State

Under Construction

For MapTool Version 1.13.x (under development)

Table of Contents