Table of Contents

Class BindManager

Namespace
RichHudFramework.UI.Client
Assembly
RichHudClient.dll

The central hub for creating and retrieving key binds, control groups, and configuring input blacklisting in the framework.

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

Examples

The following example demonstrates how to initialize a custom IBindGroup, register default key combinations using BindGroupInitializer, and apply previously saved configuration data.

IBindGroup allows binds to be retrieved by index or by name. This is convenient for initialization, but error-prone in UI integrations. For this reason, it is recommended to retrieve binds from the group once, and cache their references.

public class MyCustomBinds
{
    // Public accessors for specific binds
    public IBind MenuOpenBind { get; private set; }
    public IBind ModifierBind { get; private set; }

    public IBindGroup BindGroup { get; private set; }

    public MyCustomBinds(IReadOnlyList<BindDefinition> savedConfig = null)
    {
        // 1. Retrieve or create the group
        BindGroup = BindManager.GetOrCreateGroup("MainControls");

        // 2. Define default binds
        var defaults = new BindGroupInitializer 
        {
            { "MenuOpen", RichHudControls.Control, RichHudControls.F },
            { "Modifier", RichHudControls.Shift }
        };

        // 3. Register defaults
        BindGroup.RegisterBinds(defaults);

        // 4. Overwrite defaults with saved config (if available)
        if (savedConfig != null)
        {
            BindGroup.TryLoadBindData(savedConfig);
        }

        // 5. Store individual bind references for use in the mod
        MenuOpenBind = BindGroup["MenuOpen"];
        ModifierBind = BindGroup["Modifier"];
    }
}

Remarks

The BindManager acts as the central factory for the creation, retrieval, and management of key bindings within the Rich HUD Framework. It facilitates the organization of controls into groups, manages the registration of custom input configurations, and handles the suppression of standard game inputs (blacklisting) when necessary.

Bind Groups

This is the central interface for organizing, initializing, and modifying individual binds.

  • An IBindGroup is a collection of unique, order-independent key combinations, referred to as IBind objects.
  • Groups are created via GetOrCreateGroup. Their names are local to a given mod and must be unique (case-insensitive) within that context.
  • Binds are backed by IControl objects, which provide metadata and allow for dynamic configuration.
  • Binds can be added individually via AddBind or TryRegisterBind, or in batches via RegisterBinds, but they cannot be removed once registered.
Note

Key binds within an IBindGroup must be unique. While different groups can have overlapping binds, conflicts within a single group are not allowed. Bind names must also be unique within a group (case-insensitive).

Initialization Utilities

These convenience classes aid in the initialization and registration of binds within a group.

  • BindGroupInitializer: A convenience container used to define the initial state of an IBindGroup.
    • Used in conjunction with RegisterBinds() to batch-register default configurations.
    • It supports combinations of control names, VRage.Input.MyKeys, VRage.Input.MyJoystickButtonsEnum, and RichHudControls.
  • RichHudControls: This is the recommended enum for specifying hard-coded controls, as it unifies keyboard, mouse, and gamepad inputs into a single type for simplicity.

UI Integration

These components provide the graphical user interface layer for key binding management and event integration.

  • RebindPage: A ready-made GUI for the RichHudTerminal. It provides an interactive user interface for clearing or rebinding keys within IBindGroups registered to that page.
  • BindInputElement: An implementation of IBindInput designed to integrate declarative event-driven input into the UI tree.
    • While IBind provides global input events, BindInputElement ensures events only fire when the specific UI node is visible and input-enabled.
    • This is essential for context-sensitive controls that should not trigger when the UI is hidden or when a different window has focus.
    • Alternatively, binds can be polled manually in HandleInput.

Serialization

Key binds are not serialized automatically by the framework. It is the responsibility of the mod developer to handle persistence using the following workflow:

  1. Save: Before the session unloads, retrieve the current bind definitions using GetBindDefinitions.
  2. Write: Serialize these definitions (e.g., to XML) and write them to a configuration file in mod-local storage using WriteFileInLocalStorage.
  3. Read: On session initialization, read the file using ReadFileInLocalStorage and deserialize the data.
  4. Load: Apply the loaded definitions to the IBindGroup using TryLoadBindData.

