# Quick Start

This page gets a crowd moving in five steps, in **Blueprint**. Each step also has a **C++**
example tucked in a collapsible below it - expand it if you're scripting in C++, otherwise
ignore it. The only object you ever talk to is the **crowd actor**
([`ACrowdToolkitActor`](../api_reference/01-crowd_actor.md)): spawn agents on it, order them, and
read back their transforms to render them.

::: tip
Every step is shown as Blueprint nodes. The **▸ C++** drop-down under each one holds the
equivalent code - collapsed by default.
:::

---

## 1. Get the crowd actor

You don't have to place anything in the level. The first time you ask for the crowd, the
[subsystem](../api_reference/02-subsystem.md) **adopts a crowd actor already in the level**, or
**spawns a default one** if there is none. Grab it from anywhere with a single node.

![Get Crowd node](../assets/get-started/qs-get-crowd.png)

==- C++
```cpp
// The world comes from the calling object, so this works anywhere.
ACrowdToolkitActor* Crowd = UCrowdToolkitLibrary::GetCrowd(this);
```
===

::: tip
Place a configured **`BP_Crowd`** (or a plain *Crowd Toolkit Actor*) in your level if you want to
tune agent radius, speed, formation, pathfinding, walls, etc. in the details panel - `GetCrowd`
will adopt it. Keep **one crowd actor per level**.
:::

---

## 2. Spawn agents

Agents live at world positions. The simplest start is a grid.

![Spawn Agent Grid on BeginPlay](../assets/get-started/qs-spawn-grid.png)

==- C++
```cpp
// A 20 x 20 block, 50 units apart, starting at Origin.
Crowd->SpawnAgentGrid(Origin, /*Cols*/ 20, /*Rows*/ 20, /*Spacing*/ 50.0f);

// ...or one at a time. Position.Z is the agent's initial tracked height.
Crowd->SpawnAgent(FVector(0, 0, 0));
```
===

Each agent gets an **index** (its slot in the crowd's arrays). The query and order nodes work
in indices - that's all you need here. (For tracking a specific unit over time, see
[Indices & Stable IDs](../concepts/04-indices_and_ids.md).)

---

## 3. Select agents

To order a group you need their indices. The query nodes return them in one pass. The classic
RTS one is **marquee select straight from a screen rectangle**:

![Get Agents In Screen Rect](../assets/get-started/qs-select.png)

==- C++
```cpp
// Everything inside the on-screen drag rectangle (RTS marquee select).
TArray<int32> Picked = Crowd->GetAgentsInScreenRect(PlayerController, ScreenMin, ScreenMax);
```
===

Other ways to select: `GetAgentsInRadius(Center, Radius)` and `GetAgentsInRect(Box2D)` - same
idea, both return indices.

---

## 4. Order them to move

Hand the selected indices and a destination to **Set Agents Target**. They arrange themselves
into a [formation](../concepts/02-formations.md) centred on the point and share one path there.

![Set Agents Target node](../assets/get-started/qs-order.png)

==- C++
```cpp
Crowd->SetAgentsTarget(Picked, ClickedWorldLocation);
```
===

That's the whole movement loop - one call moves any number of units as a group. For a single
unit, **Set Agent Target** (`Index`, `Position`) is a convenience wrapper.

---

## 5. Render the agents

The crowd is **simulation only** - it stores positions, not meshes. Every frame, read the
agents' transforms and push them into an **Instanced Static Mesh**.

![Render transforms into an ISM on Tick](../assets/get-started/qs-render.png)

==- C++
```cpp
// On Tick, in your renderer actor:
TArray<FTransform> Transforms = Crowd->GetAgentTransforms({}); // {} = all agents
ISM->ClearInstances();
ISM->AddInstances(Transforms, /*bReturnIndices*/ false, /*bWorldSpace*/ true);
```
===

See [Rendering Agents](./03-rendering_agents.md) for the production pattern (updating instances
in place instead of clearing each frame) and how facing / ground alignment is baked into the
transforms.

---

## The whole loop

```
Get Crowd ──► Spawn Agents ──► (on drag-select) GetAgentsInScreenRect
                                        │
                                        ▼
                              (on right-click) SetAgentsTarget
                                        │
              (every Tick) GetAgentTransforms ──► render instances
```

From here:

- [Rendering Agents](./03-rendering_agents.md) - the render loop in detail
- [Wall Generation](./04-wall_generation.md) - block movement with walls / the nav mesh
- [Navigation](../concepts/01-navigation.md) - flow field vs Spatial A\*
- [Crowd Actor reference](../api_reference/01-crowd_actor.md) - every property and function