HUD #

This document describes the HUD auto-create system.

In short: the HUD class (the HUD auto-create) 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. That means adding the interface to a component and declaring menu widgets is sufficient to have the HUD populate the UI — you do not need to manually create or wire the menu into the HUD.

Key points: – Menu widgets are declared per-component as an array (you can provide multiple widgets per component). – Each widget entry includes the widget to add (must be a common activatable widget), an index (position along the top-bar), and a priority (used when multiple widgets claim the same index). – Index ordering: 0 is the left-most position; larger indices render to the right. – Priority ordering: when two entries request the same index, the one with the higher priority wins.

• HUD auto-create: the HUD instance that builds the UI at runtime by querying components for their declared menu widgets.
• BPI HUD auto-create interface: a blueprint / interface contract components implement to expose their menu widget array to the HUD.
• Menu widget entry: the data shape (one element in the array) describing one widget to add (widget class, index, priority).
• Common activatable widget: the type of widget 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 receive focus.

3. 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 (Player, PlayerController, GameState, or other configured owners) for their menu widget declarations via 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 and adds widgets to the top bar / in-game menu according to the declared index and priority.

4. Data contract (menu widget entry) #

The HUD expects each entry in the provider’s array to contain, at minimum, the following fields (names below are descriptive; confirm exact property names if you want them copied into code/docs):

• A class reference to the widget to create/instantiate.
• Requirement: widget must implement/be a “common activatable widget” (support activation/open/close and the project’s UI lifecycle expectations).
• The slot position along the top-bar. 0 is first/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):

• 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).
• For each component that implements the interface:
  • Call the interface method to retrieve its menu widget array (if any).
  • Validate and collect each entry.
• Resolve collisions by Index using Priority.
• 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).

6. How-to: implement the interface #

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

• Implement the BPI HUD auto-create interface on your component.
• Provide an array property (MenuWidgets / similar) exposed to designers.
• 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.
• On game start the HUD will call your interface method and automatically include your entries.

Developer checklist (implementation hints): – Make sure WidgetClass is instantiable at runtime (not Editor-only) and uses the project’s activatable interface. – Keep Index values contiguous only if intentional — gaps are allowed and will render empty slots unless HUD compresses them (decide which behavior you want and document it). – If your component’s menu entries depend on runtime state, return a filtered array from the interface call so the HUD only receives applicable entries.

7. Examples #

• 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.

8. Edge cases and recommendations #

• Same Index, different Priority: higher Priority wins.
• Same Index, same Priority: behavior not specified here — please confirm whether HUD should prefer the first-registered entry, last-registered, or apply a stable secondary sort (for example by component owner name). If you want, I can update the HUD implementation recommendation accordingly.
• Invalid / non-activatable WidgetClass: skip and log a warning.
• Empty arrays: component contributes nothing (expected).
• Dynamic availability: if a component’s menu entries change during play (for example due to 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 solely on insertion order. – Use Priority sparingly and only for deliberate overrides between systems that logically occupy the same slot.