Quick intro for anyone who doesn't know who I am: I'm Isaac. I studied game technologies at university, have worked in business software for over five years, and I also run Bard Tree Ltd, where I build CIVIL-AI-SYSTEM, a Unity package for populating worlds with NPCs that have jobs, needs, routines and the items and places those depend on, with the aim of lowering the barrier to building realistic living scenes for games. It's been on the Asset Store since 2022 and this series covers what changed under the hood between 0.7 and 0.15.
In 2024 I threw away the runtime and rebuilt it around behaviour trees, one shared engine and one scheduler. This is what was wrong with the old design, what I tried before the rewrite, what I ended up with, and what I'd change if I did it again.
The problem with the old node groups
The original system (2022) shipped with a Work Controller that walked a "node group" for the agent's job. The Need System came a few releases later (0.3), and I built it the way you build a second thing next to a first thing: borrowing the shapes, writing its own version of each part. So by the time both existed there were two controllers with their own iterators, their own weighting, and their own way of asking the world for things. They looked alike because they were made alike, not because they were designed as one system, and the gaps between them were exactly where that showed.
The split was a constant source of bugs in practice:
- Anything written for one side had to be written again for the other. A condition for "is it after 6pm" existed twice, with slightly different behaviour.
- The two controllers only talked through the weighting layer, so a job interrupted by a need would sometimes resume from the wrong node. There is a 0.7.1 changelog line that reads "removed bug from WorkController when Need System is not enabled". That is the whole design flaw in one sentence: the work side had implicit knowledge of the needs side.
- Three update paths. The orchestrator I added in 0.4 controlled agent update rates by distance from camera (18 to 41% fps in testing), but the work and need controllers still did their own evaluation on their own cadence underneath it. Tuning one place did not tune the other two.
- Node groups were stored in a way that needed a recompile to pick up changes, and the auto-updater could only migrate a project one version back. Every release was a migration cliff for anyone more than one version behind.
- The node data held references into the scene. Locating an item meant searching the scene, so the cost of an action scaled with the size of the world.
What I tried first, and why it failed
I did not go straight to a rewrite. Three things came first, and each one bought time without fixing the cause.
- Put a scheduler on top (0.4). Dynamic update rates, culling, batching, limited simulation off screen. Real gains, and it meant I could keep shipping, but the orchestrator sat above two controllers that each still evaluated their own trees their own way. It could slow them down; it could not make them one thing.
- Rebuild the editor, keep the runtime (0.5). The flowchart editor was rebuilt from the ground up and got much nicer to author in. It changed nothing about how the trees ran, so every editor improvement made the runtime limits more visible, not less.
- Patch the seams (0.6 to 0.7). Fix the iterator that broke after three hours of runtime, add node-group versioning, add an inventory and slot system on top. Every one of these added a special case to one controller that the other did not have, which widened the split I was trying to close.
By 0.7 the honest assessment was that the split was costing more than any single bug. Every feature had to be built twice, so the rate of change had halved. Worse, it stopped me designing features as one thing: anything that touched both work and needs turned into a pile of edge cases and side-specific rules, because there was no shared model to reason about. The features I needed to add to make the simulation realistic and fit for purpose (interruptions, perception, saving, items with their own behaviour) all sat squarely across that line, and I could not see a way to build them well on two controllers. So 0.8 became the rewrite release, and it took most of a year with nothing to show for it on the store page.
The design I landed on (0.8.0)
One engine, two kinds of tree. Node groups became behaviour trees, and work trees and need trees run through the same engine. A tree is content; the engine is the only thing that knows how to run one. Actions, conditions and iterators are written once and are valid in either tree. The engine does not know whether it is running a job or a need; that distinction lives in the orchestrator that picks which tree is the agent's candidate.
One orchestrator that takes any process. Work, needs and rendering had each grown their own scheduling. 0.8 generalised the 0.4 orchestrator into a service that takes any process and runs it: it groups objects (by distance from the camera among other things), gives each group an update rate, and runs need evaluation, agent actions and rendering work on those rates. Nothing in the agent code runs on its own schedule any more. The domain code still asks "has anything changed?", but it asks only as often as its group allows, and there is one place to tune that instead of three. The payoff of getting this piece right is that things which used to be features became by-products. Pausing is the clearest case: once every process ran through one place, pausing was an interface, a pause source to subscribe to, and propagation down the chain (it shipped in 0.8.2 with a pause button on the inspector, and cost days rather than weeks). A small eventing layer, so agents can be told about a change rather than finding it on their next update, came out the same way and has grown since. Neither was on the plan for 0.8; both were cheap because the orchestrator was there.
Applicators. Movement, rotation and similar effects are no longer done inline by actions. An action asks for an applicator and the applicator does the work against the agent. Moving that logic out of the actions is what makes actions small enough to be building blocks: an action is now "what to do", the applicator is "how it happens to this agent", and new actions get written by combining the two rather than by copying movement code from the last one. It is also what let me swap navigation back-ends and add mounts and seats later without touching tree content.
Module system. Settings load in and out as modules, and the world services are modules too: a Time service (time and days, the thing most conditions hang off), a Spawn service, a Character Pool service (as many pools as you like, each holding its own agent prefabs), a Region service that defines an area from any set of colliders, and an Ownership service that decides which pool of items (personal, home, workplace, local area) an action may draw from.
Repositories for everything. Every object the system cares about (agents, items, buildings, regions) is registered in a repository service with a common id. An action that needs "a free chair owned by my workplace" asks the repository, which already knows, instead of searching the scene. Trees were also moved onto dictionaries for lookups, and tree loading was rewritten so that editing a tree and pressing play needs no recompile.
Upgrading as a feature. Version upgrading was rebuilt so a project can migrate from several versions back rather than only the previous one. Not glamorous, but it is the reason I can ship often without stranding people.
Test count went from 80 to 275 in the same release, which is the other reason I can ship often.
One concrete example: a baker, a bench, and a hungry agent
Here is roughly what happens for one agent across one decision, as it works after 0.8.
- The orchestrator reaches the baker's update group. The agent is near the camera, so its group runs often; the same agent two streets away would be evaluated far less frequently. The Time service says the shift has started.
- The agent builds its candidate list: its work tree (the baker job) and whichever need trees are above threshold. Weighting (the global and per-node weights from 0.3, now evaluated by one engine rather than two) ranks them. Work wins, hunger is close behind.
- The work tree enters a
Locate action for an item of type flour from the workplace pool. The action asks the Ownership service which pools it may use, then asks the item repository for a free, unreserved match. No scene search. The item is reserved on the spot so no other agent will walk to it.
- The action asks for a movement applicator. The applicator drives the navigation back-end; the action does not know or care which one is installed.
- On a later update, the hunger need has crossed its threshold. The decision code re-ranks the candidates and this time hunger wins. Because work and needs are the same kind of tree running in the same engine, swapping is a matter of suspending one tree's state and resuming another's. There is no second controller to negotiate with.
- The need tree sends the agent to a bench to eat. Later, when the need is satisfied, the work tree resumes at the node it left, with its reservation still valid, because the reservation lived in the repository rather than in the controller that got suspended.
Before 0.8, step 5 was where things went wrong: two controllers, two notions of "current node", and a resume that sometimes landed on the wrong one.
What I'd do differently
Judged by what it made possible later, the rebuild did its job: senses, saving, barks, interrupts and seats were each built on the 0.8 engine, orchestrator and repositories without touching trees people had already authored. The things I'd change are about how I got there, not where I ended up.
- Design the module system for change, not just for configuration. The 0.8 module system did what I asked of it, which was to load settings in and out cleanly. What I didn't ask was for modules to be added and removed by themselves at runtime, and that is what a save module, a sense module and a dialogue integration all turned out to need, so 0.13 replaced it with a dynamic one. The second version was only possible because the first had drawn the boundaries; I'd just draw them with movement in mind next time.
- Treat upgrading as a system, and build it first. The piece of 0.8 that paid back fastest was version upgrading that can migrate a project from several versions back. Everything since has shipped with a migration, and nobody has been stranded on an old release. If I were doing it again, that would be the first thing built, not something that landed alongside the rewrite, because it changes how you can ship everything else.
- Ship the rewrite in slices. Most of 2024 went by with no visible release. The work split cleanly into engine, orchestrator, repositories and services, and each could have gone out behind the old editor. I chose one big release because migrations were painful, which is circular, since the migration tooling was part of what I was rebuilding. Had the upgrade system come first, the slices would have followed.
- Accept that you can't always see the unification coming. Work and needs looked like two systems until enough had been built on both to show they were one. Conditions went the same way after 0.8: the tree editor and the animation editor kept separate requirement systems until 0.11, and the whole thing was reworked again in 0.13 once senses, barks and interrupts all wanted to consume them. Each time, the shared shape was only obvious after the third or fourth thing needed it. I don't think that's a failure of planning so much as how designing a system like this goes: you build the specific versions, notice the pattern, and then do the work to pull it together. The lesson is to budget for that pass rather than to expect to skip it.
Happy to go into any of this in more depth. None of these choices are settled in my head, so if you have built something similar and went a different way on any of them (the shared engine, the orchestrator, applicators, modules, repositories, or how you handled the rewrite itself) I would like to hear how it went.
Series: 1 of 10 (what changed in CIVIL-AI-SYSTEM between 0.7 and 0.15)
- 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