# 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.*