UE5-Modular-Game-Framework/docs/architecture/CLEAN_SLATE_PLAN.md

Clean Slate Refactoring Plan

Date: 2026-05-18 Source: docs/blueprints/AUDIT_REPORT.md Master: UE5_Modular_Game_Framework.md Goal: Every Master-defined system has exactly 1 blueprint spec file with matching name. No bundled files. Consistent directory structure.

---

1. Problem Statement

The current docs/blueprints/ tree has 83 files covering ~131 Master systems via bundling, renaming, and relocation. This makes blueprint authoring ambiguous: an implementer cannot find a Master system by its name because the file is renamed, bundled inside another file, or in the wrong directory. Clean Slate makes the mapping 1:1.

---

2. Proposed Solution

flowchart TD
    A[AUDIT_REPORT.md] --> B[Step 1: Rename 18 files to match Master]
    B --> C[Step 2: Split 2 bundled files into 12 individual files]
    C --> D[Step 3: Create 12 new Data Asset spec files in 12-data/]
    D --> E[Step 4: Create 30 new runtime system spec files in existing directories]
    E --> F[Step 5: Reorganize 11-polish/ into 3 sub-directories]
    F --> G[Step 6: Remove obsolete bundled umbrella files]
    G --> H[Step 7: Renumber all files sequentially across all directories]
    H --> I[Final: ~155 files, 1:1 master-to-file mapping]

---

3. Target Directory Structure (Final State)

docs/blueprints/
├── TEMPLATE.md
├── AUDIT_REPORT.md
├── 01-core/            (12 files)  — GameInstance, GameMode, GameState, Subsystems, Interfaces, FL, DataAssets
├── 02-player/          (9 files)   — All BPC_ player components + contextual traversal
├── 03-interaction/     (11 files)  — Interaction detection/execution, doors, puzzles, hiding spots, physics
├── 04-inventory/       (12 files)  — Inventory, equipment, items, combine, documents, journal, collectibles
├── 05-saveload/        (9 files)   — SaveManager, Persistable, Checkpoint, DeathOrchestrator, 4 death sub-systems
├── 06-ui/              (13 files)  — HUD, menus (1 per widget), notifications, screen effects, menu flow
├── 07-narrative/       (11 files)  — Narrative state, objectives, dialogue, choices, cutscenes, endings, lore
├── 08-weapons/         (12 files)  — Weapons, melee, firearms, ammo, damage, recoil, reload, shield, reactions
├── 09-ai/              (9 files)   — AI controller, perception, behavior trees, enemies, patrol, alert, state machine
├── 10-adaptive/        (9 files)   — Atmosphere, lighting, audio, VFX, fear, pacing, procedural encounters
├── 11-meta/            (6 files)   — Achievements, stats tracker, ending tracker, meta progression, run summary
├── 12-settings/        (5 files)   — Settings system, accessibility, haptics, platform abstraction, settings UI
├── 13-polish/          (10 files)  — Tutorial, loading, credits, splash, FPS, cheats, debug, analytics, error handler
└── 14-data-assets/     (13 files)  — 1 Data Asset Architecture overview + 12 individual DA_ specs

Total files: ~155 (including TEMPLATE.md and AUDIT_REPORT.md)

---

4. Operation Details

4.1 RENAME Operations (18 files)

Each rename changes the filename to match the Master document system name exactly.

