Getting Started

This guide builds a working town from an empty scene, by hand, so you understand every piece.

tip

If you have not seen the system running yet, do that first. Your First Scene opens a complete working scene in about a minute, and building by hand is far easier once you know what the result should look like.

Work through Requirements and Installation before starting.

What you will achieve

By the end of this guide you should have:

• the runtime bootstrap in your scene
• module settings created and assigned
• at least one work behaviour and one need behaviour
• a building in the scene
• a population region in the scene
• item collections assigned so editor tooling works correctly
• agents spawning and taking actions in play mode

Before you begin

You should be comfortable with:

• creating and saving Unity scenes
• adding components to GameObjects
• assigning references in the Inspector

Two conventions used throughout:

• Menu paths like BardTreeLtd/Civil AI/Module Settings start at Unity's top menu bar.
• Assets > Create > ... is the Create menu, which you also get by right-clicking in the Project window.

The shortest path to first success

Follow these steps in order.

1. Add the bootstrap object

Create an empty GameObject in your scene (GameObject > Create Empty), name it something like Bootstrap, and add the BardTreeModuleBootstrap component to it.

This is the runtime entry point. It creates the shared service registry, registers each installed module, and initialises them in the correct order.

If you are upgrading from 0.12.x, this component replaces ModuleService.

2. Open Module Settings

Open BardTreeLtd/Civil AI/Module Settings.

If no settings asset exists yet, let the window create the default one, or use BardTreeLtd/Create Module Settings/CivilAI. It is written to Assets/BardTreeLtd/Resources/CIVIL-AI-SYSTEM/System/ModuleSettings.asset.

This asset is the main control panel for time, behaviour repositories, item collections, character pools and performance values. Keep the window open — the next steps all come back to it.

3. Create your core data assets

Create each of these from Assets > Create, then assign it in Module Settings.

Asset	Create menu path
Item name collection	BardTreeLtd/Civil AI/Inventory/Item Name Collection
Item type collection	BardTreeLtd/Civil AI/Inventory/Item Type Collection
Item size collection	BardTreeLtd/Civil AI/Inventory/Item Size Collection
Character pool	BardTreeLtd/Civil AI/Spawn/Character Pool
Character pool service	BardTreeLtd/Civil AI/Spawn/Character Pool Service

The character pool holds the prefabs that may be spawned; the pool service groups pools and is the asset you assign in Module Settings. Add at least one valid character entry to the pool.

You also need behaviour content. Work trees are built from several list assets under Assets > Create > BardTreeLtd/Civil AI/Behaviour/Work/ — Job List, Duty List, Duty Task List, Task Method List and Action List — plus Behaviour/Shared/Method List. Need trees use Behaviour/Need/Need List. You author how they connect in the Behaviour Tree Editor, covered in Using the Behaviour Tree Editor.

For a first run it is much quicker to point the work and need repository fields at the shipped Demo0.3.0 and Basic repositories and edit those, rather than authoring trees from nothing.

note

Repository fields take a folder name, not an asset reference. The folders live under Assets/BardTreeLtd/Resources/CIVIL-AI-SYSTEM/BehaviourTree/Work/ and /Need/.

If you skip the item collections, some editor tooling — including the Dialogue editors — cannot work correctly.

4. Create a building

Select a scene object that represents a house or workplace and add BuildingService, or use BardTreeLtd/Civil AI/Setup/Templates and Actions to apply a building template to the selected object.

Each building also needs colliders. Missing colliders lead to invalid bounds, bad placement, or agents failing to reach building-related targets.

For a first test:

• create one house
• create one workplace
• ensure the workplace has at least one work role that matches a job in your work behaviour tree

5. Create a population region

Open BardTreeLtd/Civil AI/Setup/Templates and Actions and create a region.

The region needs:

• A character pool — the pool service you created in step 3.
• Spawn settings — how many agents, and how they are placed. This is driven by buildings.
• Buildings in range — at least one house and one workplace, each with an open position, inside the region's bounds.

The region's collider defines those bounds. If the collider is offset from the object's transform, the region uses the collider's actual position, so check the bounds visually rather than assuming they are centred on the object.

6. Set up navigation

Agents need navigation data matching the Nav Mode in Module Settings. The default is UNITY:

1. Install AI Navigation (com.unity.ai.navigation) from Window > Package Manager.
2. Add an empty GameObject and add a NavMeshSurface component.
3. Set Collect Objects to All.
4. Click Bake. A blue overlay should appear over your ground.

Your ground needs a collider, or the bake produces nothing.

Pathfinding covers the A* and Agents Navigation options.

7. Press Play and validate

On the first run, confirm these basics:

• the bootstrap initializes without errors
• agents spawn into the scene
• agents have homes and jobs
• agents move to valid targets
• agents switch between work and need behaviours over time

Recommended reading order after setup

Once the scene is running, read these next:

1. Scene Setup — the minimum ingredients, as a checklist
2. Introduction to Behaviours
3. Work Behaviours
4. Need Behaviours
5. Using the Behaviour Tree Editor
6. Common Issues

If you are using Dialogue as well

Read Dialogue Setup before opening the Dialogue editor.

Dialogue is a separate paid tool that integrates with CIVIL-AI-SYSTEM through shared setup.

The Dialogue editor expects item collections to be available through the shared item catalog, so CivilAI item setup is important even if your immediate goal is conversation content.

Common first-run mistakes

• adding old scene objects from older docs instead of using the bootstrap workflow
• forgetting to assign behaviour repositories in Module Settings
• not creating item collections
• having no valid workplace role for the available work behaviour
• missing nav data for the selected nav mode
• creating regions without valid housing or workplaces in range

Want a concrete example?

If you want a mental model while building your first trees, use these:

• Your First Scene and Example Scenes — complete working scenes you can open, run and pick apart
• Work Behaviours includes a medieval blacksmith job breakdown
• Need Behaviours includes a medieval rest need breakdown

Next step

Continue to Scene Setup for the same ground covered as a checklist you can validate against.