1cc453c97b
- Add PolicySourceStore for tracking where policies come from - Implement claim extraction skill and API endpoints - Add community UI text selection extractor component - Create Go SDK aphoria client for policy operations - Document patent specifications and legal disclosures - Add guides: golden path loop, policy audit trails, pre-flight checks - Expand Unreal Engine config extractor with source tracking - Add UAT reports for policy source tracking validation - Refactor tests.rs into modular test files Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
102 lines
3.6 KiB
Markdown
102 lines
3.6 KiB
Markdown
# 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.
|