Current File	Directory	New Name	Master Ref	Reason
22_BPC_InventoryComponent.md	04-inventory	BPC_InventorySystem.md	Sec 4.1	Master name
25_BPC_EquipmentSystem.md	04-inventory	BPC_EquipmentSlotSystem.md	Sec 4.2	Master name
50_BP_RangedWeapon.md	08-weapons	BPC_FirearmSystem.md	Sec 5.2	Wrong prefix + Master name
51_BP_MeleeWeapon.md	08-weapons	BPC_MeleeSystem.md	Sec 5.1	Wrong prefix + Master name
53_BPC_DamageHandlerComponent.md	08-weapons	BPC_DamageReceptionSystem.md	Sec 5.6	Master name
33_WBP_HUD.md	06-ui	WBP_HUDController.md	Sec 6.1	Master name
35_WBP_InteractionUI.md	06-ui	WBP_InteractionPromptDisplay.md	Sec 6.3	Master name
34_WBP_InventoryUI.md	06-ui	WBP_InventoryMenu.md	Sec 6.4	Master name
45_BPC_EndingAccumulatorSystem.md	07-narrative	BPC_EndingAccumulator.md	Sec 7.8	Drop System suffix
47_BPC_NarrativeTriggerVolume.md	07-narrative	BP_NarrativeTriggerVolume.md	Sec 7.10	Component→Actor
55_BPC_AIControllerBase.md	09-ai	AI_BaseAgentController.md	Sec 10.1	Master type prefix
56_BPC_PerceptionComponent.md	09-ai	BPC_AIPerceptionSystem.md	Sec 10.3	Master name
64_BPC_AtmosphereController.md	10-adaptive	BPC_AtmosphereStateController.md	Sec 9.4	Master name
65_BPC_LightingManager.md	10-adaptive	BPC_LightEventController.md	Sec 9.6	Master name
66_BPC_AudioManager.md	10-adaptive	BPC_AudioAtmosphereController.md	Sec 9.7	Master name
20_BPC_InteractableDoorComponent.md	03-interaction	BP_DoorActor.md	Sec 3.5	Master type + name
30_BPC_CheckpointSystem.md	05-saveload	BP_Checkpoint.md	Sec 8.1	Verify master name
28_SS_SaveManager.md	05-saveload	Keep as-is	Sec 1.2	Master uses SS_SaveSystem; file content is the save manager. Decision: keep SS_SaveManager as it accurately describes the subsystem.

Note on file 28: Master Section 1 calls it SS_SaveSystem but the file is named SS_SaveManager and contains full save management logic. The Master Section 8 may use SS_SaveManager. For Clean Slate consistency, the file stays as SS_SaveManager since that's what the detailed system definition calls it.

4.2 SPLIT Operations (2 bundled files → 12 individual files)

4.2.1 Split 31_BPC_DeathHandlingSystem.md → 5 files

The existing file (311 lines) contains the orchestrator component plus 4 sub-systems each with purpose, variables, functions, and event dispatchers. Each sub-system becomes a standalone file. The orchestrator keeps the parent-level enums, structs, core component variables, core functions, the flow diagram, and the communication matrix.

#	New File	Source Lines	System Name
1	BPC_DeathHandlingSystem.md	1-64, 206-311	Orchestrator (enums, structs, core vars, core fns, flow, matrix)
2	BPC_AltDeathSpaceSystem.md	65-99	Alt death space management
3	BPC_PersistentCorpseSystem.md	102-132	Corpse spawning and persistence
4	BPC_PlayerRespawnSystem.md	136-167	Respawn mechanics
5	BPC_RunHistoryTracker.md	171-203	Run-level death tracking

Mapping: Master Section 8 lists BPC_AltDeathSpaceSystem, BPC_PlayerRespawnSystem, BPC_RunHistoryTracker as separate systems (8.5–8.7). The split matches the Master's structure.

4.2.2 Split 36_WBP_MenuWidgets.md → 7 files

The existing file (353 lines) bundles 6 widgets under one umbrella. Each widget has its own purpose, variables, functions, and in one case an enum. Split each into a standalone file.

#	New File	Source Lines	Widget Name
1	WBP_MainMenu.md	15-48	Title screen with New/Continue/Load/Settings/Credits/Quit
2	WBP_PauseMenu.md	51-94	In-game pause overlay
3	WBP_SettingsMenu.md	99-188	Full settings screen with 5 tabs
4	WBP_NotificationToast.md	191-230	Non-blocking toast notification
5	WBP_ScreenEffectController.md	233-261	Damage vignettes, jump scare flash, stress distortion
6	WBP_MenuFlowController.md	264-353	Menu state transitions, fades, level loading
7	(Extra) WBP_ObjectiveDisplay.md	—	Not in bundled file; master lists it as 6.6

Mapping: Master Section 6 lists all 6 widgets plus WBP_ObjectiveDisplay (Sec 6.6), WBP_SubtitleDisplay (Sec 6.7), WBP_JournalDocumentViewer (Sec 6.5), and WBP_DiegeticHUDFrame (Sec 6.2). The existing 37_WBP_AccessibilityUI.md already covers subtitles. Two widgets remain missing (WBP_JournalDocumentViewer, WBP_DiegeticHUDFrame — addressed in section 4.4).

