Table of Contents

Class HudMain

Namespace
RichHudFramework.UI.Client
Assembly
RichHudClient.dll

Primary entry point for the client-side UI system. Provides shared access to root UI nodes, cursor, clipboard, screen metrics, and world-space projection utilities.

public sealed class HudMain : RichHudClient.ApiModule
Inheritance
ModBase.ModuleBase
RichHudComponentBase
HudMain

Remarks

HudMain is the entry point for the framework's tree management and update system. It connects individual mod UI subtrees to the Rich HUD Master module, facilitating the creation of a unified and efficient node graph.

All UI elements created via the framework must ultimately be attached to one of the provided root nodes to be rendered and processed. This architecture allows for stable, load-order independent layering and seamless depth sorting between different mods.

  • Root: This node represents the standard pixel-space root. Elements attached here map 1:1 with screen pixels. This is useful for manual scaling or fixed-size UI.
  • HighDpiRoot: This node is designed for resolution independence, and is the recommended default for new UI. It automatically applies a scaling factor (ResScale) to its children, ensuring that UI elements maintain a consistent apparent size on high-DPI displays (such as 1440p or 4K monitors) without requiring manual layout adjustments.

Update Cycle

The framework manages the update logic for the entire node graph to ensure synchronization. Update passes are handled internally, propagating from the root down to leaf nodes. For a detailed explanation of the update cycle (including Measure, Layout, and Draw passes), refer to the documentation for HudElementBase.

Input Management

The framework creates a unified input environment to handle mouse and keyboard interactions across multiple mods.

  • Shared Cursor: Access to the global cursor is provided via the Cursor property. This interface allows for position querying, tooltip registration, and capture logic. However, direct interaction with the cursor interface is rarely necessary for standard UI components; the framework automatically handles interaction via the IMouseInput interface and the HudSpace.
  • Cursor State: The EnableCursor and RequestCursor properties are used to signal the framework that the mod requests the cursor to be visible.
  • Input Mode: The InputMode property reflects the current state of the input system, indicating whether the cursor is visible or if text input is active.
Note

EnableCursor does not indicate when the cursor has been enabled through other means, such as by other mods or incidentally by built-in Space Engineers UI. Always check InputMode to determine the actual input state.

Coordinate Systems and Metrics

While HudMain provides the 2D screen-space roots, the framework allows the definition of custom coordinate systems via HUD Spaces. These allow UI subtrees to be mapped to 3D world coordinates, such as cockpit displays. Refer to the article on HUD Spaces for details.

To assist with layout and rendering, HudMain exposes several real-time screen metrics:

  • Screen Dimensions: ScreenWidth, ScreenHeight, and AspectRatio.
  • Scaling: ResScale provides the scaling factor used by the HighDpiRoot, normalized to a 1080p baseline.
  • Projection: PixelToWorld provides the matrix required to convert 2D screen-space coordinates into 3D world-space positions for rendering.

Clipboard Integration

The ClipBoard property provides a shared, read/write clipboard specific to the framework. This clipboard supports RichText, preserving formatting data (colors and fonts) when copying text between framework controls, such as TextField and TextBox.

Note

This is separate from the write-only system clipboard API (MyClipboardHelper).

Properties

AspectRatio

The current aspect ratio of the screen, calculated as ScreenWidth / ScreenHeight (e.g., 1.777f for 16:9).

public static float AspectRatio { get; }

Property Value

float

ClipBoard

The shared clipboard for rich text operations across mods. This allows copying formatted text (including colors, scales, and positions) from one mod's UI and pasting it into another.

The is separate from the system clipboard, as access to the real clipboard is write-only. 

public static RichText ClipBoard { get; set; }

Property Value

RichText

Cursor

The shared cursor instance available across all mods. Mods can use this to manually query mouse position, capture/release focus or set tooltips.

Direct use of this interface is usually not necessary. IMouseInput already integrates the relevant functionality directly into clickable UI elements.

public static ICursor Cursor { get; }

Property Value

ICursor

EnableCursor

