The scheduling layer above every NPC system (needs, emotion, memory, social, justice, …). It keeps thousands of NPCs "alive" within a fixed per-frame CPU budget by simulating each at a distance-appropriate level of detail (phase 79.32).
The four tiers#
| Tier | Distance | What runs | ~Cost/NPC |
|---|---|---|---|
Full |
0–30 m | needs, emotion, memory, pathfinding, perception | 0.1 ms |
Simplified |
30–100 m | needs decay, waypoint following, simplified anim | 0.01 ms |
Abstract |
100 m–1 km | schedule-driven zone transitions, periodic tick | 0.001 ms |
Statistical |
1 km+ | population counts, birth/death/migration | ~0 |
How it fits together each frame#
- Re-tier every NPC with
update_tier(current, distance, is_quest)— hysteresis (promote < demote distance) stops boundary flicker; quest NPCs are pinned toFull. - Promote/demote: a newly-
FullNPC gets agenerate_alibi(schedule, hour)position + activity so it appears to have been living its life; a demoted one callsrecord_state(...)so abstract sim resumes without a jump. - Filter by temporal distribution:
is_due_staggered(tier, frame, id)— Full every frame, Simplified every 4th, Abstract every 60th, Statistical every 600th, staggered by id so they don't all tick together. - Schedule within budget:
schedule_frame(candidates, BudgetManager)sorts bypriority_score(distance, attention, importance)and spends the budget (default 8 ms) on the most relevant NPCs first.
Tuning#
- Budget: raise
BudgetManager::budget_mson stronger hardware to keep more NPCs atFull; lower it to protect frame time. - Tier bands: widen the
Fullband (intier.rs) for denser foreground life at higher cost; widen the hysteresis gap if NPCs still flicker near boundaries. - Temporal periods: increase the Abstract/Statistical periods (in
budget.rs) to shave background cost at the price of coarser off-screen simulation. - Priority weights: bump the
importanceweight so narrative NPCs win budget contention even at distance.
The stress integration test simulates 10,000 NPCs across 60 frames and asserts
no frame exceeds the budget — run it after changing any of the constants above.