Skip to main content

Getting Started

If you are new to the tool, start here.

This guide is designed to get you from an empty scene to a working medieval town setup as quickly as possible. It focuses on the 0.12.x workflow built around ModuleService and Module Settings.

What you will achieve​

By the end of this guide you should have:

  • the runtime module service in your scene
  • module settings created and configured
  • at least one work behaviour and one need behaviour
  • a building in the scene
  • a population region in the scene
  • item collections and character pool data assigned
  • 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
  • baking or generating navigation for your chosen nav setup

The shortest path to first success​

Follow these steps in order.

1. Add the runtime object​

Create an empty GameObject in your scene and add ModuleService.

This is the main 0.12.x runtime entry point. It loads module settings, creates the core services, sets up repositories, and starts the simulation.

2. Open Module Settings​

Open CIVIL-AI-SYSTEM -> Module Settings.

If no settings assets exist yet, let the tool create the defaults. This menu is the main control panel for nav mode, time, behaviour repositories, character pools, and item collections.

3. Create your core data assets​

Before agents can do anything useful, create or assign:

  • a work behaviour tree
  • a need behaviour tree if the need system is enabled
  • an item name collection
  • an item type collection
  • an item size collection
  • a character pool service with at least one valid character entry

If you skip the item collections, parts of the editor tooling and inspector workflows become much harder to use.

4. Create a building​

Select a scene object that represents a house or workplace and add BuildingService, or use CIVIL-AI-SYSTEM -> Template and Actions to apply a building template to the selected object.

The building template tool also creates a basic trigger collider and an entrance child object. If you set buildings up manually, make sure they still have valid colliders and a sensible entrance position.

For a first test:

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

5. Create a population region​

Open CIVIL-AI-SYSTEM -> Template and Actions and create a region.

Then configure the region so it can use:

  • your character pool
  • valid housing in the scene
  • valid workplaces and roles in the scene
  • region colliders that define where the population area exists

6. Set up navigation​

Agents need a working navigation solution before most actions will complete correctly.

Check the nav mode in Module Settings, then make sure the scene has matching navigation data.

If agents spawn but never complete actions, navigation is one of the first things to verify.

7. Press Play and validate​

On the first run, confirm these basics:

  • the module service 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

Once the scene is running, read these next:

  1. Scene Setup
  2. Introduction to Behaviours
  3. Work Behaviours
  4. Need Behaviours
  5. Using the Behaviour Tree Editor
  6. Common Issues

Common first-run mistakes​

  • forgetting to add ModuleService to the scene
  • forgetting to assign behaviour repositories in Module Settings
  • not creating item collections
  • having no valid workplace role for the available work behaviour
  • missing colliders on buildings or region shapes
  • missing nav data for the selected nav mode
  • creating regions without valid housing or workplaces in range
Last updated on