# Polish — Tutorials, Loading, Credits, Debug, Analytics

**Game:** Project Void | **Build Phases:** 19, 20
**Framework Systems:** 106_BPC_AnalyticsTracker, 107_BPC_DevCheatManager, 108_BPC_ErrorHandler, 109_BPC_FPSCounter, 110_BPC_LoadingScreen, 111_BPC_TutorialSystem, 112_WBP_CreditsScreen, 113_WBP_DebugMenu, 114_WBP_SplashScreen

---

## Purpose

Covers all polish systems: tutorial triggers, loading screen, credits, debug tools, analytics, and error handling. These are finalized after core gameplay is working.

---

## Tutorial System (BPC_TutorialSystem)

### Tutorial Triggers

| Trigger Actor | Level | Condition | Teaches |
|--------------|-------|-----------|---------|
| `BP_TutorialTrigger_Controls` | L_Asylum_Entry | OnBeginPlay | Move WASD + Mouse Look |
| `BP_TutorialTrigger_Interact` | L_Asylum_Entry | OnOverlap with first item | Press E to interact |
| `BP_TutorialTrigger_Crouch` | L_Asylum_Entry | OnOverlap near vent | Press C to crouch through vents |
| `BP_TutorialTrigger_Hiding` | L_Asylum_Entry | OnOverlap near locker | Press E on hiding spots |
| `BP_TutorialTrigger_Combat` | L_Asylum_WardA | OnEquip first weapon | Fire/Reload/Aim basics |
| `BP_TutorialTrigger_Battery` | L_Asylum_Basement | OnOverlap in first dark room | Battery management for flashlight |

### Tutorial Prompt Behavior

```
BP_TutorialTrigger_* → Event BeginOverlap (Player)
   │
   ├─ [Already Shown?]
   │    └─ BPC_TutorialSystem.HasSeenTutorial(TutorialTag)? → Return
   │
   ├─ [Show Tutorial]
   │    ├─ WBP_NotificationToast (special tutorial variant):
   │    │    ├─ Large prompt text (e.g., "Press E to interact with objects")
   │    │    ├─ Key icon (E key or gamepad X/Square icon)
   │    │    ├─ Timer: 10 seconds or until condition met
   │    │    └─ Position: Top-center (not to block crosshair)
   │    │
   │    ├─ [Pause hint]
   │    │    ├─ Dim surrounding screen slightly
   │    │    └─ Highlight the interaction target (glow outline)
   │    │
   │    └─ BPC_TutorialSystem.MarkTutorialSeen(TutorialTag)
   │         └─ Won't show again this save slot
   │
   └─ [Dismiss Conditions]
        ├─ Player performs the action → auto-dismiss
        ├─ Player moves away from trigger → dismiss after 2s
        └─ Timer expires (10s) → auto-dismiss
```

---

## Loading Screen (BPC_LoadingScreen + WBP_LoadingHorror)

### Full Loading Flow

```
GI_GameFramework.SetGamePhase(Loading)
   │
   ├─ [Pre-Load]
   │    ├─ BPC_LoadingScreen.Activate()
   │    ├─ WBP_LoadingHorror.AddToViewport(ZOrder = 100 — above everything)
   │    ├─ SS_AudioManager.PlaySFX("loading_start")
   │    └─ Set background image based on destination chapter
   │
   ├─ [During Load]
   │    ├─ Tick → GetAsyncLoadPercentage() → UpdateProgressBar
   │    │    └─ Smooth interpolation (lerp to actual value)
   │    ├─ Tip rotation: every 8 seconds, show random tip
   │    ├─ Chapter title: "Ward A — Patient Wing"
   │    └─ Audio: loading ambient loop plays
   │
   └─ [On Level Loaded]
        ├─ Progress bar completes (snap to 100%)
        ├─ Brief pause (0.5s) so player sees complete bar
        ├─ SS_AudioManager.StopSFX("loading_start")
        ├─ WBP_LoadingHorror.RemoveFromParent()
        ├─ BPC_LoadingScreen.Deactivate()
        └─ GI_GameFramework.SetGamePhase(InGame)
```

### Loading Tips (DT_LoadingTips)

| Category | Tip |
|----------|-----|
| **Stealth** | "Darkness is your ally. Enemies can't see what they can't hear." |
| **Resource** | "Batteries are scarce. Use the flashlight sparingly." |
| **Exploration** | "Check every drawer. The asylum hides its secrets well." |
| **Survival** | "Your sanity is as important as your health. Find pills." |
| **Combat** | "Some enemies fear the light. Others are drawn to it." |
| **Lore** | "The void watches. It remembers. It waits." |
| **Puzzle** | "Not all doors need a key. Some need a different opening." |
| **Movement** | "Running attracts attention. Sometimes walking is survival." |
| **Inventory** | "Key items cannot be lost. They persist through death." |
| **Atmosphere** | "Listen. The asylum speaks to those who pay attention." |

