realms-in-ruin-dev/Documentation/Archaeology/02-ProjectArchitecture.md

# 02 — Project Architecture

**Status: Draft**

- **Scope:** Project modules, targets, Build.cs dependencies, plugins (engine + project-local), gameplay-relevant configuration (maps, tags, input, networking, GAS-related settings), engine vs project boundaries.
- **Inspection method:** Read-only inspection of `.uproject`, Target.cs, Build.cs, module startup, plugin descriptors, `Config/*.ini`, and PluginToolset (`ListEnabledPlugins`, `GetPluginInfo`, `IsEnabled`).
- **Evidence classifications used:** Observed Implementation, Documented Intent, Inferred, Unknown.
- **Tool or visibility limitations:** No Git repository at project root (filesystem integrity used). PluginToolset `ListEnabledPlugins` returns the full editor-enabled set (engine + project). No `OnlineSubsystem` / Steam settings found under `Config/`. SemanticSearch not used.
- **Last updated:** 2026-07-16
- **Current phase:** Phase 1 — Static Architecture
- **Last completed pass:** Pass 1 (Batch 1)
- **Next pass expected to contribute:** Batch 4 Pass 10 (map/GameMode relationships); Batch 4 Pass 4 (session usage confirmation)

## Draft tracking

### Completed sections
- Module and target descriptors
- REALMSINRUIN Build.cs public dependencies
- `.uproject` plugin declarations vs project-local plugins
- Advanced Sessions / Advanced Steam Sessions descriptors
- DefaultEngine / DefaultGame / DefaultGameplayTags / DefaultInput highlights
- CoreRedirects (GAS* → RIR* rename evidence)

### Pending sections
- Per-map GameMode assignment (requires map World Settings / asset inspection without loading levels)
- Confirmation of which enabled engine plugins are referenced by live gameplay content
- OnlineSubsystem / Steam runtime configuration location

### Evidence still required
- Map asset tags / World Settings for `MainMenu`, `Test01`, `Dev_Island`, character-select maps
- Whether `NetworkPrediction` / `OnlineFramework` / `AbilitySystemGameFeatureActions` are used by project Blueprints or only enabled

### Tool or visibility limitations
- Cannot load levels; map GameMode must come from asset metadata / config
- Full enabled-plugin list is large; usage confirmation deferred to later batches

### Unknowns requiring later verification
- Where GameInstance class is configured (`GI_Dungeoneer` discovered via subclass search; not set in inspected DefaultEngine.ini)
- GlobalDefaultGameMode absent from DefaultEngine.ini — GameMode likely per-map
- No project OnlineSubsystem INI under `Config/`

---

## 1. Project descriptor

**Observed Implementation** — [`REALMSINRUIN_DEV.uproject`](REALMSINRUIN_DEV.uproject)

| Field | Value |
|-------|--------|
| EngineAssociation | `5.8` |
| Runtime module | `REALMSINRUIN` (Type Runtime, LoadingPhase Default) |
| Module AdditionalDependencies | `Engine`, `GameplayAbilities`, `CoreUObject`, `UMG` |

Enabled plugins declared in `.uproject` (non-exhaustive thematic groups):

- **Gameplay / online:** `GameplayAbilities`, `CommonUI`, `NetworkPrediction`, `OnlineFramework`, `AbilitySystemGameFeatureActions`
- **World / water:** `Landmass`, `Water`, `WaterExtras`, `Buoyancy`
- **Editor modeling:** `ModelingToolsEditorMode`, `SkeletalMeshModelingTools`, `StaticMeshEditorModeling`
- **MCP / toolsets:** `MCPClientToolset`, `ModelContextProtocol`, `AIModuleToolset`, `AllToolsets`, `GASToolsets`, `GameplayTagsToolset`, `GameFeaturesToolset`
- **Disabled in uproject:** `Cargo`, `FlatNodes`, `AutoSizeComments`

**Observed Implementation:** Project-local plugins `AdvancedSessions` and `AdvancedSteamSessions` are **not** listed in the `.uproject` Plugins array, but exist under `Plugins/` and are reported enabled by PluginToolset (see §3).

---

## 2. Modules and build

**Observed Implementation**

