Eve library

maya-sim-lod — simulation LOD & AI budget (tuning guide)

Other

Revision 1

On this page

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#

  1. Re-tier every NPC with update_tier(current, distance, is_quest) — hysteresis (promote < demote distance) stops boundary flicker; quest NPCs are pinned to Full.
  2. Promote/demote: a newly-Full NPC gets a generate_alibi(schedule, hour) position + activity so it appears to have been living its life; a demoted one calls record_state(...) so abstract sim resumes without a jump.
  3. 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.
  4. Schedule within budget: schedule_frame(candidates, BudgetManager) sorts by priority_score(distance, attention, importance) and spends the budget (default 8 ms) on the most relevant NPCs first.

Tuning#

  • Budget: raise BudgetManager::budget_ms on stronger hardware to keep more NPCs at Full; lower it to protect frame time.
  • Tier bands: widen the Full band (in tier.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 importance weight 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.