# Epic 5 - PvE Combat and Encounter Content

## Source Anchors

- Master epic reference: [`neon_sprawl_vision.plan.md`](../../../neon_sprawl_vision.plan.md) — Core Epic Map, System Modules Epic 5
- Related modules: E5.M1, E5.M2, E5.M3, E5.M4

## Ownership and success (Level 1)

- **Ownership focus:** Combat Design + Encounter Design
- **Success criteria:** PvE combat delivers tactical depth, clear readability, and repeatable fun for solo and group play.

## Objective

Deliver tab-target combat resolution, NPC behaviors and telegraphs, encounter templates with rewards, and optional group scaling so PvE is the mandatory progression path with readable isometric presentation.

## Module Breakdown

### E5.M1 - CombatRulesEngine

- Responsibility: Tab-target combat state machine, hit resolution, cooldown/resource timing.
- Key contracts: `CombatAction`, `CombatResolution`, `ThreatState`
- Dependencies: E1.M3, E2.M2
- Stage target: Prototype

### E5.M2 - NpcAiAndBehaviorProfiles

- Responsibility: Enemy archetype behavior loops, aggro logic, telegraph scheduling.
- Key contracts: `NpcBehaviorDef`, `TelegraphEvent`, `AggroRule`
- Dependencies: E5.M1
- Stage target: Prototype

### E5.M3 - EncounterAndRewardTables

- Responsibility: Encounter setup templates, completion criteria, reward drop routing.
- Key contracts: `EncounterDef`, `RewardTable`, `EncounterCompleteEvent`
- Dependencies: E5.M1, E3.M3, E7.M2
- Stage target: Prototype

### E5.M4 - GroupCombatScaling

- Responsibility: Duo/squad scaling logic and anti-trivialization balancing hooks.
- Key contracts: `ScalingProfile`, `PartySizeModifier`, `CombatDifficultyBand`
- Dependencies: E5.M3, E8.M1
- Stage target: Pre-production

## Implementation Slices (Backlog-Ready)

### Slice 1 - Combat rules MVP

- Scope: E5.M1 with target lock, basic attacks, 4-6 abilities, cooldowns/resources per prototype scope.
- Dependencies: E1.M3, E2.M2
- Acceptance criteria:
  - Combat readable in fixed isometric camera; no silent failures on ability deny.
- Telemetry hooks: `encounter_start`, `ability_used`, `player_death`, `enemy_defeat`.

**Linear backlog:** [E5M1-prototype-backlog.md](../../plans/E5M1-prototype-backlog.md) — [NEO-76](https://linear.app/neon-sprawl/issue/NEO-76) → [NEO-86](https://linear.app/neon-sprawl/issue/NEO-86); gig XP **E5M1-10** [NEO-44](https://linear.app/neon-sprawl/issue/NEO-44).

### Slice 2 - NPC archetypes and telegraphs

- Scope: E5.M2 for three archetypes: melee pressure, ranged control, elite mini-boss.
- Dependencies: E5.M1
- Acceptance criteria:
  - Telegraph timing matches UI feedback; aggro rules deterministic.
- Telemetry hooks: `telegraph_fired`, `npc_state_transition`.

**Linear backlog:** [E5M2-prototype-backlog.md](../../plans/E5M2-prototype-backlog.md) — [NEO-87](https://linear.app/neon-sprawl/issue/NEO-87) → [NEO-98](https://linear.app/neon-sprawl/issue/NEO-98); client capstone **E5M2-12** [NEO-98](https://linear.app/neon-sprawl/issue/NEO-98). Verify in **Godot**, not Bruno-only.

### Slice 3 - Encounters and loot routing

- Scope: E5.M3 wired to E3.M3 and E7.M2 for rewards and quest progress.
- Dependencies: E5.M2, E3.M3, E7.M2
- Acceptance criteria:
  - Completing defined encounters grants expected items/quest credit once.
- Telemetry hooks: `encounter_complete`, reward attribution.

### Slice 4 - Group scaling (pre-production)

- Scope: E5.M4 with party-sized modifiers behind E8.M1.
- Dependencies: E8.M1
- Acceptance criteria:
  - Duo run remains challenging but fair; metrics show no trivial farm spike.
- Telemetry hooks: `party_combat_scaling_applied`.

## Risks and Mitigations

- Risk: Tab-target feels sluggish or opaque.
  - Mitigation: Prototype readability gate; instrument time in combat and failure reasons.
- Risk: Loot tables desync from item schema.
  - Mitigation: Shared validation in content pipeline; lint reward references.

## Definition of Done

- Prototype combat, archetypes, and encounters meet documented minimums in master plan.
- Telemetry covers combat health KPIs.
