admin/UE5-Modular-Game-Framework
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
4a7c871f29d3220aac1c4c41619b7326abc417f2
UE5-Modular-Game-Framework/docs/checklists/clean-slate-refactor.md
admin 08fe41d296 add checklists
2026-05-19 10:18:28 +00:00

15 KiB
Raw Blame History

Clean Slate Refactoring — Implementation Checklist

Source Plan: docs/architecture/CLEAN_SLATE_PLAN.md Master Document: UE5_Modular_Game_Framework.md Audit: docs/blueprints/AUDIT_REPORT.md Template: docs/blueprints/TEMPLATE.md

Phase 0 — Setup

  • 0.1 Verify current git status is clean (commit any pending changes first)
  • 0.2 Create branch refactor/clean-slate from main
  • 0.3 Confirm all 83 blueprint files are readable and not corrupted

Phase 1 — Rename 18 Files to Match Master Naming

Each task: delete old file, create new file at same location with corrected name, update internal header line.

03-interaction/

  • 1.1 Rename 20_BPC_InteractableDoorComponent.md → BP_DoorActor.md

04-inventory/

  • 1.2 Rename 22_BPC_InventoryComponent.md → BPC_InventorySystem.md
  • 1.3 Rename 25_BPC_EquipmentSystem.md → BPC_EquipmentSlotSystem.md

05-saveload/

  • 1.4 Rename 30_BPC_CheckpointSystem.md → BP_Checkpoint.md (if Master uses BP_ prefix; verify against Master line)

06-ui/

  • 1.5 Rename 33_WBP_HUD.md → WBP_HUDController.md
  • 1.6 Rename 34_WBP_InventoryUI.md → WBP_InventoryMenu.md
  • 1.7 Rename 35_WBP_InteractionUI.md → WBP_InteractionPromptDisplay.md

07-narrative/

  • 1.8 Rename 45_BPC_EndingAccumulatorSystem.md → BPC_EndingAccumulator.md
  • 1.9 Rename 47_BPC_NarrativeTriggerVolume.md → BP_NarrativeTriggerVolume.md

08-weapons/

  • 1.10 Rename 50_BP_RangedWeapon.md → BPC_FirearmSystem.md
  • 1.11 Rename 51_BP_MeleeWeapon.md → BPC_MeleeSystem.md
  • 1.12 Rename 53_BPC_DamageHandlerComponent.md → BPC_DamageReceptionSystem.md

09-ai/

  • 1.13 Rename 55_BPC_AIControllerBase.md → AI_BaseAgentController.md
  • 1.14 Rename 56_BPC_PerceptionComponent.md → BPC_AIPerceptionSystem.md

10-adaptive/

  • 1.15 Rename 64_BPC_AtmosphereController.md → BPC_AtmosphereStateController.md
  • 1.16 Rename 65_BPC_LightingManager.md → BPC_LightEventController.md
  • 1.17 Rename 66_BPC_AudioManager.md → BPC_AudioAtmosphereController.md

Verify

  • 1.18 Verify all 18 renamed files exist and old files are deleted

Phase 2 — Split Two Bundled Files

2.1 Split DeathHandlingSystem (1 file → 5 files)

Read source: 05-saveload/31_BPC_DeathHandlingSystem.md (311 lines)

  • 2.1.1 Create 05-saveload/BPC_DeathHandlingSystem.md — Core orchestrator content (lines 1-64 enums/structs + 206-311 core vars/fns/flow/matrix + header section)
  • 2.1.2 Create 05-saveload/BPC_AltDeathSpaceSystem.md — Alt death space sub-system (lines 65-99)
  • 2.1.3 Create 05-saveload/BPC_PersistentCorpseSystem.md — Corpse sub-system (lines 102-132)
  • 2.1.4 Create 05-saveload/BPC_PlayerRespawnSystem.md — Respawn sub-system (lines 136-167)
  • 2.1.5 Create 05-saveload/BPC_RunHistoryTracker.md — Run history sub-system (lines 171-203)

Each split file must:

  • Include a Depends On: section referencing the orchestrator and relevant systems

  • Include a Purpose: header describing its standalone role

  • Follow TEMPLATE.md format with complete sections

  • 2.1.6 Delete original 05-saveload/31_BPC_DeathHandlingSystem.md

  • 2.1.7 Verify all 5 new files are self-contained and valid

2.2 Split MenuWidgets (1 file → 7 files)

