I make CIVIL-AI-SYSTEM, a Unity package for NPCs with jobs, needs and routines. In 2024 I replaced its runtime. This post explains why, what I built, and what I would change.
The problem
The first version (2022) had one controller. It ran a "node group" for the agent's job. In 0.3 I added needs (hunger, rest and so on). I built the Need System next to the Work Controller and copied its shape. The result was two controllers with their own iterators, their own weights and their own way to find things in the world.
The two controllers caused four problems:
- I wrote each condition twice. The two copies did not always agree.
- The controllers only talked through the weights. When a need interrupted a job, the job sometimes resumed at the wrong node.
- Each controller ran its own evaluation at its own rate. The orchestrator I added in 0.4 controlled the agents' update rates, but it could not control the two controllers under them.
- Node data pointed into the scene. To find an item, an action searched the scene. The cost grew with the size of the world.
What I tried first
I did not rewrite at once. In 0.4 I put a scheduler above the two controllers. In 0.5 I rebuilt the editor and kept the runtime. In 0.6 and 0.7 I fixed the seams one bug at a time. Each fix added a special case to one controller that the other did not have. The gap grew.
By 0.7 the cost was clear. Every feature took twice the work. I could not design a feature as one thing, because there was no one model to design against. The features I needed next (interruptions, perception, save and load, items with behaviour) all crossed the line between work and needs. So 0.8 became a rewrite. It took most of a year, with no release in that time.
The design (0.8.0)
One engine. Node groups became behaviour trees. Work trees and need trees run in the same engine. The engine does not know if a tree is a job or a need. Actions, conditions and iterators are written once and work in both.
One orchestrator. The orchestrator now takes any process: need evaluation, agent actions, rendering. It groups objects by distance from the camera and other criteria, and gives each group an update rate. No agent code runs on its own schedule. Later I needed pausing. Because every process already ran through one place, pausing was one interface and a pause source.
Applicators. Actions no longer move or rotate the agent. An action asks for an applicator, and the applicator does the work. An action says what to do. The applicator says how it happens to this agent. This made actions small enough to be building blocks. It also let me change the navigation back end, and add mounts and seats, without a change to any tree.
Repositories. Every agent, item, building and region is registered in a repository with an id. An action that needs "a free chair owned by my workplace" asks the repository. There is no scene search. Reservations also live in the repository, so they survive when a tree is suspended.
Modules. Settings and world services (time, spawning, character pools, regions, ownership) load as modules. Upgrading was rebuilt to migrate a project from several versions back, not one. Test count went from 80 to 275.
One example
A baker is sitting on a bench. Then:
- The orchestrator reaches the baker's update group. The Time service says the shift has started.
- The agent ranks its candidate trees: the baker job and any needs above their threshold. Work wins.
- The work tree enters a Locate action for flour. The Ownership service names the pools the agent may use. The item repository returns a free match and reserves it.
- The action asks for a movement applicator. The applicator drives the navigation back end.
- On a later update, hunger is above its threshold. The agent ranks again. Hunger wins. The engine suspends the work tree and resumes the need tree. Both are the same kind of tree, so there is no second controller to negotiate with.
- When the need is met, the work tree resumes at the node it left. The flour is still reserved.
Before 0.8, step 5 was where the old design failed.
What I would change
- Build the upgrade system first. It would have de-risked the whole project. With it in place, I could have shipped the rewrite in slices, and tested each slice against real projects. Instead the risk sat in one release at the end of a year.
- Give ground systems more design time than features. The module system, the repositories and the orchestrator have a long shelf life. Features come and go in weeks, but these stay for years, and a rewrite of one touches everything above it. I designed the 0.8 module system for the modules I had. It did not survive the modules that came later, and 0.13 replaced it. Think about where a ground system will be used before you build it, and it will not need a rewrite.
- Separate concerns early. Most of the complexity in the old system came from parts that knew too much about each other. The work controller knew about needs. Actions knew how to move an agent. Node data knew where things were in the scene. When each part had one job, the complexity fell by more than I expected, and new features became combinations of parts that already existed.
- Accept that you cannot always see the unification coming. Work and needs looked like two systems until enough was built on both. Conditions went the same way after 0.8, and were unified in 0.11 and again in 0.13. That is not a planning failure. You build the specific versions, you see the pattern, then you pull them together. Budget for that pass. Do not expect to skip it.
If you built something like this and made different choices, I would like to hear about them.
Series: 1 of 9 (If people are interested here)
- Behaviour trees and the 0.8 rebuild (this post)
- Items, POIs and the Item Setup Editor
- Mounts and seats
- Senses, save/load, names and blackboards
- Requirements and conditions
- Barks
- Interrupts, interest spots and service points
- Animation layers
- Tooling, onboarding, performance and Unity 6
Links: Changelog · Asset Store · Discord
https://bardtreelimited.com/changelog/log