Original umbrella file 36_WBP_MenuWidgets.md is DELETED after splits.

4.3 CREATE Operations — 12 Data Asset Specs (new 14-data-assets/ directory)

Master Section 13 defines 20 Data Asset types. 8 are already covered (07_DA_ItemData.md, 48_DA_NarrativeDataAssets.md covers 5, 49_BP_WeaponBase.md covers DA_WeaponData, 74_BPC_AchievementManager.md implicitly covers DA_AchievementData). 12 have no spec.

Create these 13 files in a new docs/blueprints/14-data-assets/ directory:

#	File	Master Ref	Purpose
1	DA_DataAssetArchitecture.md	Sec 13 overview	All 20 DA types, naming conventions, dependency rules, build order
2	DA_InteractionData.md	Sec 13	Interaction prompt types, requirements, target filters
3	DA_ObjectiveData.md	Sec 13	Objective definitions, states, rewards
4	DA_EncounterData.md	Sec 13	Enemy encounter configurations
5	DA_AtmosphereProfile.md	Sec 13	Lighting, audio, fog, post-process presets
6	DA_ScareEvent.md	Sec 13	Scare trigger definitions, jump scares, ambient horror
7	DA_RoomMutation.md	Sec 13	Environmental mutation content, memory drift
8	DA_BehaviourVariant.md	Sec 13	AI behavior variant stats, aggression, patrol patterns
9	DA_HapticProfile.md	Sec 13	DualSense/DualShock haptic patterns
10	DA_AdaptationRule.md	Sec 13	Adaptive director rule sets
11	DA_EquipmentConfig.md	Sec 13	Equipment slot configurations
12	DA_PuzzleData.md	Sec 13	Puzzle solution definitions, input/output mappings
13	DA_RareEvent.md	Sec 13	Rare world event definitions

Each Data Asset spec must include: Parent Class (UDataAsset), Gameplay Tags namespace, struct definition for rows, example data rows, validation rules, and which systems consume it.

4.4 CREATE Operations — 30 Runtime System Specs (in existing directories)

03-interaction/ (add 4 files)

#	File	Master Ref	Purpose
1	BPC_PhysicsDragSystem.md	Sec 3.4	Physics grab, drag, throw
2	BPC_ContextualTraversalSystem.md	Sec 3.8	Vault, climb, ledge grab
3	BP_PuzzleDeviceActor.md	Sec 3.9	Generic puzzle with input/output
4	BPC_UsableWorldObjectSystem.md	Sec 3.10	Light switches, levers, simple on/off objects

04-inventory/ (add 7 files)

#	File	Master Ref	Purpose
1	BPC_ActiveItemSystem.md	Sec 4.3	Active hand item, raise/lower animations
2	BPC_ItemCombineSystem.md	Sec 4.5	Item combination mechanic
3	BPC_DocumentArchiveSystem.md	Sec 4.6	Document/note storage and reading
4	BPC_JournalSystem.md	Sec 4.7	Player journal with entries
5	BPC_CollectibleTracker.md	Sec 4.8	Collectible discovery tracking
6	BPC_ConsumableSystem.md	Sec 4.9	Consumable item usage logic
7	BPC_KeyItemSystem.md	Sec 4.11	Key item management and protection

05-saveload/ (add 1 file)

#	File	Master Ref	Purpose
1	BPC_PersistentWorldStateRecorder.md	Sec 8.2	World state recording for save (currently bundled in SS_SaveManager)

06-ui/ (add 3 files)

#	File	Master Ref	Purpose
1	WBP_DiegeticHUDFrame.md	Sec 6.2	Swappable diegetic HUD skin
2	WBP_JournalDocumentViewer.md	Sec 6.5	Document and journal display widget
3	WBP_ObjectiveDisplay.md	Sec 6.6	Objective overlay widget

08-weapons/ (add 5 files)

#	File	Master Ref	Purpose
1	BPC_RecoilSystem.md	Sec 5.3	Procedural recoil
2	BPC_ReloadSystem.md	Sec 5.4	Weapon reload management
3	BPC_ShieldDefenseSystem.md	Sec 5.5	Blocking and parrying
4	BPC_HitReactionSystem.md	Sec 5.7	Hit reaction behaviour
5	BPC_DeathCauseTracker.md	Sec 5.8	Death cause logging

