Character Hierarchy

// UE base
ACharacter (UE)
  └── AWCCharacterBase  (Abstract — state machine, tag system, death, GAS)
      │   Components: WCCharacterMovementComponent  WCInteractionComponent  WCGASAttributeInitializer
      ├── AWCPlayerCharacter   — UGameplayCameraComponent (tag-driven rigs), ASC → PlayerState
      └── AWCAICharacter       — owns UWCCombatAbilitySystemComponent directly
  

ASC Ownership

// Player — ASC on PlayerState
AWCPlayerState  →  owns  UWCCombatAbilitySystemComponent
AWCPlayerCharacter::GetAbilitySystemComponent()  →  routes to PlayerState

// AI — ASC on character
AWCAICharacter  →  owns  UWCCombatAbilitySystemComponent

// Utility resolver
UWCCoreLibrary::GetWCAbilitySystemComponent(Actor)
  Pawn IAbilitySystemInterface → Actor's PlayerState → null
  

Input Flow

Enhanced Input → WCInputManagerComponent (PlayerController)
  → Priority-sorted Handler array
  → WCInputBuffer   (timing-sensitive queuing)
  → WCComboDetector (tree-based pattern matching)
  → Ability activation via ASC
  

Attack Chain vs Combo

Tag Communication

// 4 approved cross-module channels
Gameplay Tags  → event-driven state/events  (tag in WCGameplayTags.h only)
Interfaces     → type-safe calls across boundaries
Subsystems     → singleton-pattern services
Delegates      → Blueprint-accessible callbacks

// Planned module example: WCAudioSuite hears combat state
WC.State.Gameplay.Combat added to ASC
  → UWCMusicDirectorComponent registered via RegisterGameplayTagEvent()
  → transitions to CombatMusicState
  → NO direct import of WCCombat headers needed
  

Game Framework Classes

PlayerState Component Accumulation

// Components added to AWCPlayerState across phases
AWCPlayerState
  UWCCombatAbilitySystemComponent   ← WCGASCore (existing)
  UWCCraftingComponent              ← WCInventory (existing)
  UWCStoriesComponent               ← WCStories (Phase 4)
  UWCExplorationComponent           ← WCRealms (Phase 2)
  UWCKnowledgeComponent             ← WCKnowledgeSuite (Phase 3)
  // Each component defined in its feature module, CREATED here in DynamicRPGWorlds
  

Cross-Module Tag Dependencies (Planned)

// Which modules consume tags from other planned modules
WCAudioSuite  → listens: WC.Realms.Event.LocationDiscovered (discovery stinger)
               → listens: WC.Knowledge.Achievement_Unlocked (achievement stinger)
               → listens: WC.State.Gameplay.Combat (combat music — existing)

WCKnowledgeSuite → listens: WC.Realms.Event.LocationDiscovered (codex/achievement unlock)
                 → listens: WC.Combat.Event.Kill (kill-count achievements — existing)

WCStories     → condition checks: WCInventory, WCGASAlly, WCDynamicSociety (via interfaces)
              → task tasks: listens to WCInventory::OnItemAdded, WC.Combat.Event.Kill

WCAI          → watches: WC.State.Gameplay.Combat on NPC ASC → suspend/resume
              → reads: WCDynamicSociety CalendarSubsystem + NPCSocialComponent (schedule)
              → private: WCStories for WCRoutineGoal_StartDialogue

WCSaveSystem  → calls serialization on: WCGASCore, WCInventory, WCGASAlly, WCStories,
                 WCDynamicSociety, WCRealms, WCKnowledgeSuite

// All ~75 new planned tags still go to WCGASCore/Public/WCGameplayTags.h
  

The 6 Immutable Rules

Core Design Patterns

UWCItemDefinition (Primary DA) + TArray<UWCItemFragment*> = any item type (no C++ subclassing)
UWCAbilityDefinition (Primary DA) + TArray<UWCAbilityFragment*> = any ability type

// Planned modules follow same pattern:
UWCAchievementDefinition + TArray<UWCAchievementTask*> = any achievement type
UWCQuest + TArray<UWCQuestState*> + TArray<UWCQuestTask*> = any quest structure
    

// Cross-module channels (in priority order)
Gameplay Tags   → event-driven state/events (preferred)
Interfaces      → type-safe calls  (IWCSaveableInterface, IWCWorldStateSaveable)
Subsystems      → singleton services  (UWCDiscoverySubsystem, UWCAudioSubsystem)
Delegates       → Blueprint callbacks

// NEVER: feature module #includes another feature module without Build.cs declaration
// NEVER: planned module includes DynamicRPGWorlds headers
    

// Component defined in feature module, CREATED in DynamicRPGWorlds
WCRealms defines UWCExplorationComponent
  → DynamicRPGWorlds AWCPlayerState constructor creates it

WCKnowledgeSuite defines UWCKnowledgeComponent
  → DynamicRPGWorlds AWCPlayerState constructor creates it

