Add UI Overrides and Weapons Index documentation for Project Void

- 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.
2026-05-21 22:27:57 +03:00
parent c515920eea
commit 040db37720
17 changed files with 6795 additions and 43 deletions
--- a/docs/game/polish-loading-credits.md
+++ b/docs/game/polish-loading-credits.md
@@ -0,0 +1,354 @@
+# 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.*