Development roadmap

Research / presentation application. The Unreal game is in development, not a finished release. Native milestone results below are preserved dated project records, not a new playtest. Historical classifications remain explicit; unresolved research is not verified history.

Source: Docs/ARCHITECTURE.md

# ADWA Architecture

**Status:** P6 mounted-traversal foundation implemented and validated
**Version:** 1.3
**Last reviewed:** 2026-09-27

## Target

- Windows PC first.
- 1920×1080 at 60 FPS target; 30 FPS absolute early-greybox floor.
- Keyboard/mouse and standard Xbox-style controller.
- Unreal Engine 5 version must be selected from an actually installed, supported engine and recorded before project creation.

## Environment audit — 2026-09-25 (second pass)

| Area | Observed state |
|---|---|
| Windows | Windows 11 Pro x64, `10.0.26200.9550`, display version 25H2 |
| CPU | Intel Core i7-9700 @ 3.00 GHz, 8 cores / 8 logical processors |
| RAM | 25,541,074,944 bytes (23.79 GiB) |
| GPU | NVIDIA Quadro P400, 2 GiB VRAM, driver 32.0.15.8208; Intel UHD Graphics 630 also present |
| Storage | Crucial CT525MX300SSD1 SSD; C: 389.58 GiB total / 22.54 GiB free; E: 97.66 GiB total / 72.68 GiB free |
| Visual Studio | Build Tools 2026 18.7.2 complete/launchable; VS 2019 Build Tools incomplete/not launchable |
| C++ toolset | MSVC 14.51.36231; `VCTools` workload and x64/x86 tools registered |
| Windows SDK | 10.0.19041.0 and 10.0.26100.0; VS 2026 registers the 26100 component |
| CMake | Not found on PATH |
| Git / LFS | Git 2.55.0.windows.3; Git LFS 3.7.1 |
| .NET | x64 runtime 8.0.14; no standalone SDK registered |
| Epic / Unreal | No Epic Games Launcher, launcher manifests, registered engine, UnrealEditor, UnrealBuildTool, or UnrealVersionSelector found |

Some Windows management interfaces denied unprivileged CIM/PnP queries; equivalent non-mutating registry and device-enumeration evidence supplied the values above. No administrator action was taken.

## Historical engine candidate — superseded by ADR-0002

