> For the complete documentation index, see [llms.txt](https://help.intangible.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.intangible.ai/build/populators.md).

# Populators

Populators are procedural containers that distribute assets across an area. Drop one in, fill it with trees, and you get a forest without placing every tree by hand. The conceptual page is [Populators](/overview/concepts/populators.md); this page is the build-side how-to.

## Watch

{% embed url="<https://www.youtube.com/watch?v=XxbxqcGCuR4>" %}

![Active populator in Build mode with its cyan-blue trapezoidal footprint outline visible. The populator is filled with golden flowers and the contextual menu is hovering above it for adjustments](/files/damyaBQQSu0zxJUd8Gci)

## What it does

A populator is an object like any other: move it, scale it, place it in the scene. What sets it apart is that it generates a field of instances inside its bounds from rules you set, instead of you placing each one. Use it for forests, crowds, traffic, cities, asteroid fields, anything that reads as "many of a thing".

## How to create one

Two pathways, in increasing manual control:

1. **AI Composer prompt.** Type "create a tropical forest" or "build a city block" in the AI Composer panel. The agent creates a populator with the asset mix and layout that match the prompt. Fastest path; results need refinement.
2. **Library populator templates.** The asset library has a category for ready-made populators. Drag one in and adjust.

## The two control groups

Select a populator and its toolbar shows two buttons that hold everything:

* **Shape and Layout** – the size, the boundary shape, the distribution, and the variability. How the instances are arranged.
* **Populator Contents** – the assets in the populator, their colors, sizes, and how they share the available spots.

You'll move between the two as you dial a populator in: pick the assets in Contents, shape and distribute them in Shape and Layout.

## Shape and Layout

### Shape

The boundary the populator fills. Three options:

* **Rectangle** – the default. A box you size on each axis (50 × 50 × 50 to start; change any axis and the bounds grow).
* **Circle** – a round footprint.
* **Cube** – fills a 3D volume with instances rather than a flat area. Useful for asteroid fields or flocks of birds. Dense cube volumes place a lot of objects, so raise the count carefully.

![The Cube shape filling the whole boundary volume with packed instances, the way an asteroid field or a flock reads](/files/Eyp3PyogVhvLKbm9V17G)

### Size

Scales the boundary as a whole. A larger boundary holds more instances at the same density.

### Layout

How instances distribute inside the boundary. Three types, each with its own parameters:

* **Organic** – a natural scatter with no overlap. The default for vegetation and crowds.
* **Random** – like organic but allows instances to overlap, for denser, less ordered fields.
* **Grid** – aligns instances to a cell grid. Suits cities, orchards, parking lots, anything regular.

Three controls apply across every layout type:

* **Density** – how many instances fill the boundary. Roll it up for a thick forest, down for a sparse one.
* **Falloff** – how far the fill pulls in from the edges. A high falloff disintegrates the populator toward its boundary; zero fills to the edge.
* **Seed** – the random seed behind the spawn. Each seed is a different distribution of the same settings. When a forest or city layout is almost right, step the seed (or click the recycle button next to it) to roll a fresh distribution until the arrangement reads well.

![Density rising on an organic layout, the boundary going from a sparse scatter of cubes to a packed field as the slider moves](/files/ll68bm9Nl4bo65CjtbuN)

![A populator cycling through the three layout types as the Layout dropdown changes: Organic's even scatter, then Random's overlapping clumps, then Grid's aligned rows](/files/NkXOZXndTd5tIoKAL9V2)

### Grid options

Grid layout adds cell-based controls:

* **Cell Size / Cell Mode.** Fit Content and Fit Max Content size the cells to the assets automatically. Switch to **Custom** to set the cell dimensions yourself (for example 10 m × 10 m × 10 m). Smaller cells pull instances closer; a cell size of zero removes the gap entirely.
* **Gap.** The minimum distance to hold between instances, set in meters. Similar to enlarging the cell, but applied as spacing around each instance.
* **Offset.** Shifts the whole grid by a set distance, so the pattern doesn't always start in the same spot.
* **Alternate Rotation.** Off, every instance faces the same way. On, instances rotate in 90-degree increments. One building model placed across a city block reads as four different buildings because each is turned a quarter.

![Grid layout selected in the populator panel with Cell Mode set to Custom and Cell Size at 10 metres, a sparse grid of instances in the boundary](/files/2F31vDOcLPp2N9uVS1pM)

![A grid of identical dragon models, all facing the same way, then turning to varied 90-degree orientations when Alternate Rotation is switched on](/files/WthV28qOgAlqwESFvwA8)

### Object Variance

Two sliders randomize each instance so the field doesn't look stamped:

* **Rotation.** At maximum, instances face fully random directions; at zero, all face the same way. (Distinct from Alternate Rotation, which steps in 90-degree increments on grids.)
* **Size.** Varies the scale of each instance by a random percentage. At zero, every instance is the same size.

## Populator Contents

Open Populator Contents to manage the assets the populator distributes.

* **Add assets.** Drag an asset from the library onto the populator, or use the contents panel. A populator can hold several different assets at once.
* **Color.** Each asset type holds its own color. Give different assets different colors to vary the field.
* **Default size.** Sets the base size of an asset before variance. Scaling an asset up also spreads instances farther apart. Use it for variety – the same pine, scaled five times, reads as a redwood.
* **Distribution.** When a populator holds more than one asset, distribution weights how often each one takes a spot. Two assets both at 1 split the spots roughly evenly; lower one and the other takes over its spots. This is how you say "more cubes than trees" without placing either by hand.

![A mix of trees and red cubes in one populator, the balance shifting from tree-heavy to cube-heavy as the distribution weight changes](/files/QqYoLQo8oa0G31mnmZM5)

## Surfaces: snapping and masking

Populators can react to other geometry in the scene. Both behaviors are set from the target object's Populator Target dialog, which offers two toggles: let the object mask populator instances, or let populator instances snap to it.

![The Populator Target dialog open over a selected object, with two options: allow this object to mask populator instances, and allow populator instances to snap to this object](/files/Sw4SvNUXA8bTCZdIwFFo)

### Climb a surface

To make a populator follow terrain (cones up a mountain, grass over a hill), open the **target object's** three-dot (⋯) menu and allow populators to snap to it. Save, and the instances climb the surface and re-adjust whenever you move or scale it.

![Red cone instances climbing and conforming to a grey mountain surface after the mountain is allowed to accept populators](/files/jIngAFQ8FVM3jHAOwdal)

### Ignore surfaces

You can also tell a populator to ignore surfaces from its Populator Contents, so it drops flat to the ground. The two controls live in two places on purpose: a scene can mix populators that climb with ones that don't.

### Mask out part of a populator

Use another object as a mask to cut instances out of a populator – a clearing in a field of grass, a plaza in a forest. Open the masking **object's** three-dot (⋯) menu and allow it to mask a populator, then drag it into the populator's area. Any instances inside the mask are removed. Hide the mask object in the [Scene Outliner](/build/scene-outliner.md) to see the result cleanly; turn the mask off to bring the instances back.

![A sphere used as a mask over a field of cone instances, then hidden to reveal a circular clearing cut out of the populator](/files/0uylr1D9FmvGem1gfQnK)

## Editing a single instance

To pull one instance out of the procedural field – a tree in the camera's path, a cone you don't want – **double-click it**. The instance releases from the populator and becomes a regular object you can move on its own or delete. Useful for clearing a character's running path through a dense forest without thinning the whole populator.

## Common mistakes

{% hint style="warning" %}
**Don't try to lock instances inside a populator.** The lock is silently overridden the next time the populator regenerates (which happens on density changes, layout switches, footprint resizes). To keep a specific instance, double-click it to release it as a regular object first, then place or lock that.
{% endhint %}

* **Tuning density before fixing the asset mix.** Density is a multiplier; the contents are the substance. Get the assets and their distribution right first, then adjust density.
* **A cube layout at high density.** A 3D cube fill places instances through a volume, not a plane. The count climbs fast; raise it in steps.

## Related

* [Populators (concept)](/overview/concepts/populators.md)
* [Spline populator](/build/spline-populator.md)
* [AI Composer](/build/ai-composer.md)
* [Asset library](/build/asset-library.md)
* [Scene Outliner](/build/scene-outliner.md)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://help.intangible.ai/build/populators.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.