65 lines
3.7 KiB
Markdown
65 lines
3.7 KiB
Markdown
# 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)
|