| Artifact | Path | Notes |
|----------|------|--------|
| Game target | [`Source/REALMSINRUIN.Target.cs`](Source/REALMSINRUIN.Target.cs) | `TargetType.Game`; `BuildSettingsVersion.V7`; `EngineIncludeOrderVersion.Unreal5_8`; ExtraModule `REALMSINRUIN` |
| Editor target | [`Source/REALMSINRUINEditor.Target.cs`](Source/REALMSINRUINEditor.Target.cs) | Same settings; `TargetType.Editor` |
| Module rules | [`Source/REALMSINRUIN/REALMSINRUIN.Build.cs`](Source/REALMSINRUIN/REALMSINRUIN.Build.cs) | Public deps: Core, CoreUObject, Engine, InputCore, EnhancedInput, GameplayAbilities, GameplayTags, GameplayTasks |
| Module startup | [`Source/REALMSINRUIN/REALMSINRUIN.cpp`](Source/REALMSINRUIN/REALMSINRUIN.cpp) | `IMPLEMENT_PRIMARY_GAME_MODULE(FDefaultGameModuleImpl, REALMSINRUIN, "REALMSINRUIN")` |
| Module header | [`Source/REALMSINRUIN/REALMSINRUIN.h`](Source/REALMSINRUIN/REALMSINRUIN.h) | Defines `CUSTOM_DEPTH_RED 250` (used by enemy highlight) |

**Observed Implementation:** `PrivateDependencyModuleNames` is empty. UMG is listed in `.uproject` AdditionalDependencies but **not** in Build.cs Public/Private dependencies. Native HUD/widget code includes UMG headers regardless.

**Inferred — Technical Debt:** Module may rely on transitive/engine linkage for UMG; Build.cs does not declare UMG or OnlineSubsystem (commented OnlineSubsystem line present).

**Observed Implementation:** There is a **single** project runtime module. No native GameMode, GameInstance, or GameState classes exist under `Source/REALMSINRUIN/`.

---

## 3. Plugins

### 3.1 Project-local plugins

**Observed Implementation** — PluginToolset `GetPluginInfo` / `ListEnabledPlugins`

| Plugin | Enabled | Descriptor | Depends on |
|--------|---------|------------|------------|
| AdvancedSessions | Yes | `Plugins/AdvancedSessions/AdvancedSessions.uplugin` (VersionName 5.8) | OnlineSubsystem, OnlineSubsystemUtils |
| AdvancedSteamSessions | Yes | `Plugins/AdvancedSteamSessions/AdvancedSteamSessions.uplugin` (VersionName 5.8) | AdvancedSessions, OnlineSubsystem, OnlineSubsystemSteam, OnlineSubsystemUtils, SteamShared |

AdvancedSessions Build.cs defines `WITH_ADVANCED_SESSIONS=1` and depends on OnlineSubsystem / Networking / Sockets.

AdvancedSteamSessions Build.cs defines `WITH_ADVANCED_STEAM_SESSIONS=1`; on Win64/Linux/Mac also depends on SteamShared, Steamworks, OnlineSubsystemSteam.

**Classification:** Foundational to multiplayer session UI flow (usage confirmation deferred to Batch 4 Pass 4). Do not recommend removal.

### 3.2 Foundational engine plugins (project-declared)

**Observed Implementation:** `GameplayAbilities` enabled — required by native ASC / AttributeSet / EffectActor / RIRGameplayAbility.

**Observed Implementation:** `EnhancedInput` enabled (also Build.cs dependency) — used by `ARIRPlayerController`.

**Observed Implementation:** `CommonUI` enabled in `.uproject` — **usage unconfirmed** in native code (no CommonUI includes under `Source/REALMSINRUIN/`). **Issue:** Requires Manual Editor Inspection / Batch 4 UI pass.

### 3.3 Enabled but usage unconfirmed (sample)

From `.uproject` + ListEnabledPlugins: `NetworkPrediction`, `OnlineFramework`, `AbilitySystemGameFeatureActions`, Water stack, MCP toolset plugins. **Issue:** Defer usage confirmation; do not recommend disable.

---

## 4. Configuration

### 4.1 Maps ([`Config/DefaultEngine.ini`](Config/DefaultEngine.ini) `[/Script/EngineSettings.GameMapsSettings]`)