Enables or disables the shared cursor and switches the input mode accordingly (e.g., from movement controls to UI interaction). Setting this to true shows the cursor and allows mouse input for HUD elements.

public static bool EnableCursor { get; set; }

Property Value

bool

Fov

The current field of view (FOV) angle in radians, as set by the game's camera settings.

public static float Fov { get; }

Property Value

float

FovScale

A scaling factor applied to billboard matrix transforms to compensate for changes in apparent size and position due to FOV adjustments

public static float FovScale { get; }

Property Value

float

HighDpiRoot

The root node dedicated to high-DPI scaling for resolutions exceeding 1080p. This node automatically applies a draw matrix that rescales UI elements to compensate for the reduced apparent size caused by high-DPI displays, maintaining consistent visual sizing.

All top-level UI elements added by mods should be parented to this node or Root to function.

public static HudParentBase HighDpiRoot { get; }

Property Value

HudParentBase

InputMode

The current input mode for the HUD system, indicating whether UI elements should process cursor (mouse) input, text (keyboard) input, or neither.

public static HudInputMode InputMode { get; }

Property Value

HudInputMode

PixelToWorld

The primary transformation matrix used to convert 2D screen-space coordinates (in pixels) to 3D world-space positions (in meters). This is required for rendering UI in screen space.

public static MatrixD PixelToWorld { get; }

Property Value

MatrixD

PixelToWorldRef

The primary transformation matrix used to convert 2D screen-space coordinates (in pixels) to 3D world-space positions (in meters). This is required for rendering UI in screen space.

public static MatrixD[] PixelToWorldRef { get; }

Property Value

MatrixD[]

ResScale

The resolution scaling factor normalized to a 1080p baseline. For resolutions above 1080p, this provides a multiplier (e.g., 2.0 for 4K) to adjust UI sizing. For resolutions at or below 1080p, it returns 1.0f to avoid unnecessary scaling.

public static float ResScale { get; }

Property Value

float

Root

The root parent node for all client-side HUD elements in the framework.

All top-level UI elements added by mods should be parented to this node or HighDpiRoot to function.

public static HudParentBase Root { get; }

Property Value

HudParentBase

ScreenDim

The current screen dimensions as a Vector2 (ScreenWidth x ScreenHeight) in pixels.

public static Vector2 ScreenDim { get; }

Property Value

Vector2

ScreenDimHighDPI

The current screen dimensions (ScreenWidth x ScreenHeight) adjusted for high-DPI scaling by dividing by ResScale, providing normalized coordinates for resolution-independent layouts.

public static Vector2 ScreenDimHighDPI { get; }

Property Value

Vector2

ScreenHeight

The current vertical resolution of the screen in pixels, updated every frame.

public static float ScreenHeight { get; }

Property Value

float

ScreenWidth

The current horizontal resolution of the screen in pixels, updated every frame.

public static float ScreenWidth { get; }

Property Value

float

UiBkOpacity

The current opacity level (0.0f to 1.0f) for in-game UI backgrounds and menus, as configured in the game's settings. Mods can use this to match native UI transparency.

public static float UiBkOpacity { get; }

Property Value

float

Methods

EnableCursorTemp()

Temporarily enables the cursor until the next frame.

public static void EnableCursorTemp()

GetFocusOffset(Action<byte>)

Retrieves a overlay offset for layering a focused UI window and registers a callback that will be invoked if another element gains focus, passing the new offset. This helps manage UI overlap and depth sorting in 3D HUD space.

Layering updates and callbacks are handled automatically in WindowBase.

public static byte GetFocusOffset(Action<byte> LoseFocusCallback)

Parameters

LoseFocusCallback Action<byte>

Returns

byte

GetInputFocus(IFocusHandler)

Registers a callback for changes in input focus on UI elements. The callback is invoked whenever another element (e.g., a game menu or different mod UI) takes input focus away from the registered element.

Input focus is typically handled automatically in MouseInputElement and standard library UI.

public static void GetInputFocus(IFocusHandler handler)

Parameters

handler IFocusHandler
Edit this page