6.3. macro_fill

A brush entity that randomly places template instances inside its brushes. Useful to fill an area with particles or other things.

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. 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.
  • 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 volume, the instance radius and the coverage factor.
  • Instance orientation (instance_orientation) -- The relative orientation of each instance.
    • Global (0)
    • Local (1)
  • Fill mode (fill_mode) -- This mode determines how instances will be placed.
    • Random points (0)
    • Random grid points (1)
    • All grid points (2)
  • Grid orientation (grid_orientation) -- The orientation of the grid, if fill_mode is set to a mode that uses grid points.
    • Global (0)
    • Local (1)
  • Grid granularity (x y z) (grid_granularity) --
  • 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, fill_mode, grid_orientation and grid_granularity, are evaluated again for every instance.
  • This entity can be used together with a macro_brush to create things like a trigger_hurt that is decorated with poison sprites. Create a macro_brush that covers the poisoned area, and create an extra template that contains a trigger_hurt and a macro_fill that references a template that contains a poison sprite.
  • 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.