UE5-Modular-Game-Framework/docs/game/polish-loading-credits.md

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 for full game structure. See 13-polish/ for framework polish system specs.