8.1. Convert options

MESS convert command-line
MESS convert command-line

The -convert mode has its own specific command-line arguments. The most important arguments are INPUT_PATH and OUTPUT_PATH, which specify the input and output file. Both are required. Supported file formats are .map, .rmf and .jmf (and the backup variants .rmx and .jmx). All other command-line arguments must be placed before the input and output map paths.

Available options

Input options:

Output options:

.jmf output:

.rmf output:

.map output:

VIS group filtering:

Cordoning:

Logging:

Input & output files:

Option descriptions

-duplicatekeys DUPLICATE_KEY_HANDLING

Most editors don't allow entities to have duplicate property keys, and MESS doesn't support it either. If a map does contain entities with duplicate keys, then this option determines what will happen to those entities. Available options are:

  • usefirst - Uses the value of the first property. This is the default behavior.
  • uselast - Uses the value of the last property. Previous values are ignored.
  • fail - File conversion will fail with an error message.

-rmfspawnflagproperty RMF_SPAWNFLAGS_HANDLING

Hammer saves entity spawnflags as part of an entity object in an .rmf file, but J.A.C.K. saves them as a property (key-value pair). This can cause inconsistencies when an .rmf file is opened and saved by J.A.C.K., and then opened in Hammer again.

This option determines what MESS should do when it encounters an entity with a spawnflags property in an .rmf file. Available options are:

  • ignore - Ignores the spawnflags property, like Hammer does.
  • use - Uses the spawnflags property, like J.A.C.K. does. This is the default behavior.
  • fail - File conversion will fail with an error message.

-tbfuncgroup FUNCGROUP_HANDLING

TrenchBroom stores groups and layers (VIS groups) as func_group entities with special properties. This option determines how these func_group entities should be treated:

  • converttogroup - Converts them to groups and VIS groups. This is the default behavior.
  • leaveasentity - Leaves them as entities.

-keyvaluetoolong LONG_KEYVALUE_HANDLING

In .rmf files, entity keys and values are limited to 255 characters. This option determines what should happen if a map contains keys or values that are longer:

  • truncate - The key or value is truncated, and a warning is logged.
  • fail - File conversion will fail with an error message. This is the default behavior.

-texturenametoolong LONG_TEXTURE_HANDLING

In .rmf files, texture names are limited to 260 characters (40 characters in v1.6 and older). In .jmf files, they are limited to 64 characters. This option determines what should happen if a map contains texture names that are longer:

  • truncate - The texture name is truncated, and a warning is logged.
  • fail - File conversion will fail with an error message. This is the default behavior.

-invalidkeyvalue INVALID_KEYVALUE_HANDLING

