6.1. macro_insert

A point entity that creates one or more template instances at a specific position. Instances can be scaled, rotated and translated.

The properties of this entity are visible to scripts in the selected template, so each instance can be made unique. This entity is often used together with macro_template, but it can also use other map files as templates.

Properties

  • Name (targetname) -- The name of this entity. Templates can reference this in scripts with {targetname} or by using the special function {id()}, which returns either the name of the instance-creating entity, or the unique numerical ID of the current instance.
  • Template map path (template_map) -- The relative or absolute path (or paths) of a map file. If no template entity is specified then the entire map is used as a template. In the main map, relative map paths are taken to be relative to the template maps directory. In template maps, they are relative to the current map.
  • Template entity (template_name) -- The name (or names) of a macro_template entity in the chosen map, or in the current map if no template map path is specified. If there are multiple templates with the same name, one will be chosen randomly per instance.
  • Random seed (random_seed) -- Random seed value, used for deterministic pseudo-randomness. This affects the rand and randi functions. Default is 0.
  • Instance count (instance_count) -- The number of instances to create. Default is 1. Use the nth() function in other macro_insert properties to customize each instance.
  • Instance orientation (instance_orientation)
    • Local (0) -- The orientation (angles) of the current instance is relative to the orientation (angles) of this macro_insert.
    • Global (1) -- The orientation (angles) of the current instance is not affected by this macro_insert. This is useful for entities that must always face a specific direction in the editor, such as func_tank.
  • Instance angles (Pitch Yaw Roll) (angles) -- The orientation of the current instance. This also affects the angles property of entities within the selected template.
  • Instance scaling (instance_scaling)
    • Relative (0) -- The instance scale and instance geometry scale are affected by the scaling of this macro_insert.
    • Absolute (1) -- The instance scale and instance geometry scale are not affected by the scaling of this macro_insert.
  • Instance scale (scale) -- The scale of the current instance. This also affects the scale property of entities within the selected template.
  • Instance geometry scale (x y z) (instance_geometry_scale) -- Geometry (brushes) can be scaled along the x, y and z axis. If empty, the scale property is used instead.
  • Instance positioning (instance_positioning)
    • Relative (0) -- The instance offset is an offset relative to the position of this macro_insert.
    • Absolute (1) -- The instance offset is used as an absolute position.
  • Instance offset (x y z) (instance_offset) -- Moves an instance along the x, y and z axis. This enables script-based positioning.

Custom properties

Custom properties can be used by MScript expressions in entities inside the selected template. This makes it possible to further customize instances. This is also the mechanism that template entities use for their properties to have any effect.

For example, imagine a template that contains a game_text entity with a message of Hello {name}. If a macro_insert creates an instance of that template, the resulting game_text entity will have a message value of Hello . Adding a custom name property to the macro_insert entity and setting it to John will result in a game_text entity with a message of Hello John. Another macro_insert can have a name property with a different value, and its resulting game_text will have a different message accordingly.

Notes

  • Angles are usually written in pitch-yaw-roll order, but Half-Life and MESS perform rotations in roll-pitch-yaw order, which corresponds to rotating around the x, y and z axis respectively:
    • pitch (y-axis): positive = looking down, negative = looking up (note that this is inverted for model and light entities!)
    • yaw (z-axis): positive = turning left, negative = turning right
    • roll (x-axis): positive = leaning to the right, negative = leaning to the left
  • All properties, except for random_seed and instance_count, are evaluated again for every instance. This means that if instance_offset is set to {nth() * 16} 0 0, the first instance will have an offset of 0 0 0, the second instance will have an offset of 16 0 0, the third an offset of 32 0 0, and so on.
  • To randomly select one of several templates, use a comma-separated list of paths or template names: prop_cactus, prop_rock will randomly use either prop_cactus or prop_rock. It's also possible to specify a selection weight: prop_cactus: 1, prop_rock: 4 will select prop_cactus 20% (1/5) of the time, and prop_rock 80% (4/5) of the time. This also works for template map paths.