@its-not-rocket-science/ananke 0.1.0 → 0.1.1

package/docs/performance.md

@@ -0,0 +1,233 @@
+# Ananke — Performance & Scalability Report
+
+Generated by `npm run run:benchmark` (Item #9).
+Re-run this tool after breaking changes to detect regressions.
+
+---
+
+## Reference hardware
+
+| Field | Value |
+|-------|-------|
+| CPU | Intel i7-12700 (reference) |
+| Runtime | Node.js 22 LTS |
+| OS | Windows 10 Pro 10.0.19045 |
+| TypeScript | 5.5 compiled to ES2022 modules |
+
+---
+
+## Benchmark results
+
+| Scenario | Entities | Ticks | Median tick | p99 tick | Throughput |
+|----------|----------|-------|-------------|----------|------------|
+| Melee skirmish (open ground) | 10 | 5 000 | 0.190 ms | 0.905 ms | **5.3k ticks/s** |
+| Mixed ranged/melee | 100 | 2 000 | 4.680 ms | 9.758 ms | **214 ticks/s** |
+| Formation combat | 500 | 500 | 31.1 ms | 55.4 ms | **32 ticks/s** |
+| Battle with weather + disease | 1 000 | 200 | 64.5 ms | 126 ms | **16 ticks/s** |
+
+At the default simulation rate (20 Hz / 50 ms per tick):
+
+| Entity count | Tick budget used (median) | Headroom |
+|---|---|---|
+| 10 | 0.4% | 99.6% |
+| 100 | 9.4% | 90.6% |
+| 500 | 62% | 38% |
+| 1 000 | 129% | **over budget** |
+
+At 1 000 entities and 20 Hz, median tick cost (64.5 ms) exceeds the 50 ms budget.
+Reduce update rate to 10 Hz or apply the mitigations below.
+
+---
+
+## Tick-budget breakdown at 500 entities
+
+| Phase | Median cost | % of tick |
+|-------|-------------|-----------|
+| `buildWorldIndex` + `buildSpatialIndex` + `buildAICommands` | 0.29 ms | 1% |
+| `stepWorld` (kernel) | 30.6 ms | 98% |
+| **Total** | **31.1 ms** | **100%** |
+
+**Finding:** kernel physics computation dominates at all entity counts.
+AI command generation is negligible (< 1%) and does not warrant optimisation.
+
+---
+
+## Spatial index comparison at 500 entities
+
+| Cell size | Median tick | Throughput |
+|-----------|-------------|------------|
+| 4 m (optimal for melee) | 35.7 ms | 28 ticks/s |
+| 10 km (naïve O(n²)) | 30.0 ms | 33 ticks/s |
+| Ratio | 1.19× **slower with index** | — |
+
+**Finding:** For a dense close-formation scenario (all entities within ~100 m),
+the `SpatialIndex` cell-map overhead cancels the pair-count reduction.
+Benefit becomes measurable only in sparse large-area engagements where the
+majority of entity pairs never interact.
+
+---
+
+## Memory footprint
+
+Heap delta measured after JIT warmup (figures are approximate due to GC timing):
+
+| Scenario | Heap Δ / entity |
+|---|---|
+| 10 entities, melee | ~256 KB |
+
+Note: JavaScript heap includes GC overhead and JIT artefacts.
+Per-entity allocation in the kernel itself is dominated by the `Entity` object
+(~15 fields, most numeric) — estimated < 2 KB cold per entity.
+
+---
+
+## Tuning guide
+
+### Use smaller entity counts for real-time play
+
+| Use case | Recommended entity cap | Rationale |
+|---|---|---|
+| 1v1 duel | 2–10 | Full resolution, well under budget |
+| Squad skirmish | 10–50 | 20 Hz easily achievable |
+| Battle scene | 50–200 | 20 Hz achievable with mitigations |
+| Army simulation | 200–500 | Reduce to 5–10 Hz |
+| Strategic/campaign | 500–1 000 | Run in downtime mode (1–5 Hz) |
+
+### Mitigations for high entity counts
+
+1. **Reduce tick rate**: At 500 entities, 5 Hz (200 ms tick) gives ample headroom.
+   Physics remain accurate — the simulation is tick-rate agnostic.
+
+2. **Skip AI on distant entities**: Entities beyond engagement range can skip
+   `buildAICommands` entirely; they take no action but still receive kernel effects.
+
+3. **Stagger AI updates**: Update AI for ¼ of entities per tick (round-robin).
+   Full coverage every 4 ticks at 20 Hz = 200 ms AI latency — imperceptible.
+
+4. **SpatialIndex cell size**: For dense close-formation combat (≤ 500 m² area),
+   naïve O(n²) pair scanning matches or beats a 4 m spatial grid.
+   Use 30–50 m cells for ranged-heavy scenarios (engagement range ≥ 30 m).
+
+5. **Skip `ctx.weather`** when weather is not relevant: saves ~2–5% per tick.
+
+6. **Keep `spreadDisease` out of combat ticks**: `spreadDisease` is O(n²) in pairs.
+   Call it once per in-game minute in downtime/campaign simulations, not each tick.
+
+---
+
+## Regenerating this report
+
+```
+npm run build && npm run run:benchmark
+```
+
+Results will vary by hardware. The reference numbers above were measured on
+an Intel i7-12700 running Node 22 LTS under Windows 10.
+
+---
+
+## Operational Guide
+
+> Run `npm run benchmark:guide` to regenerate this table from a live measurement on your
+> hardware.  The numbers below are from the reference configuration (Intel i7-12700,
+> Node 22 LTS, Windows 10).
+
+### Quick-reference: entity cap by tick rate
+
+This table answers "how many entities can I run at tick rate X?" without running benchmarks.
+
+| Entities | 20 Hz (50 ms) | 10 Hz (100 ms) | 5 Hz (200 ms) | 1 Hz (1 000 ms) |
+|----------|:-------------:|:--------------:|:-------------:|:---------------:|
+| 10       | ✅ (0.4%)     | ✅             | ✅            | ✅              |
+| 50       | ✅ (~5%)      | ✅             | ✅            | ✅              |
+| 100      | ✅ (9%)       | ✅             | ✅            | ✅              |
+| 200      | ✅ (~25%)     | ✅             | ✅            | ✅              |
+| 300      | ✅ (~40%)     | ✅             | ✅            | ✅              |
+| 500      | ⚠️ (62%)     | ✅             | ✅            | ✅              |
+| 750      | ⚠️ (~95%)    | ✅             | ✅            | ✅              |
+| 1 000    | ❌ (129%)     | ⚠️ (65%)      | ✅            | ✅              |
+| 2 000    | ❌            | ❌             | ⚠️ (~65%)    | ✅              |
+| 5 000    | ❌            | ❌             | ❌            | ⚠️ (~65%)      |
+
+**Legend:** ✅ = comfortably within budget  ⚠️ = p99 may spike above budget under load  ❌ = over budget
+
+### Recommended tick rate by scenario class
+
+| Scenario class | Typical entity count | Recommended tick rate | Notes |
+|----------------|---------------------|-----------------------|-------|
+| 1v1 duel / tactical combat | 2–20 | **20 Hz** | Full physics resolution; headroom > 90% |
+| Squad skirmish | 20–100 | **20 Hz** | Safe on any modern CPU |
+| Battle scene (real-time) | 100–500 | **20 Hz** (or 10 Hz if p99 spikes) | Monitor p99; enable AI staggering |
+| Large battle / RTS simulation | 500–1 000 | **10 Hz** | Reduces tick budget to ~65% at 1k entities |
+| Campaign / world-simulation | 1 000–5 000 | **1 Hz** | One tick per in-game second; plenty of headroom |
+| Downtime / recovery simulation | any | **0.01–0.1 Hz** | Sleeping, disease, aging — not real-time |
+
+### Supported real-time envelope
+
+What Ananke guarantees on the reference hardware at 20 Hz (50 ms tick budget):
+
+| Guarantee | Value |
+|-----------|-------|
+| **Maximum entity count within median budget** | 500 entities |
+| **Maximum entity count within p99 budget** | ~350 entities |
+| **Median tick at 500 entities** | 31 ms (62% of budget) |
+| **p99 tick at 500 entities** | 55 ms (110% — occasional overrun) |
+| **Median tick at 100 entities** | 4.7 ms (9% of budget) |
+| **Minimum entity count for budget to matter** | > 200 entities |
+
+For reliable real-time at 20 Hz, stay under **300 entities** to keep p99 inside the 50 ms budget.
+At 500 entities, median is fine but occasional p99 spikes exceed the budget by ~10%.
+
+### Subsystem feature-toggle guidance
+
+Each optional subsystem adds per-tick cost when entities carry the corresponding
+`@subsystem` field.  Costs below are rough estimates at 500 entities.
+
+| Subsystem | `Entity` field | Tick cost (500 entities) | Toggle guidance |
+|-----------|----------------|--------------------------|-----------------|
+| AI command generation | `ai?` | < 1% (negligible) | Always safe; stagger updates to save CPU |
+| Ablative armour | `armourState?` | < 1% | Negligible; enable freely |
+| Weather modifiers | `ctx.weather` | ~2–5% | Omit when weather is irrelevant |
+| Disease spread | `activeDiseases?` / `spreadDisease()` | O(n²) in pairs | **Call once per in-game minute**, not each tick |
+| Thermoregulation | `physiology?` | < 2% | Negligible at combat scale |
+| Sleep deprivation | `sleep?` | < 1% | Downtime only; safe in combat ticks |
+| Aging | `age?` | < 1% | Downtime only; negligible in combat ticks |
+| Mounted combat | `mount?` | < 1% | Negligible |
+| Extended senses | `extendedSenses?` | < 1% | Negligible |
+| Capability / magic | `capabilitySources?` | 1–3% depending on active effects | Profile if many entities have active auras |
+
+**Rule of thumb:** subsystems add < 1–3% each at combat scale.  The dominant cost at all entity
+counts is the kernel physics computation (`stepWorld`), not subsystems.  Removing subsystems
+rarely buys more than 5–10% at high entity counts.
+
+### Spatial-index guidance
+
+| Scenario | Recommended setting | Rationale |
+|----------|---------------------|-----------|
+| Dense close-formation (≤ 500 m² area, melee-only) | **No spatial index** (cell size = arena) | Cell-map overhead cancels pair-count reduction |
+| Mixed melee + ranged (engagement range ≥ 10 m) | **4–10 m cell size** | Filters most non-interacting pairs |
+| Sparse open-field (engagement range ≥ 30 m) | **30–50 m cell size** | Large benefit; most pairs never interact |
+| Large-scale simulation (> 500 entities, spread over km) | **50–200 m cell size** | Essential; naïve O(n²) is prohibitive |
+
+For dense formations (all entities within ~100 m), the overhead of building and querying the
+spatial index exceeds its benefit.  At 500 entities in a 100 m² arena, naïve scanning is
+1.19× faster than a 4 m cell grid (see benchmark data above).
+
+### Choosing a tick rate
+
+Use this decision tree:
+
+1. Is the simulation **interactive / real-time**?
+   - **Yes** → start at 20 Hz; profile at your target entity count; step down to 10 Hz if p99 > 50 ms.
+   - **No (campaign / downtime)** → use 1 Hz or lower; entity count is rarely the bottleneck.
+
+2. Do you have **> 300 entities**?
+   - **No** → 20 Hz is safe; no further tuning needed.
+   - **Yes** → enable AI staggering (update ¼ of entities per tick); consider 10 Hz if still over budget.
+
+3. Are entities **spread across > 1 km**?
+   - **No** → omit spatial index or use large cells.
+   - **Yes** → use a 50–200 m spatial grid.
+
+4. Do you use `spreadDisease`?
+   - **Yes** → call it once per in-game minute, not each tick (it is O(n²)).