Note: BPC_AmmoResourceSystem (Sec 4.10) is handled by moving/renaming 52_BPC_AmmoComponent.md from 08-weapons to 04-inventory.

09-ai/ (add 3 files + relocate 1)

#	File	Master Ref	Purpose
1	BB_AgentBoard.md	Sec 10.2	Blackboard asset for AI agents
2	BPC_AIMemorySystem.md	Sec 10.4	AI memory of player actions
3	BPC_BehaviourVariantSelector.md	Sec 10.5	Behaviour variant selection
4	BPC_EncounterDirector.md	Sec 10.6	Relocated from 10-adaptive (currently 70_BPC_ProceduralEncounter.md)

10-adaptive/ (add 5 files)

#	File	Master Ref	Purpose
1	BPC_PlaystyleClassifier.md	Sec 9.1	Player playstyle analysis
2	BPC_AdaptiveEnvironmentDirector.md	Sec 9.2	Master adaptive controller
3	BPC_MemoryDriftSystem.md	Sec 9.3	Room mutation / environmental drift
4	BPC_ScareEventSystem.md	Sec 9.5	Scare event scheduling and triggering
5	BPC_PacingDirector.md	Sec 9.8	Tension and pacing control
6	BPC_RareEventSystem.md	Sec 9.9	Rare world events

New 11-meta/ directory (move 3 from 11-polish + add 3 new)

Existing files to move from 11-polish:

• 74_BPC_AchievementManager.md → SS_AchievementSystem.md
• 75_BPC_StatsTracker.md → BPC_ProgressStatTracker.md

New files:

#	File	Master Ref	Purpose
1	BPC_EndingCompletionTracker.md	Sec 11.4	Ending tracking across save files
2	BPC_MetaProgressionSystem.md	Sec 11.5	NG+ unlock system
3	BPC_RunSummarySystem.md	Sec 11.6	End-of-run summary generation

New 12-settings/ directory (move 2 from 11-polish + add 2 new)

Existing files to move from 11-polish:

• 71_SS_SettingsManager.md → SS_SettingsSystem.md
• 72_BPC_AccessibilitySettings.md

New files:

#	File	Master Ref	Purpose
1	BPC_HapticsController.md	Sec 12.2	Haptic feedback (DualSense)
2	BPC_PlatformServiceAbstraction.md	Sec 12.3	Platform API abstraction layer

4.5 REORGANIZE Operations — 11-polish/ split into 3 directories

The current 11-polish/ directory has 13 files spanning 3 different Master sections plus extras. Split into:

11-meta/ (6 files) — Achievement, progression, meta systems:

• SS_AchievementSystem.md (from 74_BPC_AchievementManager.md)
• DA_AchievementData.md (extracted from achievement manager or optionally kept bundled)
• BPC_ProgressStatTracker.md (from 75_BPC_StatsTracker.md)
• BPC_EndingCompletionTracker.md (new)
• BPC_MetaProgressionSystem.md (new)
• BPC_RunSummarySystem.md (new)

12-settings/ (5 files) — Settings, accessibility, platform:

