docs: add ultraplan performance-overhaul prompt

[J3vb]

What

Adds PERFORMANCE_PLAN_PROMPT.md — a paste-ready planning brief to feed into ultraplan to get the best possible performance-upgrade plan for the game.

This is documentation only; no game code changes.

How it was produced

The prompt is grounded in a full, evidence-based performance audit of the codebase (parallel deep-reads across every dimension that matters for a browser 3D game). Every hotspot in the brief cites a concrete file:line, so the planner starts from facts rather than guesses. Dimensions covered:

• Render pipeline — moon shadow re-rendering the whole scene every other frame; frustumCulled = false forced everywhere (defeats culling on beauty and shadow passes); no LOD; GTAO+Bloom+SMAA every frame.
• Per-frame CPU — Math.hypot in the inner collision loop; per-frame scratch-array / {x,z} literal / [...monsters] allocations feeding a GC drip.
• Entity/AI scaling — no spatial partitioning: O(P×M) projectile→monster collision, homing re-scans, O(M²) death-nova on wipes; the recommended keystone fix is one uniform monster grid threaded through every proximity query.
• Assets & GPU memory — KTX2 Basis transcoder still fetched from unpkg at runtime; entire ~27 MB roster (incl. all bosses) eagerly loaded and never evicted; never-evicting zone caches.
• DOM/HUD — full-canvas minimap repaint and per-monster float projection every tick; querySelectorAll('.cd') ~15×/sec.
• World/zone build — dead ground vertex-color bake at load; full ground-vertex rewrite on every town↔combat transition; cullLights scanning an ever-growing light registry.
• Boot/load — no modulepreload for the ~687 KB-gz renderer; un-yielded synchronous boot block; autosave synchronously stringifying all three save slots + blocking localStorage.setItem on a timer.

What the prompt instructs

• Measure first: promote the existing dev-only perf harness into an always-available overlay and record a baseline before any change.
• Deliver a prioritized, phased plan (quick wins → structural CPU → GPU budget → assets/memory/boot), each item with problem / fix / expected gain / risk / verification.
• Respect the hard constraints: no build step, ordered classic scripts, don't break localStorage saves, keep WebGPU-first + WebGL2 fallback, keep npm run check green, no gameplay/balance drift.
• Propose explicit acceptance targets (steady 60 fps mid-combat, bounded memory across zone transitions, a boot/TTI target) and ship as small, revertible PRs.

🤖 Generated with Claude Code

https://claude.ai/code/session_01FDUgow6KbNRbJRZgCyACi9

---

Generated by Claude Code