Project Eternal Technical Documentation¶
Project Eternal is an Unreal Engine 5.8 multiplayer ARPG built with C++. This documentation covers all major systems for developers working on the codebase.
New to the docs? Start with Documentation Setup. Product direction: Roadmap.
Quick Links¶
| System | Description | Key Classes |
|---|---|---|
| Ability System | GAS implementation | UEternalAbilitySystemComponent, UEternalAttributeSet |
| Combat | Melee, projectiles, damage | UCombatComponent, UMontageManagerComponent |
| Inventory | Items and containers | UItemContainerComponent, UItemObject |
| UI Framework | MVVM and CommonUI | UEternalUISubsystem, UBaseViewModel |
| Multiplayer | Replication patterns | FFastArraySerializer, Server RPCs |
| Enemy AI | Behavior trees, balance scaling | AEternalAIController, UBalanceSubsystem |
| World Map | Chasm navigation | UWorldMapSubsystem, FWorldMapNode |
| Dungeons | Procedural generation | UDungeonSubsystem, FDungeonTopology |
| Quests | Quest tracking | UPlayerQuestComponent, UQuestManagerComponent |
| DevOps | CI/CD, EGS deployment | GitHub Actions, BuildPatchTool |
Architecture Overview¶
┌─────────────────────────────────────────────────────────────────────────┐
│ GAME INSTANCE │
│ ┌─────────────────────────────────────────────────────────────────┐ │
│ │ UEternalUISubsystem (UI Controllers, ViewModels) │ │
│ │ UBalanceSubsystem (Enemy stat scaling) │ │
│ └─────────────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────────────────────┐
│ GAME STATE │
│ ┌──────────────────────┐ ┌──────────────────────┐ │
│ │ UQuestManagerComponent│ │UWorldPOIManagerComponent│ │
│ └──────────────────────┘ └──────────────────────┘ │
└─────────────────────────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────────────────────┐
│ PLAYER CONTROLLER │
│ ┌──────────────────────┐ ┌──────────────────────┐ │
│ │UItemContainerComponent│ │ UEquipmentComponent │ │
│ └──────────────────────┘ └──────────────────────┘ │
└─────────────────────────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────────────────────┐
│ PLAYER STATE │
│ ┌──────────────────────┐ ┌──────────────────────┐ │
│ │ UPlayerQuestComponent │ │ UMapExplorationComponent│ │
│ └──────────────────────┘ └──────────────────────┘ │
└─────────────────────────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────────────────────┐
│ CHARACTER / PAWN │
│ ┌────────────────┐ ┌────────────────┐ ┌────────────────────────┐ │
│ │ UCombatComponent│ │UMontageManager │ │UEternalAbilitySystemComponent│
│ └────────────────┘ └────────────────┘ └────────────────────────┘ │
└─────────────────────────────────────────────────────────────────────────┘
Documentation Index¶
01 - Foundation¶
Core framework classes and project setup.
| Document | Topics |
|---|---|
| Core Architecture | Project structure, naming conventions |
| Game Framework | GameMode, GameState, subsystems |
| Character Framework | Character, Controller classes |
| Interfaces | Core gameplay interfaces |
| Persistence System | Save/load, providers, demo presets |
02 - Ability System¶
Gameplay Ability System implementation.
| Document | Topics |
|---|---|
| GAS Overview | ASC setup, ability activation |
| Ability Classes | Ability types, activation flow |
| Damage Execution | Damage calculation, effects |
| Resource Recovery | Health, stamina, mana recovery |
| 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¶
Combat mechanics and damage systems.
| Document | Topics |
|---|---|
| Combat Overview | UCombatComponent, combat flow |
| Combo System | Attack chains, combo windows |
| Charge System | Charged attacks, release mechanics |
| Poise System | Stagger, poise break, the Sunder window and its presentation |
| Hit Tracing | Traces, collision, hit events |
| Combat Animation | Montages, animation state |
| Block System | Hold-to-block, stamina chip, guard break, parry, enemy guard stance |
04 - Items & Equipment¶
Item system and inventory management.
| Document | Topics |
|---|---|
| Item System | UItemObject, FItemManifest |
| Item Fragments | Modular item properties |
| Inventory System | UItemContainerComponent, grid layout |
| Equipment System | UEquipmentComponent, slots |
| Loot System | Loot tables, drop mechanics |
| 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 |
| Greed System | Hidden per-item craft-risk meter, consumption, blessings |
| Item Generation | Modifier rolling, implicit-by-base-type, seeded tiers |
05 - UI Framework¶
User interface architecture.
| Document | Topics |
|---|---|
| UI Architecture | UEternalUISubsystem, controllers |
| MVVM Framework | UBaseViewModel, FieldNotify |
| CommonUI Integration | Input handling, tooltips |
| Widget Library | HUD, inventory, character widgets |
06 - Multiplayer¶
Networking and replication.
| Document | Topics |
|---|---|
| Replication Overview | FFastArraySerializer, RepNotify |
| Server Authority | Server RPCs, validation |
| API Layer | UEternalApiSubsystem, HTTP services |
| Backend Server | ASP.NET Core 8 + PostgreSQL persistence, sessions |
| Spawn & Transition Ordering | Spawn, possession, travel ordering |
07 - AI & World¶
Enemy AI and world systems.
| Document | Topics |
|---|---|
| Enemy AI | Behavior trees, perception, bosses |
| World Systems | Exploration, POIs, zones |
| Spawning System | Items, projectiles, enemies |
| World Map System | The Chasm, node navigation, domains |
| Dungeon System | Topology generation, room pools |
08 - Progression¶
Quest and progression systems.
| Document | Topics |
|---|---|
| Quest System | Quests, objectives, compendium |
09 - Audio¶
Mix graph, audio triggers, authoring, and the external audio workflow.
| Document | Topics |
|---|---|
| Audio Architecture | Mix hierarchy, bus graph, trigger layers, surface taxonomy, replication rules |
| Audio Authoring | D7 naming, folder layout, wiring recipes, Eternal.Audio.Audit |
| External Deliverable Spec | The spec handed to external composers and sound designers (WAV/stem/naming/delivery) |
| Capture Workflow | Recording and processing incoming audio to the deliverable spec |
10 - Standards¶
Coding standards and style guides.
| Document | Topics |
|---|---|
| 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, commandlet, on-save / pre-push / CI gates |
11 - Tools¶
External tooling and editor utilities.
| Document | Topics |
|---|---|
| Blender Room Workflow | Room data export, Blender import, USD pipeline |
| Skeletal Mesh Rig Transfer | Re-rig a mesh onto a different skeleton (Blender → UE) |
| Unreal MCP + Python Automation Guide | Driving the editor headless, materials/UMG/BP limits, crash recovery |
| Itemization Tooling | Editor sim/index/validate/preview suite, Greed Monte Carlo, send-to-PIE |
| WidgetForge | Agent-drivable UMG authoring: JSON specs ↔ WidgetBlueprints, staleness gate |
| Balance Sweep Workflow | Build Lab, BuildSweep, build-power evaluation |
| UE Python Material API Reference | Material scripting quirks: pin names, expression editing, Custom HLSL, redirector-deletion hazard |
| Foliage Pivot Baking | Per-blade pivot/wind encoding (UV2/VertexColor.R) for M_Grass, lightmap-UV 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, icon manifest, determinism gate |
12 - DevOps¶
Build pipeline, deployment, and infrastructure.
| Document | Topics |
|---|---|
| CI/CD Pipeline | GitHub Actions, branch strategy, build stages |
| EGS Deployment | BuildPatchTool, labels, sandboxes, upload flow |
| Infrastructure Setup | Runner setup, directories, secrets, scaling |
13 - Rendering¶
Rendering pipeline, color, and post-processing.
| Document | Topics |
|---|---|
| Tonemapping | AgX tonemapper, color grading, scene buffer config |
| RVT Landscape Blend | Meshes fade into landscape via Runtime Virtual Texture; world-space normal lerp, dither, PDO |
14 - Guides¶
The designer front door — task-shaped walkthroughs rather than system reference. Start at the Guides README.
| Document | Topics |
|---|---|
| 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 |
Key Patterns¶
Component Ownership¶
| Owner | Components | Reason |
|---|---|---|
| PlayerController | Inventory, Equipment | Persist across pawn death |
| PlayerState | Quest, Exploration | Long-term player identity |
| Character/Pawn | Combat, Montage, ASC | Tied to physical pawn |
| GameState | QuestManager, POIManager | Global game state |
Replication Patterns¶
| Pattern | Usage |
|---|---|
FFastArraySerializer |
Inventory, Exploration, POIs |
Server_ RPCs |
Gameplay-critical operations |
Multicast_ RPCs |
Visual sync (death, equipment) |
RepNotify |
State change callbacks |
MVVM Flow¶
Naming Conventions¶
| Prefix | Type | Example |
|---|---|---|
A |
Actor | AEternalCharacter |
U |
UObject/Component | UItemContainerComponent |
F |
Struct | FItemManifest |
E |
Enum | EItemRarity |
I |
Interface | ICombatInterface |
Eternal |
Core framework | UEternalUISubsystem |
Getting Started¶
Reading Order for New Developers¶
- Core Architecture - Understand folder layout
- Game Framework - Learn base class hierarchy
- GAS Overview - Ability system fundamentals
- Combat Overview - Combat system basics
- Inventory System - Item handling
- Replication Overview - Networking patterns
Key Files to Know¶
| File | Purpose |
|---|---|
EternalCharacter.h |
Base player character |
EternalPlayerController.h |
Player controller with inventory |
EternalAbilitySystemComponent.h |
GAS component |
ItemContainerComponent.h |
Inventory container |
CombatComponent.h |
Combat state management |
EternalUISubsystem.h |
UI controller management |
Cross-References¶
Each document includes: - Summary box at the top with key points - Table of contents for navigation - Related Systems section linking to dependent systems - Refactoring Considerations with improvement suggestions
Source Code¶
All source code is located in Source/ProjectEternal/:
- Public/ - Header files
- Private/ - Implementation files
Content assets are in Content/ with corresponding folders for each system.