Manual

Manual

Input actions

A game asks whether Jump was pressed, not whether Space or a gamepad's South button was. This page covers input actions: the maps they are kept in, their bindings to keys, the mouse and gamepads, settings/input.json and the Input page of Project Settings that edits it, reading actions in code, actions made in code, and letting players rebind them.

Actions, maps and bindings

An action is something a player does: Move, Look, Jump. It has a type:

TypeIts valueBound to, for example
ButtonZero to one, how far it is pressed. Held past halfway.A key, a mouse button, a gamepad's button or trigger
AxisOne number, from −1 to 1One direction of a stick, or two keys for less and more
Vector2Two numbers, up positiveA stick, four keys, the mouse's motion

A binding is one way of driving an action: a key, a mouse button, the mouse's motion, wheel or position, a gamepad's button, one direction of a stick, a whole stick, or a composite of things pressed, two for an axis (Negative and Positive) and four for a vector (Up, Down, Left and Right). An action reads all its bindings each frame and the strongest wins: for a button the one pressed furthest, for an axis the one furthest from zero, for a vector the longest. So W, A, S and D and a stick drive Move together, and four keys pressed on a diagonal are never longer than one, as a stick at its edge is.

Each binding has:

SettingWhat it does
Dead ZoneHow far from zero it must go before it reads anything, the rest scaled back up to one. A stick or one of its axes has 0.2 unless you say; everything else none.
ScaleWhat its value is multiplied by, last
InvertTurns its value the other way; for a vector, Invert X and Invert Y

A map is a set of actions a player has on or off as a whole: the game's own, a menu's. Each has a Priority and whether it is On at Start.

What a game has to start with

A game with no settings/input.json has two maps:

MapActionTypeBindings
Player, onMoveVector2W A S D, the arrow keys, the left stick
LookVector2The mouse's motion, the right stick
JumpButtonSpace, South
InteractButtonE, West
UI, off, priority 10NavigateVector2The arrow keys, the left stick (dead zone 0.5), the pad's arrows
SubmitButtonEnter, South
CancelButtonEscape, East
PointVector2Where the mouse's cursor is
ClickButtonThe mouse's left button
ScrollVector2The mouse's wheel

The UI map is what works a game's menus (see Keys and a gamepad). A gamepad's buttons are named for where they sit: South is A on one maker's pad and Cross on another's (see Gamepads).

The mouse's motion is in pixels a frame and a stick's from −1 to 1, so Look reads very different numbers from each. Give the mouse's binding a Scale to bring them together, or tell the two apart by the device last used.

The Input page

Edit ▸ Project Settings… ▸ Input edits the game's actions, in three columns:

  • Maps: the game's maps. + adds one. A map that is not on at start says off.
  • Actions of the map picked: its actions, each with its type at the right and its bindings under it, a composite's parts under the composite. + adds an action.
  • Properties of what is picked:
    • a map's Name, Priority and On at Start;
    • an action's Name and Type, and + Binding, which adds a Binding, or an Up/Down/Left/Right Composite for a Vector2, or a Negative/Positive Composite for an Axis;
    • a binding's Path, what it reads, with its Dead Zone, Scale, Invert, and Delete Binding; a composite's part has a path of its own.

Click a binding's path for a menu of what it can read: Keyboard, Mouse and Gamepad, each listing only what fits the binding, and Listen, which binds the next key or gamepad button pressed, a stick pushed past halfway, or the mouse's middle or side button. The path says Listening: press a key or a button until it hears one; click it to stop. The mouse's left and right buttons are picked from Mouse, since a click on the page is what stops listening. A binding you add listens at once.

Drag a row up or down to move it. Right-click one for Duplicate and Delete, or press Delete. An action whose type you change loses the bindings that no longer fit, and the page says how many; Ctrl+Z puts them back.

Every change is written to settings/input.json as you make it, is one step of Ctrl+Z, and reaches a game already playing without resetting what its players hold. A file changed by anything else is read again.

The page also shows what code calls the map or action picked, such as input.Pressed(Actions.Player.Jump).

Forget Players' Bindings at the top forgets the keys the players of the game played in the editor bound of their own (see Rebinding).

settings/input.json

The page writes the file; you can also write it by hand, or merge it in version control. Each map, action and binding has an identity of sixteen hexadecimal digits that stays with it as it is renamed or moved:

