7.6. Rewrite rules

Rewrite rules are the glue that enable template entities and behaviors. They can turn an entity with a custom classname into a macro_insert or other macro entity, and link it to a specific template map. Rewrite rules are stored in .ted (Template Entity Definition) files, and they are used to modify entity properties when a map file is read, or when the final output map file is written.

7.6.1. .ted files

.ted files are similar to .fgd files. They typically contain a single entity definition and some rewrite rules that are related to that entity. MESS combines all .ted files in the templates directory into a single .fgd file, mess.fgd. This makes it easier to share template entities and behaviors with other people: place their .ted, .map and .mscript files in the templates directory, run MESS.exe, and restart your editor (or reload the fgd) to get access to new template entities.

Strings inside entity definitions can contain MScript expressions. This enables things like using custom editor sprites and models.

7.6.2. Rewrite rule syntax

Rewrite rule blocks start with a // @MESS REWRITE: line, and end with a // @MESS; line. Every rule line starts with a //, so they will be ignored by fgd-readers.

Rule types

There are two types of rules:

  • // "property-name": "new-value" - This will overwrite (or create) the specified property with a new value.
  • // delete "property-name" - This will delete the specified property.

Note that both property names and values can contain MScript expressions. This makes it possible to modify existing values. For example: // "renderamt": "{rendermode == 4 ? 255 : renderamt}" will set the FX amount (renderamt) to 255 if the Render mode (rendermode) is set to Solid (4), but else it will leave the old value in place (renderamt).

Conditional rule blocks

Rule blocks can also contain conditional blocks, whose rules are only applied if the condition holds:

  • // @IF "{condition}": starts a conditional rule block. Conditional blocks cannot be nested.
  • // @ELSE: starts an alternate rule block. The rules in this block are only applied if the @IF condition does not hold. Else blocks are optional.
  • // @ENDIF; marks the end of a conditional rule block.

Clauses

Most rewrite rules are only applied to a specific entity type, but it's also possible to apply rules to all entities, or to entities that match specific criteria. A rewrite rule block that is directly followed by an entity definition is automatically associated with that entity type:

// @MESS REWRITE: // "targetname": "test" // @MESS; @PointClass = info_test [ ]

If a rule block is not followed by an entity definition, then it must have a FOR or WHEN clause that determines which entities it applies to. A FOR clause must be followed by one or more entity classnames, each surrounded by double quotes. These are the entities that the rule block will be applied to:

// @MESS REWRITE FOR "info_test" "info_test2": // delete "targetname" // @MESS;

A WHEN clause must be followed by a condition, which must also be surrounded by double quotes. The condition can contain MScript expressions. All entity properties are available in these expressions, but MScript expressions in these properties have not been evaluated yet at this point. The rule block will be applied to any entity that matches the given condition (an empty string or a 0 is treated as false, anything else is seen as a match):

// @MESS REWRITE WHEN "{rendermode == 4 && renderamt != 255}": // "renderamt": "255" // @MESS;

By default, rewrite rules are applied before macro entities are processed. This is used by template entities to change their classname to a macro entity, and then setting a specific template map. But it's also possible to apply rewrite rules after macro entity processing:

// @MESS REWRITE AFTER_MACRO_EXPANSION WHEN "{_tb_group}": // delete "_tb_group" // @MESS;

This can be useful for cleaning up unwanted properties, or for automatically fixing problematic property values.

7.6.3. Rewrite rule functions

MScript expressions inside .ted files have access to standard functions and template functions (except for the instance ID functions). There are also a few functions that are only available in .ted files:

string ted_dir()

Returns the directory or .zip file path that contains the .ted file that contains the current rewrite rule.

For example, ted_dir() may return something like 'C:\HL\Tools\MESS\template_entities\my_templates.zip', if the current .ted file is stored in a .zip file, or 'C:\HL\Tools\MESS\template_entities\my_templates' if it's stored in a directory.

string ted_path()
string ted_path(string relative_path)

If no relative path is given, then this function will return the absolute path of the .ted file that contains the current rewrite rule. If the .ted file is stored in a .zip file, then the path will contain the .zip filename as if it were a directory.

If a relative path is given, then this function will search through all template entity directories for the given relative path, and it will return the full path of the first file that it can find.

For example, ted_path() may return something like 'C:\HL\Tools\MESS\template_entities\my_templates.zip\landmine.ted', and ted_path('target_pattern_handler.map') may return 'C:\HL\Tools\MESS\template_entities\mess_template_entity\target_pattern_handler.map', depending on the current configuration file. See Configuration files: template-entity-directories for more information.