-
Notifications
You must be signed in to change notification settings - Fork 0
Architecture Overview
PGX v0.4.0 | Unreal Engine 5.6.1 | 26 Plugins | 13 Production Systems
Every Unreal Engine project starts the same way. A small team creates a save system. Then a loading screen. Then a game state machine. Then audio management. Then shader warm-up. Every project rebuilds these systems from scratch, with inconsistent patterns, undocumented interfaces, and fragile interdependencies.
Six months in, someone asks: "Where is the configuration for the loading screen timeout?" The answer is: "Check the C++ constructor, the ini file, the developer settings, and maybe a Blueprint default. It depends on who wrote it."
PGX exists to eliminate that answer. Every system follows the same pattern. Configuration lives in the same kind of asset. Console commands follow the same naming convention. Editor panels follow the same layout rules. A developer who has learned one PGX system already knows how to use the next one.
This is not a template. Templates give you a starting point and then you are on your own. PGX is middleware -- an architectural layer between raw Unreal Engine and your game code. You bring the game design. PGX provides the engineering foundation.
PGX is built on a three-layer model. Each layer has a clear responsibility and a strict dependency direction: layers only depend downward, never upward or sideways.
+-------------------------------------------------+
| |
| TEMPLATE LAYER (Your Game) |
| Your actors, your game modes, your UI |
| Consumes L1 + L2 via BP or C++ |
| |
+-------------------------------------------------+
|
| depends on
v
+-------------------------------------------------+
| |
| L2: FEATURE PLUGINS (21 slots) |
| |
| Save GameFlow PSO Audio Loading |
| LevelFlow MGOS Profile Log ... |
| |
| Each plugin depends ONLY on L1 Core Runtime |
| No L2-to-L2 runtime dependencies |
| |
+-------------------------------------------------+
|
| depends on
v
+-------------------------------------------------+
| |
| L1: CORE RUNTIME (Foundation) |
| |
| Message Bus Event Handler Data Registry |
| Construction Profile Log Config |
| |
| Base classes, interfaces, shared tags, |
| object pool, state machine |
| |
+-------------------------------------------------+
The foundation. Contains infrastructure that every system might need: a typed message bus for cross-plugin communication, an event handler bus for data-driven behavior resolution, a data registry for runtime asset lookup, a construction system for data-driven actor composition, platform profiling, structured logging, and configuration management.
Every L2 plugin depends on L1. L1 depends on nothing except Unreal Engine itself.
Independent systems that solve specific game development problems. Save/load with slots, auto-save, versioning, and migration. Game state machines with multi-channel phases. PSO (Pipeline State Object) warm-up for eliminating shader hitches. Audio management with dual backends. Level transitions with deterministic timing. Garbage collection observability.
The key constraint: each L2 plugin depends only on L1. They never depend on each other at runtime. This is the star topology rule, and it is the single most important architectural decision in PGX.
Your game. PGX provides no game logic, no player controllers, no HUDs, no menus. You consume PGX systems through Blueprints or C++, configure them through Data Assets, and extend them through class overrides. PGX is the infrastructure; the template layer is where your game lives.
The alternative is what most projects do: a flat collection of modules with ad-hoc dependencies. Module A includes Module B which includes Module C. When you want to ship Module A without Module C, you discover they are entangled. When you want to reuse Module B in another project, you discover it drags in half the codebase.
Three layers solve three problems:
Isolation. An L2 plugin cannot know about another L2 plugin. If the Save system needs to communicate with the Audio system, it goes through the L1 Message Bus. This means you can remove the Audio plugin entirely and the Save system keeps working. No recompilation. No broken references. No cascading failures.
Reuse. Any L2 plugin can be shipped independently. It needs only L1 to function. A studio that only wants the Save system does not need to carry Audio, PSO, or Loading along with it.
Scalability. New systems are added as new L2 plugins. They depend on L1 and nothing else. The existing plugins do not need to change. The build does not slow down. The dependency graph does not become more complex.
The dependency graph of PGX looks like a star, not a web:
+-------------+
| L1 Core |
| Runtime |
+------+------+
|
+----------+----------+----------+----------+
| | | | |
v v v v v
+------+ +--------+ +-----+ +-------+ +-------+
| Save | |GameFlow| | PSO | | Audio | |Loading|
+------+ +--------+ +-----+ +-------+ +-------+
| | | | |
v v v v v
+------+ +--------+ +-----+ +-------+ +-------+
| MGOS | |LevelFl.| | Log | |Profile| |DataReg|
+------+ +--------+ +-----+ +-------+ +-------+
Every arrow points inward toward L1. No arrows connect the outer nodes to each other.
This is enforced at the build system level. If an L2 plugin adds a build dependency on another L2 plugin, the CI validation script catches it and fails the build. The rule is structural, not aspirational.
Architectural purity is valuable, but shipping software is more valuable. PGX has exactly three L2-to-L2 runtime dependencies, each justified by hard technical requirements:
-
Loading depends on GameFlow. The loading system needs to know the current game flow state to determine when it is safe to begin a level transition. Without this, the loading screen could initiate a transition during an invalid state, causing race conditions.
-
Loading depends on PSO. The loading system coordinates Pipeline State Object warm-up before showing the level. If loading does not know about PSO status, the player sees the level before shaders are compiled, causing visible hitches.
-
PSO depends on GameFlow. The PSO system needs to know when the game state changes to activate the correct shader pipeline set. Menu pipelines differ from gameplay pipelines, and PSO must switch at the right moment.
These three exceptions form a small triangle at the intersection of loading, rendering, and state management. They are documented in the workspace manifest, validated by the CI pipeline, and justified by load-order requirements that cannot be solved through the message bus alone (because the message bus introduces timing uncertainty, and these systems require deterministic ordering).
No new L2-to-L2 exceptions have been added since the architecture was established. Any future exception would require explicit justification and validation.
PGX v0.4.0 contains 26 plugins organized across the three layers:
The Core plugin contains all infrastructure systems:
| System | What It Solves |
|---|---|
| Message Bus | Typed pub/sub messaging between any two systems, with channels, history, and async listeners |
| Event Handler | Data-driven behavior resolution -- route events to handlers by tag, with lifecycle management and telemetry |
| Data Registry | Runtime asset lookup -- register Data Assets and query them by tag at runtime |
| Construction | Data-driven actor composition -- define what components and properties an actor gets through Data Assets, not code |
| Profile | Platform capabilities, budgets, and feature flags -- detect hardware and configure systems accordingly |
| Log | Polymorphic structured logging with 13 domain renderers, filter bars, and in-editor visualization |
| Config | Configuration management and dashboard |
| Plugin | Status | What It Solves |
|---|---|---|
| Save | Production | Complete save/load: slots, auto-save, versioning, compression, async I/O, domain separation, migration chains |
| GameFlow | Production | Multi-channel game state machine with tag-driven phases and validation rules |
| PSO | Production | Pipeline State Object warm-up: batched loading, concurrency policies, auto-population |
| Audio | Production | Dual-backend audio management: legacy + modulation, 5-layer mix, ducking, HDR, music, dialogue |
| Loading | Production | Level transitions: deterministic timing, async loading, loading screens, sub-level streaming |
| LevelFlow | Production | Level flow management, sub-level orchestration, transition coordination |
| MGOS | Production | Garbage collection observability: inference-based monitoring, leak detection, behavioral profiling |
| Input through Cinematic | Scaffolded | 14 systems with plugin structure ready, awaiting implementation |
| Plugin | What It Does |
|---|---|
| Editor Tools | System observer, test dashboard, visual showcase, panel management |
| Docs | In-editor Markdown documentation viewer with native Slate rendering |
| Sim Harness | Simulation and testing harness with deep injection across 13 systems |
| Scaffold | Automated project scaffolding with templates and transactional execution |
Plus two specialized tools: Version Control integration and Agent Bridge for automation.
Every production system in PGX delivers the same 15 artifacts. This is not a suggestion. It is a checklist that blocks a system from being marked as complete.
| # | Deliverable | Purpose |
|---|---|---|
| 1 | Types | Enums, structs, dynamic delegate declarations |
| 2 | Subsystem | Core logic class (GameInstance, World, or Engine scope) |
| 3 | Delegates | Native delegate header for C++ binding |
| 4 | Config Data Asset | All configuration via Data Asset, auto-discovered at initialization |
| 5 | Gameplay Tags | System-specific tags with documented ownership branches |
| 6 | Console Commands | Runtime inspection and debugging, registered at initialization |
| 7 | Blueprint Library | Static Blueprint-callable functions for designers |
| 8 | Test Utility | Seven standardized test functions per system |
| 9 | Inspector Panel | Dockable editor panel showing live PIE data |
| 10 | Content Browser Factories | Right-click creation of all system Data Assets |
| 11 | Toolbar Entry | Quick access from the PGX toolbar |
| 12 | Architecture Document | Technical documentation for the system |
| 13 | Usage Guide | How-to documentation for developers |
| 14 | Testing Guide | How to test the system |
| 15 | Inspector Guide | How to use the editor panel |
Thirteen systems have completed this checklist. Each system that deviates documents which items are not applicable and why. For example, the Construction system is data-only (no subsystem of its own), so items 2, 3, 6, 7, 8, and 9 are marked as not applicable. The MGOS system runs at Engine scope (not GameInstance), so its Blueprint Library is not applicable -- you cannot call Engine subsystem functions from a Blueprint context.
Because the number-one cause of "incomplete" in the project history was forgetting the editor wiring. A system would compile, pass tests, and have documentation -- but the Content Browser factory was missing, or the toolbar entry was not registered, or the inspector panel was not spawned. Thirteen specific editor wiring items are tracked separately as a mandatory checklist.
The 15-deliverable rule exists because a system is not done when it works. It is done when it is clean, documented, wired into the editor, and discoverable by a developer who has never seen it before.
PGX systems initialize in a deterministic order. This matters because some systems depend on others being ready first:
Profile --> GameFlow --> Log --> Save --> PSO --> Widget --> Audio --> Registry --> Message --> EventHandler
Profile initializes first because every other system may query platform capabilities during its own setup. GameFlow initializes second because the game state machine must be ready before systems that react to state changes. Log initializes third because every subsequent system will log during its initialization.
This order is explicit, not discovered. Each system declares its priority, and the engine respects it. If a system tries to initialize before its dependencies, the framework logs a warning and the dependency graph makes the problem visible.
If L2 plugins cannot depend on each other, how do they communicate?
Through the Message Bus. The L1 Core Runtime provides a typed publish-subscribe messaging system. Any system can broadcast a message on a tagged channel. Any system can subscribe to that channel. The publisher does not know who is listening. The subscriber does not know who is publishing.
Example flow: When the Save system completes an auto-save, it broadcasts a message on the "save completed" channel. The Audio system subscribes to that channel to play a confirmation sound. The Loading system subscribes to know that it is safe to transition. Neither Save, Audio, nor Loading reference each other directly.
For deterministic behavior resolution (where multiple handlers might respond to the same event), the Event Handler bus provides priority ordering, lifecycle management (singleton, cached, or ephemeral handlers), and telemetry.
| Metric | Value |
|---|---|
| Plugins | 26 (1 L1, 21 L2, 4 tool) |
| Production systems | 13 |
| Source files | 1,300+ |
| Data Asset types | 58 |
| Editor panels | 23 dockable NomadTabs |
| Console commands | 95+ |
| Blueprint nodes | 170+ |
| Gameplay tags | 180+ |
| Test functions | 95+ |
| Custom SVG icons | 26 |
| Documentation files | 90+ |
| Static analysis warnings fixed | 957 |
| L2-to-L2 runtime exceptions | 3 (validated, documented) |
| Per-system deliverables | 15 (enforced checklist) |
| Editor wiring checklist items | 13 per system |
Most frameworks treat editor tooling as an afterthought -- something bolted on after the runtime systems are complete. PGX treats the editor experience as a first-class architectural deliverable, equal in importance to the runtime API.
Every production system ships with an inspector panel -- a dockable Slate tab that shows live data during Play-In-Editor sessions. The Save inspector shows slot states and auto-save timers. The GameFlow inspector shows multi-channel phase visualization. The Audio inspector shows active sounds, mix layers, and backend status. These are not debug-only tools. They are the primary way developers verify that their configuration is working.
A unified PGX toolbar provides quick access to all 23 inspector panels, organized by system. Quick-access pins allow developers to dock their most-used panels. The toolbar also hosts the system observer (a live dashboard of all subsystem states), the test dashboard (run all system tests with color-coded results), and shortcuts to documentation.
The Content Browser extension adds a dedicated PGX section to the right-click menu. All 58 Data Asset types are organized by system with color-coded icons. Blueprint creation entries let designers create project-specific Blueprints derived from PGX base classes. The visual language -- colors, icons, categories -- makes it possible to identify which system owns an asset without reading its name.
PGX panels follow a visual construction system with shared design tokens -- fonts, colors, spacing, and accent colors are defined in a single source of truth. Eleven atomic widgets (accent bars, section dividers, KPI chips, status badges, footer bars, and more) ensure visual consistency across all 23 panels. Ten UX design dogmas govern layout decisions. The result is that every panel looks like it belongs to the same product, not like it was written by thirteen different developers on thirteen different days.
Editor tooling reveals architectural problems that unit tests miss. If an inspector panel cannot display a system's state, the state is not observable. If a Data Asset cannot be created from the Content Browser, the factory is missing. If a console command does not appear in the command list, it was not registered.
The 13-item editor wiring checklist exists because these failures are silent. The system compiles. Tests pass. But a developer opening the editor for the first time cannot find anything. Making editor integration a deliverable -- not a nice-to-have -- ensures that every system is discoverable from day one.
Architecture without enforcement is aspiration. PGX codifies its engineering standards into eight numbered rules (S0 through S7) that govern every line of code.
S0: UE5 C++ Core Discipline. Eleven rules for memory safety, garbage collection, and UObject lifecycle. Every pointer has the correct property markup. Every reference is tracked. Every initialization is explicit.
S1: Delegate Lifecycle Guard. Every delegate binding has a symmetric unbinding. This is the number-one source of crashes in UE5 projects -- a delegate fires into a destroyed object. PGX enforces bind/unbind symmetry at the pattern level, with verification rules for every delegate call.
S2: Contract Truth Sync. Documentation must match code. When a system changes, both AI navigation docs and human-facing docs must be updated in the same session. Stale documentation is treated as a defect.
S3: Build Dependency Integrity. Every include implies a build dependency. Dependencies are minimal and correct. No L2-to-L2 runtime dependencies (star topology enforcement).
S4: Single Source of Truth. Metadata, configuration, and display data live in one canonical location. If the same data appears in two files, one of them is wrong.
S5: Tooling Honesty. No placeholder buttons. No TODO strings in user-facing text. No hardcoded test data in inspector panels. If a feature is not implemented, its UI does not exist.
S6: Audit-Ready Definition of Done. A system is not done when it compiles. It is done when it compiles with zero warnings, all 15 deliverables are complete, documentation is current, and the editor wiring checklist is satisfied.
S7: Logging Hygiene. Every system has its own log category. No temporary log output in production code. Initialization and shutdown are always logged. Warning and error severities are used correctly.
PGX integrates clang-tidy with a three-layer configuration (project, plugin, file) and 30 active checks. A Python orchestrator runs per-plugin analysis with incremental caching, generating both Markdown and JSON reports. 957 warnings have been resolved across the codebase. An audit doctrine (13 rules) governs how warnings are triaged, deferred, or suppressed.
If you are evaluating PGX for a studio, a course, or a technical review, these are the key takeaways:
It is a framework, not a template. PGX provides systems, not game logic. You build your game on top of it.
It is data-driven. All configuration flows through Data Assets. No ini files, no hardcoded constructors, no scattered constants. One type of asset, one workflow for every system.
It is modular by construction, not by convention. The star topology is enforced at the build system level. You cannot accidentally create an L2-to-L2 dependency. If you try, the build fails.
It is editor-integrated. Every system has a dockable inspector panel with live runtime data, Content Browser integration for asset creation, toolbar entries for quick access, and console commands for debugging. The editor experience is a first-class deliverable, not an afterthought.
It is documented uniformly. Every system has the same four documentation files: architecture, usage, testing, and inspector guide. Every system follows the same naming conventions for classes, tags, console commands, Blueprint categories, and log categories.
It is tested and audited. 957 static analysis warnings resolved through clang-tidy integration. Every system has standardized test utilities. A simulation harness exercises 160+ API calls across all 13 production systems.
It is designed for one person or fifty. The patterns are simple enough for a solo developer to use from day one, and consistent enough for a team of fifty to navigate without friction.
Lyra is a complete game built by Epic to demonstrate best practices. It shows how to build a shooter using Game Features, Enhanced Input, GAS, and Modular Gameplay. PGX is infrastructure -- it provides the systems that sit beneath game-specific architecture. Where Lyra demonstrates "here is how you build a game," PGX provides "here is the reusable foundation you build it on."
The two are complementary. You could build Lyra-style modular gameplay on top of PGX systems. PGX handles save/load, audio management, loading screens, and state machines so your game code can focus on what makes your project unique.
Unreal's Game Feature Plugin system provides modularity at the content level -- activating and deactivating gameplay features at runtime. PGX provides modularity at the systems level -- independent infrastructure plugins that any feature can consume. They complement each other. PGX systems can be activated via GFP, and GFP content can consume PGX APIs through Blueprint Libraries or C++ subsystems.
Most studios build their own framework incrementally over multiple shipped titles. The save system from project one gets copied to project two. The audio wrapper from project two gets adapted for project three. After five projects, the studio has a framework -- but it has no consistency, no documentation, and no enforced patterns.
PGX provides that accumulated wisdom from day one, with the consistency that in-house frameworks often lack because "we will document it after we ship" and "we will clean it up in the next project."
Individual marketplace plugins solve individual problems. You get a save plugin, an audio plugin, a loading screen plugin. Each has different naming conventions, different configuration mechanisms, different editor integration approaches, and different documentation styles. Combining five marketplace plugins means learning five different workflows.
PGX is one framework. Every system follows the same patterns, the same naming conventions, the same configuration mechanism (Data Assets), and the same editor integration approach. Learning one system teaches you all of them.
Adding a new L2 system means:
- Create a plugin with Runtime (and optionally Editor) modules
- Add the single L1 dependency
- Implement the 15 deliverables
- Register in the workspace manifest
The existing plugins do not change. The build graph gains one new spoke. Compile times increase linearly with the new module's size, not with the framework's total size.
Removing an L2 plugin means:
- Delete the plugin folder
- Remove it from the workspace manifest
Nothing else changes. No other plugin referenced it. No other build file included it. The star topology guarantees clean removal.
Any message bus subscriptions that targeted the removed system's channels simply stop receiving messages. Any Blueprint nodes from the removed system will show as unresolved in Blueprints that used them, which the engine flags at compile time. The failure is loud and localized, not silent and cascading.
PGX patterns are designed to eliminate coordination overhead. Two developers can work on two different L2 systems simultaneously without merge conflicts, because:
- Each system lives in its own plugin folder (file isolation)
- Each system depends only on L1 (dependency isolation)
- Each system has its own log category, tag namespace, and console command prefix (naming isolation)
A team of ten can have ten developers building ten systems in parallel, merging without conflict, compiling independently.
PGX uses a branch strategy for engine version support:
-
maintargets the active development engine version -
ue/5.6freezes the current snapshot when adopting a new engine version - Release tags encode both framework and engine version:
v0.4.0-ue5.6
This strategy allows studios to stay on a stable engine version while PGX development moves forward, then upgrade on their own schedule.
PGX es un framework modular C++ para Unreal Engine 5 construido sobre un modelo de tres capas: L1 (Core Runtime), L2 (plugins de funcionalidad), y la capa Template (tu juego). La topologia estrella es la decision arquitectonica mas importante: cada plugin L2 depende unicamente de L1, nunca de otro L2, con solo 3 excepciones validadas y documentadas relacionadas con el orden de carga. Esto garantiza que cualquier plugin puede ser eliminado o distribuido de forma independiente sin afectar al resto. Cada sistema production-ready entrega 15 artefactos obligatorios que incluyen subsistema, Data Asset de configuracion, comandos de consola, libreria Blueprint, utilidad de testing, panel inspector, y documentacion. La comunicacion entre plugins se realiza exclusivamente a traves del Message Bus de L1, un sistema pub/sub tipado con canales basados en Gameplay Tags. El framework contiene 26 plugins, 13 sistemas en produccion, mas de 1300 archivos fuente, 23 paneles de editor, y 170+ nodos Blueprint. PGX no es un template -- es la capa arquitectonica entre UE5 y tu juego, disenada para escalar desde un desarrollador solo hasta un equipo de 50 personas sin fricciones.
- Development Preview
- Getting Started
- Release branch catalog
- Public Plugin Matrix
- Early Preview Plugins
- Known Issues
- Architecture Overview
- Plugin Topology
- Module Reference
- Configuration and Registry
- Data-Driven Design
- Profiles and Budgets
- Gameplay Tag Architecture
- Initialization Pipeline
- Cross-Plugin Communication
- Message System
- Event Handlers
- Logging and Trace
- Runtime Flows
- Blueprint API Design
- Editor Integration
- Editor Visual System