General Information

All non self-explanatory blueprint classes and most functions or blueprint graphs in general, have a blue comment within them that explain what the class is for and possibly how it works. Also all events are inside comments to make the overview a bit easier as well as a convenience in finding a specific event when looking at a blueprint graph due to the comment title being larger than the event title. Right in front of the spawn location on the lobby and game maps there are comments on the wall that explain typical use cases lobbies and game maps.

You’ve probably noticed that almost all files are inside the OGMainMenu folder instead of directly in the Content folder. That’s on purpose. It makes migrating this template into your own project (or the other way around) much cleaner. In most cases, folders like “Characters” or “GameModes” already exist, and mixing them with template content can get messy fast. If you do want everything in one place, feel free to move the files after migrating. If not, no need to thank. Just smile, nod, and enjoy the folder structure.

Common UI

Overview

Citing the Unreal Engine Common UI Documentation:
“Common UI supports the development of cross-platform UIs with complex navigation, such as menus with layers, submenus, or popups. Originally developed for UI in Fortnite, this plugin is available to Unreal Engine users through the Plugins menu.”

Problems Common UI solves

• Selective interactivity between layers of UIs
• Handling of various input methods through all the different platforms and controllers (ie. Mouse and Keyboard, Playstation Controller, Xbox controller, Smartphone etc. )
• Return to the previously selected element with cardinal navigation in case of closing a pop up for example
• Display Console-specific UI Elements depending on which input method is being used.
  Example Jumping: “A” Button icon when using an Xbox controller and spacebar icon when using Mouse and keyboard

Common UI’s Features

• Selective widget interactivity, providing an easy way of creating rich UIs with layering.
• Multiplatform console and PC support.
• On consoles:
  • Cardinal navigation management, including breadcrumbs and history.
  • Console-specific UI element management.

The concept of Input Routing and Nodes in Common UI

Input Routing refers to how user input (from a mouse or gamepad) is directed to specific UI elements. It ensures that only the relevant widgets can respond to input at any given time, helping manage complex menus. For example, one button may always receive input, while another only gets it when selected.

Nodes are the building blocks that handle input routing. CommonUI turns widgets into nodes, which are organized in a tree structure. Each node represents a part of the UI, such as a button or a menu, and the tree shows how they’re connected visually.

When a user interacts with the interface, CommonUI checks which node (=widget) is on top and sends input to that node. The node then forwards the input to the next relevant part of the UI until it’s processed. This method keeps input management clean and efficient, especially for complex layouts.

Activatable Widgets

Within Common UI, only certain widgets are converted into nodes for the purpose of handling input, and only widgets that are ready to handle input receive input. These widgets are called activatable widgets, and they are considered  “active” if they are ready to receive input.

Activatable widgets help manage input flow, especially in overlays. If an overlay widget is dismissed, CommonUI ensures that input is routed to the next active widget, even if it’s on a lower UI layer. Only the topmost active tree receives input at any time, so lower layers don’t need to worry about being inactive if they’re still in use.

Throughout the template, you will notice widgets inheriting from the Common Activatable Widget class. Widgets inheriting from this class usually aren’t created like normal User widgets usually would. Instead they get pushed on Stack layers and become active by doing so.

Layer Widgets in CommonUI

In this template, different types of UI content are managed by specific layers. Each layer represents a stack of widgets that can be pushed or popped/deactivated to control which UI elements are visible at a given time.

The layer structure used in this template consists of:

• Game: For HUD and similar elements.
• GameUI: For gameplay-related menus (e.g., inventory).
• Menu: For settings or options screens.
• Modal: For overlays like Pop-Up windows.
• PopUpMsg: For Pop-up Messages

The hierarchy of WB_CmnUI.

When a widget is pushed onto a layer with existing content, it replaces the current widget until it is deactivated (popped off). For example, pushing a new UI element onto the GameUI layer replaces the old one.

Each layer operates as a separate stack, so when a new widget is pushed onto a higher layer (e.g., Menu), the layers below it remain visible. This allows for flexible, non-overlapping UI structures.

Initial Common UI Setup

These are the steps this template took to properly setup common ui. You don’t need to do them if you build on top of the OG Main Menu project. However, for your convenience and because templates should also be learning material, the steps that were taken are listed below:

1. Open Edit > Project Settings > Engine > General Settings and set your Game Viewport Client Class to CommonGameViewportClient.
2. Enable the Common UI Plugin and restart the engine.
3. Create an Input Action for each of the following Common UI Actions:
   1. Accept, Back, NextTab, PreviousTab.