---

## Credits Screen (WBP_CreditsScreen)

### Credits Layout

```
┌──────────────────────────────────────────────┐
│                                              │
│              PROJECT VOID                    │
│         ═══════════════════════              │
│                                              │
│    A Psychological Horror Experience         │
│                                              │
│    ──────── DEVELOPMENT ────────             │
│    Game Director:          [Name]            │
│    Lead Programmer:        [Name]            │
│    Systems Designer:       [Name]            │
│    Level Designer:         [Name]            │
│    Narrative Designer:     [Name]            │
│    Audio Designer:         [Name]            │
│    Environment Artist:     [Name]            │
│    Character Artist:       [Name]            │
│    UI/UX Designer:         [Name]            │
│    QA Lead:               [Name]            │
│                                              │
│    ──────── SPECIAL THANKS ────────          │
│    UE5 Modular Game Framework Team           │
│    GASP Animation System                     │
│    ...                                       │
│                                              │
│    ──────── POWERED BY ────────              │
│    Unreal Engine 5                           │
│                                              │
│    © 2026 [Studio Name]. All rights reserved.│
│    "In the void, memory is currency."        │
│                                              │
│    [SKIP — ESC]     [RETURN TO MENU — ENTER] │
└──────────────────────────────────────────────┘
```

### Credits Flow

```
L_Credits.OnBeginPlay
   │
   ├─ WBP_CreditsScreen.AddToViewport()
   ├─ Start scroll animation (Timeline: verticalTranslation, duration 45s)
   ├─ SS_AudioManager.PlayMusic("credits_theme", MS_MusicBus)
   │
   ├─ [Skip]
   │    └─ IA_SkipCutscene (Hold 1.5s) → jump to end
   │
   ├─ [On Complete]
   │    ├─ Show post-credit stats (WBP_DeathScreen variant)
   │    ├─ Achievement unlocks fire
   │    └─ Buttons: "Main Menu" / "New Game+"
   │
   └─ On Return to Menu → OpenLevel("L_MainMenu")
```

---

## Debug Tools (BPC_DevCheatManager + WBP_DebugMenu)

### Dev Cheats (BPC_DevCheatManager)

| Cheat | Key | Effect |
|-------|-----|--------|
| God Mode | `F1 → Toggle` | Infinite health, no damage |
| Noclip | `F2` | Fly through walls |
| Give Item | `F3 → type item tag` | Adds any item to inventory |
| Teleport | `F4 → click on level` | Teleport to cursor location |
| Toggle AI | `F5` | Freeze/unfreeze all AI |
| Toggle HUD | `F6` | Show/hide HUD for screenshots |
| Spawn Enemy | `F7 → select type` | Spawn test enemy at cursor |
| Stress Slider | `F8 → mouse wheel` | Adjust player stress 0-100 |
| Skip Chapter | `F9 → select chapter` | Jump to any level |
| Reload Level | `F10` | Quick level restart |
| Toggle Debug | `F11` | Show AI paths, perception, stress values |

### WBP_DebugMenu (toggle via F11 or console command)

```
Debug Menu Tabs:
  ├─ [State Viewer]
  │    ├─ Current Game Phase
  │    ├─ Player Health / Stamina / Stress / Sanity
  │    ├─ Active chapter
  │    ├─ Current BPC_StateManager state
  │    ├─ All narrative flags (map view)
  │    └─ Active objectives
  │
  ├─ [Inventory]
  │    ├─ Grid view of all items
  │    ├─ Add/Remove buttons
  │    └─ Weight/space display
  │
  ├─ [AI]
  │    ├─ List all active enemies + states
  │    ├─ Toggle AI perception debug (cones + hearing radius)
  │    ├─ Toggle patrol path display
  │    └─ Force alert/calm all enemies
  │
  ├─ [Performance]
  │    ├─ FPS counter (min/max/avg)
  │    ├─ Memory usage
  │    ├─ Draw calls
  │    └─ Actor count
  │
  ├─ [Audio]
  │    ├─ Bus volume sliders (live)
  │    ├─ Active room zone
  │    └─ Playing sounds list
  │
  └─ [Cheats] (if enabled)
       ├─ God Mode, Noclip toggles
       ├─ Give Item dropdown
       ├─ Teleport to cursor
       └─ Skip Chapter dropdown
```

---

## Error Handler (BPC_ErrorHandler)

