stemedb/applications/aphoria/docs/guides/aaa-game-development.md

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).

$ 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.

$ 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) 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.