Performance Intro

Simulating a town means running a lot of agents at once. The tool keeps that affordable by doing less work for agents the player is not looking at, rather than by doing less work overall.

All of the settings on this page live in BardTreeLtd/Civil AI/Module Settings.

The two mechanisms

Distance banding. Agents are grouped into bands by their distance from the camera. Nearer bands update every tick; further bands update less often, and beyond a chosen band agents stop being rendered entirely. This is the main lever.

Tick rates. Separate rates control how often each subsystem runs — behaviour, needs, culling and the grouping calculation itself. Slowing a subsystem down affects every agent equally, regardless of distance.

Reach for banding first. It reduces cost where the player cannot tell, whereas lowering tick rates is visible everywhere.

Settings reference

Batching and tick rates

Setting	What it does	Default
maxBatchSize	How many agents are processed per batch	150
tickRate	How often agent behaviour is evaluated	1
needSystemTickRate	How often needs are evaluated	5
cullingTickRate	How often culling is reconsidered	10
groupingTickRate	How often agents are re-sorted into bands	1000

Higher tick-rate values mean the subsystem runs less often. Needs change slowly, so 5 is comfortable; regrouping is expensive and rarely urgent, which is why groupingTickRate is far higher.

Distance banding

Setting	What it does	Default
npcGroupingDistance	The distance threshold for each band, as a list	[100]
npcBandUpdateInterval	How often each band updates, one entry per band	2 entries
npcCullFromBand	The band from which agents stop being rendered	1
groupingMoveThreshold	How far an agent must move before its band is reconsidered	2

npcGroupingDistance is a list of Distance < X thresholds shown as a grid in Module Settings. Each row is one band. An agent falls into the first band whose threshold it is inside; anything beyond the last threshold falls into an implicit final band.

The default of a single 100 entry therefore gives you two bands: everything within 100 units, and everything beyond it. With npcCullFromBand set to 1, that second band is not rendered.

note

This changed in 0.13.0. The previous default was two thresholds (500 and 0) with culling from band 3. If you are upgrading and had not tuned these, your effective draw distance will change.

Where to start tuning

1. Confirm banding is doing something. Put the camera in a busy area and watch whether distant agents stop rendering. If not, npcCullFromBand is probably higher than your band count.
2. Set the cull distance to match your camera. The last threshold in npcGroupingDistance should be roughly the furthest a player can meaningfully see an agent.
3. Add a middle band if you have a wide view distance — one near band at full rate, one middle band updating less often, then culled.
4. Only then touch tick rates. needSystemTickRate is the safest to raise; tickRate is the most visible.

FpsTracker can be added to a scene to watch the effect of a change while playing.

Next step

Rendering Groups covers banding in more detail.