040db37720
- Created ui-overrides.md detailing game-specific Widget Blueprint overrides, including purpose, widget index, visual styling, and accessibility requirements. - Established weapons-index.md outlining all held weapon actors, including their components, logic, and comparisons for gameplay mechanics.
355 lines
13 KiB
Markdown
355 lines
13 KiB
Markdown
# 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.*
|