Read source: 06-ui/36_WBP_MenuWidgets.md (353 lines)

  • 2.2.1 Create 06-ui/WBP_MainMenu.md — Main menu widget (lines 15-48)
  • 2.2.2 Create 06-ui/WBP_PauseMenu.md — Pause menu widget (lines 51-94)
  • 2.2.3 Create 06-ui/WBP_SettingsMenu.md — Settings menu widget (lines 99-188)
  • 2.2.4 Create 06-ui/WBP_NotificationToast.md — Toast notification widget (lines 191-230)
  • 2.2.5 Create 06-ui/WBP_ScreenEffectController.md — Screen effects widget (lines 233-261)
  • 2.2.6 Create 06-ui/WBP_MenuFlowController.md — Menu flow widget (lines 264-353)
  • 2.2.7 Create 06-ui/WBP_ObjectiveDisplay.md — New file (not in bundled source; Master Sec 6.6)

Note for 2.2.7: WBP_ObjectiveDisplay is listed in Master Section 6.6 but was NOT in the bundled WBP_MenuWidgets.md. Create from scratch using TEMPLATE.md. It displays current objectives as an overlay.

  • 2.2.8 Delete original 06-ui/36_WBP_MenuWidgets.md
  • 2.2.9 Verify all 7 new files are self-contained and valid

Phase 3 — Create 12 Data Asset Spec Files (new 14-data-assets/ directory)

All DA files should follow this structure:

# DA_<Name> — Data Asset
**Parent Class:** `UDataAsset`
**Dependencies:** (systems that consume this data)
**Purpose:** (what content this data asset defines)

## Variables / Structure
(complete row structure definition)

## Gameplay Tags
(tag namespace this DA operates in)

## Validation Rules
(editor-time validation logic)

## Example Data
(1-2 example rows)

## Consumed By
(systems that read this DA)

## Reuse Notes
  • 3.0 Create directory docs/blueprints/14-data-assets/
  • 3.1 Create 14-data-assets/DA_DataAssetArchitecture.md — overview of all 20 DA types, naming conventions, dependency rules
  • 3.2 Create 14-data-assets/DA_InteractionData.md
  • 3.3 Create 14-data-assets/DA_ObjectiveData.md
  • 3.4 Create 14-data-assets/DA_EncounterData.md
  • 3.5 Create 14-data-assets/DA_AtmosphereProfile.md
  • 3.6 Create 14-data-assets/DA_ScareEvent.md
  • 3.7 Create 14-data-assets/DA_RoomMutation.md
  • 3.8 Create 14-data-assets/DA_BehaviourVariant.md
  • 3.9 Create 14-data-assets/DA_HapticProfile.md
  • 3.10 Create 14-data-assets/DA_AdaptationRule.md
  • 3.11 Create 14-data-assets/DA_EquipmentConfig.md
  • 3.12 Create 14-data-assets/DA_PuzzleData.md
  • 3.13 Create 14-data-assets/DA_RareEvent.md

Phase 4 — Create 30 Runtime System Spec Files

03-interaction/ (4 files)

  • 4.1 Create 03-interaction/BPC_PhysicsDragSystem.md
  • 4.2 Create 03-interaction/BPC_ContextualTraversalSystem.md
  • 4.3 Create 03-interaction/BP_PuzzleDeviceActor.md
  • 4.4 Create 03-interaction/BPC_UsableWorldObjectSystem.md

04-inventory/ (7 files)

  • 4.5 Create 04-inventory/BPC_ActiveItemSystem.md
  • 4.6 Create 04-inventory/BPC_ItemCombineSystem.md
  • 4.7 Create 04-inventory/BPC_DocumentArchiveSystem.md
  • 4.8 Create 04-inventory/BPC_JournalSystem.md
  • 4.9 Create 04-inventory/BPC_CollectibleTracker.md
  • 4.10 Create 04-inventory/BPC_ConsumableSystem.md
  • 4.11 Create 04-inventory/BPC_KeyItemSystem.md

05-saveload/ (1 file)

  • 4.12 Create 05-saveload/BPC_PersistentWorldStateRecorder.md

06-ui/ (3 files)

  • 4.13 Create 06-ui/WBP_DiegeticHUDFrame.md
  • 4.14 Create 06-ui/WBP_JournalDocumentViewer.md
  • 4.15 Create 06-ui/WBP_ObjectiveDisplay.md (already created in Phase 2.2.7)

