# Player & Pawn Model

## Purpose
This document describes the per-client data model, pawn ownership/view routing, and core pawn subsystems.

## Authority map
- Client session container: `Code/Players/ConnectedClient.cs`
  - Host-authored identity, AFK/penalty flags, pawn binding contract, local viewer/control routing.
- Pawn contract: `Code/Players/Pawn.cs`
  - `IPawn` abstraction used for possession/viewer control.
- Main pawn component: `Code/Players/Pawn/PlayerComponent.cs`
  - Core pawn state, ownership bind, camera/input bridge, weapon/deployment integration, gameplay stats fields.
- Pawn state/extensions:
  - `Code/Players/Pawn/PlayerComponent.State.cs`
  - `Code/Players/Pawn/PlayerComponent.Resync.cs`
  - `Code/Players/Pawn/PlayerComponent.Commands.cs`
- Body and corpse representation:
  - `Code/Players/Pawn/PlayerBody.cs`
  - `Code/Players/Pawn/PlayerBody.Corpse.cs`
  - `Code/Players/Pawn/FirstPersonBodyComponent.cs`
- Spectating:
  - `Code/Players/Spectator/SpectateSystem.cs`
  - `Code/Players/Spectator/SpectateController.cs`

## Pawn ownership/view rules
- `ConnectedClient` is the authoritative owner container for a player session.
- `ConnectedClient.Viewer` is local control/view truth (self pawn or spectate target routing).
- Pawn binding is explicit and epoch-driven (`PawnBindEpoch`, `BindState`) to reduce desync during transitions.
- Local respawn finalize waits for pawn/lifecycle/life convergence before possession finalize.
- Respawn finalize uses normal possession path (`ClearSpectateTarget` + `Possess`) rather than force-control fallback.

## Spectate transitions
- Spectate target assignment is managed by `Code/Players/Spectator/SpectateSystem.cs`.
- Entering spectate during local death camera defers auto-target assignment until death camera has ended.
- If the active spectate target becomes non-spectatable (dead or outside `PreRound`/`Playing` lifecycle), spectator mode exits to freecam and orients toward that target position.
- If the current target reference is invalid/missing, next-target fallback selection is still used.
- Spectate overlay visibility is derived in `Code/UI/Core/UIContext.cs` and is intentionally suppressed during local death camera view.

## Pawn subsystems
- Damage/life:
  - `Code/Players/Pawn/Damage/*`
- Movement/controller:
  - `Code/Players/Pawn/Movement/*`
- Inventory/ammo/use:
  - `Code/Players/Pawn/Inventory/*`
- Player-level stat tracking:
  - `Code/Players/Stats/*`

## Integration points
- Lifecycle transitions are authored in `PlayerState` (`Code/Players/Lifecycle/PlayerState.cs`).
- Spawning/respawning is routed through spawn execution authority.
- Presentation reads viewer/pawn state but render mutations are centralized in presentation services.
- Targeted respawn-recovery resync requests are authored in `PlayerComponent.Resync` and logged under `t.db.resync`.

## Related docs
- Lifecycle authority: `Code/Core/Documentation/Structure/lifecycle.md`
- Spawning authority: `Code/Core/Documentation/Structure/spawning.md`
- Presentation flow: `Code/Core/Documentation/presentation-audit.md`