Bind names should be registered via RegisterBinds before attempting to load deserialized definitions to ensure the group structure exists.

Input Blacklisting

The framework allows for the suppression of standard game inputs (such as camera rotation or mouse clicks) while UI elements are active. This is controlled via InputFilter, BlacklistMode, or RequestTempBlacklist using SeBlacklistModes flags.

  • Common Use Cases: Disabling camera look while a cursor is visible, intercepting chat input for text fields, or blocking interactions with the game world while a menu is open.
  • Limitations: Blacklisting is not comprehensive; some Space Engineers controls cannot be disabled via the Mod API. Gamepad/Joystick blacklisting functionality may vary.
Warning

BindManager coordinates blacklisting between mods using the framework to prevent conflicts. Avoid using the native SetPlayerInputBlacklistState API directly, as it may interfere with this system.

Fields

MaxBindLength

The maximum number of controls allowed in a single key bind combination (currently 3).

public const int MaxBindLength = 3

Field Value

int

Properties

BlacklistMode

Gets or sets the persistent input blacklist mode.

This setting remains active until explicitly changed. Use this to block game inputs (like mouse clicks or camera movement) while UI elements are interactable.

public static SeBlacklistModes BlacklistMode { get; set; }

Property Value

SeBlacklistModes

Controls

A read-only collection of all available controls (keys, mouse buttons, gamepad inputs) supported by the framework.

public static IReadOnlyList<IControl> Controls { get; }

Property Value

IReadOnlyList<IControl>

Groups

A read-only collection of all registered bind groups.

public static IReadOnlyList<IBindGroup> Groups { get; }

Property Value

IReadOnlyList<IBindGroup>

IsChatOpen

Checks if the chat window is currently open.

Unlike the standard game API, this updates instantly when the chat bind is pressed.

public static bool IsChatOpen { get; }

Property Value

bool

Methods

GetBindGroup(string)

Retrieves an existing bind group by name. Returns null if the group is not found.

public static IBindGroup GetBindGroup(string name)

Parameters

name string

The name of the group to retrieve.

Returns

IBindGroup

GetComboIndices(IReadOnlyList<ControlHandle>, List<int>, bool)

Converts a list of ControlHandle objects into a list of integer IDs.

public static void GetComboIndices(IReadOnlyList<ControlHandle> controls, List<int> combo, bool sanitize = true)

Parameters

controls IReadOnlyList<ControlHandle>

Input list of control handles.

combo List<int>

Output list to store integer IDs.

sanitize bool

If true, sorts the list and removes duplicates/invalid IDs.

GetControl(ControlHandle)

Retrieves the IControl object associated with the given ControlHandle.

public static IControl GetControl(ControlHandle handle)

Parameters

handle ControlHandle

Returns

IControl

GetControl(string)

Looks up the unique ID for a control by its name and returns a ControlHandle.

public static ControlHandle GetControl(string name)

Parameters

name string

The name of the control (e.g., "LeftButton", "W", etc.).

Returns

ControlHandle

GetControlName(ControlHandle)

Retrieves the string name associated with a specific ControlHandle.

public static string GetControlName(ControlHandle con)

Parameters

con ControlHandle

Returns

string

GetControlName(int)

Retrieves the string name associated with a specific control ID.

public static string GetControlName(int conID)

Parameters

conID int

Returns

string

GetControlNames(IReadOnlyList<int>)

Batch retrieves the names for a list of control IDs.

public static string[] GetControlNames(IReadOnlyList<int> conIDs)

Parameters

conIDs IReadOnlyList<int>

Returns

string[]

GetOrCreateGroup(string)

Retrieves an existing bind group by name, or creates a new one if it does not exist.

public static IBindGroup GetOrCreateGroup(string name)

Parameters

name string

The unique name of the group.

Returns

IBindGroup

RequestTempBlacklist(SeBlacklistModes)

Applies a temporary blacklist flag that lasts only for the current frame.

This is additive to the persistent BlacklistMode.

public static void RequestTempBlacklist(SeBlacklistModes mode)

Parameters

mode SeBlacklistModes
Edit this page