Because of how entity data is stored in .map and .bsp files, keys and values should not contain double quotes ("). This option determines what should happen if a key or value does contain a double quote:

  • replace- Invalid characters are replaced by the value of -keyvaluereplacement (which by default is a single quote: '). This is the default behavior.
  • ignore - Invalid characters are ignored. If the output format is .map, the resulting .map file will be invalid.
  • fail - File conversion will fail with an error message.

-keyvaluereplacement TEXT

If -invalidkeyvalue is set to replace (the default behavior), invalid characters in keys and values are replaced with the value of this setting. The default value is a single quote ('). Setting this to an empty string (-keyvaluereplacement "") will cause invalid characters to be removed.

-invalidtexturename INVALID_TEXTURE_HANDLING

The .map file format does not allow texture names to contain spaces. This option determines what should happen if a texture name does contain a space:

  • replace - Spaces are replaced by the value of -texturenamereplacement (which by default is an underscore: _). This is the default behavior.
  • ignore - Spaces are ignored. If the output format is .map, the resulting .map file will be invalid.
  • fail - File conversion will fail with an error message.

-texturenamereplacement TEXT

If -invalidtexturename is set to replace (the default behavior), spaces in texture names are replaced with the value of this setting. The default value is an underscore (_). Setting this to an empty string (-texturenamereplacement "") will cause spaces to be removed.

-visgroups VISGROUP_ASSIGNMENT

In .jmf files, objects can belong to multiple VIS groups. In .rmf and TrenchBroom .map files, objects can belong to at most one VIS group. This option determines what should happen when an object belongs to multiple VIS groups, but the output format only supports one VIS group:

  • usefirst - The object is put in the first VIS group that it was part of. This is the default behavior.
  • uselast - The object is put in the last VIS group that it was part of.
  • fail - File conversion will fail with an error message.

-jmfversion VERSION

The output .jmf file version. Available options are:

  • v121 - The most common version, before the J.A.C.K. 1.1.3773 update.
  • v122 - The latest version as of early 2024, which introduces background images for the 2D views. This is the default version.

-rmfversion VERSION

The output .rmf file version. Available options are:

  • v1_6 - Used by Worldcraft 1.5b.
  • v1_8 - Used by Worldcraft 1.6 to 2.1. This version increases the maximum length of texture names to 260.
  • v2_2 - Used by Worldcraft 3.3 and Hammer 3.4 and 3.5. This version adds support for texture UV axis. This is the default version.

-mapdecimals N

The precision of numbers in the output .map file. This should be zero or higher. By default, a roundtrip format is used that uses the minimum number of decimals that still uniquely 'identifies' a given floating point value. This roundtrip format may use scientific notation.

-mapformat FORMAT

The output .map format. Available options are:

  • valve220 - The 'standard' valve220 .map format. This is the default value.
  • trenchbroomvalve220 - The TrenchBroom variant of the standard valve220 format. This file format uses func_group entities and TrenchBroom-specific properties to store groups and layers (VIS groups).

-tbgame NAME

When exporting to a TrenchBroom .map file, this determines the game name that is stored at the start of the file. This affects which game configuration TrenchBroom uses when opening the file. Use -tbgame Half-Life for Half-Life maps.

-wad NAMES

When exporting to a .map file, this setting sets the wad map property (a special property in the worldspawn entity). This property tells the game which .wad files to load. Multiple wad names must be separated by semicolons.

.map files that are meant to be compiled only need to contain .wad filenames: halflife.wad;liquids.wad. .map files that are meant to be edited by TrenchBroom should use relative or absolute paths: valve/halflife.wad;valve/liquids.wad.

-onlyvisgroups NAMES

Only objects that belong to one of the listed VIS groups will be included in the output map. VIS group names can contain wildcards (*). Multiple names must be separated by commas. This setting does not exclude objects that do not belong to any VIS group - use -onlyvisgroupobjects to exclude those objects.

For example, if a map contains the following VIS groups: buttons, doors, area1_triggers and area2_triggers, then -onlyvisgroups doors,*triggers will only include objects from the doors, area1_triggers and area2_triggers VIS groups.

-notvisgroups NAMES

Objects that belong to one of the listed VIS groups will be excluded from the output map. VIS group names can contain wildcards (*). Multiple names must be separated by commas.

For example, if a map contains the following VIS groups: buttons, doors, area1_triggers and area2_triggers, then notvisgroups buttons,*triggers will exclude objects from the button, area1_triggers and area2_triggers VIS groups.

-onlyvisgroupobjects

This switch causes all objects that do not belong to a VIS group to be excluded from the output map.

-noinvisiblevisgroups

This switch causes all objects that belong to an invisible VIS group to be excluded from the output map.

-novisiblevisgroups

This switch causes all objects that belong to a visible VIS group to be excluded from the output map.

-noomittedlayers

This switch causes all objects that belong to a TrenchBroom layer that is marked as 'omitted from export' to be excluded from the output map.

-cordonarea AREA

This sets a cordon area. Anything that is completely outside the cordon area is excluded from the output map. The cordon area is sealed off with brushes to ensure that no leaks will occur.

The format is -cordonarea "min_x min_y min_z max_x max_y max_z". For example, -cordonarea "-512 -512 -128 512 512 128" will take a 1024x1024x256 box from the center of the map.

-jmfcordonarea

If this switch is set, and the input file is a .jmf file that contains a cordon area, then that cordon area is used to exclude anything outside the cordon area.

-cordontexture TEXTURE

The texture that will be applied to the cordon brushes. The default value is "BLACK".

-cordonpadding N

This setting determines how far the cordon brushes should extend beyond the map's leftover content. The default value is 16. This is the default behavior. It guarantees that cordoning will not cause leaks, and it matches how Hammer creates cordon brushes.

-cordonthickness N

This setting gives cordon brushes a fixed thickness. This may cause leaks, because not all of the map's leftover content may be covered. This matches how J.A.C.K. creates cordon brushes.

-log OPTION

This determines how much information will be logged. Available log levels are off, minimal, error, warning, info (the default level) and verbose. See configuration file: log-level for more information.

INPUT_PATH

The input map file. Supported formats are:

  • .map - The export format for all editors, and the native format for TrenchBroom. Only the valve220 format is supported.
  • .rmf - The native format for Hammer. The backup variant, .rmx, is also supported.
  • .jmf - The native format for J.A.C.K. The backup variant, .jmx, is also supported.

OUTPUT_PATH

The output map file. Supported formats are .map, .rmf and .jmf.