# Scope: FreeExile Modern ARPG UX/UI, Character Animation, PoE2 Skill VFX & Asset Catalog Overhaul

## Architecture
- **UX/UI & Controls Layer**:
  - `hud_orbs.js` (`client/webapp/js/ui/hud_orbs.js`): Dual Fluid Orbs (Health/Blood & Mana/Qi) with sinusoidal wave crests, specular highlights, level fills, and low-HP crimson pulse.
  - `skill_bar_controller.js` (`client/webapp/js/ui/skill_bar_controller.js`): Action bar controller managing 5 active skill slots (Primary, Q, W, E, R), Dodge (Space), Potion (4), radial cooldown sweeps, and ready flash pulses.
  - `hud_skills.css` (`client/webapp/css/hud_skills.css`): Modern ARPG styling for Dual Orbs, docked action bar, cooldown sweep masks, and responsive ergonomics.
- **Combat Feel & Animation Engine**:
  - `animation_engine.js` (`client/webapp/js/engine/animation_engine.js`): 5-phase kinetic state machine (Idle, Run, Wind-up, Hit-stop, Recovery).
  - `weapon_swing_catalog.js` (`client/webapp/js/data/weapon_swing_catalog.js`): Data specifications for 4 weapon archetypes: Slash (cleave), Thrust (pierce), Slam (ground pound), and Bolt (sky lightning).
  - `combat_feel_engine.js` (`client/webapp/js/engine/combat_feel_engine.js`): Micro hit-stop freeze timer (2-4 frames / 33-66ms), directional camera shake, and static Ring Buffer DamageNumberPool (64 slots) with pop-in bounce scale (1.6 -> 1.0).
  - `weapon_swing_renderer.js` (`client/webapp/js/engine/weapon_swing_renderer.js`): Renders dynamic weapon swing arcs, thrust cones, ground slam fissures, and sky lightning bolts.
  - `entity_renderer.js` (`client/webapp/js/engine/entity_renderer.js`): Isometric character drawing with tinted ghost trails (`GhostTrailPool`).
- **PoE2 Hybrid Skill VFX & Telegraph Engine**:
  - `vfx_renderer.js` (`client/webapp/js/engine/vfx_renderer.js`): 4-stage multiphase VFX pipeline (Charge -> Trajectory -> Impact -> Lingering ground decals), 5-element visuals (Fractal Lightning, Metallic Blood, Shattered Ice, Toxic Smoke, Earthen Fissures).
  - `telegraph_renderer.js` (`client/webapp/js/engine/telegraph_renderer.js`): Ground telegraph decals (orange/red cones, expanding circles, directional rectangular beams) with wind-up progress tracking.
  - `vfx_presets_catalog.js` (`client/webapp/js/data/vfx_presets_catalog.js`): Elemental color palettes, particle kinematics, and decal durations.
- **Catalog & Object Pooling Layer**:
  - `skill_catalog.js` (`client/webapp/js/data/skill_catalog.js`): Canonical metadata for all 10 active skills + Primary Strike + Huyễn Ảnh Bộ.
  - `vfx_pool.js` (`client/webapp/js/engine/vfx_pool.js`): Zero-allocation pre-allocated static Object Pool (512 particles, 64 projectiles) with O(1) Swap-and-Pop recycling.
  - `combat_skills.js` (`client/webapp/js/engine/combat_skills.js`): Decoupled combat execution wiring inputs to catalog skills and telegraph engine.