4. Create a new Input Mapping Context and add the Input Actions created in the previous step to it. Also, assign a keyboard and controller key to each.
5. Create a new data asset of type Common Mapping Context Metadata.
   1. Assign Common Input Metadata to the field called Enhanced Input Metadata
   2. Check Is Generic Input Action.
   3. Create an element for each of the Input Actions that you’ve created in step 2, set it’s value to Common Input Metadata, set Nav Bar Priority to 10 and check Is Generic Input Action.
6. Go back to each Input Action that you have created, open it and expand Player Mappable Key Settings.
   1. Assign the Data Asset you have created to it.
   2. Set it’s Name and Display Name values (For the Back Key for example: “Back” for both).
7. Create a blueprint class of type Common Input Base Controller Data.
   1. Set it’s Input Type to Mouse and Keyboard.
   2. Create an array element inside the Input Brush Data Map for each key that you want to have an icon for. In these elements, assign the keys to their icons.
8. Create another blueprint class of type Common Input Base Controller Data.
   1. Set it’s Input Type to
   2. Set it’s Gamped Name to Generic and it’s Gamepad Display Name to the platform ie. Xbox/Playstation Controller probably.
   3. Again, create the wanted array elements inside the Input Brush Data Map.
9. Create a new blueprint class of type CommonUIInputData and assign the Accept and Back Input Actions to the appropriate fields.
10. Open Game > Common Input Settings > Input.
    1. Assign the previously created CommonUIInputData class to Input Data.
    2. Enable Enhanced Input Support and Allow Out Of Focus Device Input. Uncheck Enable Default Input Config as it prevents the default Set Input Mode nodes from working.
    3. Expand Platform Input > Windows > Default and set it’s Default Input Type to Mouse and Keyboard as well as it’s Default Gamepad Name to Generic. Then expand Controller Data and create 2 elements, one for each of the Common Input Base Controller Data classes that you’ve created.

If you have additional questions, consider joining the Outface Games Discord server.

Also, checkout this in-depth tutorial on how to set up the different parts of Common UI by MrButier (and subscribe to him as well).

Common Styles

CommonUI comes with its own set of widgets, found under the Common UI Plugin section in the UMG Palette. Unlike regular UMG widgets, these don’t have built-in styling options. Instead, they use Common Style Assets to control appearance.

You’ll find the style assets of the OG Main Menu in the CoreUI folder, under the subfolders Button, Borders, and Text. Changing a style asset updates every CommonUI widget that uses it. For example, if you update the font of a CommonTextStyle asset, all CommonText widgets using that style will update automatically, making it easy to keep your UI consistent.

You can create new style assets by creating a Blueprint of the Style type that you want as you can see in the following image.

Feel free to try them all out, it’s surely a great learning experience!

For More information, checkout the Common UI Quickstart Documentation.

Structure

Dependencies

The architecture planned for this template regarding almost all widgets is that the Player Controller depends on the HUD, the HUD depends on the main menu widget and other independent widgets like the pause menu, the main menu depends on it’s subwidgets and single widgets depend on nothing other than their contents like fonts and images. Additionally, wherever applicable soft references and async loading was used. This way, the game is light on the hardware of the player.

Inheritance

Gamemode, Game State, Player Controller and HUD

There is one parent class each for the Gamemodes, Game States, Player Controllers and the HUDs that combines all the functionality that multiple of its children might need. The main menu, lobby and game maps all have separate classes that inherit from these. Additionally, only the parents have interfaces added to them, even if some of the functions are only used by one of their children. The reason that there isn’t a separate interface for each of the children as well, is simplicity. The scope of this project didn’t need it, you might need it, so feel free to do these changes.

Like previously mentioned, the OG Main Menu makes large use of inheritance. Not only the Gamemodes and co. use it, but also the Character class with its children that essentially are the selectable skins in the Character selection menu as well as a lot of the other classes. Take the widgets for example,

Maps

The startup map is the map called… “Startup”, who would’ve thought? Then there are the MainMenu, LobbyMap, the 3 game maps ie. Prison, Dungeon and Temple as well as the TransitionMap that is needed for seamless travel. Anyways, the reason the game doesn’t start in the main menu map is that if we want the party system to work, we need to have a session opened already inside the main menu to close it and reopen another one.

This however is only a workaround as a party system is not possible in the current Unreal Engine subsystem and could lead to some warnings in the logs like “LogOnlineSession: Warning: OSS: Player (..) is not part of session (GameSession)”.

