Laby/docs/06_Refactoring_Game.md

06 – Refactoring & Performance (Advisory für Aegis-Labyrinth.html)

Advisory-Dokumentation – Empfehlungen, Aegis-Labyrinth.html (~707 KB, Single-File-Game) sauberer, schneller und wartbarer zu machen, ohne das sichtbare Spielverhalten zu ändern.

⚠️ Diese Datei gehört nicht zur Test-Suite selbst – sie ist ein Beratungs-Backlog für die extern eingelegte Game-Datei. Die Suite (tests/*) prüft nur, dass Änderungen daran die 3 Audits nicht brechen (→ 02_Audits.md) und die Performance nicht einbricht (→ 04_Resultate_Report.md).

---

1. Ist-Zustand (kurz)

Aspekt	Status
Struktur	Eine HTML-Datei: CSS + ~4.500 Zeilen JS + UI
Rendering	Canvas 2D, requestAnimationFrame-Loop, Partikel-/Projectile-Arrays
State	Globale Game-Objekte + freie Funktionen im Global Scope
Persistenz	localStorage (Skilltree, Audio, Unlocks, Custom Levels)
Debug	window.__AEGIS_DEBUG__ (Audits, State, Audio, Levels) → 01_Debug_API.md
Tests	3 eingebauten Audits + externe Suite (tests/)
Bundle	Base64-PNG-Logo (ca. 350 KB) inline – bereits optimiert

---

2. Priorisierte Maßnahmen (P0 = mach heute, P2 = Backlog)

P0 – Hohe Wirkung, geringes Risiko

#	Maßnahme	Wo	Erwarteter Effekt
1	Partikel-/Projectile-Pooling statt push/filter pro Frame	updateProjectiles, updateEnemies, Partikel-Arrays	−30–50 % GC-Pressure
2	Spatial Hash (Grid 32 px) für towerFire-Zielwahl (heute O(N·M) alle Paare)	towerFire(t,dt)	−50–80 % CPU bei 50+ Türmen
3	Canvas-Layer-Trennung: bgCanvas, midCanvas, fxCanvas + ctx.imageSmoothingEnabled=false	render()	Weniger Re-Draws, stabilerer 60 fps
4	Offscreen-Canvas für statische Route (1× pro Level zeichnen, dann drawImage)	Route-Drawing	−10–20 % Framezeit
5	Delta-Clamp: dt = Math.min(dt, 1/30) am Loop-Start	Game-Loop	Keine Explosionen nach Tab-Wechsel
6	willReadFrequently:true nur bei getImageData-Puffern, desynchronized:true bei FX-Canvas	Canvas-Kontexte	Geringere GPU-Roundtrips
7	Event-Debounce auf mousemove (Tooltip) & resize	HUD/Tooltip	Weniger Layout-Thrashing

P1 – Mittlere Wirkung

#	Maßnahme
8	Modularisierung in IIFE/Module: core/loop, core/state, units/tower, units/enemy, systems/pathflow, systems/aura, systems/skills, ui/*, audio, persistence, debug
9	State-Reduktion: Game-Objekt durch store-Muster mit subscribe/get ersetzen (~60 Zeilen)
10	Pure-Function-Tests für Pfadlogik: flowField, diagnoseRouteState, computePath extrahieren → unit-testbar
11	Konstanten-Block (CELL, MAP_W, NANITE_LIMIT, PARTICLE_MAX, …) in constants
12	Magic-Number-Audit: 1/60, 0.05, 180 etc. in Konstanten umbenennen
13	Symbol()-Keys für interne Game.towers[i]._internal* statt String-Props

P2 – Backlog

#	Maßnahme
14	Web Worker für Flow-Field-Berechnung bei großen Maps
15	WebGL2-Option (<canvas>-Fallback bleibt) für Partikel > 5.000
16	requestIdleCallback für UI-Rebuilds (Tower-Panel, Skilltree)
17	Code-Splitting via import() hinter „Menu"
18	Intl.NumberFormat für Zahlen im HUD
19	i18n-Datei (DE/EN) statt inline-Strings
20	PWA-Shell (manifest.json, sw.js) für Offline

---

3. Rendering-Optimierung (Details)

3.1 Frame-Pipeline (empfohlen)

[1] input       → pointer events, key state
[2] update(dt)  → enemies → towers → projectiles → nanites → particles
[3] dirty check → bgDirty / midDirty / fxDirty  (Boolean pro Layer)
[4] render()    → if bgDirty: drawImage(bgCanvas);
                  if midDirty: draw towers+enemies;
                  fxCanvas always (additive)

3.2 Konkrete Canvas-Techniken

const fx = document.createElement('canvas');
const fctx = fx.getContext('2d', { alpha: true, desynchronized: true });
fctx.globalCompositeOperation = 'lighter';   // Partikel additiv
// pro Frame:
fctx.clearRect(0, 0, fx.width, fx.height);   // oder 'destination-out' Fade für Trails

• Batching: Alle Partikel gleicher Farbe in einen beginPath() → eine fill().
• roundRect nativ (Chrome 99+) statt Hand-Rotation.
• createPattern für Tile-Boden (1× erzeugen).
• Sprite-Atlas für die 9 Türme: 1 Atlas 512×512, drawImage(atlas, sx,sy,sw,sh, x,y,w,h).

3.3 Zielwerte

Metrik	Vorher (Messung in DevTools)	Nachher (Ziel)
Framezeit @ 4K, 80 Türme, 150 Feinde	18–24 ms	≤ 12 ms
GC-Pausen/Minute	~12	≤ 4
Heap-Wachstum (10 Min)	~40 MB	≤ 10 MB

---

4. Refactoring-Checkliste (Definition of Done)

• Alle drei Audits (self, extension, redesign) vor & nach Refactoring grün
• window.__AEGIS_DEBUG__.getState() liefert identisches Schema (nur interne Keys dürfen sich ändern)
• Kein sichtbarer Frame-Drop bei 60 fps Test-Level
• localStorage-Schema unverändert (oder Migration in persistence.js)
• Editor-Map & Custom-Level import/export byte-identisch
• Lighthouse-Performance ≥ 95 (mobile emulation)

---

5. Vorschlag: Refactoring in 3 Sprints

Sprint	Inhalt	Aufwand
S1 (Tag 1–2)	P0 1–7 (Pooling, Spatial Hash, Layer-Cache, dt-Clamp)	~6 h
S2 (Tag 3–4)	P1 8–11 (Modularisierung + Konstanten + Store)	~8 h
S3 (Tag 5)	P1 12–13 + P2 14 (Worker) + Lighthouse-Polish	~5 h

Regressionsschutz: Vor jedem Sprint einen „Golden Frame" (Screenshot + getState()-Dump) mit der Test-Suite erzeugen (tests/audit.mjs + tests/perf-test.mjs, siehe 03_Automatisierung_CI.md).