maptools (CLI)

Warzone 2100 Map Tools

• maptools package
• maptools map
• Output Level Info Formats
• Output Map Formats

A CLI for converting Warzone 2100 maps between different map formats, extracting information, and generating preview images.

maptools has subcommands to deal with both map packages (ex. .wz files) and directly with map folders.

Usage: maptools [OPTIONS] [SUBCOMMAND]

[OPTION]	Description
-h,--help	Print help message and exit
-v,--verbose	Verbose output

[SUBCOMMAND]	Description
package	Manipulating a map package (ex. <map>.wz file)
map	Manipulating a map folder

maptools package

NOTE: To operate directly on map packages / archives (i.e. .wz files), maptools must be compiled with libzip support.

Usage: maptools package [OPTIONS] [SUBCOMMAND]

[SUBCOMMAND]	Description
convert	Convert a map from one format to another
genpreview	Generate a map preview PNG
info	Extract info / stats from a map package

maptools package convert

Convert a map from one format to another

Usage: maptools package convert [OPTIONS] input output

input must exist, and must be a map package (.wz package, or extracted package folder)

output should not exist

[OPTION]	Description	Values	Required
-h,--help	Print help message and exit
-l,--levelformat	Output level info format	ENUM:value in {lev, json, latest}	DEFAULTS to latest
-f,--format	Output map format	ENUM:value in { bjo, json, jsonv2, latest}	REQUIRED
-i,--input	Input map package (.wz package, or extracted package folder)	TEXT:PATH	REQUIRED (may also be specified as positional parameter)
-o,--output	Output path	TEXT:PATH	REQUIRED (may also be specified as positional parameter)
--preserve-mods	Copy other files from the original map package (i.e. the extra files / modifications in a map-mod)
--output-uncompressed	Output uncompressed to a folder (not in a .wz file)
--set-name	Set / override the map name when converting

Note: When converting a script-generated map:

• If the output format is jsonv2 (or later) the map script will be preserved
• If the output format is bjo or json, a warning will be output and the script-generated map will be converted to a static map

maptools package genpreview

Generate a map preview PNG

Usage: maptools package genpreview [OPTIONS] input output

input must exist, and must be a map package (.wz package, or extracted package folder)

output should not exist, and should end with .png

[OPTION]	Description	Values	Required
-h,--help	Print help message and exit
-i,--input	Input map package (.wz package, or extracted package folder)	TEXT:PATH	REQUIRED (may also be specified as positional parameter)
-o,--output	Output PNG filename (+ path)	TEXT:PATH	REQUIRED (may also be specified as positional parameter)
-c,--playercolors	Player colors	ENUM:value in {simple, wz}	DEFAULTS to simple
--scavcolor	Specify the scavengers hex color	RGB hex color code	DEFAULTS to #800000 (maroon)

maptools package info

Extract info / stats from a map package to JSON

Usage: maptools package info [OPTIONS] input

input must exist, and must be a map package (.wz package, or extracted package folder)

[OPTION]	Description	Values	Required
-h,--help	Print help message and exit
-i,--input	Input map package (.wz package, or extracted package folder)	TEXT:PATH	REQUIRED (may also be specified as positional parameter)
-o,--output	Output filename (+ path)	TEXT:PATH

If --output is not specified, the JSON result is output to stdout

maptools map

Usage: maptools map [OPTIONS] [SUBCOMMAND]

[SUBCOMMAND]	Description
convert	Convert a map from one format to another
genpreview	Generate a map preview PNG

maptools map convert

Usage: maptools map convert [OPTIONS] inputmapdir outputmapdir

Both inputmapdir and outputmapdir must exist.

[OPTION]	Description	Values	Required
-h,--help	Print help message and exit
-t,--maptype	Map type	ENUM:value in {campaign,skirmish}	DEFAULTS to skirmish
-p,--maxplayers	Map max players	UINT:INT in [1 - 10]	REQUIRED
-f,--format	Output map format	ENUM:value in { bjo, json, jsonv2, latest}	REQUIRED
-i,--input	Input map directory	TEXT:DIR	REQUIRED (may also be specified as positional parameter)
-o,--output	Output map directory	TEXT:DIR	REQUIRED (may also be specified as positional parameter)

maptools map genpreview

Usage: maptools map genpreview [OPTIONS] inputmapdir output

Both inputmapdir and the parent directory for the output filename (output) must exist.

[OPTION]	Description	Values	Required
-h,--help	Print help message and exit
-t,--maptype	Map type	ENUM:value in {campaign,skirmish}	DEFAULTS to skirmish
-p,--maxplayers	Map max players	UINT:INT in [1 - 10]	REQUIRED
-i,--input	Input map directory	TEXT:DIR	REQUIRED (may also be specified as positional parameter)
-o,--output	Output PNG filename (+ path)	TEXT:FILE(*.png)	REQUIRED (may also be specified as positional parameter)
-c,--playercolors	Player colors	ENUM:value in {simple, wz}	DEFAULTS to simple
--scavcolor	Specify the scavengers hex color	RGB hex color code	DEFAULTS to #800000 (maroon)
--layers	Specify layers to draw	Either all or a comma-separated list of any of: {terrain, structures, oil}	DEFAULTS to all

Output Level Info Formats

[format]	Description	flaME	WZ < 3.4	WZ 3.4+	WZ 4.1+	WZ 4.3+
lev	<map>.addon.lev / <map>.xplayers.lev	✅	✅	✅	✅	✔️*
json	level.json					✅
latest	currently, an alias for json					✅

^* Loadable by this version, but not recommended. May be missing features / have trade-offs.

Output Map Formats

[format]	Description	flaME	WZ < 3.4	WZ 3.4+	WZ 4.1+
bjo	Binary .BJO	✅	☑️	✔️*	✔️*
json	JSONv1			✅	✔️*
jsonv2	JSONv2				✅
latest	currently, an alias for jsonv2				✅

^* Loadable by this version, but not recommended. May be missing features / have trade-offs.

Note: When converting from a newer format to an older format, it is recommended that you enable --verbose mode, as there are certain conditions in which a 1-to-1 conversion is not possible and adjustments may be made by the converter.