# Player Lifecycle & Participation

## Purpose
This document defines host-authored player lifecycle state, participation admission, and side-effect gating rules.

## Authority map
- Lifecycle authority: `Code/Players/Lifecycle/PlayerState.cs`
  - Centralized host-only transitions for lifecycle, life, health, and respawn state.
- Lifecycle state model: `Code/Players/Lifecycle/PlayerState.cs`
  - `PlayerLifecycleState`: `NotInRound`, `PreRound`, `Playing`, `DeadSpectating`.
- Participation admission authority: `Code/Players/Lifecycle/ParticipationService.cs`
  - AFK/penalty admission decisions and penalty consumption hooks.
- Participation model: `Code/Players/Lifecycle/ParticipationDisposition.cs`
  - Round admission outcomes.
- Side-effect policy authority: `Code/Players/Lifecycle/RoundEventPolicy.cs`
  - Gates kill/reward/stats side effects to valid live-round windows.

## Core rules
- Lifecycle transitions are host-only and routed through `PlayerState`.
- `NotInRound` means excluded/spectating for this round.
- `PreRound` and `Playing` are participating states.
- `DeadSpectating` is post-death spectator posture for participants.
- AFK and skip-round penalties feed participation admission each pre-round.
- Client respawn finalize is local-only and does not call back to the host.

## Round integration
- Pre-round:
  - Admission is evaluated (`ParticipationService.ShouldParticipateThisRound`).
  - Included players -> `PrepareForRound`.
  - Excluded players -> `EnterObserver`.
- Round start:
  - `PreRound` participants are promoted to `Playing`.
- Death:
  - Lifecycle moves to `DeadSpectating` via centralized lifecycle/damage flow.

## Resync window integration
- `GameMode` controls resync-revive windows and optional sanity passes.
- Lifecycle reconciliations during resync windows are routed through `PlayerState` APIs.
- Targeted respawn-recovery resync requests are owner-only and host-validated (owner, spawn sequence, time window).

## Related docs
- Host loop: `Code/Core/Documentation/Structure/game-loop.md`
- Spawn flow: `Code/Core/Documentation/Structure/spawning.md`
- Player model: `Code/Core/Documentation/Structure/player-pawn.md`