Project Eternal - Documentation Plan
Summary: This document outlines the structure, style guidelines, and maintenance strategy for Project Eternal documentation. Documentation follows a concept-first approach optimized for rapid iteration during early development.
Table of Contents
Documentation Philosophy
Concept-First Approach
Documentation prioritizes understanding over implementation details:
| Tier |
Content |
Update Frequency |
Format |
| Concepts |
Architecture, patterns, data flow |
Rarely |
Diagrams + prose |
| Contracts |
Public API signatures, events |
On breaking changes |
Tables |
| References |
File locations |
As code moves |
Source pointers |
Why This Approach?
| Problem |
Solution |
| Code snippets become outdated |
Use ASCII diagrams and tables instead |
| Implementation details change often |
Document concepts that stay stable |
| Copying code creates maintenance burden |
Point to source files instead |
| New devs need to understand "why" |
Lead with design rationale |
Style Guidelines
DO
| Guideline |
Example |
| Use ASCII diagrams |
Box-drawing for architecture |
| Use tables for APIs |
Method / Parameters / Purpose |
| Add Source References |
EquipmentComponent.h:33-76 |
| Explain "why" |
"Why PlayerController Ownership?" |
| Add Recent Changes |
Date / Change / Impact table |
| Keep snippets <10 lines |
Only for critical patterns |
DON'T
| Avoid |
Instead |
| Large code blocks |
ASCII flow diagrams |
| Full class definitions |
Property/method tables |
| Implementation details |
Conceptual explanations |
| Copying code |
Source file references |
| Time estimates |
Implementation steps only |
ASCII Diagram Style
┌─────────────────────┐
│ Component Name │
│ • Key property 1 │
│ • Key property 2 │
└──────────┬──────────┘
│
▼
┌─────────────────────┐
│ Related System │
└─────────────────────┘
Table Style
| Method | Parameters | Purpose |
|--------|------------|---------|
| `DoThing` | `(Item, Slot)` | Brief description |
Document Template
Each document follows this structure:
# System Name
> **Summary:** 2-3 sentence overview.
## Table of Contents
[Links to sections]
---
## Architecture Overview
- ASCII diagram
- Key design principles table
---
## Core Concepts
### Why This Design?
- Rationale for architecture decisions
---
## [Topic Sections]
- Flow diagrams
- Responsibility tables
- No large code blocks
---
## Public Contracts
### Methods
| Method | Parameters | Purpose |
### Events
| Delegate | Payload | When Fired |
---
## Source References
| Component | Location |
|-----------|----------|
| `ClassName` | `Path/File.h:lines` |
---
## Related Systems
- [System Name](./path.md) - Brief description
---
## Recent Changes
| Date | Change | Impact |
|------|--------|--------|
Document Index
01_Foundation
| Document |
Description |
| Core Architecture |
Project structure, modules, naming |
| Game Framework |
GameMode, GameInstance, subsystems |
| Character Framework |
Character hierarchy, component ownership |
| Interfaces |
Cross-system communication |
| Persistence |
Save/load, providers (Local/Remote/Preset), demo presets |
02_AbilitySystem
| Document |
Description |
| GAS Overview |
ASC, attribute sets, input |
| Ability Classes |
Hierarchy and configuration |
| Damage Execution |
Calculation pipeline |
| Resource Recovery |
Regeneration systems |
| Gameplay Cue Visuals |
Data-driven buff auras, elemental weapon VFX |
| Ailment Model |
Bleed/Poison/Shock, resistance inheritance |
| Ability Kits |
Grant, ordering, input slots |
| Chain Semantics |
Damage provenance, generations, chain rails |
03_Combat
| Document |
Description |
| Combat Overview |
Component hierarchy |
| Combo System |
Chains and states |
| Charge System |
Charge attacks |
| Poise System |
Stagger mechanics, the Sunder break window, break presentation |
| Hit Tracing |
Collision detection |
| Combat Animation |
Montages and notifies |
| Block System |
Hold-to-block, stamina chip, guard break, parry, enemy guard stance |
04_Items
| Document |
Description |
| Item System |
UItemObject, FItemManifest |
| Item Fragments |
Composable behaviors |
| Inventory System |
Container management |
| Equipment System |
Equip/unequip flow |
| Loot System |
Drop tables, generation |
| Remnant Item System |
Portal → realm → event → awaken loop |
| Item State Modules |
Polymorphic per-instance runtime state pattern |
| Crafting System |
Cube crafting, recipes, shard tooltip ranges |
| Conditional Modifiers |
Wearer-state & target-state conditional affixes, StateTagComponent |
| Greed System |
Hidden per-item craft-risk meter, consumption, blessings |
| Item Generation |
Modifier rolling, implicit-by-base-type, seeded tiers |
05_UI
| Document |
Description |
| UI Architecture |
Layer system, controllers |
| MVVM Framework |
ViewModel binding |
| CommonUI Integration |
Input handling |
| Widget Library |
Common widgets |
06_Multiplayer
| Document |
Description |
| Replication Overview |
FastArray, property replication |
| Server Authority |
RPC patterns, validation |
| API Layer |
Backend communication |
| Backend Server |
ASP.NET Core 8 + PostgreSQL persistence, sessions |
| Spawn & Transition Ordering |
Spawn, possession and travel ordering |
07_AI_World
| Document |
Description |
| Enemy AI |
Behavior trees, phases |
| World Systems |
Exploration, POIs |
| Spawning System |
Enemy, projectile, AOE |
| World Map System |
The Chasm, node navigation, domains |
| Dungeon System |
Topology generation, room pools |
08_Progression
| Document |
Description |
| Quest System |
Tags, objectives, dialogue |
09_Audio
| Document |
Description |
| Audio Architecture |
Mix hierarchy, bus graph, trigger layers, ducking, surface taxonomy, replication rules |
| Audio Authoring |
D7 naming, folder layout, wiring recipes, cue layering, Eternal.Audio.Audit, the Eternal.Audio debug window |
| External Deliverable Spec |
The spec handed to external composers and sound designers |
| Capture Workflow |
Recording and processing incoming audio to the deliverable spec |
10_Standards
| Document |
Description |
| C++ Style Guide |
Naming, formatting, patterns |
| Testing |
Automation Framework, DEFINE_SPEC, unit vs integration |
| Data Authoring Pipeline |
JSON source-of-truth vs UASSET DataAssets |
| Asset Naming & Organization |
Content/ naming and folder conventions |
| Content Validation |
Validator registry + EternalValidation commandlet; on-save / pre-push / CI delivery |
| Document |
Description |
| Blender Room Workflow |
Room data export, Blender import, USD pipeline |
| Blender → UE Skeletal Mesh Rig Transfer |
Re-rig a mesh onto a different skeleton (reshape, weight transfer, FBX, MCP/Python import) |
| Unreal MCP + Python Automation Guide |
What works/crashes driving the editor headless: import-via-slate-tick, materials via Python, UMG/BP-graph limits, build/Live-Coding flow, crash recovery |
| Itemization Tooling |
Editor sim/index/validate/preview suite: Roll/Loot/Craft simulators, Greed Monte Carlo, archetype coverage, where-used, validators, send-to-PIE |
| WidgetForge |
Agent-drivable UMG authoring: JSON specs ↔ WidgetBlueprints, widget-as-truth staleness gate, headless render |
| Balance Sweep Workflow |
Build Lab, BuildSweep, build-power evaluation |
| UE Python Material API Reference |
Material scripting quirks: pin names, expression editing, Custom HLSL nodes, redirector-deletion hazard, sampler naming |
| Foliage Pivot Baking |
Per-blade pivot/wind encoding (UV2 = pivot XY, VertexColor.R = root-tip) for M_Grass; lightmap-UV regen footgun |
| New Ability Archetype Recipe |
Adding a new ability base class end-to-end |
| Ability Authoring Tools |
Ability wizard (Eternal.Ability.Stamp), Kit Composer |
| TextureForge |
Spec-driven painterly UI textures: recipes vs comps, icon manifest, determinism gate |
12_DevOps
| Document |
Description |
| CI/CD Pipeline |
GitHub Actions, branch strategy, build stages |
| EGS Deployment |
BuildPatchTool, labels, sandboxes, upload flow |
| Infrastructure Setup |
Runner machine, directories, secrets, scaling |
13_Rendering
| Document |
Description |
| Tonemapping |
AgX tonemapper, color grading, scene buffer config |
| RVT Landscape Blend |
Meshes fade into landscape via Runtime Virtual Texture; world-space normal lerp, dither window, manual PDO |
14_Guides
Task-shaped designer walkthroughs rather than system reference. These follow a different template
from the rest of the docs: they walk one job end to end and explain only the concepts that step needs.
| Document |
Description |
| Author Your First Ability |
End-to-end first pass through the ability pipeline |
| Hand-Finish an Ability |
What the wizard leaves for you: montage, tags, cues |
| Register a Gameplay Tag |
Native vs ini tags, where each belongs |
| Feel-Test Your Ability |
Running a feel pass and reading the result honestly |
| Author an Ability Chain |
Chains, generations, provenance |
| Author a Quest |
Manifest → stamp → dialogue → validate → overview |
Maintenance Strategy
When to Update Documentation
| Trigger |
Action |
| API signature changes |
Update Public Contracts table |
| New pattern introduced |
Add to relevant concept section |
| File/class renamed |
Update Source References |
| Major refactoring |
Add to Recent Changes table |
What NOT to Update
| Avoid |
Reason |
| Adding code snippets |
Will become outdated |
| Implementation details |
Changes frequently |
| Line numbers in source |
Brittle references |
Recent Changes Table
Each document has a Recent Changes section:
| Date | Change | Impact |
|------|--------|--------|
| 2025-12-27 | FFragmentEquipContext | Fragments receive context |
Update this when making breaking changes.
Cross-Reference Convention
| Reference Type |
Format |
| Document link |
[System Name](./XX_Document.md) |
| Section link |
[Section](./XX_Document.md#section-name) |
| Source file |
Path/File.h:LineRange or Path/File.h → FunctionName() |
| Class reference |
Inline code: UClassName |