feat: Add multiplayer networking architecture and documentation updates

- Updated Master Blueprint Index to include Multiplayer Networking support.
- Added detailed Multiplayer Networking sections across all developer documentation (01-11).
- Introduced authority maps, key patterns, and RPC guidelines for each system.
- Established a comprehensive multiplayer networking architecture document outlining core principles, replication strategies, and anti-cheat considerations.
- Enhanced UI documentation to clarify local-only behavior and binding to replicated dispatchers.
- Implemented client prediction strategies and RPC naming conventions for consistency across the framework.

docs/blueprints/02-player/08_BPC_HealthSystem.md

@@ -337,4 +337,70 @@ flowchart TD
 
 ---
 
+## 11. Multiplayer Networking (Expanded)
+
+### Replicated Variables (Existing + New)
+
+| Variable | Type | Condition | Description |
+|----------|------|-----------|-------------|
+| `CurrentHealth` | `Float` | `Replicated Using OnRep_CurrentHealth` | Clients sync via OnRep → dispatcher |
+| `DeathState` | `E_DeathState` | `Replicated Using OnRep_DeathState` | Death state synced; OnRep triggers death effects |
+| `bIsInvincible` | `Boolean` | `Replicated` | Invincibility visible to other players |
+| `MaxHealth` | `Float` | `Replicated` | Synced for UI percentage calculations |
+
+### Server RPCs
+
+| RPC | Direction | Description |
+|-----|-----------|-------------|
+| `Server_ApplyDamage` | Client→Server | Client reports taking damage. Server validates source, range, damage type. |
+| `Server_ApplyHealing` | Client→Server | Client requests healing. Server validates heal source, applies. |
+| `Server_KillInstant` | Client→Server | Only accepted from authoritative sources (GM, traps). Client calls are rejected. |
+
+### Authority Gates
+
+```
+Function ApplyDamage(DamageEvent)
+  Switch HasAuthority
+    Authority:
+      → Calculate resistance, apply damage, fire dispatchers
+    Remote:
+      → Return (clients never modify health directly)
+      → Server_ApplyDamage is called by damage source (weapon/trap), not victim
+
+Function ApplyHealing(HealAmount)
+  Switch HasAuthority
+    Authority:
+      → Apply healing, fire dispatchers
+    Remote:
+      → Return
+      → Consumable use calls Server_UseConsumable → server calls ApplyHealing
+```
+
+### Client Prediction
+
+- **Health bar:** Client predicts damage flash on hit; server-corrected value arrives via `OnRep_CurrentHealth`.
+- **Death:** No prediction. `OnRep_DeathState` triggers all death effects (screen fade, ragdoll).
+- **Healing:** Client shows green flash immediately + predicted health; server corrects within one RTT.
+- **Invincibility:** Visual effect (shield shimmer) is local cosmetic; state is replicated.
+
+### OnRep Handlers
+
+```
+OnRep_CurrentHealth()
+  → Broadcast OnHealthChanged(OldHealth, CurrentHealth, Delta)
+  → UI updates identically to single-player path
+
+OnRep_DeathState()
+  → Broadcast OnDeathStateChanged(OldState, NewState)
+  → If Dead: play death animation, screen effects, notify GM
+```
+
+### Anti-Cheat
+
+- Server validates all `Server_ApplyDamage` calls: check instigator range, weapon fire rate, damage type validity.
+- Server never trusts `DamageEvent.BaseAmount` from client — always recalculates from weapon data.
+- `Server_KillInstant` is only callable from server-authoritative systems (traps, death zones, GM).
+
+---
+
 *Blueprint Spec: Health System. Conforms to TEMPLATE.md v1.0 — part of the UE5 Modular Game Framework.*

docs/blueprints/02-player/09_BPC_StaminaSystem.md

@@ -326,6 +326,41 @@ flowchart TD
 - The drain rate map supports runtime modification for buffs/debuffs (e.g. Adrenaline reduces sprint cost).
 - UI widgets should bind to OnStaminaChanged for smooth bar animation, not tick polling.
 - For multiplayer: Server authorises all DrainStamina calls; client predicts and corrects on repnotify.