```
BPC_ErrorHandler — catches and handles errors gracefully

OnError(ErrorMessage, ErrorSeverity)
   │
   ├─ Severity == Warning:
   │    ├─ FL_GameUtilities.LogWarning(ErrorMessage)
   │    └─ WBP_NotificationToast.Show("Warning: " + ErrorMessage, 5s)
   │
   ├─ Severity == Error:
   │    ├─ FL_GameUtilities.LogError(ErrorMessage)
   │    ├─ WBP_NotificationToast.Show("Error: " + ErrorMessage, 10s)
   │    └─ (Continue execution if recoverable)
   │
   └─ Severity == Critical:
        ├─ FL_GameUtilities.LogCritical(ErrorMessage)
        ├─ BPC_AnalyticsTracker.LogCrash(ErrorMessage, StackTrace)
        ├─ SS_SaveManager.QuickSave("CrashRecovery")
        ├─ Show error screen:
        │    ├─ "A critical error occurred."
        │    ├─ "Your progress has been saved."
        │    ├─ [Return to Main Menu]
        │    └─ [Send Error Report] (if analytics enabled)
        └─ OpenLevel("L_MainMenu") (safe fallback)
```

---

## FPS Counter (BPC_FPSCounter) — Dev Only

```
BPC_FPSCounter — Simple FPS display in top-right corner

Config:
  ├─ bShowFPS: Bool (default: false — enable via debug menu or -showfps launch arg)
  ├─ bShowMinMax: Bool
  ├─ UpdateInterval: Float (0.5s)

Display Format:
  "FPS: 60 | Min: 42 | Max: 120"
  
Colors:
  ├─ FPS >= 60: Green
  ├─ FPS 30-59: Yellow
  └─ FPS < 30: Red

Launch Arg: -ShowFPS → auto-enables on boot
```

---

## Analytics Tracker (BPC_AnalyticsTracker) — Opt-in

```
BPC_AnalyticsTracker tracks session metrics:

Session Events:
  ├─ GameStart (timestamp, platform, settings)
  ├─ GameEnd (ending, playtime, deaths, timestamp)
  ├─ ChapterEnter (chapter tag, timestamp)
  ├─ ChapterComplete (chapter tag, time spent, deaths during chapter)
  ├─ PlayerDeath (cause, location, chapter, time in chapter)
  ├─ ItemPickup (item tag, location, chapter)
  ├─ WeaponUsed (weapon tag, shots fired, hits, misses)
  ├─ PuzzleSolved (puzzle tag, time spent, hints used)
  ├─ ScareExperienced (scare tag, location)
  ├─ MenuOpen (menu type, duration)
  ├─ Crash (error message, stack trace, last 10 events)
  └─ SettingsChanged (setting name, old value, new value)

Privacy:
  ├─ All analytics are OPT-IN (prompt on first launch)
  ├─ No PII collected (no usernames, IP addresses)
  ├─ Data stored locally, sent only if player enables
  └─ SS_SettingsSystem stores analytics consent
```

---

## Blueprint Wiring Checklist

### Tutorials
- [ ] Create 6 `BP_TutorialTrigger_*` actors
- [ ] Wire `BPC_TutorialSystem` with seen-tutorial tracking
- [ ] Create tutorial variant of `WBP_NotificationToast`
- [ ] Place triggers at appropriate tutorial moments in levels

### Loading
- [ ] Wire `BPC_LoadingScreen` to game phase changes (InGame ↔ Loading)
- [ ] Create `DT_LoadingTips` Data Table with 10 tips
- [ ] Wire tip rotation + progress bar + background selection

### Credits
- [ ] Create `L_Credits` level with dark background
- [ ] Create scroll animation for credits text
- [ ] Wire post-credit stats display + achievement checks

### Debug
- [ ] Create `BPC_DevCheatManager` with all cheat functions
- [ ] Create `WBP_DebugMenu` with 5 tabs
- [ ] Bind cheats to F1-F11 keys (dev only, exclude from shipping)
- [ ] Add `BPC_FPSCounter` with -ShowFPS launch arg

### Error Handling
- [ ] Wire `BPC_ErrorHandler` to catch critical errors
- [ ] Create error screen widget with Return to Menu button
- [ ] Wire crash auto-save before error screen

### Analytics
- [ ] Wire `BPC_AnalyticsTracker` to key events (death, chapter, item, scare)
- [ ] Add analytics consent prompt on first launch
- [ ] Wire opt-in/opt-out toggle in Settings

---

## Notes for Expansion

- Add **achievement integration**: all polish systems should fire achievement checks
- Add **speedrun timer**: optional HUD element showing real-time + chapter splits
- Add **photo mode**: pause game, free camera, filters, hide HUD
- Add **benchmarking tool**: automated walkthrough to measure performance
- Add **controller remapping UI**: rebind every action via `SS_EnhancedInputManager.RebindKey()`
- Add **multi-language support**: loading tips, tutorial text, credits in localized string tables
- All debug tools and cheats must be **excluded from shipping builds** (use `#if !UE_BUILD_SHIPPING`)

---

*Polish Systems for Project Void. See [GAMEINDEX.md](GAMEINDEX.md) for full game structure. See [13-polish/](../blueprints/13-polish/) for framework polish system specs.*