08-weapons/ (5 files)

  • 4.16 Create 08-weapons/BPC_RecoilSystem.md
  • 4.17 Create 08-weapons/BPC_ReloadSystem.md
  • 4.18 Create 08-weapons/BPC_ShieldDefenseSystem.md
  • 4.19 Create 08-weapons/BPC_HitReactionSystem.md
  • 4.20 Create 08-weapons/BPC_DeathCauseTracker.md

09-ai/ (3 files)

  • 4.21 Create 09-ai/BB_AgentBoard.md
  • 4.22 Create 09-ai/BPC_AIMemorySystem.md
  • 4.23 Create 09-ai/BPC_BehaviourVariantSelector.md

10-adaptive/ (6 files)

  • 4.24 Create 10-adaptive/BPC_PlaystyleClassifier.md
  • 4.25 Create 10-adaptive/BPC_AdaptiveEnvironmentDirector.md
  • 4.26 Create 10-adaptive/BPC_MemoryDriftSystem.md
  • 4.27 Create 10-adaptive/BPC_ScareEventSystem.md
  • 4.28 Create 10-adaptive/BPC_PacingDirector.md
  • 4.29 Create 10-adaptive/BPC_RareEventSystem.md

Phase 5 — Reorganize 11-polish/ into 3 New Directories

5.1 Create new directories

  • 5.1.1 Create docs/blueprints/11-meta/
  • 5.1.2 Create docs/blueprints/12-settings/
  • 5.1.3 Create docs/blueprints/13-polish/

5.2 Move files to 11-meta/ (3 files)

  • 5.2.1 Move 11-polish/74_BPC_AchievementManager.md → 11-meta/SS_AchievementSystem.md
  • 5.2.2 Move 11-polish/75_BPC_StatsTracker.md → 11-meta/BPC_ProgressStatTracker.md
  • 5.2.3 Create 11-meta/BPC_EndingCompletionTracker.md (new)
  • 5.2.4 Create 11-meta/BPC_MetaProgressionSystem.md (new)
  • 5.2.5 Create 11-meta/BPC_RunSummarySystem.md (new)

5.3 Move files to 12-settings/ (4 files)

  • 5.3.1 Move 11-polish/71_SS_SettingsManager.md → 12-settings/SS_SettingsSystem.md
  • 5.3.2 Move 11-polish/72_BPC_AccessibilitySettings.md → 12-settings/BPC_AccessibilitySettings.md
  • 5.3.3 Create 12-settings/BPC_HapticsController.md (new)
  • 5.3.4 Create 12-settings/BPC_PlatformServiceAbstraction.md (new)

5.4 Move remaining files to 13-polish/ (9 files)

  • 5.4.1 Move 11-polish/73_BPC_TutorialSystem.md → 13-polish/BPC_TutorialSystem.md
  • 5.4.2 Move 11-polish/76_BPC_LoadingScreen.md → 13-polish/BPC_LoadingScreen.md
  • 5.4.3 Move 11-polish/77_WBP_CreditsScreen.md → 13-polish/WBP_CreditsScreen.md
  • 5.4.4 Move 11-polish/78_WBP_SplashScreen.md → 13-polish/WBP_SplashScreen.md
  • 5.4.5 Move 11-polish/79_BPC_FPSCounter.md → 13-polish/BPC_FPSCounter.md
  • 5.4.6 Move 11-polish/80_BPC_DevCheatManager.md → 13-polish/BPC_DevCheatManager.md
  • 5.4.7 Move 11-polish/81_WBP_DebugMenu.md → 13-polish/WBP_DebugMenu.md
  • 5.4.8 Move 11-polish/82_BPC_AnalyticsTracker.md → 13-polish/BPC_AnalyticsTracker.md
  • 5.4.9 Move 11-polish/83_BPC_ErrorHandler.md → 13-polish/BPC_ErrorHandler.md

5.5 Clean up

  • 5.5.1 Delete empty 11-polish/ directory

Phase 6 — Delete Extra/Unmatched Files (7 files)

These files define systems not present in the Master document or are replaced by split/new files:

  • 6.1 Delete 03-interaction/17_BPC_PickupComponent.md (covered by ItemPickup + InteractionExecutor)
  • 6.2 Delete 03-interaction/19_BPC_LeverPuzzleComponent.md (covered by BP_PuzzleDeviceActor)
  • 6.3 Delete 04-inventory/23_BPC_InventoryWeightSystem.md (sub-feature of InventorySystem)
  • 6.4 Delete 04-inventory/24_BPC_InventoryQuickSlot.md (sub-feature of ActiveItemSystem)
  • 6.5 Delete 09-ai/57_BPC_BehaviorTreeManager.md (covered by BB_AgentBoard + BehaviourVariantSelector)
  • 6.6 Delete 10-adaptive/68_BP_DynamicEvent.md (covered by BPC_RareEventSystem)
  • 6.7 Delete 10-adaptive/67_BPC_VFXManager.md (not in Master; VFX controlled by AtmosphereController)

