6.2. macro_cover

A brush entity that randomly places template instances across its non-NULL faces. Useful for covering terrain with props.

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 one or multiple macro_template entities, but it can also use other map files as templates.

Properties

  • Name (targetname) -- The name of this entity. Because this entity creates multiple instances, it's better to use the unique instance ID in templates (with {iid()}), unless every instance really does need to use the same name.
  • 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.
  • Brush behavior (brush_behavior) -- What to do with the brushwork of the macro_cover entity.
    • Remove brushes (0)
    • Leave as world geometry (1)
    • Leave as func_detail (2)
  • Coverage (<1) or max instance count (>=1) (max_instances) -- The maximum number of instances that will be created. Instances will not be placed if they are too close to existing instances, so the actual number of instances may be lower. A value between 0 and 1 is treated as a coverage factor: the number of instances will be derived from the available area, the instance radius and the coverage factor.
  • Instance orientation (instance_orientation) -- The relative orientation of each instance.
    • Global (0)
    • Local (1)
    • Face (2)
    • Texture plane (3)
  • Instance angles (Pitch Yaw Roll) (instance_angles) -- The orientation of the current instance. This also affects the angles property of entities within the selected template.
  • Instance scale (instance_scale) -- The scale of the current instance. This also affects the scale property of entities within the selected template.
  • Instance geometry scale (instance_geometry_scale) -- Geometry (brushes) can be scaled along the x, y and z axis. If empty, the scale property is used instead.
  • Instance offset (instance_offset) -- Moves an instance along the x, y and z axis. This enables script-based positioning.
  • Instance radius (radius) -- The minimum distance between each instance. This is also used to calculate the number of instances when max_instances is a coverage factor (<1). This property is evaluated up-front, so all instances use the same radius.

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.

Notes

  • All properties, except for max_instances, radius, random_seed and brush_behavior, are evaluated again for every instance.
  • If the macro_cover brushwork must be turned into a specific entity, turn the macro_cover into a macro_brush instead, and create an extra template that contains a macro_cover and brush entity of the desired type.
  • 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.