Note: the HUD queries Character and PlayerController components by default for the BPI HUD auto-create interface.

This document describes the HUD auto-create system.

The HUD class gathers menu widget declarations from game components that implement the BPI HUD auto-create interface and constructs the top bar and in-game menus automatically. Adding the interface to a component and declaring menu widgets is enough for the HUD to populate the UI; you do not need to manually create or wire the menu into the HUD.

Key points:

• Play

• BPI HUD auto-create interface: the Blueprint/interface contract components implement to expose their menu widget array to the HUD.
• Menu widget entry: the data shape that describes one widget to add, including widget class, index, and priority.
• Common activatable widget: the widget type expected by the HUD. Widgets added to the menu must support the project’s activatable UI contract so they behave correctly when opened, closed, and focused.

Components and Interface

This system relies on two roles:

• HUD auto-create: requester and assembler.
  • On creation, the HUD asks all components on relevant actors, such as Player, PlayerController, GameState, or other configured owners, for their menu widget declarations through the BPI HUD auto-create interface.
• Components implementing the BPI HUD auto-create interface: providers.
  • Each provider returns an array of menu widget entries. The HUD reads these entries and adds widgets to the top bar or in-game menu according to the declared index and priority.

Data Contract: Menu Widget Entry

The HUD expects each entry in the provider’s array to contain, at minimum, the following fields. The names below are descriptive; use the local implementation as the source of truth for exact property names.

• A class reference to the widget to create or instantiate.
• Requirement: the widget must be a common activatable widget that supports activation, opening, closing, and the project’s UI lifecycle expectations.
• The slot position along the top bar. 0 is first and left-most; indexes increase left to right.
• When multiple entries claim the same Index, the entry with the higher Priority wins and is placed in that slot. Priority is intended for resolving conflicts when multiple systems occupy the same logical location.

How the HUD builds itself at runtime (high-level):

1. HUD BeginPlay / Initialize:
   • Enumerate actors/components that may implement the BPI HUD auto-create interface (this may be a targeted search or a broad query depending on your project conventions).
2. For each component that implements the interface:
   • Call the interface method to retrieve its menu widget array (if any).
   • Validate and collect each entry.
3. Resolve collisions by Index using Priority.
4. Instantiate widget classes and place them in the top-bar according to their Index (create bindings to activation system so the widgets can open their full UIs when activated).

How To: Implement the Interface

Steps for a component to add a menu entry to the HUD:

1. Implement the BPI HUD auto-create interface on your component.
2. Provide an array property (MenuWidgets / similar) exposed to designers.
3. For each array element, set:
   • WidgetClass: the widget to create. Must be a common activatable widget.
   • Index: integer slot (0 = left-most).
   • Priority: integer to resolve collisions when multiple entries use the same Index.
4. On game start the HUD will call your interface method and automatically include your entries.

Developer checklist:

• Make sure WidgetClass is instantiable at runtime and not Editor-only.
• Make sure WidgetClass uses the project’s activatable interface.
• Keep Index values contiguous only when that is intentional. Gaps are allowed and will render empty slots unless the HUD compresses them.
• If a component’s menu entries depend on runtime state, return a filtered array from the interface call so the HUD only receives applicable entries.

Examples

Example (descriptive / blueprint-style pseudo example):

• Component: YourComponent (implements BPI HUD auto-create)
• MenuWidgets array:
  • Entry A:
    • WidgetClass: YourInventoryWidget (CommonActivatableWidget)
    • Index: 0
    • Priority: 10
  • Entry B:
    • WidgetClass: YourVendorWidget (CommonActivatableWidget)
    • Index: 1
    • Priority: 5

At HUD creation, Entry A is placed in slot 0 (left-most). Entry B is placed in slot 1. If another component also requested slot 1 with Priority 7, that other component’s widget would win slot 1 instead of Entry B.

Edge Cases and Recommendations

• Same Index, different Priority: higher Priority wins.
• Same Index, same Priority: behavior is not specified here. Keep the implementation conservative and use a stable project policy, such as first-registered, last-registered, or a secondary sort by component owner name.
• Invalid or non-activatable WidgetClass: skip it and log a warning.
• Empty arrays: the component contributes nothing, which is expected.
• Dynamic availability: if a component’s menu entries change during play, such as through unlocks, the HUD should either:
  • provide an API to re-query all components and rebuild the top bar, or
  • listen to component-dispatched events that tell the HUD to refresh the relevant slots.

Recommended UX policy:

• Prefer explicit Index values for stable layout. Avoid relying only on insertion order.
• Use Priority sparingly and only for deliberate overrides between systems that logically occupy the same slot.