Phase 7 — Renumber All Files Sequentially

After all renames/splits/creates/moves/deletes, renumber every file prefixed with XX_ (where XX is the existing number).

New numbering order:

  1. 01-core/ → 01–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

Renumbering rules:

  • Each file gets prefix XX_ where XX is zero-padded to 2 digits

  • The prefix matches the directory's slot in the numbering order

  • Example: 01-core/01_GI_GameFramework.md stays 01_. 06-ui/ files get 54_ through 66_.

  • Internal cross-references in each file must be updated to new filenames

  • 7.1 Renumber 01-core/ files (7 files → verify, may need expansion to 12)

  • 7.2 Renumber 02-player/ files (9 files → 13–21)

  • 7.3 Renumber 03-interaction/ files (11 files → 22–32)

  • 7.4 Renumber 04-inventory/ files (12 files → 33–44)

  • 7.5 Renumber 05-saveload/ files (9 files → 45–53)

  • 7.6 Renumber 06-ui/ files (13 files → 54–66)

  • 7.7 Renumber 07-narrative/ files (11 files → 67–77)

  • 7.8 Renumber 08-weapons/ files (12 files → 78–89)

  • 7.9 Renumber 09-ai/ files (9 files → 90–98)

  • 7.10 Renumber 10-adaptive/ files (9 files → 99–107)

  • 7.11 Renumber 11-meta/ files (6 files → 108–113)

  • 7.12 Renumber 12-settings/ files (5 files → 114–118)

  • 7.13 Renumber 13-polish/ files (10 files → 119–128)

  • 7.14 Renumber 14-data-assets/ files (13 files → 129–141)

Phase 8 — Update Cross-References

After renumbering, every internal cross-reference in every file must point to the correct filename.

  • 8.1 Search all .md files for ](XX_ patterns
  • 8.2 Verify each link target exists at the referenced path
  • 8.3 Fix any broken or stale links

Phase 9 — Update AUDIT_REPORT.md

  • 9.1 Update all status columns to ✅ for previously missing/bundled systems
  • 9.2 Update file counts (final: ~141 files, 0 missing)
  • 9.3 Remove "Recommendations" section (all completed)
  • 9.4 Add "Resolved" section documenting what was done

Phase 10 — Update CONTEXT.md

  • 10.1 Update directory structure to reflect all 14 directories
  • 10.2 Update file count to ~141
  • 10.3 Update build order to 14 phases
  • 10.4 Update naming conventions reference
  • 10.5 Mark Clean Slate refactoring as complete

Phase 11 — Final Verification

  • 11.1 Run list_files recursively on docs/blueprints/ — verify 14 directories, ~141 files
  • 11.2 Cross-reference: every Master system (Section 1–12) should have exactly 1 file
  • 11.3 Cross-reference: all 20 Data Asset types from Section 13 have a spec
  • 11.4 Verify no duplicate system names across directories
  • 11.5 Verify all files follow TEMPLATE.md format (header, enums, structs, variables, functions, dispatchers, flow, communications, reuse)
  • 11.6 Verify sequential numbering from 01 to 141
  • 11.7 Run git status — should show renames, new files, deleted files, no orphaned files

Phase 12 — Git Commit

  • 12.1 Stage all changes
  • 12.2 Commit with message: refactor: clean slate — 1:1 master-to-file mapping for all 141 systems
  • 12.3 Verify commit is clean
  • 12.4 (Optional) Create PR to main

Notes for Execution Agent

  1. Use apply_diff for renaming file header lines — change the # XX_SystemName line only
  2. Use write_to_file for creating new files (always with complete content)
  3. Use delete_file for removing obsolete files
  4. NEVER use sed, awk, or cat > for file operations
  5. Read the Master document section for each new file before writing it to get accurate variable/function definitions
  6. Follow TEMPLATE.md religiously — every new file must have all required sections
  7. Commit after each Phase (not after every file) to keep git history reasonable
  8. If a Master section is unclear on a detail, use the conventions from nearby systems and document the assumption in Reuse Notes

Checklist created 2026-05-18