Quick Start

By the end of this page you have the full UI stack running: a policy that creates one root layout per local player, tag-keyed layers registered on it, and a HUD layout pushed onto the Game layer at startup. Every screen you build later is a two-line push onto this stack.

1. Enable the plugin

Open Edit -> Plugins, type Crimson in the search box, tick CrimsonUI's checkbox (and CrimsonCommon, its dependency), and restart the editor when prompted. For a Blueprint project that is the entire install - you never hand-edit the .uproject or any .Build.cs.

C++ projects: after enabling the plugin, add its module to your build file so your game code can use its types:

// YourGame.Build.cs
PublicDependencyModuleNames.Add("CrimsonUI");
PublicDependencyModuleNames.Add("CrimsonCommon"); // policy/layout base layer

2. Set the Game Instance and Local Player classes

The UI manager boots off two classes from CrimsonCommon. UCrimsonCommonGameInstance broadcasts player-added/removed events the manager subscribes to; UCrimsonCommonLocalPlayer is the local-player type the manager requires (players of any other class are silently ignored). UCrimsonCommonGameInstance is Abstract, so make a subclass first.

BlueprintC++

3. Set the viewport client

UCrimsonGameViewportClient (a UCommonGameViewportClient) drives hardware vs software cursor from the Platform.Trait.Input.HardwareCursor platform trait. CommonUI needs a UCommonGameViewportClient for its input routing, so set it even if you never touch cursors:

BlueprintC++

Open Edit -> Project Settings -> Engine -> General Settings, expand the Default Classes section, and set Game Viewport Client Class = Crimson Game Viewport Client. The editor prompts to restart - accept it, because the viewport client class is only swapped in on startup. No .ini editing needed; the picker writes the same GameViewportClientClassName line for you.

4. Give CommonUI its Click and Back actions

CommonUI's action router needs a Click and a Back input action to drive activatable widgets. Create two Input Action assets (Content Browser -> right-click -> Input -> Input Action), e.g. IA_UI_Confirm and IA_UI_Back, then register them. On UE 5.8 use the Enhanced Input path - it resolves live key bindings so button glyphs update on rebind:

; Config/DefaultGame.ini
[/Script/CommonInput.CommonInputSettings]
bEnableEnhancedInputSupport=True
EnhancedInputClickAction=/Game/Input/IA_UI_Confirm.IA_UI_Confirm
EnhancedInputBackAction=/Game/Input/IA_UI_Back.IA_UI_Back

5. Define your layer tags

Layers are gameplay tags under the UI.Layer parent. CrimsonUI defines UI.Layer.Menu and UI.Layer.Modal natively (CrimsonCommon adds UI.Layer.ContextMenu); your project defines the rest. Add at least the Game layer in Project Settings -> Project -> GameplayTags -> Gameplay Tag List, or in ini:

; Config/DefaultGameplayTags.ini
[/Script/GameplayTags.GameplayTagsSettings]
+GameplayTagList=(Tag="UI.Layer.Game",DevComment="Always-visible HUD content")
+GameplayTagList=(Tag="UI.Layer.GameMenu",DevComment="In-game menus: inventory, map")

6. Create the root layout Blueprint

The root layout is one widget Blueprint deriving from UCrimsonPrimaryGameLayout (CrimsonCommon). It holds one UCommonActivatableWidgetStack per layer and registers each stack under its tag.

BlueprintC++

In the Designer add an Overlay, then four Common Activatable Widget Stack children named GameStack, GameMenuStack, MenuStack, ModalStack (each slot set to fill). In the Event Graph, from Event On Initialized call Register Layer four times: (UI.Layer.Game, GameStack), (UI.Layer.GameMenu, GameMenuStack), (UI.Layer.Menu, MenuStack), (UI.Layer.Modal, ModalStack). Register Layer is callable because your Blueprint is the layout class - it does not appear on external references.

7. Create the policy Blueprint

The policy (UCrimsonGameUIPolicy, CrimsonCommon) decides which layout class to spawn and how local multiplayer shares the screen. Create a Blueprint Class with parent Crimson Game UI Policy, name it BP_UIPolicy, and set:

8. Point Project Settings at the policy

Open Project Settings -> Crimson -> Crimson UI (UCrimsonUISettings, saved to DefaultGame.ini) and set:

9. Create a HUD layout and push it

Create a widget Blueprint BP_HUDLayout with parent Crimson HUD Layout (UCrimsonHUDLayout) - it is the always-present root HUD screen (leave its defaults alone for now; How-To: HUD Layout & Escape Menu wires the pause menu). Push it onto the Game layer when the local player is ready:

BlueprintC++

The node is Push Content To Layer For Player (async, from UCrimsonAsyncAction_PushToLayer). Its BeforePush pin fires with the created widget before activation - use it to set variables the widget reads on activate; AfterPush fires once it is live.

10. (Recommended) Set the HUD actor class

ACrimsonHUD registers itself with UGameFrameworkComponentManager, which lets GameFeature actions attach HUD widgets/components later, and feeds the ability-system debugger a useful actor list. Set it as your GameMode's HUD Class:

BlueprintC++

Open Project Settings -> Maps & Modes. Under Default Modes, set Default GameMode to your GameMode Blueprint, then set Selected GameMode -> HUD Class = Crimson HUD (or a Blueprint subclass of it). This saves onto your GameMode Blueprint - no .ini editing required.

The Selected GameMode rows are editable only while the Default GameMode is a Blueprint. You can set the same value directly on the GameMode Blueprint instead: open it and use Class Defaults -> Classes -> HUD Class.