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)

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.

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