• SS_SettingsSystem.md (from 71_SS_SettingsManager.md)
• BPC_AccessibilitySettings.md (from 72_BPC_AccessibilitySettings.md)
• BPC_HapticsController.md (new)
• BPC_PlatformServiceAbstraction.md (new)
• WBP_SettingsMenu.md (from 06-ui after menu split — it's the settings widget)

13-polish/ (10 files) — Remaining polish/extras:

• BPC_TutorialSystem.md (from 73_BPC_TutorialSystem.md)
• BPC_LoadingScreen.md (from 76_BPC_LoadingScreen.md)
• WBP_CreditsScreen.md (from 77_WBP_CreditsScreen.md)
• WBP_SplashScreen.md (from 78_WBP_SplashScreen.md)
• BPC_FPSCounter.md (from 79_BPC_FPSCounter.md)
• BPC_DevCheatManager.md (from 80_BPC_DevCheatManager.md)
• WBP_DebugMenu.md (from 81_WBP_DebugMenu.md)
• BPC_AnalyticsTracker.md (from 82_BPC_AnalyticsTracker.md)
• BPC_ErrorHandler.md (from 83_BPC_ErrorHandler.md)
• WBP_NotificationToast.md (relocated from 06-ui after menu split — it's a global toast, not menu-specific)

4.6 RENUMBER Operations

After all renames, splits, creates, and reorganizations, assign sequential numbering starting from 01. Numbering is global across all directories (keeps the current convention).

Numbering Priority Order:

1. 01-core/ → 1–12
2. 02-player/ → 13–21
3. 03-interaction/ → 22–32
4. 04-inventory/ → 33–44
5. 05-saveload/ → 45–53
6. 06-ui/ → 54–66
7. 07-narrative/ → 67–77
8. 08-weapons/ → 78–89
9. 09-ai/ → 90–98
10. 10-adaptive/ → 99–107
11. 11-meta/ → 108–113
12. 12-settings/ → 114–118
13. 13-polish/ → 119–128
14. 14-data-assets/ → 129–141

Total: ~141 numbered files + TEMPLATE.md + AUDIT_REPORT.md = ~143 total

4.7 DELETE Operations

File to Delete	Reason
06-ui/36_WBP_MenuWidgets.md	Split into 7 individual widget files
05-saveload/31_BPC_DeathHandlingSystem.md (original)	Replaced by 5 split files
03-interaction/17_BPC_PickupComponent.md	Not in Master; functionality covered by InteractionExecutor + ItemPickup
03-interaction/19_BPC_LeverPuzzleComponent.md	Not in Master; covered by BP_PuzzleDeviceActor
04-inventory/23_BPC_InventoryWeightSystem.md	Not in Master; weight is a sub-feature of InventorySystem
04-inventory/24_BPC_InventoryQuickSlot.md	Not in Master; quick slots are sub-feature of ActiveItemSystem
09-ai/57_BPC_BehaviorTreeManager.md	Not in Master; covered by BB_AgentBoard + BPC_BehaviourVariantSelector

---

5. File Count Summary

Phase	Operation	Count
Start	Existing files (including TEMPLATE + AUDIT)	85
	Rename (in-place, no net change)	18
	Split 2 bundled → 12 individual (-2 +12)	+10
	Create new runtime specs	+30
	Create new Data Asset specs	+13
	Reorganize (move across dirs, no net change)	0
	Delete extra/unmatched files	-7
End	Final file count	~141

---

6. Dependencies and Rules

Content Creation Rules (for Execution Agent)

1. Every new file MUST follow TEMPLATE.md format
2. Parent Class, Dependencies, Purpose are mandatory sections
3. Variables must have Name, Type, Description columns
4. Functions must have Name, Inputs, Outputs, Description columns
5. Event Dispatchers must have Name, Parameters, "Fired When" columns
6. Every spec must include a Blueprint Flow Diagram (Mermaid)
7. Every spec must include a Communication Matrix
8. Every spec must include Reuse Notes

Master Document Authority

• The Master document (UE5_Modular_Game_Framework.md) is the single source of truth for system names, types, and dependencies
• When in doubt about a variable or function name, consult the Master document section for that system
• If the Master document does not specify a detail, use the naming conventions defined in Section 13 of the Master

Naming Conventions (from Master Section 13)

Prefix	Asset Type
BP_	Blueprint Actor
BPC_	Blueprint Actor Component
WBP_	Widget Blueprint
I_	Blueprint Interface
DA_	Data Asset
E_	Enumeration
S_	Structure
GI_	Game Instance
GM_	Game Mode
GS_	Game State
SS_	Subsystem
FL_	Function Library
AI_	AI Controller
BB_	Blackboard
BTT_	Behavior Tree Task
BTS_	Behavior Tree Service
BTD_	Behavior Tree Decorator

---

7. Success Criteria

1. Every system in the Master document (Sections 1–13) has exactly 1 blueprint spec file
2. Every blueprint spec file name matches the Master system name exactly (including prefix)
3. No file bundles multiple Master-defined systems
4. Directory structure maps cleanly to Master sections
5. All markdown cross-references ([link](file.md)) are valid
6. All files follow TEMPLATE.md format
7. Sequential file numbering is contiguous from 01 to ~141
8. AUDIT_REPORT.md is updated to reflect final state (all ✅)
9. CONTEXT.md is updated with final directory structure and file count
10. git status shows clean, logical file operations (renames detected as renames, not delete+create)

---

End of Clean Slate Plan