WCStories defines UWCStoriesComponent
  → DynamicRPGWorlds AWCPlayerState constructor creates it

WCAudioSuite defines UWCMusicDirectorComponent
  → DynamicRPGWorlds AWCHUD::BeginPlay creates it (after ASC resolves)
    

WC.[Module].[Category].[Subcategory]

// Existing
WC.Combat.State.Aiming
WC.Combat.Event.HitConfirmed
WC.State.Gameplay.Combat
WC.State.Gameplay.Exploring

// Planned (50 new tags across 5 modules)
WC.Audio.State.MusicTransitioning
WC.Realms.Event.LocationDiscovered
WC.Knowledge.Achievement.Unlocked
WC.Quest.State.Active
WC.Dialogue.State.Active
WC.Save.Event.SaveStarted

Key File Locations

showdebug abilitysystem   // GAS state, attributes, effects
showdebug gameplaytags    // Active tags on actors
showdebug input           // Enhanced Input debug

AWCDummy  // Drop in level — logs all GAS hits
UWCAbilityFragment_Debug  // Add to any ability

// Per-module debug flags in Project Settings:
UWCInputSettings       → bEnableInputLogging
UWCInteractionSettings → bEnableDebugVisualization
UWCCombatSettings      → bEnableTraceDebug
// Add bDebugX to each new module's Settings class

"<UE5_ROOT>/Engine/Build/BatchFiles/Build.bat"
  WC_RPG_Worlds Win64 Development
  -Project="U:/UE Projects/Diversion/
            WC_RPG_Worlds/WC_RPG_Worlds.uproject"

"<UE5_ROOT>/Engine/Build/BatchFiles/
  GenerateProjectFiles.bat"
  "U:/UE Projects/Diversion/
   WC_RPG_Worlds/WC_RPG_Worlds.uproject"

// Build config:
IWYU: ON  ·  Warnings-as-errors: WCGASCore
Unity builds: OFF (complex modules)

• 1
  Create folder structure — Plugins/DynamicRPGWorlds/Source/WC[Name]/Public/ and Private/. Follow the existing layout pattern from WCInteraction or WCInput.
• 2
  Create .Build.cs — Minimum public dep: WCGASCore. NEVER add DynamicRPGWorlds. Set PCHUsage = ExplicitOrSharedPCHs. Copy the WCInventory.Build.cs as your template.
• 3
  Add to .uplugin — Add entry in the Modules array with "Type": "Runtime" and "LoadingPhase": "Default".
• 4
  Create WC[Name].h/.cpp — Standard module declaration. Follow WCInput.h pattern.
• 5
  Create Settings class — UWC[Name]Settings in Public/Settings/. Register under Project Settings > Dynamic RPG Worlds > [Name]. Always include bDebug[Name] flag.
• 6
  Add all new gameplay tags to WCGameplayTags.h/.cpp ONLY — In WCTags namespace, format WC.[ModuleName].[Category].[Name]. All 50 planned tags from the 5 specs must go here.
• 7
  Create core classes — Subsystems, components, data assets, interfaces. Follow naming conventions exactly. Blueprint-expose everything meaningful with UFUNCTION(BlueprintCallable).
• 8
  Cross-module communication via approved channels only — Tags for events, Interfaces for type-safe calls, Subsystems for services, Delegates for BP. Never include feature module headers without Build.cs declaration.
• 9
  Wire components into DynamicRPGWorlds — New PlayerState components go in AWCPlayerState constructor. HUD components go in AWCHUD::BeginPlay(). Never let the feature module create things on framework classes.
• 10
  Create Docs/WC[Name]_Overview.md — Document architecture, key classes, enums, delegates, multiplayer notes, configuration hierarchy. Follow the existing overview docs format.
• 11
  Update CLAUDE.md — Add to the "Current Modules" table. Move from Planned to Implemented. This is the master reference — keep it current.
• 12
  Add editor module if needed — WCStories needs WCStoriesEditor for the graph editor. WCRealms may want WCRealmsEditor for volume visualization. Register in .uplugin with "Type": "Editor".

WCAudioSuite — First Build Reference

1. WCAudioSuite.h + WCAudioSuite.Build.cs + WCAudioSettings.h  // module compiles
2. WCMusicTypes.h + WCMusicStateDefinition.h + WCMusicLayerDefinition.h  // data assets
3. UWCAudioSubsystem.h/.cpp  // world subsystem, stub implementations
4. UWCMusicDirectorComponent.h/.cpp  // tag watching, calls subsystem
5. Wire into DynamicRPGWorlds: AWCHUD creates MusicDirectorComponent  // playable
6. UWCAmbientZoneDefinition + AWCAmbientZoneVolume  // ambient zones
7. UWCCombatAudioDefinition + UWCStingerDefinition  // combat audio
8. WCDynamicSociety calendar integration  // day/night ambient switch