Skip to content
Enzo Herrera.
All projects
Unreal EngineC++MultiplayerNetworkingGameplayToolsFrameworks

Mirage Game Framework

A modular, server-authoritative gameplay framework for Unreal Engine 5.8. Twenty-six C++ modules covering combat, AI, inventory, crafting, quests, dialogue, saving, online sessions and UI, with measured performance budgets and over a thousand automation tests.

Framework Architect & ProgrammerSeptember 2026

Objectives

  • Provide the gameplay systems an online action RPG needs, with server authority and replication designed in from the start.
  • Extend by composition: a new capability is a fragment, a data asset or a component, not a change to the core.
  • Keep modules independent, so a project can use one system without taking the others.
  • Base performance decisions on measurements taken on the server, not on estimates.

Overview

Mirage Game Framework (MGF) is a C++ plugin for Unreal Engine 5.8 that provides the gameplay layer of an online action RPG: combat, AI, inventory and equipment, containers and loot, crafting, quests, dialogue, saving, online sessions, UI and editor tooling.

It started as two separate plugins, one for inventory and one for combat, and became a single architecture that two games in development now build on.

Design principles

  1. Composition over inheritance. An item is a data asset holding a list of fragments, each adding one capability (stackable, equippable, craftable, firearm). Components reach actors through data-driven composition recipes instead of being placed by hand on Blueprints.
  2. Server authority. Clients send requests; the server validates them and changes the replicated state. A client never changes gameplay state on its own.
  3. Gameplay tags as identifiers. Slots, weapon types, states, factions and message channels are native FGameplayTags declared in C++, so adding one is a data change rather than an enum edit.
  4. Data-driven content. Designers author items, recipes, quests, dialogue, AI archetypes and death profiles as assets. Programmers extend the systems that read them.
  5. Measure before optimizing. Periodic sweeps and server hot paths are instrumented, and budgets are written from recorded baselines.

Architecture

Modules are organized in tiers, and dependencies only point downward. MirageFoundationModule depends on the engine alone and holds the shared services: stats, damage, factions, spatial hashing, the message bus, lag compensation, component resolution, actor pooling and profiling. Gameplay modules build on it without depending on each other. MirageIntegrationModule is the only runtime module that combines several of them, and holds the base characters, controllers and cross-system bridges.

ModuleResponsibility
FoundationStats and modifiers, damage pipeline, factions, lag compensation, RPC rate limiting, actor pooling, asset residency, lifecycle and death, item ledger, profiling.
SaveServer-side save orchestration over a swappable storage backend, with slot saves and per-record saves.
AnimationData-driven animation layering: bone masks portable across skeletons, overlays and linked layer sets, built on stock engine nodes.
MovementMover-based character movement, offered alongside the Character Movement Component.
OnlineBackend-agnostic sessions, parties, sign-in and overlay, split by capability.
OnlineEOSEpic Online Services implementation of the online contract.
UILayered UI stack, notification queue, screen-space indicators, menu navigation, themes, nameplates.
AIStateTree nodes, perception and awareness, squads, patrols, population budget, significance LOD, AI director.
CombatGAS combo trees, melee actions, firearms with hitscan and projectile modes, ballistics, hit-stop, camera shake.
HitboxAnimation-driven hit detection, projectiles, damage volumes, hit zones resolved per skeleton.
DismembermentRuntime severing of any bone on any skeletal mesh, with optional generated cut geometry.
InventoryItems and fragments, per-copy instance data, equipment, overflow escrow, item store contract.
ContainerContainers and loot generation, with contents replicated only to the player viewing them.
CraftServer-side crafting queues, stations, quality tiers, recipe discovery, offline progress.
InteractionServer-side candidate detection on a spatial grid, multi-point interactables, interaction sessions.
QuestQuest definitions kept separate from per-player progress, event-indexed objectives.
DialogueBranching conversations, server-validated choices, cinematic shot framing.
AudioMusic and ambient directors, audio zones, gameplay sound routing.
CameraCamera modes and rigs on Gameplay Cameras, lock-on, per-player preferences.
CheatServer-authoritative cheat commands with permission levels and an audit log, excluded from Shipping.
IntegrationBase classes, cross-system bridges, actor composition, dropping and picking up items.
GameFrameworkEditorEditor mode, asset factories and asset actions, component visualizers.
QuestEditorNode-based quest graph editor.
DialogueEditorNode-based dialogue editor with shot preview and an embedded Sequencer timeline.
EditorAutomationContent Browser folder colors applied automatically from project rules.
TestAutomation specs, test harnesses and test doubles.

Gameplay systems

  • Combat. Combo trees resolve abstract inputs against the equipped weapon, with direction, hold and timing conditions per step. Abilities run as GAS LocalPredicted, so an attack starts on the frame of input and the server validates it. A character with nothing equipped attacks with a natural weapon (claws, fists) through the same resolution path.
  • Firearms. One component drives every firearm from data: hitscan or projectile, stance-based spread, recoil patterns, damage falloff and armor penetration. The ballistics model is a pure function library, so the client and the server compute the same spread cone.
  • AI. StateTree behaviors with perception, awareness and suspicion, squads that share stimuli, patrols and tactical positioning. A significance system lowers decision rate, replication rate and network activity with distance. An AI director steers one hunting creature by sending it to areas of interest rather than to the player's exact position.
  • Dismemberment. Any bone can be severed at runtime without pre-cut meshes. The server replicates only which parts are gone. Clients collapse the limb at the cut and can generate a capped mesh piece off the game thread, cached per mesh so identical creatures reuse the result.
  • Quests and dialogue. Definitions are shared assets, and a player's progress is a small replicated record. Dialogue replicates node indices and a bitmask of available choices, never text, and the server checks each choice before applying it.
  • Crafting. Recipes are built from requirement, cost and output fragments. Queue progress is based on timestamps rather than per-tick replication, and carries over saves, reloads and offline time.

