> 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

How to create, adjust, and customize populators in Build mode – the procedural environment generators that scatter one asset set across an area.

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. Think of it as Houdini-style procedural distribution for creatives without a TD on call.

## 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](https://1179478100-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FSWrjIqlgVAblx6vHGJiM%2Fuploads%2Fgit-blob-a31f57fb986f206f0eaa1fff3389362fb8d4f0d3%2Fpopulator-footprint-01.png?alt=media)

## 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. **Chat with Intangible.** Type "create a tropical forest" or "build a city block" in the chat panel. The [agents](https://help.intangible.ai/chat-agents-intangible/in-the-modes.md#build) create 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.

## When to reach for one

* **You need fifty or more of the same kind of object.** Crowds, vegetation, traffic, dense urban features. Manual placement falls apart past a couple dozen.
* **You want the distribution to look natural.** A forest dragged in by hand looks like an orchard. A populator with an organic layout and varied density looks like a forest.
* **You want to iterate the look.** Change the asset mix or density and the populator regenerates in seconds. Doing the same by hand means re-dragging.

Skip it for one specific hero object: drag the hero in directly. Skip it too when every instance needs an exact position. Populators distribute procedurally, so release the instances you need to place by hand (see [Editing a single instance](#editing-a-single-instance)).

## 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. Open it from **Populator shape and size** on the populator's toolbar; the **Shape and Dimensions** panel offers four options:

* **Volume** – fills a 3D box with instances rather than a flat area, sized by L, W and H (50 × 50 × 50 to start). Useful for asteroid fields or flocks of birds. A dense volume places a lot of objects, so raise the count carefully.
* **Rectangle** – the default. A flat area you size by L and W.
* **Circle** – a round footprint, sized by L and W.
* **Spline** – distributes objects along a curve you draw. Its dimensions follow the curve, so there are none to type. See [Spline populator](https://help.intangible.ai/build/spline-populator.md).

![The Shape and Dimensions panel with Shape set to Volume and the box packed with instances, then the Shape list opened and Rectangle picked, and the instances redistribute into a flat layer on the floor](https://1179478100-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FSWrjIqlgVAblx6vHGJiM%2Fuploads%2Fgit-blob-ccc782e6e21d024e5094ef633a21ef4d119f3660%2Fpopulator-cube-fill-07.gif?alt=media)

### 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, then Falloff raised to thin the field toward its edges and set back to zero](https://1179478100-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FSWrjIqlgVAblx6vHGJiM%2Fuploads%2Fgit-blob-f671281934c9f69cd6140da1f7c5e5333979a15b%2Fpopulator-density-06.gif?alt=media)

![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](https://1179478100-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FSWrjIqlgVAblx6vHGJiM%2Fuploads%2Fgit-blob-bbbbb19a46d0a018d8544a37ebd382c64ef674f0%2Fpopulator-layout-cycle-11.gif?alt=media)

### 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](https://1179478100-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FSWrjIqlgVAblx6vHGJiM%2Fuploads%2Fgit-blob-d8cee05364225ca1270a98a6a48a17ba6738102a%2Fpopulator-grid-cellsize-02.gif?alt=media)

![A grid of identical dragon models turning in 90-degree steps as Alternate Rotation is switched on and off, then Density raised and Layout switched to Random](https://1179478100-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FSWrjIqlgVAblx6vHGJiM%2Fuploads%2Fgit-blob-acc6dcfa7a0c361c3258e9688a5336c53ded9f18%2Fpopulator-alt-rotation-10.gif?alt=media)

### 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. Adding from the contents panel, you can pick several assets in the library in one go: select them, then confirm with the button that appears. Closing the library instead cancels. Each pick becomes its own entry.
* **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 on an Organic layout, with Populator Contents open to show the split: Tree Birch Dead at 35% and Box at 65%](https://1179478100-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FSWrjIqlgVAblx6vHGJiM%2Fuploads%2Fgit-blob-e960bff4812ff038b7464f1e981fa50d9f851710%2Fpopulator-distribution-08.gif?alt=media)

## 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](https://1179478100-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FSWrjIqlgVAblx6vHGJiM%2Fuploads%2Fgit-blob-fb43ba7f9f6b7575796e8038109c447c8b0a193a%2Fpopulator-target-dialog-09.png?alt=media)

### 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](https://1179478100-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FSWrjIqlgVAblx6vHGJiM%2Fuploads%2Fgit-blob-e1ea12084837655c537cc93f2530af6dda377b21%2Fpopulator-surface-snap-04.gif?alt=media)

### 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](https://help.intangible.ai/build/scene-outliner.md) to see the result cleanly; turn the mask off to bring the instances back.

It works on objects already standing in the populator too. A forest scattered straight through a castle clears out of the walls once the castle is allowed to mask it.

![Selecting a castle that a forest populator runs through, opening the Populator Target dialog, ticking Allow this object to mask populator instances and saving: the trees intersecting the castle disappear](https://1179478100-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FSWrjIqlgVAblx6vHGJiM%2Fuploads%2Fgit-blob-8d0912a869fcb965ee23938cf99be15234c17d8d%2Fpopulator-mask-target-01.gif?alt=media)

Only instances that intersect the object go. A tree standing just in front of a gate, touching nothing, stays where it is.

![A sphere used as a mask over a field of cone instances, then hidden to reveal a circular clearing cut out of the populator](https://1179478100-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FSWrjIqlgVAblx6vHGJiM%2Fuploads%2Fgit-blob-e7f0e7c6ce61027383e56f59646b53a6e1803d88%2Fpopulator-mask-05.gif?alt=media)

## 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**, or select the populator, click **Isolate instance** (or press **I**) and click the instance. It releases from the populator and becomes a regular object, in the same color, that 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.

To delete instances outright, select the populator and click **Prune instances**, then click the instances you want to delete. Press **Esc** to stop.

Both tools work in Build with only the populator selected.

## Turn objects into a populator

Select the objects, open **More options** and click **Convert Selection to Populator**. You get one populator with an element for each model, and the original objects are removed. If you selected several copies of the same model, the populator keeps the color and scale of the first one.

## Name it for the render

A populator's name reaches the visualizer. The [auto-prompt](https://help.intangible.ai/visualize/auto-prompt.md) builds its Environment & Props block from populator labels, so renaming `populator-3` to `dense rainforest understorey` changes the prompt the model receives without you touching the prompt. See [How the visualizer thinks](https://help.intangible.ai/learn-more/concepts/how-the-visualizer-thinks.md).

## 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 Volume shape at high density.** A Volume fill places instances through a 3D box, not a plane. The count climbs fast; raise it in steps.

## Related

* [Spline populator](https://help.intangible.ai/build/spline-populator.md)
* [What the agents do in Build](https://help.intangible.ai/chat-agents-intangible/in-the-modes.md#build)
* [How the visualizer thinks](https://help.intangible.ai/learn-more/concepts/how-the-visualizer-thinks.md)
* [Asset library](https://help.intangible.ai/build/asset-library.md)
* [Scene Outliner](https://help.intangible.ai/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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

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

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.