## Feature Inventory
| # | Feature | Description | Milestone | Source |
|---|---------|-------------|-----------|--------|
| 1 | Dual Health & Mana Orbs | Twin glass globes with liquid wave oscillation, specular sheen, and low-HP pulse | M1 (DONE) | ORIGINAL_REQUEST §R1 |
| 2 | Unified ARPG Skill Bar | Docked action bar with slots: Primary, Q, W, E, R, Space, Potion (4) | M1 (DONE) | ORIGINAL_REQUEST §R1 |
| 3 | Radial Cooldown Sweep | Clockwise 360° radial sweep overlay with numeric countdown text | M1 (DONE) | ORIGINAL_REQUEST §R1 |
| 4 | Ready Flash Animation | 0.25s luminous border pulse and spring bounce when cooldown completes | M1 (DONE) | ORIGINAL_REQUEST §R1 |
| 5 | Unified Control Scheme | Full dual-platform controls: PC (Q/W/E/R/Space/Mouse) and Mobile (Dynamic Joystick + Action Cluster) | M1 (DONE) | ORIGINAL_REQUEST §R1 |
| 6 | 5-Phase Kinetic State Machine | Idle (6fps), Velocity-matched Run, Wind-up, Impact frame, Recovery follow-through | M2 | ORIGINAL_REQUEST §R2 |
| 7 | 2–4 Frame Impact Hit-Stop | Micro-freeze (33–66ms pause) on attacker and target upon impact | M2 | ORIGINAL_REQUEST §R2 |
| 8 | Weapon Archetype Swing Clips | Distinct visual swing motions: Slash (cleave), Thrust (pierce), Slam (pound), Bolt (lightning) | M2 | ORIGINAL_REQUEST §R2 |
| 9 | Huyễn Ảnh Bộ Evasion | 250ms i-frame dodge roll, animation cancelling, 3-charge pool, and tinted ghost trails | M2 | ORIGINAL_REQUEST §R2 |
| 10 | 4-Stage Multiphase VFX Pipeline | Charge (wind-up) -> Trajectory (flight) -> Impact (burst) -> Lingering Crater | M3 | ORIGINAL_REQUEST §R3 |
| 11 | PoE2 Fractal Lightning | Random 7-segment fractal bolt with secondary forks, white-hot core, and shockwave | M3 | ORIGINAL_REQUEST §R3 |
| 12 | Metallic Blood & Crescent Cleave | Viscous arterial droplets, deep carnelian crimson (#7f1d1d), spinning crescent blade | M3 | ORIGINAL_REQUEST §R3 |
| 13 | Sub-Zero Shattered Ice | 3-fan bone javelins, crystalline frost shards, ground ice decal, freeze aura | M3 | ORIGINAL_REQUEST §R3 |
| 14 | Corrosive Poison Smoke Mist | Slow-diffusing toxic green smoke clouds, curling wisps, bubbling ground pool | M3 | ORIGINAL_REQUEST §R3 |
| 15 | Earthen Fissure & Shockwave | Ground terrain cracks, stone spikes, expanding shockwave rings, heavy gravel | M3 | ORIGINAL_REQUEST §R3 |
| 16 | Visceral Screen Shake & Camera Flash | Directional camera shake matrix (intensity 2.5–8.5, duration 0.12–0.45s) | M3 | ORIGINAL_REQUEST §R3 |
| 17 | Visual Telegraph Decals | Orange/red warning cones, circles, and beams indicating wind-up progress | M3 | ORIGINAL_REQUEST §R3 |
| 18 | 100% Skill Coverage Catalog | Complete metadata and assets for all 10 canonical skills + Primary + Dodge | M4 | ORIGINAL_REQUEST §R4 |
| 19 | Zero-Allocation Object Pools | Pre-allocated static arrays (512 particles, 64 projectiles, 64 damage texts, 32 ghost trails) | M4 | ORIGINAL_REQUEST §R5 |
| 20 | 8.33ms Frame Budget Monitor & 120 FPS | Telemetry tracking frame micro-budgets (input, anim, VFX, render) <= 8.33ms | M5 | ORIGINAL_REQUEST §R5 |
| 21 | Requirement-Driven E2E Test Suite | Comprehensive opaque-box E2E test suite across Tiers 1-4 | E2E-Track (DONE) | Dual-Track |
| 22 | Final E2E Test Pass & Adversarial Hardening | 100% pass on E2E test suite + Tier 5 white-box adversarial stress testing | M5 | Project Pattern |
| 23 | Strict Code & Document Hygiene Gate | Pass `python tools/lint/check_code_and_doc_hygiene.py --strict` with zero hard cap violations | M5 | ORIGINAL_REQUEST §R5 |

## Milestones
| # | Name | Scope | Dependencies | Status |
|---|------|-------|-------------|--------|
| E2E | E2E Testing Track | Requirement-driven test suite (Tiers 1-4), runner, publishing `TEST_READY.md` | none | DONE |
| M1 | Modern ARPG UX/UI & Controls Rework | Dual Orbs, docked action bar, radial cooldown sweep, ready flash, PC/Mobile controls | none | DONE |
| M2 | Character Animation & Visceral Combat Feel Engine | 5-phase kinetic machine, 4 weapon archetypes, 2-4 frame hit-stop, i-frame dodge roll | M1 | IN_PROGRESS |
| M3 | PoE2 Hybrid Skill VFX Engine & Visual Telegraphs | Multiphase pipeline, 5-element visuals, screen shake, visual telegraph decals | M1 | PLANNED |
| M4 | Comprehensive Skill Asset Catalog & Object Pooling | Canonical 10 skills catalog, zero-allocation pooling (vfx_pool.js), combat_skills refactor | M2, M3 | PLANNED |
| M5 | 100% E2E Pass, Adversarial Hardening & 120 FPS | Full E2E pass, Tier 5 adversarial stress testing, 120 FPS telemetry, hygiene gate pass | E2E, M4 | PLANNED |

## Interface Contracts
### HudOrbs & SkillBarController ↔ Game State
- `HudOrbs.update(hp: number, maxHp: number, mana: number, maxMana: number) -> void`: Updates liquid levels and text labels smoothly.
- `SkillBarController.registerSlot(slotIndex: number, skillDef: SkillVfxDefinition, keybinding: string) -> void`.
- `SkillBarController.triggerCooldown(slotIndex: number, durationSec: number) -> void`: Starts 360° radial sweep.
- `SkillBarController.onReady(slotIndex: number) -> void`: Triggers 0.25s ready flash pulse.

### CombatFeelEngine ↔ Game Loop
- `CombatFeelEngine.triggerHitStop(frames: number = 3, durationSec: number = 0.05) -> void`: Sets micro-pause timer.
- `CombatFeelEngine.isHitStopped(dt: number) -> boolean`: Returns true if engine should pause frame advancement.
- `CombatFeelEngine.spawnDamageNumber(text: string, x: number, y: number, color: string, isCrit: boolean) -> void`: Acquires slot from pool with pop-in scale.
- `CombatFeelEngine.triggerScreenShake(intensity: number, durationSec: number) -> void`.

### VfxPoolManager ↔ VfxRenderer
- `VfxPoolManager.acquireParticle(initProps: Object) -> Object | null`: O(1) allocation-free slot acquisition.
- `VfxPoolManager.update(dt: number) -> void`: O(1) Swap-and-Pop deactivation for expired particles.
- `VfxPoolManager.render(ctx: CanvasRenderingContext2D) -> void`: Batched Canvas 2D particle rendering.

### TelegraphRenderer ↔ Monster / Boss AI
- `TelegraphRenderer.addTelegraph(type: 'cone'|'circle'|'line', wx: number, wy: number, duration: number, params: Object) -> void`.
- `TelegraphRenderer.updateAndRender(ctx: CanvasRenderingContext2D, dt: number) -> void`.