performance-notes.md

Performance Considerations

Key Optimizations

1. Batch Updates: Process agents in parallel batches.
2. SoA Layout: Positions, states, goals stored contiguously for SIMD/cache efficiency.
3. LOD Scaling: Lower frequency updates for distant/non-critical agents.
4. Planner Cache: Avoid recomputation of repeated action sequences.
5. Event Filtering: Only deliver relevant world events to each agent.

MVP Benchmarks

• Target: 500–1000 agents at 60fps on mid-tier PC.
• Goal: planner recalculations < 5% of frame time.
• Action execution batch updates: <1ms per 1000 agents.

Future GPU Offload

• Perception queries, neighbor searches, or large-scale flocking/crowd steering.
• Deferred until after MVP due to complexity.

Profiling Tools

• AgentInspector: live agent states, goals, LOD.
• Heatmaps for active planners, perception, and bottleneck detection.