3.1. Configuration files

The default MESS configuration file, mess.config, is a plain-text file that contains various settings. A different configuration file can be selected with the -config command-line parameter, which can be useful for switching between configurations for different games or mods.

`template-maps-directory`

Relative template map paths are relative to this directory. For example, if the template maps directory is C:\HL\Tools\MESS\template_maps, then a macro_insert entity with a template map path of fire.jmf will create an instance of C:\HL\Tools\MESS\template_maps\fire.jmf.

Maps in this directory can be used by macro entities in all maps, so it's a useful place for template maps with common props and entity setups.

The path can contain MScript expressions, and the executable directory can be referenced with EXE_DIR. The default value is {EXE_DIR}\template_maps.

`template-entity-directories`

These directories contain .ted (Template Entity Definition) files, their associated template map files, and .mscript files that can contain utility functions. .ted files are small text files that contain fgd-formatted entity definitions and MESS rewrite rules. They are used to generate or update the mess.fgd file. This makes it possible to share custom template entities without having to add additional .fgd files to a level editor: put their .ted, .mscript and template map files in one of the template entity directories, run MESS.exe to update mess.fgd, and restart the level editor to see the new entities.

To make it easier to share template entities, MESS will also look for .ted, .mscript and template map files inside .zip files in these directories.

The paths can contain MScript expressions, and the executable directory can be referenced with EXE_DIR.

`fgd-path`

All .ted (Template Entity Definition) files in the template entities directory are combined into a single .fgd file (mess.fgd by default), which can be added to a level editor to get access to these template entities. If a level editor requires .fgd files to be put in a specific directory, then use that location as the fgd-path setting, so MESS can keep the .fgd file up-to-date.

The path can contain MScript expressions, and the executable directory can be referenced with EXE_DIR. The default value is {EXE_DIR}\mess.fgd.

`max-recursion`

The maximum recursion depth (recursion is when a macro entity inside a template inserts another template). This is a failsafe to prevent accidental infinite recursion.

The default value is 100.

`max-instances`

The maximum number of template instances to create. This is a failsafe to prevent accidental infinite loops.

The default value is 100000.

`log-level`

The default log level. Available levels are:

off -- All logging is disabled.
minimal -- Only a few important messages are logged.
error -- Only critical errors are logged.
warning -- Non-critical warnings are also logged.
info -- Additional information is logged, such as which templates are being loaded.
verbose -- Even more information is logged, such as details about each instantiation.

The default value is info.

`variables`

These variables will be available in MScript expressions in the map properties and top-level entities of the input map. This can be useful for things like setting an author name, or for setting wad paths when compiling .rmf or .jmf files directly. Each assignment in this section must be on a separate line:

variables: variable_1 = 'value 1' variable_2 = [1, 2, 3]

`globals`

Global variables are available in MScript expressions anywhere, via the getglobal, setglobal and useglobal functions. Unlike variables, which are only available in the map properties and in top-level entities, globals are also available inside templates and template maps.

This makes it possible to create templates whose behavior can be configured via global variables. For example, a template could generate additional entities if a global variable named DEBUG is set to 1.

Each assignment in this section must be on a separate line:

globals: DEBUG = none MAX_LANDMINES = 15

`lifted-properties`

'Lifted' properties are always evaluated first, and are then made available to MScript expressions in the other properties of the same entity. One use-case for this is with TrenchBroom linked groups, where entities that are part of a linked group are tagged with a special _tb_group property. By 'lifting' this property and referencing it in other properties, each linked group instance can produce entities with different names and other values.

Each property name must be on a separate line:

lifted-properties: _tb_group other_property

`inverted-pitch-predicate`

Most Half-Life entities with a positive pitch will face downwards. However, some entities will face upwards instead (generally speaking, anything that displays a model). The value of this setting is evaluated for every non-macro entity to determine whether it uses inverted pitch behavior.

The predicate can (and most likely should) contain MScript expressions. All properties of the current entity are available, although the classname property is typically the most important one. If the result is none or 0 then MESS will use normal pitch behavior, else it will use inverted pitch behavior.

The default value (which applies to Half-Life) is: {classname.match('^(?:ammo_|item_|monster_|weapon_|xen_|cycler_|env_sprite)')}