/maptools-cli

A command-line utility to work with Warzone 2100 map formats

Primary LanguageC++GNU General Public License v2.0GPL-2.0

maptools (CLI)

Warzone 2100 Map Tools

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
--map-seed Specify the script-generated map seed uint32_t DEFAULTS to rand()

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)
--layers Specify layers to draw Either all or a comma-separated list of any of: {terrain, structures, oil} DEFAULTS to all
--map-seed Specify the script-generated map seed uint32_t DEFAULTS to rand()

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
--map-seed Specify the script-generated map seed uint32_t DEFAULTS to rand()

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)
--map-seed Specify the script-generated map seed uint32_t DEFAULTS to rand()

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
--map-seed Specify the script-generated map seed uint32_t DEFAULTS to rand()

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.