# Guide: Preventing Epistemic Drift in AAA Game Development

**Target Audience:** Technical Directors, Lead Engineers, Release Managers
**Technology:** Unreal Engine 5 (C++, INI, Blueprints)

---

## The Problem: Invisible Rot

Games are massive. A AAA project might have 10,000 assets, 500 C++ classes, and 50 `.ini` config files.

In that complexity, "Truth" gets lost.
*   **Performance Truth:** "Never load assets synchronously on the game thread."
    *   *Reality:* A junior dev writes `LoadSynchronous()` in a UI widget. The game hitches every time the menu opens.
*   **Security Truth:** "Never ship with `bAuthorizeAutomaticWidgetVariableCreation=True`."
    *   *Reality:* Someone toggled it for debugging 6 months ago and forgot.
*   **Architecture Truth:** "Don't hardcode asset paths like `/Game/UI/Logo`."
    *   *Reality:* It works fine until the UI artist moves the folder, and the game crashes on boot.

These aren't compile errors. They are **Epistemic Drift**—the code drifting away from the architectural truth.

---

## 1. The Unreal Engine Corpus

Aphoria ships with a dedicated **Vendor Corpus** for Unreal Engine. It knows things like:

*   `vendor://unreal/performance/sync_loading`: "Synchronous loading blocks the game thread."
*   `vendor://unreal/security/exec_function`: "Exec functions are callable by clients/console."
*   `vendor://unreal/network/max_client_rate`: "Bandwidth limits below 15000 cause replication issues."

You don't have to write these rules. They are built-in.

## 2. Scanning a Game Project

Navigate to your project root (where `.uproject` lives).

```bash
$ aphoria scan .
```

Aphoria parses your C++ Source and Config INI files.

### Example Findings

#### Finding 1: The Frame Hitch
```
  BLOCK    code://cpp/unreal/performance/sync_loading
         Your code:  LoadSynchronous() (MasqSubsystem.cpp:55)
         Epic Docs:  Synchronous loading causes hitches. Use AsyncLoad.
         Conflict:   0.95
```
**Impact:** You just found the cause of that mysterious stutter on the main menu.

#### Finding 2: The Security Hole
```
  BLOCK    code://config/unreal/security/api_key
         Your code:  ApiKey=sk_live_... (DefaultMasq.ini:102)
         Epic Docs:  Never store secrets in INI files.
         Conflict:   0.98
```
**Impact:** You prevented shipping live credentials in the client build.

#### Finding 3: The Fragile Reference
```
  FLAG     code://cpp/unreal/assets/hardcoded_path
         Your code:  TEXT("/Game/UI/Logo")
         Best Practice: Use SoftObjectPtr or DataAssets.
         Conflict:   0.60
```
**Impact:** You identified a crash-waiting-to-happen before the asset was moved.

## 3. The "Shipping Build" Check

Game development has distinct phases. "Hack it together" (Pre-Alpha) vs "Lock it down" (Gold).

Aphoria supports this via **Strict Mode**.

**In Development:**
Run standard scans. FLAGs (like hardcoded paths) are warnings. You can ignore them to move fast.

**For Release Candidates:**
Run with `--strict`.

```bash
$ aphoria scan --strict --exit-code
```

Now, those architectural FLAGs become blockers. You cannot ship a Gold Master with hardcoded paths or sync loads.

## 4. Customizing for Your Studio

Every studio has its own "Truth."
*   *"We use `TArray`, never `std::vector`."*
*   *"All textures must be power-of-two."*

You can create a **Studio Trust Pack** (see [Federating Truth](./federating-truth.md)) to enforce these specific rules alongside the standard Unreal ones.

## Summary

Aphoria treats your game's **Architecture** and **Performance Guidelines** as authoritative sources, just like RFCs. It ensures that the game you *built* is the game you *intended* to build.