Common Issues

Use this page as a fast diagnosis checklist when the simulation is not behaving as expected.

Agents do not move

Check these first:

• the scene has navigation data that matches the selected nav mode
• the target point is reachable
• the action target is placed close enough to the ground
• the agent is not blocked by invalid collision or world geometry

If the target point is too high or slightly unreachable, the agent may never satisfy the completion condition.

Agents spawn but do nothing

Common causes:

• the current time does not allow the available job to start
• need weightings are too low to trigger behaviour
• no usable action targets exist in the scene

Also check colliders in the places the simulation depends on them:

• buildings need colliders so their bounds and related interaction setup are valid
• population region areas need colliders so the world space is defined correctly
• scene items and targets may need colliders when your setup expects physical reachability or trigger-based interaction

Fewer agents spawn than expected

Check:

• not enough houses
• not enough workplace roles
• region setup not matching available world content
• buildings missing valid colliders or usable bounds
• character pool entries failing requirements

Population usually collapses to the smallest valid resource pool.

An item exists but agents cannot use it

Common reasons:

• ownership rules do not allow access
• the item is not in the expected location or room context
• the action is looking for a different type, size, or name than the item provides
• the required slot or point of interest is missing

The Dialogue editor shows a warning instead of the graph

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

Check that your item collections are configured.

The Dialogue tooling expects the shared item catalog to provide:

• item names
• item types
• item sizes

If those are missing, set them in CIVIL-AI-SYSTEM -> Module Settings first.

Work behaviour never starts

Check:

• the workplace has a valid role
• the role matches your work content
• job timings allow the work to begin
• the agent has a valid workplace assignment

Need behaviour never takes over

Check:

• the need exists and is assigned correctly
• the weighting curve makes the need urgent enough
• at least one fulfillment method is available in the current scene

Best debugging order

When in doubt, inspect the setup in this order:

1. bootstrap present
2. module settings valid
3. behaviour trees assigned
4. item collections assigned
5. buildings and region valid
6. navigation working
7. scene targets reachable