Rendering Groups

Rendering groups — also called bands — are how the system spends its budget where the player is looking. Read Performance Intro first if you have not.

How agents are banded

Every agent belongs to exactly one band, decided by its distance from the camera.

npcGroupingDistance in BardTreeLtd/Civil AI/Module Settings is the list of thresholds. The settings window shows it as a grid with the columns Group Id and Distance < X. An agent joins the first band whose threshold it is inside.

There is always one more band than there are thresholds, because everything past the last threshold falls into an implicit final band.

With the default single threshold of 100:

Band	Contains
0	Agents closer than 100 units
1	Everything further away

Adding a second threshold of 250 would give three bands: under 100, 100 to 250, and beyond 250.

What a band controls

Update frequency. npcBandUpdateInterval holds one entry per band. A higher number means that band's agents are updated less often. Band 0 should normally be the most frequent.

Whether agents render at all. npcCullFromBand names the first band that stops rendering. At the default of 1, band 0 renders and band 1 onward does not.

Culled agents are still simulated — they keep working, moving and satisfying needs. They are simply not drawn. This is why a town still behaves consistently when the player returns to it.

note

Set npcCullFromBand higher than your highest band index to disable culling entirely. With one threshold you have bands 0 and 1, so a value of 2 renders everything.

Regrouping

Recalculating every agent's band every frame would cost more than it saves, so two settings throttle it:

• groupingTickRate (default 1000) — how often the grouping pass runs at all.
• groupingMoveThreshold (default 2) — how far an agent must have moved before its band is reconsidered.

The move threshold matters most for agents hovering near a boundary. Without it, an agent standing at exactly 100 units would flicker between bands, and its renderer would flicker with it.

Choosing your bands

Start from your camera rather than from the numbers.

1. Find your real view distance. Stand where the player normally stands and note the distance at which an agent stops being distinguishable. That is your cull threshold.
2. Use one band if that distance is short. A single threshold at your cull distance is often enough for a tight third-person camera.
3. Add a middle band for wide cameras. A strategy or high-angle camera benefits from near / mid / far: full rate up close, reduced in the middle, culled beyond.
4. Match the interval list to the band count. npcBandUpdateInterval needs one entry per band.

Add FpsTracker to a scene to watch the effect while playing, and test in a build rather than the editor — editor overhead hides the difference.

Common problems

Symptom	Cause
Agents pop in and out at a fixed distance	groupingMoveThreshold too low, or a band boundary sitting exactly where players stand
Distant agents still render	npcCullFromBand is higher than your band count
Distant agents freeze rather than just disappearing	That is a tick rate, not a band — check npcBandUpdateInterval for that band
No visible difference from changing bands	Regrouping has not run yet; groupingTickRate defaults to a high value

warning

0.13.0 changed these defaults from two thresholds (500, 0) culling from band 3, to a single threshold of 100 culling from band 1. If you upgraded without tuning them, your draw distance is now considerably shorter.

Next step

Back to Performance Intro, or Common Issues if agents are behaving oddly at distance.