{
  "abyssInput": 1,
  "maps": [
    {
      "id": "122fb0bdbee384bd",
      "name": "Player",
      "priority": 0,
      "enabled": true,
      "actions": [
        {
          "id": "3219e890154b9e3f",
          "name": "Move",
          "type": "Vector2",
          "bindings": [
            {
              "id": "cb15d39d0a6ebb53",
              "composite": {
                "up": { "key": "W" },
                "down": { "key": "S" },
                "left": { "key": "A" },
                "right": { "key": "D" }
              }
            },
            { "id": "8f0cb683886829da", "stick": "Left", "deadzone": 0.2 }
          ]
        },
        {
          "id": "f903b5715b13271c",
          "name": "Jump",
          "type": "Button",
          "bindings": [
            { "id": "bc867645c8803632", "key": "Space" },
            { "id": "5b1e0c27d64aa9f2", "button": "South" }
          ]
        }
      ]
    }
  ]
}

A binding names what it reads by one of key, mouse, button, axis or stick, or holds a composite, and may say deadzone, scale, and invert, or for a Vector2 invertX and invertY. A name is written as its enum writes it: ArrowUp, ShiftLeft, South, LeftStickX, Motion. A file that cannot be read leaves the game with the default actions, and the log says why. A build packs the file with the game.

Read actions in code

Ask about an action through a player's PlayerInput: context.Input in a system, world.Input outside one.

PlayerInput input = context.Input;
Vector2 move = input.Vector(Actions.Player.Move);   // W A S D, the arrows or the left stick; up is +Yif (input.Pressed(Actions.Player.Jump)) { /* ... */ }if (input.HeldFor("Interact", 0.5f)) { /* ... */ }  // once, on the frame the hold gets thereinput.Enable(Actions.Maps.UI);                      // the menu's map, from the next frame

Actions is written into your game by the build from settings/input.json: a class for each map with a field for each action, and Actions.Maps with a field for each map. An action mistyped is a compile error. Each field carries the action's identity, so an action renamed on the Input page while the game plays is still found. A path also names an action: "Player/Jump", or "Jump" where one map alone has an action so called. A name with a space is written as one word in code, New Action as NewAction.

MemberWhat it says
Pressed(action)It went down this frame
Held(action)It is held: a button past halfway, an axis or vector off zero
Released(action)It came up this frame
Value(action)A button's value, an axis's, or a vector's x
Vector(action)A vector's value, up positive
HeldTime(action)Seconds it has been held, by the game's clock; on the frame it is let go of, how long it was
HeldFor(action, seconds)True on the one frame a hold reaches that long
Tapped(action, within)It came up this frame after being held no longer than within seconds, 0.2 unless you say
State(action)All of these at once
PointerWhere the mouse's cursor is over the game's picture, in logical pixels from its top left, or null off it; see below

Pointer is the point a camera's ScreenRay and ScreenToWorld take, for what is under the pointer (see Cameras). In the editor it is measured in the Game panel's picture, as a built game's is in its window, and is null while the panel does not have the mouse. Only the first player has one.

The first question of a frame reads every action's state from the engine in one go, and the rest are answered from that, so asking is cheap and the same from every system. Ask before a system's work is spread across cores: context.Input is refused inside ForEachChunkParallel.

Naming an action that is not in use throws, and so does a bare name two maps have.

Maps and their priority

A player switches each map on or off: input.Enable(map), input.Disable(map) and input.IsEnabled(map), each from the next frame. A map switched off reads zero, and an action held in it comes up.

Where two maps that are on bind the same key, the map of higher priority claims it for as long as it is on, pressed or not. So a menu's Cancel on Escape keeps the game's Pause on Escape from firing behind it. Maps of one priority share a key. A composite gives up only the parts claimed: a menu that claims the arrow keys leaves W A S D moving.

A button held as its map comes on waits to be let go of: it is neither held nor pressed until it is released and pressed again. So the E that opens an inventory, whose modal document switches the UI map on, is not also a press of the UI map's Close on E. Axes and sticks read as they are at once, so a held W walks on as a menu closes.

Players

Every state belongs to a player. Player 0 reads every keyboard, mouse and gamepad. world.InputOf(1), or context.InputOf(1), up to seven, has maps of its own on and off, and reads no device yet: devices cannot be given to players.

Actions made in code

world.InputActions is a copy of the actions in use, to change and give back. Add maps and actions with Bind, then world.UseInputActions:

