add blueprints

docs/blueprints/05-saveload/38_BPC_AltDeathSpaceSystem.md

@@ -0,0 +1,95 @@
+# BPC_AltDeathSpaceSystem — Actor Component (Alt Death Space)
+
+**File:** [`Content/Framework/Save/BPC_AltDeathSpaceSystem`](Content/Framework/Save/BPC_AltDeathSpaceSystem.uasset)
+
+**Purpose:** Manages the limbo / between-world death space where the player can wander, find clues, or trigger special mechanics before being returned to the living world.
+
+**Depends On:** [`BPC_DeathHandlingSystem`](BPC_DeathHandlingSystem.md), [`BP_Checkpoint`](BP_Checkpoint.md), [`SS_SaveManager`](35_SS_SaveManager.md)
+**Used By:** [`BPC_DeathHandlingSystem`](BPC_DeathHandlingSystem.md) (orchestrator)
+
+---
+
+## Variables
+
+| Name | Type | Description |
+|------|------|-------------|
+| `AltDeathSpaceMap` | Map (GameplayTag → Level Soft Reference) | Tag-to-level mapping for alt death space variants |
+| `CurrentAltDeathSpace` | Level Soft Reference | The active alt death space level |
+| `AltDeathSpaceEnterCount` | Integer | How many times the player has entered alt space this run |
+| `ExitPortalTransform` | Transform | Where the player emerges back into the living world |
+| `bIsInAltDeathSpace` | Bool | Is the player currently in the alt death space? |
+| `AltSpaceTimeline` | Float | Current time-in-alt-space (for atmosphere changes) |
+| `MaxTimeInAltSpace` | Float | Max seconds before forced exit (default 60.0) |
+
+---
+
+## Functions
+
+| Name | Inputs | Outputs | Description |
+|------|--------|---------|-------------|
+| `EnterAltDeathSpace` | Context: S_DeathContext | — | Loads the alt death space level, moves player |
+| `ExitAltDeathSpace` | — | — | Unloads alt space, returns player to ExitPortalTransform |
+| `GetCurrentAltDeathSpaceTag` | — | GameplayTag | Returns which variant of alt space the player is in |
+| `SetExitPortal` | Transform: Transform | — | Sets where the player exits alt space |
+| `IsInAltDeathSpace` | — | Bool | Public getter for bIsInAltDeathSpace |
+
+---
+
+## Event Dispatchers
+
+| Name | Parameters | Fired When |
+|------|-----------|------------|
+| `OnEnteredAltDeathSpace` | SpaceTag: GameplayTag | Player enters alt death space |
+| `OnExitedAltDeathSpace` | — | Player exits alt death space back to living world |
+| `OnAltSpaceTimeLow` | RemainingSeconds: Float | 10s remaining before forced exit (every 1s tick) |
+| `OnAltSpaceForcedExit` | — | Timer expired, player forcibly returned |
+
+---
+
+## Blueprint Flow
+
+```
+[EnterAltDeathSpace]
+  └─► Set bIsInAltDeathSpace = true
+  └─► Increment AltDeathSpaceEnterCount
+  └─► Lookup CurrentAltDeathSpace from AltDeathSpaceMap by Context tag
+  └─► Load stream level (CurrentAltDeathSpace)
+  └─► Move player to level entry point
+  └─► Set ExitPortalTransform to Context.CurrentCheckpoint respawn location
+  └─► Start AltSpaceTimeline countdown
+  └─► Broadcast OnEnteredAltDeathSpace
+
+[ExitAltDeathSpace]
+  └─► Unload alt death space stream level
+  └─► Move player to ExitPortalTransform
+  └─► Set bIsInAltDeathSpace = false
+  └─► Broadcast OnExitedAltDeathSpace
+
+[Tick: AltSpaceTimeline]
+  └─► If TimeRemaining <= 10.0:
+         Broadcast OnAltSpaceTimeLow(TimeRemaining)
+  └─► If TimeRemaining <= 0:
+         Broadcast OnAltSpaceForcedExit
+         ExitAltDeathSpace()
+```
+
+---
+
+## Communications With
+
+| Target System | Method | Why |
+|---------------|--------|-----|
+| [`BPC_DeathHandlingSystem`](BPC_DeathHandlingSystem.md) | Direct call | Orchestrator triggers enter/exit |
+| [`BP_Checkpoint`](BP_Checkpoint.md) | Direct call | Get respawn transform for exit portal |
+| [`SS_SaveManager`](35_SS_SaveManager.md) | Direct call | Save alt space state |
+| [`BPC_AtmosphereStateController`](../10-adaptive/BPC_AtmosphereStateController.md) | Dispatcher | Atmosphere changes based on time in alt space |
+| [`SS_AudioManager`](../10-adaptive/132_SS_AudioManager.md) | Direct call | Audio ambience for alt space (`PlayAmbient()`, `SetRoomPreset()`) |
+
+---
+
+## Reuse Notes
+- Alt death space levels are loaded via `UGameplayStatics::LoadStreamLevel` and must be in the persistent level's Streaming Levels list
+- The ExitPortalTransform is set to the last checkpoint location by default, but can be overridden by alt space mechanics
+- Alt space variants are data-driven via AltDeathSpaceMap — designers add new entries without code changes
+- The MaxTimeInAltSpace timer prevents the player from being stuck indefinitely
+- Split from original bundled `31_BPC_DeathHandlingSystem.md` per Clean Slate refactoring plan