# E5.M1 — CombatRulesEngine

## Summary

| Field | Value |
|--------|--------|
| **Module ID** | E5.M1 |
| **Epic** | [Epic 5 — PvE Combat](../epics/epic_05_pve_combat.md) |
| **Stage target** | Prototype |
| **Status** | Planned (see [dependency register](module_dependency_register.md)) |

## Purpose

**Authority:** [Client vs server](client_server_authority.md#e5m1-combatrulesengine) — server validates intents and computes all outcomes; never trust client damage/healing/crit/death.

Core tab-target combat resolution: valid actions against a locked target, hit resolution, cooldown and resource timing, and threat state as needed for prototype encounters. Presents readable outcomes in fixed isometric view and feeds XP awards through [E2.M2](E2_M2_XpAwardAndLevelEngine.md).

**PvP:** Single engine for PvE and PvP; player-target hostility **gates** on [E6.M1](E6_M1_PvPEligibilityAndFlagState.md). See [PvP and the combat engine](pvp_combat_integration.md).

## Responsibilities

- Combat state machine for tab-target flow (attacks, abilities per prototype scope).
- Validate and apply `CombatAction`; produce `CombatResolution` for UI and logs (include **PvP deny reasons** when player targets are blocked; see [pvp_combat_integration.md](pvp_combat_integration.md)).
- Integrate with targeting/interaction from **E1.M3** (target lock, valid target checks).
- Award combat XP via E2.M2 integration where specified in slices.

## Key contracts

| Contract | Role |
|----------|------|
| `CombatAction` | Attack, ability, or other combat intent from client/input scaffold. |
| `CombatResolution` | Hits, misses, damage, denies with reason codes (no silent failures). |
| `ThreatState` | Aggro/threat for NPC and encounter coordination (as scoped). |

## Module dependencies

- **E1.M3** — [InteractionAndTargetingLayer](E1_M3_InteractionAndTargetingLayer.md): `TargetState`, selection, and alignment with **E1.M4** ([AbilityInputScaffold](E1_M4_AbilityInputScaffold.md)) for `AbilityCastRequest` wiring.
- **E2.M2** — [XpAwardAndLevelEngine](E2_M2_XpAwardAndLevelEngine.md): combat XP grants.

## Dependents (by design)

- **E5.M2** — NpcAiAndBehaviorProfiles.
- **E5.M3** — EncounterAndRewardTables.
- **E1.M4** — AbilityInputScaffold sends `AbilityCastRequest` to combat.
- **E7.M1** — QuestStateMachine for combat-related quest steps.
- **E2.M2** — Invoked as integration caller for XP (not a structural child).

## Related implementation slices

See Epic 5 **Slice 1 — Combat rules MVP**: target lock, basic attacks, 4–6 abilities, cooldowns/resources; telemetry `encounter_start`, `ability_used`, `player_death`, `enemy_defeat`.

## Prototype notes (NEO-28)

Epic 1 **Slice 3** exercises a minimal cast accept/deny surface on **`POST /game/players/{id}/ability-cast`** before the full engine exists: after hotbar/loadout validation ([E1.M4](E1_M4_AbilityInputScaffold.md)), the server requires **`targetId`** to match the persisted combat lock, resolve in the prototype target registry, and sit within horizontal lock radius against authoritative **`PositionState`**. Deny codes **`invalid_target`** and **`out_of_range`** reuse the same strings as E1.M3 **`TargetState.validity`** for vocabulary alignment. **`accepted: true`** still does not imply damage, cooldown commit, or a full **`CombatResolution`** payload — those remain E5.M1 scope.

## Risks and telemetry

- Sluggish or opaque tab-target: prototype readability gate; instrument time-in-combat and deny reasons.
- Desync logging via E9.M1 taxonomy when available.

## Source anchors

- Master plan: [`neon_sprawl_vision.plan.md`](../../../neon_sprawl_vision.plan.md) — Core Epic Map, Epic 5.
- [Module dependency register](module_dependency_register.md)