InputActions actions = world.InputActions;if (actions.Map("Debug") is null){    InputMap debug = actions.AddMap("Debug", priority: 0, enabled: true);    debug.Add("Dash", ActionType.Button, Bind.Key(Key.ShiftLeft), Bind.Button(GamepadButton.East));    debug.Add("Steer", ActionType.Axis, Bind.Keys(Key.A, Key.D), Bind.Axis(GamepadAxis.LeftStickX));    debug.Add("Aim", ActionType.Vector2, Bind.Stick(GamepadStick.Right) with { Deadzone = 0.3f });    world.UseInputActions(actions);}
if (world.Input.Pressed("Debug/Dash")) { /* ... */ }

Bind.Key, Bind.Mouse, Bind.Button, Bind.Axis and Bind.Stick read one thing. Bind.Keys makes a composite of two keys or four, and Bind.Composite one of any things pressed. Each is an InputBinding, so with sets its Deadzone, Scale, InvertX and InvertY. A binding that does not fit its action, a stick on a button, is refused and says why.

UseInputActions starts every player again from the next frame: maps on as the actions say, nothing held. ChangeInputActions changes them as the game plays, each player keeping its maps, what it holds and its own bindings, as the Input page does. Actions made in code have no field in Actions, so name them by their paths.

InputActions.Default() makes the default actions, and InputActions.Read(folder) a game's from its folder.

Rebinding

A player can bind an action to a key of their own, in place of the game's binding. The engine keeps it in their folder (see Player preferences) and reads it back as the game starts again.

In a settings menu, flow.Rebind listens for what the player presses next and binds it:

schedule.AddFlow("Rebind Jump", async flow =>{    PlayerInput input = flow.World.Input;    RebindResult? done = await flow.Rebind(input, Actions.Player.Jump);   // null if Escape or Start    if (done is { Clashes.Count: > 0 })    {        // Tell them another action has that key too.    }});

It binds the action's first binding unless you say which, binding: 1, and for a composite the part you name, part: "up". It hears only what goes down after it begins, on the device the binding reads now, a key for the keyboard's binding and a button for the pad's, and only what fits it. Escape or a gamepad's Start cancels it. RebindOptions changes that: Cancel lists what cancels, AnyDevice binds whatever device is used, and Mouse the mouse buttons heard, all of them unless you say.

The result says what the binding reads now, what it read before, and Clashes: the other actions of its map the player has on that key too. The binding is made anyway, so the game can move theirs or tell the player.

From code, without listening:

input.Rebind(Actions.Player.Move, 0, BindingSource.Of(Key.I), part: "up");BindingSource now = input.SourceOf(Actions.Player.Jump);   // the player's, or the game'sbool own = input.IsRebound(Actions.Player.Jump);input.ResetBinding(Actions.Player.Jump);                   // the game's againinput.ResetBindings();                                     // every one the game's again

input.Rebindings lists the player's own, and input.ClashesOf(action, source) the actions a source would clash with. Rebinding the game's own source back is the game's binding again, nothing of the player's kept for it.

A player's own bindings that no longer fit, after the game's actions changed, are let go of.

Prompts

input.Prompt(action) names what to press for an action on the device the player used last: Space, W/A/S/D for four keys, A on one maker's pad and Cross on another's. It is the action's first binding on that device, the player's own where they have one.

if (input.DeviceChanged){    Hint.Text = $"Press {input.Prompt(Actions.Player.Jump)} to jump";}

input.LastDevice says which device the player last used, the keyboard and mouse or a gamepad, and for a pad, whose: Gamepad is Xbox, PlayStation, Nintendo or Other. input.DeviceChanged is true on the frame it changed, when prompts should be drawn again. A prompt is a name, not a picture: draw your own glyphs from LastDevice and the binding where you want them. InputNames gives the same names for a game's own menus.

In the editor

While the game plays in the editor, its actions read the keyboard and the mouse only while the Game panel has focus. Play gives the panel focus, and a click into it gives it back. While it has focus, the Scene panel's own keys, W, E, R, F and the rest, are the game's. Gamepads reach the game whatever has focus. Point is measured in the game's picture.

What the players bind of their own while the game plays in the editor is kept in the project's cache folder, apart from a built game's. Forget Players' Bindings on the Input page clears it, the playing game's players included.

In the Scripting API