Networking

  • Push-model replication on every replicated property, with FastArray serialization for collections.
  • Data split by audience. Equipment sends the full item record to its owner and only the slot and item ID to other players. Container contents go only to the player who opened the container. A player's GAS montages and cues travel on the pawn instead of the always-relevant PlayerState, so distant players do not receive them.
  • Iris support with prioritizer tiers per actor type, distance bands that match the AI significance bands, and tests that check the configuration against the code.
  • Lag compensation for hitscan shots and melee sweeps, using a fixed-size history buffer per actor. Timestamps ahead of the server are rejected and old timestamps are clamped.
  • RPC rate limiting per connection and per request category, resolved in constant time, with throttled feedback to the client.
  • Online services behind an abstract backend, with the EOS implementation in its own module and credentials kept in each project's configuration.

Persistence

The save module has no knowledge of gameplay modules. A system becomes saveable by implementing a Foundation interface or by marking properties with SaveGame.

  • Two granularities. Whole-world slot saves for single-player, with Oodle compression, checksums, backups, version migration and World Partition support. Per-record saves for online play, where each player or entity is written on its own.
  • Concurrency. Record writes carry a revision and are rejected on conflict instead of overwriting newer data. Entity leases stop two servers from owning the same character. Writes to the same record are queued and merged.
  • Asynchronous API. Every record operation has an asynchronous form, so a database or cloud backend never blocks a server frame.
  • Item ledger. An append-only journal records every server-side item movement with its source, destination and reason, and detects gaps in its own sequence.

Performance and testing

A single MGF_PERF_SCOPE line reports to Unreal Insights, the engine's stat counters and the framework's own accumulator. Memory pools and per-connection bandwidth are recorded through the same system, and mgf.perf.baseline writes the timing, memory and bandwidth figures to a document that budgets are written from.

One measurement changed a design decision. A 36-creature test session showed StateTree decisions taking 95% of the framework's frame time. The engine reset the tick interval set by the significance system after every tick, so every agent was deciding every frame. The component now reapplies its interval after the engine's own update.

Tests are automation specs. World-backed specs create a real UWorld and game instance, so components and subsystems run their normal lifecycle. Key specs are checked by mutation: the code under test is deliberately broken to confirm the test fails.

Editor tooling

  • An editor mode that groups the framework's live pages (cheats, saves, profiler, memory, stats, combat, AI significance, AI director, UI) under five categories: Session, Performance, Character, World and Presentation.
  • Quest and dialogue graph editors. The dialogue editor previews shots with the runtime camera solver and embeds a Sequencer timeline per node.
  • 43 asset factories, component visualizers for patrol routes and interaction points, and 14 Gameplay Debugger categories that collect on the server.
  • A content audit that reports asset types with no content, and content the Asset Manager cannot find.

Source tree

MirageGameFramework26 modules · 1,742 files · C++ · UE 5.8 plugin
MirageAIModule.Build.cs
MirageAnimationModule.Build.cs
MirageAudioModule.Build.cs
MirageCameraModule.Build.cs
MirageCheatModule.Build.cs
MirageCombatModule.Build.cs
MirageContainerModule.Build.cs
MirageCraftModule.Build.cs
MirageDialogueEditorModule.Build.cs
MirageDialogueModule.Build.cs
MirageDismembermentModule.Build.cs
MirageEditorAutomationModule.Build.cs
MirageFoundationModule.Build.cs
MirageGameFrameworkEditor.Build.cs
MirageHitboxModule.Build.cs
MirageIntegrationModule.Build.cs
MirageInteractionModule.Build.cs
MirageInventoryModule.Build.cs
MirageMovementModule.Build.cs
MirageOnlineEOSModule.Build.cs
MirageOnlineModule.Build.cs
MirageQuestEditorModule.Build.cs
MirageQuestModule.Build.cs
MirageSaveModule.Build.cs
MirageTestModule.Build.cs
MirageUIModule.Build.cs
MirageGameFramework.uplugin
.h
.cpp
.cs
.uplugin

Roadmap

  • Server topology. A world router for instance lifetime, capacity and handoff between server processes.
  • Genre systems. Progression, threat tables, groups, economy and social features.
  • Networked testing. Automated tests on a live listen-server session, run on every framework commit.

Results & highlights

  • 26 modules (20 runtime, 4 editor, 2 development) in 1,742 C++ files and about 196,000 lines, with no circular module dependencies.
  • Push-model replication on every replicated property, with per-player data sent only to the players who can use it.
  • 91 automation specs and 1,073 test cases, most running against a real UWorld and game instance rather than mocks.
  • 62 instrumented systems and 14 memory pools reporting to Unreal Insights, stat counters and budget reports, including on a dedicated server.
  • Record-based save backend with optimistic concurrency, entity leases and an append-only item ledger.
  • Shared foundation of two games in development: an online listen-server project and a single-player project.