# Damage Description Authoring Guide

## Purpose
This guide explains how to add or adjust death-description text for weapon kills, damage types, and environment kills.

## Where description text comes from
- Canonical cause/kind classification:
  - `Code/Players/Pawn/Damage/Classification/DamageCatalog.cs`
  - `Code/Players/Pawn/Damage/Classification/TttDamageClassifier.cs`
- Descriptor definitions and variants:
  - `Code/Players/Pawn/Damage/Descriptors/TttDamageDescriptor.cs`
  - `Code/Players/Pawn/Damage/Descriptors/TttDamageDescriptorRegistry.cs`
- Optional source overrides from components:
  - `Code/Players/Pawn/Damage/Descriptors/EquippableDamageDescriptorComponent.cs`
  - `Code/Players/Pawn/Damage/Descriptors/MapHazardDamageDescriptorComponent.cs`
  - `Code/Players/Pawn/Damage/Descriptors/GenericWorldDamageDescriptorComponent.cs`

## Descriptor source precedence (current runtime)
1. `DamageInfo.Inflictor` equippable descriptor (weapon-authored text).
2. Attacker-side equippable descriptor (typically attacker current weapon) when inflictor has no equippable source.
3. Other descriptor sources on the damage context object (hazard/world components).
4. Cause-based fallback descriptor from `TttDamageDescriptorRegistry`.

## When to use each path
- Add a global cause descriptor when text should apply game-wide by cause ID.
- Add a source component override when text should be specific to one weapon/entity/hazard.

## A) Add a new global cause description
1. Add cause constant in `Code/Players/Pawn/Damage/Classification/TttDamageCause.cs`.
2. Add/update classifier rule in `Code/Players/Pawn/Damage/Classification/TttDamageClassifier.cs` so damage resolves to that cause.
3. Register descriptor in `Code/Players/Pawn/Damage/Descriptors/TttDamageDescriptorRegistry.cs`.
4. Add variants per context (`BodyInfo`, `KillFeed`, `RoundSummary`, etc.) as needed.
5. Confirm the producer sets meaningful tags/attacker/inflictor so classification is stable.

## B) Add weapon-specific or environment-specific description
1. Add an appropriate descriptor source component to the damage source object:
- weapon/equipment: `EquippableDamageDescriptorComponent`
- map hazard/trap: `MapHazardDamageDescriptorComponent`
- generic world object: `GenericWorldDamageDescriptorComponent`
2. Configure override fields (body text, killfeed text, summary text).
3. Ensure the object is passed as `DamageInfo.Inflictor` when damage is applied.
4. For equippable/manual authoring, prefer placing all front-facing text on the weapon prefab descriptor so it wins resolution first.

## Grammar slots (current wiring)
- `BodyInfoText` / `HeadshotBodyInfoText`
  - Slot: leading clause in body inspection UI.
  - Final render shape: `"{descriptor} {seconds} second(s) ago"`.
  - Write as a past-tense phrase, not including trailing time words.
  - Example author text: `Shot in the chest` -> UI: `Shot in the chest 12 seconds ago`.
- `KillFeedText` / `HeadshotKillFeedText`
  - Intended slot: kill method verb/phrase between killer and victim.
  - Current status: consumed by `KillFeedProjection`.
- `ConsoleLogText`, `RoundSummaryText`, `StatsText`, `DetectiveInfoText`
  - Intended slot: context-specific override strings for those views.
  - Current status: reserved; active runtime path currently resolves only `BodyInfo` context.
- `PreferWeaponName`
  - BodyInfo-only behavior: when applied and weapon name exists, descriptor appends `with {weapon}`.
  - Example: `Beat to death` -> `Beat to death with Crowbar 12 seconds ago`.
- `{weapon}` token
  - Supported in descriptor text values and variants.
  - Token is replaced with resolved weapon display name (fallback: `their weapon`).

## C) Add headshot/distance-sensitive variants
- Use `AddVariant(...)` in descriptor registration with a predicate against `TttDamageEvent`.
- Example triggers:
- `e.IsHeadshot`
- cause/kind checks
- context checks (`BodyInfo` vs `KillFeed`)

## DNA policy
- Descriptors can control whether hits leave DNA.
- Prefer descriptor-driven DNA policy instead of ad-hoc checks by weapon class.

## Safe defaults
- If unsure, keep fallback text explicit and non-leaky (example: `Died mysteriously`).
- Keep world/unknown attribution as fallback only.

## Validation in editor
1. Enable diagnostics:
- `t.db.damage 1`
- `t.db.damage_class 1`
- `t.db.damage_dump 1`
2. Test one direct player kill, one environment death, and one self-kill.
3. Confirm:
- corpse/body info text is correct,
- kill-feed text payload is populated,
- no role secrecy is leaked before reveal.