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

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.
