How-To: Show a Widget on a UI Layer

Goal: use the CommonUI foundation in CrimsonCommon to push an activatable widget onto a named layer of the primary game layout - the HUD/menu stack that replaces the CommonGame plugin.

Prerequisites
CrimsonCommon and CommonUI enabled. A UCrimsonGameUIPolicy set up with your UCrimsonPrimaryGameLayout subclass (the layout Blueprint that owns your layer containers).

1. Register your layers

In your primary-layout widget, register each layer container against a UI.Layer.* tag (e.g. UI.Layer.Game, UI.Layer.GameMenu, UI.Layer.Menu, UI.Layer.Modal). The layout calls RegisterLayer(LayerTag, Container) for each UCommonActivatableWidgetContainerBase it owns. Layer tags are project-defined - CrimsonCommon doesn't hardcode them.

2. Push a widget to a layer

From anywhere with a player, push an activatable widget class onto a layer. The widget is created, activated, and added to that layer's stack.

Screenshot pendingImages/CrimsonCommon/howto-ui-push.png
Push Content To Layer (For Player): Local Player, Layer Name tag, Widget Class.
Verify
The widget appears on the chosen layer and participates in CommonUI back/activation handling. Pop it by deactivating it (or FindAndRemoveWidgetFromLayer).

3. (Optional) Make a layer extensible

To let other plugins inject widgets into a slot without you referencing them, use the UI Extension system. Register an extension point (a named slot) in the host widget, and have contributors register an extension widget against the same tag. CrimsonCommon brokers the match.

cpp
// Contributor side - inject a widget into a named slot, no host reference:
UGameInstance::GetSubsystem<UCrimsonUIExtensionSubsystem>(GI)
    ->RegisterExtensionAsWidget(Tag_UI_Extension_HUD_Bottom, MyWidgetClass, /*Priority*/ 0);
Blueprint nodes
The extension API is exposed to Blueprint as Register Extension Point and Register Extension (Widget) (UCrimsonUIExtensionSubsystem), returning handles you keep to unregister.

See also

  • Concept: Modular Actors & Player Layer - where the UI policy and local player fit
  • API Reference - UCrimsonPrimaryGameLayout, UCrimsonUIExtensionSubsystem