neon-sprawl/docs/decomposition/modules/E5_M1_CombatRulesEngine.md

E5.M1 — CombatRulesEngine

Summary

Field	Value
Module ID	E5.M1
Epic	Epic 5 — PvE Combat
Stage target	Prototype
Status	Planned (see dependency register)
Linear	Label E5.M1 · E5M1-prototype-backlog.md E5M1-01 NEO-76 → E5M1-12 NEO-86; gig XP E5M1-10 NEO-44

Purpose

Authority: Client vs server — 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.

PvP: Single engine for PvE and PvP; player-target hostility gates on E6.M1. See PvP and the combat engine.

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).
• 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: TargetState, selection, and alignment with E1.M4 (AbilityInputScaffold) for AbilityCastRequest wiring.
• E2.M2 — XpAwardAndLevelEngine: 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.

Linear backlog (decomposed)

Full story tables, kickoff defaults, and blockedBy graph: E5M1-prototype-backlog.md.

Slug	Linear
E5M1-01	NEO-76
E5M1-02	NEO-77
E5M1-03	NEO-79
E5M1-04	NEO-78
E5M1-05	NEO-80
E5M1-06	NEO-81
E5M1-07	NEO-82
E5M1-08	NEO-83
E5M1-09	NEO-84
E5M1-10	NEO-44
E5M1-11	NEO-85
E5M1-12	NEO-86

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), 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 — Core Epic Map, Epic 5.
• Module dependency register