| Setting | Value | Evidence |
|---------|--------|----------|
| GameDefaultMap | `/Game/_Main/Levels/Maps/MainMenu.MainMenu` | Observed Implementation |
| EditorStartupMap | `/Game/_Main/Levels/Testing/Test01.Test01` | Observed Implementation |

**Unknown:** `GlobalDefaultGameMode` not present in this file.

### 4.2 CoreRedirects (GAS rename history)

**Observed Implementation** — `[CoreRedirects]` in DefaultEngine.ini:

- `GASPlayerBase` / `GASBaseCharacter` → `RIRBaseCharacter`
- `GASBaseEnemy` / `GASEnemyCharacter` / `GASBaseEnemyCharacter` → `RIRBaseEnemyCharacter`
- `GASPlayerState` → `RIRPlayerState`
- `GASPlayerController` → `RIRPlayerController`
- `GASPlayerCharacter` → `RIRPlayerCharacter`
- `EffectActor` → `RIREffectActor`

**Documented Intent / Incomplete Refactor:** Class names were renamed from a GAS-* prefix to RIR-*; redirects preserve asset compatibility.

### 4.3 Gameplay Tags ([`Config/DefaultGameplayTags.ini`](Config/DefaultGameplayTags.ini))

Project tags (Observed Implementation, with DevComment Documented Intent):

- State: `State.Dead`, `State.Stunned`, `State.Blocking`, `State.Casting`
- Disable: `Disable.Movement`, `Disable.Input`, `Disable.Attack`, `Disable.Ability`
- Effect: `Effect.Damage`, `Effect.Heal`, `Effect.Buff`, `Effect.Debuff`

FastReplication=False.

### 4.4 Input ([`Config/DefaultInput.ini`](Config/DefaultInput.ini))

**Observed Implementation:**

- `DefaultPlayerInputClass=/Script/EnhancedInput.EnhancedPlayerInput`
- `DefaultInputComponentClass=/Script/EnhancedInput.EnhancedInputComponent`
- Legacy ActionMappings: Jump (SpaceBar / Gamepad)
- Legacy AxisMappings: Move Forward/Backward, Move Right/Left, Look, Turn

**Inferred:** Dual input stack (Enhanced Input defaults + legacy mappings). Ability input bindings not present in this INI — likely Blueprint / IMC assets (Batch 2+).

### 4.5 DefaultGame.ini

**Observed Implementation:** ProjectID, CopyrightNotice; empty `[/Script/GameplayAbilitiesEditor.GameplayEffectCreationMenu]` section.

### 4.6 Networking / online

**Unknown:** No `OnlineSubsystem` / Steam / NetDriver sections found under `Config/` via text search. OnlineFramework and OnlineSubsystem* appear enabled via plugins. Location of Steam AppId / OSS config **Requires Manual Editor Inspection** or Engine/default config outside inspected files.

---

## 5. Engine vs project boundaries

| Layer | Responsibility (Batch 1 evidence) |
|-------|-----------------------------------|
| Engine plugins | GAS, Enhanced Input, CommonUI, Water, OnlineSubsystem*, MCP toolsets |
| Project plugins | AdvancedSessions, AdvancedSteamSessions |
| Project module REALMSINRUIN | Character/Player/ASC/AttributeSet/EffectActor/HUD/WidgetController scaffolding |
| Project Blueprints (seeds only) | GI_Dungeoneer, GM_Dungeoneer, GM_MainMenu, player/enemy BPs, widgets, GEs |

---

## 6. Issue classifications (Batch 1)

| Finding | Classification |
|---------|----------------|
| GAS* → RIR* CoreRedirects | Incomplete Refactor |
| AdvancedSessions not listed in `.uproject` but enabled | Intended Behavior (project plugin discovery) — confirm |
| UMG used without Build.cs dependency | Technical Debt |
| No OnlineSubsystem INI in Config/ | Unknown / Requires Manual Editor Inspection |
| CommonUI enabled, unused in native | Requires Manual Editor Inspection |
| GlobalDefaultGameMode absent | Unknown until map inspection |

No findings classified as Runtime Regression (UE 5.8 migration).