UI Framework

Every game needs a UI. Menus, prompts, pop-ups, and overlays. I found the implementation of those features was often annoying and troublesome to scale. In an effort to investigate ‘good practices’ when managing UI in Unreal Engine, I created a UI framework using some of the newer tools in the engine. The framework is designed to be reusable across projects and to give teams a consistent structure for screen registration, layer management, modal flows, and UI lifecycle.

The framework is bundled as a standalone plugin. It comes with a set of pre-made widgets and blueprints for faster setup, but the core architecture is gameplay-agnostic and can be extended with custom widgets and screen flows.

This framework is my interpretation of a solid, reusable foundation for UI in Unreal Engine, based on the CommonUI / Lyra-style patterns.

Technologies

I explored what plugins and paradigms were available in Unreal Engine for building and managing UI. I learned to appreciate CommonUI as a solid foundation for widget lifecycle, input handling, and widget navigation. I also examined the ‘CommonGame’ plugin found in the Lyra example project, mainly its layer-based screen management system.

I also explored the ‘Model-View-ViewModel’ pattern, available in Unreal with the MVVM plugin. I experimented with it and found it interesting, but ultimately chose not to use MVVM in the framework.

MVVM does not compete with CommonUI and actually complements it well. It is valuable when widgets have significant state and transformation logic to manage. I found no use for it in the framework’s higher-level context, but I ended up using it in my Settings Plugin, a more proper use case for MVVM.

CommonGame Architecture

At the center of the framework is the Primary Layout Widget and its ‘layers’, a setup inspired by the CommonGame plugin’s approach to screen management.

The Primary Layout Widget is a unique widget that is created at startup and persists across the game’s lifespan. It is responsible for maintaining the overall UI structure, handling different aspect ratios, and managing ‘layers’.

Each ‘layer’ is backed by a UCommonActivatableWidgetContainerBase widget, associated with a Gameplay Tag. Any widget can be pushed to a layer, and the layer will handle its activation, deactivation, and input routing. Widget pushing is data-driven through a registry of screen definitions, which specify the widget class, input mode, and layer for each screen. Pushed widgets are loaded from soft references for better memory management.

It is also possible to configure a layer as ‘modal’, meant for pop-ups, blocking screens, and other temporary UI. The ‘modal’ layer supports additional methods to push pre-configured pop-ups for easier use. It also supports queuing, so if a pop-up is already open, the next one will wait until the current one is closed before showing.

Making the Primary Layout Widget a persistent, always-present widget required some custom handling. Normally, widgets in the viewport are destroyed on level change. The Primary Layout Widget is temporarily stored in a UGameInstanceSubsystem on level transition, and then re-added to the viewport once the new level is loaded. Layers can be configured to maintain their state across level transitions or to be reset, depending on the use case. This also applies to the pushed widgets, which may override the default behavior to persist across level transitions if needed.

Other Core Features

Editor-Side Configuration
The framework can be configured in the editor. In most scenarios, it won’t be required to modify any code to set up the main menu, pause menu, and other common screens. This is meant to make it easy for designers to iterate and extend the UI without needing engineering support.

Aspect Ratio Management
The Primary Layout Widget includes logic to manage different aspect ratios. Various solutions are supported, such as pillarboxing, letterboxing, extending the UI to fill the screen, or scaling the UI.

Localization Support
All user-facing text is implemented as FText for localization support.

Optional Features

These are not part of the framework’s core architecture; they are optional convenience features that grew out of the same exploration.

News Feed

Fetch and display ‘news’ from a remote source. Show the player updates, announcements, and other relevant information.

First Experience Flow

Implement a ‘First Experience’ UI flow, screens that are only shown to the player the first time they launch the game, such as language selection or disclaimer / EULA acceptance.

Splash Screens

On game startup, show a sequence of ‘splash screens’ to the player. It can be configured to show any widget (image, video, etc.), and supports skipping and ‘show only once’ behavior.

Version Check

A simple version check system that compares the local version with a remote version file on startup. This may be useful to notify the player of updates.

Template Content

The framework includes blueprint and helper classes for common use cases, such as a main menu or common ‘pop-up’ layouts.

ImGui Debug Integration

I’ve added integration with my ImGui-based debug tooling so the framework’s internal state can be inspected at runtime. See Debug Shard for more details.

Tradeoffs

The plugin depends on CommonUI. I found CommonUI to be a very good foundation, filling many of the gaps in Unreal Engine’s UMG system. It provides stronger patterns for widget lifecycle, input routing, and widget navigation.

CommonUI requires non-trivial setup and comes with a learning curve. Both CommonUI and my framework expect a fairly opinionated widget lifecycle and navigation model, which may be unnecessary for smaller projects. In those cases, plain UMG may be entirely sufficient.