6.5. macro_template

Anything inside the bounding box of this entity becomes part of a template. Templates are removed from the map, but instances can be created in various places by other macro entities. For templates that are useful in multiple maps it's better to create a separate template map (MESS supports MAP, RMF and JMF files).

Template customization

Entities inside a template have access to the custom properties of their template, and to the properties of the macro entity that is currently creating an instance of the template. This makes it possible to customize each instance. Such references are surrounded by curly brackets: {property_name}.

For example, imagine a template named beam_template, which contains an env_beam with the following properties:

If a macro_insert named machine is used to create an instance of this template, then the resulting env_beam will have a targetname of machine_beam. If another macro_insert named ice also creates an instance, then that env_beam will be named ice_beam. Both beams will have the same render amount and render color. The {targetname} part simply refers to the targetname property of the macro entity that is creating the current instance.

But curly brackets can be used for more than just property references - they can also contain small scripts. For example, button_{4 + 5} becomes button_9, and {damage < 10 ? 'small' : 'big'}_spr becomes small_spr if damage is less than 10, and big_spr otherwise.

One of the most common scripts is {id()}. The id() function is similar to referencing the targetname property, but if the macro entity that's creating the current instance does not have a name then id() returns the numerical ID of the current instance. This ID can also be obtained with the iid() function, which is useful when an entity must have a unique name, even when the targetname of the instance-creating macro entity is not unique.

Properties

• Name (targetname) -- The name (or names) of this template. If multiple templates have the same name, one of them is chosen randomly each time an instance is created. Multiple names must be separated by commas.
• Anchor point (origin) (anchor) -- The origin of this template.
  • Bottom center (0) -- The bottom center of the template's bounding box.
  • Center (1) -- The center of the template's bounding box. This is the default.
  • Top center (2) -- The top center of the template's bounding box.
  • Origin brush (3) -- The center of the template's origin brush. Uses the bottom center if there is no origin brush.
• Random selection weight (selection_weight) -- This determines how likely this template is to be chosen when there are multiple templates with the same name. If this is set to 0 then the template will not be chosen at all, even if there are no other templates with the same name. The default value is 1.

Custom properties

When an instance of a template is created, any scripts inside its custom properties are evaluated. These scripts have access to the properties of the macro entity that is creating the current instance. Custom template properties are a good place to set values that are used in multiple places inside the template.

Notes

• Because it's the bounding box that counts, it's better to mark template areas with two brushes rather than one: one on the left and one on the right. This makes it easier to select and modify the template contents.
• When multiple templates have the same name, one of them is chosen randomly each time an instance is created. This can be used to group related templates together: for example, a cactus, a rock and a shrub template could all be named prop_desert.
• Use multiple names for templates that should be part of multiple groups: a shrub template named prop_shrub, prop_desert, prop_temperate can be referenced by using either prop_shrub, prop_desert or prop_temperate.
• Templates can contain macro_insert and other instance-creating macro entities, making them recursive.
• To exclude parts of a template in specific instances, use a macro_remove_if entity. To exclude specific entities, add a _mess_remove_if property to them.