Key bindings

A mod can add actions of its own to the game's key bindings. Players find them in the Controls tab under your mod's name and rebind them like the game's own. Your code reacts to the action, whatever keys the player gave it. The types are in Mafi.Unity.dll and the keys are Unity's KeyCode; the example project already references both.

Adding an action 

The class below adds an action that writes a line to the game log when the player presses F8:

using Mafi;
using Mafi.Unity;
using Mafi.Unity.InputControl;
using UnityEngine;

namespace ExampleMod;

[GlobalDependency(RegistrationMode.AsSelf)]
public sealed class ExampleModKeyBindings {

  public static readonly KbHandle SayHello = KbHandleBuilder.Start("ExampleMod.SayHello", "Say hello")
    .SetPrimary(KeyCode.F8)
    .Build();

  public ExampleModKeyBindings(ExampleMod mod, IShortcutsRegistry shortcutsRegistry, IUnityInputMgr inputMgr) {
    shortcutsRegistry.Add(mod, SayHello);
    inputMgr.RegisterGlobalShortcut(SayHello, sayHello);
  }

  private bool sayHello() {
    Log.Info("ExampleMod: hello!");
    return true; // The press was handled.
  }
}

A class marked [GlobalDependency(RegistrationMode.AsSelf)] is one the game creates for you. The game finds it in your DLL and creates it in every game, new or loaded, before the game starts. The constructor gets what it asks for: here your mod class, the registry of actions and the input manager.

KbHandleBuilder defines the action: its ID, its title in the Controls tab and its default keys. The ID is your mod ID, a period, and a name of letters, digits and underscores. The mod ID marks the action as yours: the Controls tab lists it under your mod's name, and the player's keys, saved under the action's ID, cannot clash with another mod's.

shortcutsRegistry.Add registers the action, and every action you define needs it: an action that is not registered is missing from the Controls tab and never reports a press. Registration closes when the game starts, which is why the constructor is the place for it. A mod that implements IMod directly can register in Initialize instead, through resolver.Resolve<IShortcutsRegistry>(). When Add comes too late, or the ID is invalid or does not start with the ID of the mod you pass in, the action is rejected with an error in the log.

RegisterGlobalShortcut calls sayHello in the frame in which the action's keys go down. It is not called while the player types in a text field, so typing the key into a search box does not trigger the action. The return value says whether you handled the press. Return true, as here, and the game stops looking for other actions with the same keys; return false and an action of the game or of another mod bound to the same keys can still react to the press.

Default keys 

SetPrimary sets the keys an action starts with: a key alone, or modifiers and a key. SetSecondary adds a second binding that works as well:

public static readonly KbHandle ShowDetails = KbHandleBuilder.Start("ExampleMod.ShowDetails", "Show details")
  .SetPrimary(KbModifiers.Ctrl, KeyCode.F8) // Ctrl+F8, with either Ctrl key
  .SetSecondary(KeyCode.F9)                 // F9 works too
  .Build();

Combine modifiers with |, like KbModifiers.Ctrl | KbModifiers.Shift. Pick keys the game does not already use. The Controls tab marks actions that share keys as conflicts, so check your action there before you publish. The game saves only the keys a player changed, so when a later version of your mod changes a default, players who kept the old one get the new one.

If your mod's own UI tells the player which keys to press, read them from the action instead of writing them down, or the text goes stale when the player rebinds: ShowDetails.Current.ToNiceString() gives the keys in use as text like CTRL + F8.

Keys the player holds 

The callback reports only the moment the keys go down. For an action that lasts while the player holds its keys, like ShowDetails above, ask ShortcutsManager.IsOn every frame instead. The class that holds ShowDetails takes ShortcutsManager and IGameLoopEvents in its constructor, like the other parameters, and adds a method to IGameLoopEvents.InputUpdate, which the game calls every frame:

private readonly ShortcutsManager m_shortcutsManager;
private bool m_isShown;

public ExampleModHeldKeys(ExampleMod mod, IShortcutsRegistry shortcutsRegistry,
  ShortcutsManager shortcutsManager, IGameLoopEvents gameLoopEvents
) {
  shortcutsRegistry.Add(mod, ShowDetails);
  m_shortcutsManager = shortcutsManager;
  gameLoopEvents.InputUpdate.AddNonSaveable(this, onInputUpdate);
}

private void onInputUpdate(GameTime time) {
  bool isHeld = UnityInputManager.IsInputFieldFocused() == false && m_shortcutsManager.IsOn(ShowDetails);
  if (isHeld != m_isShown) {
    m_isShown = isHeld;
    Log.Info(isHeld ? "ExampleMod: details shown" : "ExampleMod: details hidden");
  }
}

Unlike the callback, this method also runs while the player types in a text field, hence the UnityInputManager.IsInputFieldFocused() check. Compare IsOn from one frame to the next, as here, rather than waiting for IsUp: a player who lets go of Ctrl before F8 releases the action without an IsUp.

If your mod has its own tool or window, an IUnityInputController, check its keys with IsDown or IsOn in its InputUpdate() instead. The game calls it every frame while the tool or window is active, and not while the player types.

Grouping actions 

Actions without a group are listed in a General section under your mod's name. To list some of them in a section of their own, create a KbGroup and pass it to each of them with SetGroup:

public static readonly KbGroup ToolsGroup = new KbGroup("ExampleMod.Tools", "Example tools");

public static readonly KbHandle Measure = KbHandleBuilder.Start("ExampleMod.Measure", "Measure")
  .SetPrimary(KbModifiers.Ctrl, KeyCode.F9)
  .SetGroup(ToolsGroup)
  .Build();

A group ID follows the same rule as an action ID: your mod ID, a period and a name. Create each group once, in a static readonly field like this one, and pass that same object to its actions: an action whose group is a second object with the same ID is rejected.

Renaming an action 

The player's keys are saved under the action's ID, so an action whose ID changes starts over from your defaults. To keep them, list the old ID with SetSupersededIds, and the game moves them to the new ID:

public static readonly KbHandle Greet = KbHandleBuilder.Start("ExampleMod.Greet", "Greet")
  .SetPrimary(KeyCode.F8)
  .SetSupersededIds("ExampleMod.SayHello")
  .Build();

Translating the titles 

The title you pass to Start, the tooltip you add with SetTooltip, and a group's title become strings of your mod when you give them as plain text, with IDs made from the action's or group's ID:

  • the title of ExampleMod.SayHello is ExampleMod.Kb_SayHello__label,
  • its tooltip is ExampleMod.Kb_SayHello__tooltip,
  • the title of the group ExampleMod.Tools is ExampleMod.KbGroup_Tools.

They are exported with your mod's other texts and translated in its language files like any other string, see Translations.