Recommend **Unreal Engine 5.8.x launcher binary** for validation. This is based on direct toolchain alignment: Epic’s 5.8 release notes list VS 2026 as recommended, MSVC 14.50 as recommended (14.38 minimum), and Windows SDK 10.0.26100.0 as default. The machine already has VS Build Tools 2026, MSVC 14.51, and SDK 26100. UE 5.8 also contains the required World Partition, Enhanced Input, Gameplay Tags, StateTree, Sequencer, MetaSounds, PCG, Nanite, and Lumen capabilities. See [Epic’s UE 5.8 release notes](https://dev.epicgames.com/documentation/unreal-engine/unreal-engine-5-8-release-notes) and [hardware/software specifications](https://dev.epicgames.com/documentation/unreal-engine/hardware-and-software-specifications-for-unreal-engine).

This is not an ADR or project pin yet. `ADR-0002-UNREAL-ENGINE-VERSION.md` must be created only after the installed editor, UnrealBuildTool, compiler, SDK, project generation, and minimal C++ launch are actually validated.

## UE 5.8.3 first validation attempt — 2026-09-25

The installed launcher binary was located at `E:\UE_5.8` despite stale/empty Epic registration metadata.

| Check | Evidence | Result |
|---|---|---|
| Editor executable | `E:\UE_5.8\Engine\Binaries\Win64\UnrealEditor.exe`; file CL `58210709` | Pass: located and version metadata read |
| Engine build | `Build.version`: 5.8.3, promoted, branch `++UE5+Release-5.8`, compatible CL `55116800` | Pass |
| UnrealBuildTool | UBT 5.8 executable/DLL located; `-help` executed with bundled .NET | Pass |
| Bundled .NET | SDK 10.0.203; runtime 10.0.7 | Pass; system .NET 10 is not required for Epic’s build wrapper |
| C++ project generation | Disposable `ToolchainSmoke` project generated Visual Studio solution files | Pass with warning noted below |
| MSVC detection | MSVC family 14.51.36231, compiler 14.51.36248, x64 | Detected; accepted with warning that it is newer than Epic’s preferred 14.50.35717 |
| Windows SDK | Windows SDK 10.0.26100.0 installed and aligned with UE 5.8 default | Present |
| Development Editor compile | `ToolchainSmokeEditor Win64 Development` | **Fail:** missing .NET Framework SDK; `SwarmInterface` requires SDK 4.6.0 or higher |
| Editor launch | Not attempted because compilation prerequisite failed | Blocked |

UBT project generation also reported the missing NetFxSDK while binding full editor IntelliSense data, although solution generation completed. The disposable project was removed after capturing the result. No ADWA `.uproject` or production module was created.

### Required remediation

Use Visual Studio Installer to modify **Visual Studio Build Tools 2026** and add a supported **.NET Framework SDK/Developer Pack (4.6 or newer; prefer the current 4.8/4.8.1 development tools offered by the installer)**. Keep the existing C++ build tools and Windows 11 SDK 10.0.26100. Administrator approval may be required. After installation, rerun solution generation, Development Editor compilation, and unattended editor launch before writing ADR-0002 or creating ADWA.

## Hardware constraints

Epic recommends 32 GB RAM and at least 8 GB graphics RAM for UE 5.8 development. This machine has 23.79 GiB RAM and 2 GiB discrete VRAM. The Quadro P400 is not among Epic’s supported GPU families for Lumen hardware ray tracing (RTX 2000-series or newer). P1 may be testable at low scalability with Lumen disabled and simple placeholders, but 1080p/60 cannot be promised before measurement; the 30 FPS floor is also unverified. Nanite/SM6 support must be tested rather than assumed.

Current free space is too tight for a comfortable engine install plus derived data, project intermediates, and builds. The Epic Launcher will show the exact selected-component size. Maintain at least **120 GiB free on the chosen engine/project volume** before installation; more is preferable for this project.

No `.uproject` or engine source scaffold is created until the prerequisite audit passes. This prevents silently pinning an unavailable engine association or claiming a build that cannot be run.

## Implemented P1 architecture — 2026-09-26

ADR-0002 pins UE 5.8.3, MSVC 14.51.36248, and Windows SDK 10.0.26100. The NetFxSDK prerequisite is resolved. Solution generation, Development Editor compilation, unattended launch, standalone Development build, cook, and stage all pass.

The four-module boundary remains intact:

- `AdwaCore`: stable IDs, evidence classes, source/historical record contracts, provisional P1 records, settings, and logs.
- `AdwaNarrative`: objective state, observations, knowledge gating, checkpoint snapshots, and mission subsystem.
- `AdwaGameplay`: primary game module, pawn/input/camera, procedural neutral route, interactions, triggers, danger proxies, mobilization proof, runtime benchmark, and functional traversal harness.
- `AdwaTests`: six Editor automation tests; it is a `DeveloperTool` module and is excluded from the Game target.

`/Game/Maps/P1_FirstFootstep` is a bounded World Partition map. It retains only partition infrastructure; all P1 geometry is code-generated at runtime from engine primitives and labeled `NON_CANON_PROXY_TERRAIN`. This avoids committing any terrain or cultural asset as a reconstruction while still proving the required map, streaming initialization, traversal, and cook path.

P400 defaults are DX11/SM5, low scalability, 35% internal scene resolution in a native 1920×1080 window, and Lumen/ray tracing/Nanite disabled. The final staged-build sample cleared the 30 FPS greybox floor at 46.33 FPS average.

## Authorized modules

Only these runtime/test modules may be introduced during P1:

- `AdwaCore`: stable IDs, gameplay tags, evidence classification, historical record schema, logging, settings.
- `AdwaGameplay`: placeholder pawn/movement, interaction, observation state, checkpoint state.
- `AdwaNarrative`: minimal objective state machine and knowledge-gated report.
- `AdwaTests`: automation tests for IDs, classifications, objective/observation/checkpoint rules, and invalid report knowledge.

Deferred: `AdwaAI`, `AdwaWorld`, `AdwaMounts`, `AdwaAudio`, `AdwaCinematics`, and `AdwaEditor`.

## P1 data flow

```text
Interaction/reach trigger
        │
        ▼
Minimal objective state machine ──► Checkpoint snapshot
        │                                  │
        ▼                                  ▼
Observation state (Seen/Uncertain) ◄── Restore
        │
        ▼
Knowledge-gated report options
        │
        ▼
PROTOTYPE_MOBILIZATION_TIMING_ONLY ──► Dawn endpoint
```

## P2 movement and presence

P2 keeps movement inside `AdwaGameplay` and does not add a new module. `UAdwaMovementSettings` is the config-backed tuning source for walk/run speeds, acceleration, braking, turn precision, slope limits, input accessibility, camera follow, and intentional interaction thresholds. `AAdwaP1Character` applies these values to `UCharacterMovementComponent` and `USpringArmComponent` at runtime.

Camera-relative movement with movement-oriented body facing is the durable exploration policy. Walking uses the higher turn rate for precision; running increases speed while lowering turn rate. Horizontal ground velocity is maintained so slope direction does not create artificial acceleration.

`UAdwaLocomotionAnimInstance` is a replaceable Animation Blueprint parent contract. It publishes locomotion state, speed, signed direction, airborne state, and floor slope without depending on P1 mission state. Ordinary locomotion remains in-place; root motion is reserved for future authored one-shot traversal actions if explicitly approved.

Interaction remains intentionally small: the character selects only the current objective's closest eligible point, with config-backed prompt range, execution range, and facing threshold. Mission progression and historical evidence rules are unchanged.

## P2.1 founder playtest support

P2.1 remains inside `AdwaGameplay` and adds no module or durable final UI framework. The founder controls and objective/status panels use transient engine on-screen messages; interaction points use code-generated magenta developer beacons and labels. These are explicitly temporary test aids, contain no historical or cultural claim, and do not alter interaction eligibility, mission order, checkpoints, movement, camera, or route geometry.

The `ToggleControlsOverlay` action is mapped to keyboard `F1` and controller Menu (`Gamepad_Special_Right`). The existing `AdwaTests` input-mapping test verifies those exact keys as well as the checkpoint-restore mappings; the test module links `InputCore` explicitly for those `EKeys` symbols.

## P2.2 grounded movement and recovery

P2.2 extends the existing `UAdwaMovementSettings` rather than adding a system or module. Horizontal and vertical look sensitivity are independent for mouse and controller. Interaction evaluation now reports horizontal distance, camera-facing acceptance, and current-objective eligibility separately so temporary UI and execution use the same decision.

`AAdwaP1Character` owns the bounded out-of-bounds guard. Below the configured Z threshold it asks the existing mission subsystem to restore the latest checkpoint snapshot and transform, or uses its initial safe transform before any checkpoint exists, then clears movement. A two-fall command-line harness validates repeatability. A separate actor-level harness validates rejection just outside the interaction radius and success at a natural in-range approach. The world builder still generates only labeled `NON_CANON_PROXY_TERRAIN`; P2.2 overlaps route slabs and adds a connected movement loop rather than introducing authored geography or a traversal mechanic.

## P3 mission framework

P3 keeps the existing four-module boundary and replaces the narrative module's linear progression with a reusable dependency graph. `FAdwaMissionDefinition` owns immutable authored objective and observation definitions. `FAdwaP1MissionState` retains its compatibility name but owns only mutable runtime/save state after initialization: objective states, player-knowledge records, report entries, route state, checkpoint snapshot, observation sequence, and mission status.

Objectives carry stable ID, type, completion condition, prerequisites, optional/failure flags, checkpoint policy, evidence classification, player text, and developer text. Eligibility is graph-derived, so multiple branches can be active. The current P3 definition uses `Travel`, `Interaction`, `Observation`, `Return`, `Report`, and `Completion`; future objective families require an authorized milestone.

Observation definitions keep internal world-truth IDs separate from player records. Player records retain encountered/valid state, `Confirmed`/`Uncertain`/`NotObserved` certainty, order, timestamp, evidence class, and reported state. Player UI reads only valid observation records. Report entries are generated from those records and validated for exact certainty equality, preventing an unobserved fact from becoming an affirmative report.

Checkpoint snapshots persist the complete runtime/save boundary, including route state and report finalization, but do not duplicate the authored mission definition. This is ready for a future serializer without implementing a disk save/profile system in P3.

```text
Authored mission definition
        │ initialize
        ▼
Objective dependency graph ───────► Active/completed/failed runtime state
        │                                      │
        ▼                                      ▼
Observation definition ──► player knowledge ──► knowledge-consistent report
  (internal truth ID)       (certainty/order)            │
        │                         │                       ▼
        └── never player UI       └──────────────► explicit completion node

Runtime objective + knowledge + report + route + mission state
        │
        └────────────────────────► checkpoint snapshot / future save boundary
```

## P4 combat framework

P4 remains inside `AdwaGameplay`; no speculative module was added. `AdwaP4Combat` separates replaceable authored weapon/melee/damage definitions from combatant, ammunition, event, and AI-knowledge runtime state. Stable IDs and `GAME_FICTION` evidence tags prevent prototype content from silently becoming canon.

`FAdwaCombatRules` is the deterministic policy layer for mutually exclusive state transitions, ammunition/reload, ranged/melee validation, team hostility, dangerous damage, pressure, checkpoint reset, and `Known`/`Suspected`/`Unknown` perception decay. `UAdwaP4CombatComponent` supplies engine line/sweep traces and actor integration. `AAdwaP4PrototypeCombatant` is the replaceable neutral AI shell.

Ranged validation uses visibility-channel hitscan: the first blocking geometry or combatant determines miss/block/hit, so terrain and cover are authoritative. The player character owns input/camera-facing invocation and failure recovery, not the combat model. Combat reset and mission restore are deliberately separate boundaries; the existing mission checkpoint remains authoritative for objectives and observations.

The P3 definition now contains two optional P4 combat nodes. Required observation/report completion is unchanged, and combat events have no route into mission knowledge records.

## P5 NPC camp and world-life framework

P5 remains inside `AdwaGameplay`. `AdwaP5WorldLife` separates authored NPC/activity/conversation/presentation definitions from runtime activity, schedule, local danger knowledge, destination, conversation, carrying, and checkpoint state. Stable IDs and `GAME_FICTION` classification keep the technical population replaceable.

`FAdwaNpcRules` is the deterministic policy layer for state transitions, schedules, role-configured danger reactions, interaction eligibility, conversations, separation, and reset normalization. `AAdwaP5CampNpc` is an ambient full-actor shell with a temporary humanoid-shaped presentation; `AAdwaP5ActivityPoint` owns reusable camp destinations. The world builder composes the non-canon zone and population without becoming the NPC behavior implementation.

Camp-local movement follows authored activity destinations through `CharacterMovement`, forward swept obstacle checks, lateral steering, and neighbor separation. NPC capsules overlap the Pawn channel so ambient actors cannot permanently imprison the player while world geometry remains blocking. This is a validated small-camp navigation solution, not a replacement for future general navigation, Mass AI, or army simulation.

Mission overrides are explicit and limited to mission-relevant NPC definitions. Danger knowledge is local and event-driven; it never writes player observation records or reveals mission truth. NPC checkpoints restore runtime state and location without spawning replacements, preventing reset duplication.

Population tiers are explicit: `HeroImportant` is reserved for future authored actors, `AmbientFullActor` is the P5 implementation, and `FutureLightweightCrowd` is the scaling boundary. P5 does not implement the future lightweight tier.

## P6 horse and mounted-traversal framework

P6 stays inside `AdwaGameplay`. `FAdwaHorseDefinition` is stable-ID authored data; `FAdwaHorseRuntimeState` is mutable relationship/movement/terrain/danger state; `FAdwaMountedRules` is deterministic policy; and `AAdwaP6Horse` owns movement, proxy presentation, relationship, autonomy, safe dismount, and checkpoint reconstruction.

The player delegates move/steer/gait input while mounted and restores normal movement/camera configuration on dismount. Mission triggers accept a horse only through its current rider. Checkpoints store horse transform, player transform, runtime state, and relationship and always restore the existing actor, keeping identity and population cardinality stable.

P4 attacks are gated while mounted; danger hooks exist without mounted combat. P5 NPCs receive bounded proximity acknowledgement without acquiring global horse knowledge or blocking the rider. Horse presentation, movement data, and historical equestrian content remain replaceable.

## P7 audio, atmosphere, and Negarit framework

P7 remains inside `AdwaGameplay`. `FAdwaAudioDefinition` is authored data; `FAdwaRuntimeAudioEvent` is an asset-independent occurrence; `FAdwaAudioListener` stores bounded listener state; `FAdwaCulturalAudioMetadata` carries provenance and approvals; and `FAdwaAudioRuntimeState` owns zone, daypart, loops, recent bounded history, category muting, and counters. `FAdwaAudioRules` provides deterministic zone, loop, propagation, cultural-activation, Negarit-safety, and reset policy. `AAdwaP7AudioDirector` bridges those contracts to the world and the single neutral procedural presentation layer.

Gameplay systems consume stable event IDs, source position, range, intensity, category, and relevance without depending on a `USoundBase`. This keeps a heard gameplay event distinct from a played asset. P5 mission-relevant listeners can receive abstract Negarit signals inside range; unrelated or distant listeners do not. P3 mission, P4 combat, P5 camp activity, P6 mounted movement, checkpoint, and session reset hooks preserve their existing authority boundaries.

The current zone model is camp center, camp edge, open route, lookout, and danger/combat. One persistent ambience loop is replaced rather than stacked during transitions. Pre-dawn, dawn, daytime, and evening are prototype state hooks. The dedicated Negarit definition stays `RESEARCH_REQUIRED` and `UNASSIGNED`; its event and listener path works without an audio asset, and activation requires complete provenance and approvals.

## Implemented core contracts

- Stable IDs are namespaced values with validity and deterministic equality/hash behavior.
- Historical classification is a closed enum with the four approved values.
- Historical records carry ID, title, classification, claim summary, sources, uncertainty notes, and affected references.
- Objectives use stable IDs, typed completion conditions, prerequisites, optional/failure policy, checkpoint metadata, evidence class, and separate player/debug text.
- Observation records separate encounter/validity from certainty and retain order, timestamp, evidence, and report state.
- Report entries are generated and validated against actual player knowledge; absent information is represented only as `NotObserved`.
- Checkpoint snapshots contain transform plus all mutable mission, objective, observation, report, sequence, and route state.

## Planned world

One bounded World Partition map, one runtime grid, no HLOD tuning, no final Landscape claim. Grey primitives and high-contrast developer labels identify `NON_CANON_PROXY_TERRAIN`. The abstract obstacle has no faction or real-world identity. The mobilization proof uses light/proxy reposition/objective state plus a neutral developer tone—never a drum.