+
+---
+
+## 11. Multiplayer Networking (Expanded)
+
+### Server RPCs
+
+| RPC | Direction | Description |
+|-----|-----------|-------------|
+| `Server_DrainStamina` | Client→Server | Client requests stamina drain for action. Server validates MinStamina, applies. |
+| `Server_StartContinuousDrain` | Client→Server | Client starts sprinting. Server begins drain timer. |
+| `Server_StopContinuousDrain` | Client→Server | Client stops sprinting. Server stops drain, begins regen. |
+| `Server_RestoreStamina` | Client→Server | Client uses stamina item. Server validates item, applies restore. |
+
+### Authority Gates
+
+```
+Function DrainStamina(ActionType)
+  If HasAuthority:
+    → Check cooldown, MinStamina
+    → Apply drain, update exhaustion, fire dispatchers
+  Else:
+    → Client predicts stamina bar decrease for responsiveness
+    → Server_ RPC called; server corrects via OnRep if wrong
+
+Function SetMaxStamina(NewMax, bMaintainRatio)
+  If NOT HasAuthority → Return
+  → Apply change, fire dispatchers, auto-replicates
+```
+
+### Client Prediction
+
+- **Stamina bar:** Client predicts decrease on sprint/jump. Server corrects via `OnRep_CurrentStamina`.
+- **Exhaustion:** ExhaustionState replicated. Client plays breathing audio locally.
+- **Cooldowns:** Server-authoritative. Client shows cooldown timer after server confirms action.
 - Exhaustion state can drive conditional audio: heavy breathing, heart-beat, fatigue voice lines.
 
 ---

docs/blueprints/02-player/10_BPC_StressSystem.md

@@ -337,6 +337,28 @@ flowchart TD
 - Stress tiers can gate narrative content — questgivers behave differently based on player stress.
 - Hallucination types can be configured via Data Asset (DA_HallucinationConfig).
 - For multiplayer: Stress is server-authoritative; clients receive tier changes for local effects.
+
+---
+
+## 11. Multiplayer Networking (Expanded)
+
+### Server RPCs
+| RPC | Direction | Description |
+|-----|-----------|-------------|
+| `Server_AddStress` | Client→Server | Client reports stress event. Server validates source, applies. |
+| `Server_AddStressSource` | Client→Server | Client enters enemy proximity zone. Server adds/updates source. |
+| `Server_RemoveStressSource` | Client→Server | Client leaves enemy zone. Server removes source. |
+| `Server_SetSafeZone` | Client→Server | Client reports safe zone status. Server validates, applies decay. |
+
+### Authority
+- **Server** calculates total stress from all sources, updates tier, replicates.
+- **Client** plays local hallucination/audio effects based on replicated tier.
+- `ForcePanic()` is server-only (narrative system calls it directly on server).
+
+### Client Prediction
+- Stress bar: predicted on client, corrected by `OnRep_CurrentStress`.
+- Hallucinations: randomly triggered by client based on replicated tier (cosmetic only).
+- Safe zone: server-authoritative; clients see OnSafeZoneChanged dispatcher.
 - The HealthDeficitMultiplier creates a death spiral feel — use carefully for horror pacing.
 - Safe zones double as narrative checkpoints and stress recovery areas.
 

docs/blueprints/02-player/11_BPC_MovementStateSystem.md

@@ -320,4 +320,33 @@ flowchart TD
 
 ---
 
+## 11. Multiplayer Networking (Expanded)
+
+### Replication
+Movement state is natively handled by `CharacterMovementComponent` replication. `BPC_MovementStateSystem` replicates state enums for non-movement consumers (UI, camera, audio).
+
+| Variable | Condition | Notes |
+|----------|-----------|-------|
+| `CurrentPosture` | `Replicated Using OnRep_Posture` | Synced posture for other players' animation |
+| `CurrentMovementMode` | `Replicated Using OnRep_MovementMode` | Synced mode for audio/camera systems |
+| CMC velocity | Native replication | Position/velocity handled by CharacterMovementComponent |
+
+### Server RPCs
+| RPC | Direction | Description |
+|-----|-----------|-------------|
+| `Server_SetMovementMode` | Client→Server | Client requests mode change. Server validates against MovementSettings. |
+| `Server_SetPosture` | Client→Server | Client requests posture change. Server validates ceiling clearance. |
+| `Server_SetSprinting` | Client→Server | Client toggles sprint. Server checks stamina before authorizing. |
+
+### Authority
+- `SetMovementMode` and `SetPosture` check `HasAuthority()` before modifying state.
+- Movement penalties (`ApplyMovementPenalty`) are server-authoritative.
+- `CanTransitionToPosture` is read-only; clients can call for local prediction.
+
+### Client Prediction
+- Posture/mode transitions: client predicts movement locally; server validates.
+- Footstep sounds: local calculation based on replicated state.
+
+---
+
 *Blueprint Spec: Movement State System. Conforms to TEMPLATE.md v1.0 — part of the UE5 Modular Game Framework.*

docs/blueprints/02-player/12_BPC_HidingSystem.md

@@ -321,6 +321,30 @@ flowchart TD
 - The LOS trace channel should be custom (e.g., DetectionChannel) to ignore small props.
 - Breath-hold mechanic adds depth to stealth gameplay near enemies.
 - For multiplayer: only the hiding player knows their state; other players see a generic "occupado" on the spot.