That being said, it does work but if you’re uncomfortable with potentially having some warnings in your logs, you can fix it by setting the MainMenu map as the startup map and removing the party window.

Main Widgets

WB_CmnUI

This widget is the core widget which holds the stack layers onto which almost all other widgets get pushed on. To understand better what stack layers are, checkout the section on Layer Widgets in CommonUI!

Additionally, this class handles pushing and removing widgets. This is handled by utilizing gameplay tags, one for each stack layer, then giving it over as an input through that function call, test which tag was given over and push the widget on the appropriate stack layer. The default Push Widget node does not take a gameplay tag or stack layer as an input and instead just. pushes. widgets. Almost as if the name was too perfect, right?

AWB_BaseWindow

This is the parent of almost all pop-ups and generally most non-base widgets in this template (Base widget in the sense of Main Menu etc.). This widget handles removing widgets when clicking outside of the window and allows its children to set their own size through the NamedSlot widget, by having a SizeBox widget as their root widget. Also it has a Common Action Bar at the bottom of the screen that displays action icons that are active/clickable.

AWB_MainMenuBase

This widget holds all other tab menus (like CharacterMenu, HomeMenu etc.) as well as additional sub-widgets (like the party window) in it. Whenever one of these menus or subwidgets need to communicate to the HUD, either this AWB_MainMenuBase plays the middleman or via an interface.

AWB_Lobby

This widget does the same middle man job as the AWB_MainMenuBase but in the Lobby map instead.

WB_MouseCursor

This widget is being used as the default cursor in this project. That being said, you can change it by changing the cursor aesthetically in this widget, creating a new similar widget or by removing it from Engine > User Interface > Software Cursors and thus returning to the default platform cursor style.

AWB_SettingsMenu

Within this widget the player sets all settings.

These are seperated into 3 categories:

1. Video settings – consists of graphics and some general settings like displaying the FPS.
2. Controls – allows the player to remap keys and change camera settings.
3. Audio – displays multiple sliders of which everyone changes a specific audio category like UI, ambient etc. .

Inside the functions tab you can see that each graphics setting has 5 functions to it.

First, there is the getter that handles displaying the quality in the widget. Then there are two for changing that specific setting, one for setting it to a lower and one to a higher value. Finally, there are 2 more that are being used within the lower and higher functions and are necessary to check if that setting goes any lower or any higher than what it already is. If not, then that specific arrow gets disabled.

Also, there is an “overall” quality setting that handles changing all settings at once. Whenever a setting is changed to a value that doesn’t align with all the others anymore, then the overall quality shows “Custom” as a value.

WB_SettingsItemBase

This widget is the parent of all other setting item widgets like WB_Settings_Bool or WB_KeyRemap that are extensively used inside the settings menu. This is mainly due to easily maintaining a consistent design.

This is the design used by all setting items. Beautiful, right?

Main Classes

Game Instance

The game instance has multiple “jobs” in the context of the OG Main Menu.

Firstly, to store values like the selected skin ID or the selected mode to retrieve them when traveling to the Lobby or Game map.

Secondly, to retrieve or create the appearance SaveGame file on initialization and apply it’s values to the appropriate classes through Blueprint function library functions.

Lastly, printing a log of the reason when a player disconnects due to network errors.

Player State

The player state handles replicating the profile cards to other players, as well as updating them whenever changed by a player.

Character Class

The character class handles basic movement functionality and is subclassed into multiple skin classes that each only have a different character mesh.

Actor Components

AC_ChatSystem

This component is attached to the Base Player Controller class and handles opening, closing and sending messages through the chat window. It’s basically the brain of the chat widget.

AC_Settings

This component is attached to the Base Player Controller and handles setting and saving Player specific settings like the mouse sensitivity. Additionally, it has some useful functions especially for the Key Mappings.

Input

This template utilizes 3 Input Mapping contexts in total.

• IMC_UI_Generic is for the Common UI Inputs like the Back Button, Accept Button, Right tab, Left Tab, as well as some menu buttons. To make it easier to differentiate, Input Actions used in this context are prefixed with IA_UI_Generic and can be found inside Input > Actions > Generic.
• IMC_PlayerCharacter is for the actual “game” controls like the pawn movement keys as well as menu buttons that are only present while controlling a pawn, here for example the Game Menu. This Mapping context is changed when changing keybindings in the settings menu.
• IMC_PlayerCharacter_Default is the same as IMC_PlayerCharacter but unedited and thus at it’s default keybindings.