Trace damage from intent to outcome

571. Lesson identity

Module

2.1 — Combat

Lesson

Trace damage from intent to outcome

Academic type

Guided Build

Schema type

Practical

Order

2 of the module

Estimated time

35–45 minutes, including the diagramming practice

572. Learning objective

After this lesson, you can produce a damage-flow diagram that assigns ownership to each combat step, identifies the authoritative health transition, and exposes duplicate-authority failures before implementation.

573. Why this matters

An attack is not complete when input is detected or an animation plays. It is complete when a valid combat rule produces an authoritative state transition whose outcome other systems can observe consistently.

A precise damage flow gives you a boundary for implementation and debugging. When an outcome is wrong, you can inspect validation, resolution, state mutation, event publication, and presentation in order instead of searching every weapon, hitbox, animation, and interface script.

574. Prior knowledge

You should already be able to:

• Describe combat as a bounded contract with conditions, authority, and an outcome.
• Separate combat rules from weapon or effect content.
• Identify the attacker, target, proposed damage, and protected neighboring systems in a small encounter.

These capabilities come from the previous lesson, Combat is a contract, not a weapon list.

575. Core concept

A successful attack should follow one authoritative path from intent to outcome:

1. Intent requests an attack.
2. Validation decides whether the request is allowed.
3. Resolution calculates the combat result without mutating target health.
4. State ownership applies and records the resolved result as the authoritative health transition.
5. Result communication tells observers what state transition occurred.
6. Feedback presents that result without recalculating or applying it again.

The ownership distinction is essential:

• The combat resolver owns calculation of the resolved combat result.
• The target health or combat-state owner owns the authoritative health mutation and records the resulting value.
• Presentation, animation, audio, AI, and logging systems may observe the outcome, but they do not acquire health authority by subscribing to an event.

For a successful transition, a DamageResolved event may contain the attacker, target, attack identifier, resolved damage, and resulting health or defeat outcome. It describes a result that the health owner has already applied.

A rejected request follows a separate path. It may emit an AttackRejected event containing the request identity and rejection reason, but it must not emit a successful resolved-damage outcome or cause a health transition.

576. Mental model

Use the single-authority damage chain:

ATTACK INTENT
    ↓
VALIDATE CONTRACT
    ↓
RESOLVE DAMAGE ONCE
    ↓
TARGET HEALTH OWNER APPLIES AND RECORDS THE TRANSITION
    ↓
EMIT DAMAGE RESOLVED
    ↓
PRESENT OR OBSERVE THE RESULT

The invariant is: one valid hit produces one authoritative health transition. Feedback may be repeated or delayed, but health mutation must not be duplicated.

577. Concrete example

Consider a melee attack with these values:

• Attacker: guard
• Target: courier
• Resolved damage: 12
• Target health before the hit: 40
• The attack is in range and the target is not invulnerable

A sound flow is:

Guard requests slash
→ Combat contract validates range and attack state
→ Combat resolver calculates 12 damage without changing health
→ Courier health owner applies and records 40 → 28
→ DamageResolved carries { target: courier, amount: 12, healthAfter: 28 }
→ Hit flash, sound, floating number, combat log, and other observers react

A presentation listener can display 12. It must not subtract another 12. If a hitbox callback also changes health, the courier may end at 16 instead of 28, even though the displayed event data looks correct. That is a duplicate-authority failure.

A rejected attack follows a distinct branch:

Guard requests slash
→ Combat contract rejects the request because the target is out of range
→ No resolution and no health transition occur
→ Optional AttackRejected event communicates the reason
→ Optional feedback presents the rejection

The absence of damage is therefore an explicit result of validation rather than an accidental side effect.

578. Common mistake

A common mistake is treating every listener that receives a hit or result signal as authorized to apply damage. This can happen when a weapon script, hitbox callback, enemy controller, animation event, and interface presenter each contain a subtraction or damage calculation.

The code may appear modular, but its authority is duplicated. Renaming functions does not solve the problem. The correction is to keep calculation in one combat resolver, keep mutation in the target health owner, and make all remaining systems consume the recorded outcome without recalculating or reapplying it.

579. Guided practice

Produce one canonical damage-flow diagram. Add two clearly labelled unauthorized mutation paths to that same diagram: one for Case A and one for Case B. Do not create a separate full diagram for each case.

Use this compact template:

[Attack intent]
      ↓
[Validation] ── rejected ──→ [AttackRejected] → [Optional rejection feedback]
      ↓ accepted
[Combat resolver: calculates ______; does not mutate health]
      ↓ resolved result
[Target health owner: applies and records ______ → ______]
      ↓
[DamageResolved: carries ____________________]
      ↓
[Observers and feedback: ____________________]

Unauthorized path A: ____________________ → second health mutation
Unauthorized path B: ____________________ → recalculation + second health mutation

Case A — Hitbox duplicates the health transition

A player attacks a raider with a charged strike. The combat resolver validates the request and calculates 10 damage without changing health. It passes that resolved result to the raider's health owner, which applies and records the authoritative transition from 30 to 20. After observing the result, a hitbox callback performs an unauthorized second subtraction of 10, leaving the raider at 10.

Case B — Presentation recalculates after a valid transition

A player attacks a courier with a quick strike. The combat resolver validates the request and calculates 8 damage. The courier's health owner applies and records the transition from 24 to 16. A floating-number presenter observes DamageResolved, recalculates damage from the attack's base value, and applies another 8 before displaying the number. The courier incorrectly ends at 8.

Complete the diagram and its annotations:

1. Write the attack intent in one sentence.
2. List the validation conditions and add one rejected branch that produces no health transition.
3. Name the combat resolver and state that it calculates the resolved result but does not mutate target health.
4. Name the target health owner and state that it applies and records the resolved result.
5. Show the resolved-result handoff between those two owners.
6. Define the minimum successful DamageResolved payload needed by observers.
7. Label unauthorized path A with its second system, incorrect 30 → 20 → 10 sequence, and correction.
8. Label unauthorized path B with its second system, incorrect 24 → 16 → 8 sequence, and correction.

For each unauthorized path, add three brief notes:

• Cause: Which observer acquired unauthorized mutation authority?
• Evidence: Which value changed twice, and what final value exposes the fault?
• Correction: Which mutation must be removed, and which resolved event data may the observer still consume?

Your diagram must distinguish request, decision, calculation, state mutation, communication, and presentation. A box labelled only “deal damage” is not sufficient evidence.

580. Validation and evidence

Your work is complete when it contains:

• One combat resolver that calculates damage without mutating health.
• One target health owner that applies and records the transition.
• One rejected branch with no damage resolution or health transition.
• One successful DamageResolved event that communicates the applied outcome.
• Observers that present or react to the result without changing health.
• Two separately labelled unauthorized paths on the same canonical diagram.
• The intended and incorrect health sequences for both cases.
• A cause, observable evidence, and correction for each duplicate-authority failure.

Review each arrow by asking: Does this step request, decide, calculate, mutate, communicate, or present? If one step performs multiple authority roles, either separate those roles or justify the boundary explicitly.

581. Key takeaways

• Trace combat from intent to outcome instead of beginning with weapon scripts.
• The combat resolver calculates the result; the target health owner applies and records it.
• DamageResolved communicates a successful applied outcome, while rejected requests follow a distinct rejection path.
• Presentation and other observers must not become additional health authorities.
• Duplicate authority becomes visible when the same health value changes twice for one valid hit.

582. Next lesson

Continue to 2.2 — Enemy AI. Enemy states and transitions may observe DamageResolved or defeat outcomes to decide how to react, but observation does not transfer health authority away from the target health owner.

583. Knowledge check