+
+---
+
+## 11. Multiplayer Networking (Expanded)
+
+### Server RPCs
+| RPC | Direction | Description |
+|-----|-----------|-------------|
+| `Server_EnterHideSpot` | Client→Server | Client requests entering hide spot. Server validates slot availability, proximity. |
+| `Server_ExitHideSpot` | Client→Server | Client requests exiting. Server validates, teleports player, replicates. |
+| `Server_StartPeek` | Client→Server | Client starts peeking. Server validates peek ability, starts duration timer. |
+| `Server_StopPeek` | Client→Server | Client stops peeking. Server returns to Hidden state. |
+| `Server_TryBreathHold` | Client→Server | Client holds breath. Server validates, applies noise reduction on server. |
+
+### Authority
+- `EnterHideSpot`, `ExitHideSpot` are server-authoritative.
+- `IsPlayerDetectable` is server-only — AI runs on server.
+- `PerformLOSCheck` runs on server; results multicast to clients for UI feedback.
+- `ForceKickFromHide` is server-only (triggered by enemy discovery / damage).
+
+### Client Prediction
+- Enter/exit animations: client predicts; server confirms via replicated `CurrentHideState`.
+- Peek: camera offset is local; state replicated.
+- Hide spot occupation: `I_HidingSpot.OccupantPawn` is replicated — other clients see "Occupied".
 - Hide spots with bBlocksStress = true can double as narrative safe rooms.
 
 ---

docs/blueprints/02-player/13_BPC_EmbodimentSystem.md

@@ -255,4 +255,21 @@ flowchart TD
 
 ---
 
+## 11. Multiplayer Networking
+
+**Replication: Minimal.** Embodiment is primarily local rendering. Only visibility mode and overlay state sync for shared visual consistency.
+
+| Variable | Condition | Purpose |
+|----------|-----------|---------|
+| `CurrentVisibility` | `Replicated` | Other clients see correct body visibility (FullBody in mirrors/death) |
+| `CurrentOverlay` | `Replicated` | Blood/water visible to other players |
+| Arms IK, wall proximity, overlay blending | **Local only** | First-person rendering is per-client |
+
+### Authority
+- `SetVisibilityMode` is server-authoritative for replicated variable; client applies local mesh changes.
+- `ApplyOverlay` and `ClearOverlay` are server-authoritative.
+- `CheckWallProximity` and `ApplyOverlayBlendTick` are **local only**.
+
+---
+
 *Blueprint Spec: Embodiment System. Conforms to TEMPLATE.md v1.0 — part of the UE5 Modular Game Framework.*

docs/blueprints/02-player/14_BPC_CameraStateLayer.md

@@ -326,4 +326,22 @@ flowchart TD
 
 ---
 
+## 11. Multiplayer Networking
+
+**Replication: State only — effects are local.** Camera FOV blending, shake, and post-processing are per-client experiences. Only the state enum syncs.
+
+| Variable | Condition | Purpose |
+|----------|-----------|---------|
+| `CurrentCameraState` | `Replicated` | Synced for shared context (e.g., all players know someone is aiming) |
+
+### Authority
+- `RequestCameraState` can be called by client; state replicates to all.
+- `PlayCameraShake`, `ApplyPostProcessOverride`, `BlendToTargetFOV` are **local only**.
+- FOV pulse, head bob, camera offset blending are **local only**.
+
+### Client Prediction
+- Camera is inherently local — no prediction needed. State changes replicate for other players' awareness.
+
+---
+
 *Blueprint Spec: Camera State Layer. Conforms to TEMPLATE.md v1.0 — part of the UE5 Modular Game Framework.*

docs/blueprints/02-player/15_BPC_PlayerMetricsTracker.md

@@ -332,4 +332,26 @@ flowchart TD
 
 ---
 
+## 11. Multiplayer Networking
+
+### Replication
+| Variable | Condition | Purpose |
+|----------|-----------|---------|
+| `CurrentSnapshot` | `Replicated` | Synced for scoreboard, playstyle classification |
+
+### Authority
+- **Server** accumulates all metrics (listens to gameplay dispatchers server-side).
+- **Server** creates periodic snapshots and replicates.
+- **Clients** only read metrics (for local HUD/scoreboard display).
+
+### Server RPCs
+| RPC | Direction | Description |
+|-----|-----------|-------------|
+| `Server_LogEvent` | Client→Server | Client reports a metric event. Server validates before recording. |
+
+### Anti-Cheat
+- Server validates `Server_LogEvent` calls: damage dealt must match server calculations, distance traveled must be plausible, item pickups validated by inventory system.
+
+---
+
 *Blueprint Spec: Player Metrics Tracker. Conforms to TEMPLATE.md v1.0 — part of the UE5 Modular Game Framework.*