Input

Scripts never ask about a key. They ask about an action, such as “Jump” or “Move”, and an input map says which keys, buttons, sticks and touches make it happen. One action can have a keyboard key, a gamepad button and a touch area at once, and the scripts work the same with each.

The input map

Make one with New > Input Map in the Assets panel, and make it the project’s map in Project > Project Settings…, in the Startup section, as Default input map. A new map has a Gameplay set with four actions and no bindings yet: Move, Look, Jump and Fire.

A map holds action sets, a set holds actions, and an action holds bindings. Double-click the map to open its page. The left side lists the sets and their actions as a tree, with a button to add a set, a button to remove the chosen set or action, and a search box that finds actions by name or by input. The right side shows the chosen set: its name, its Priority and its Actions, each of which opens to show its settings.

Actions

Each action has a kind, which decides what it reads:

• Button: down or up. Jump, fire, interact.
• 1D axis: one value, such as -1 to 1. Throttle, zoom.
• 2D axis: two values, X and Y, each from -1 to 1. Moving, looking.

A Button action can also have an Interaction that decides when it counts: On press (the default), Hold (counts once held for Hold For seconds, 0.3 by default), Tap (counts on release, if released Within that time) or Double tap (counts on a second press within that time).

An action’s Processing shapes its value:

• Sensitivity: above 0, an axis driven by keys ramps toward its value at this rate a second, instead of jumping to it.
• Gravity: above 0, the rate a second at which it returns to rest once released.
• Curve: shapes an analog input by raising the value to this power (1 is straight).
• Snap on Reverse: jump to zero first when the direction flips.
• Scale with Time: multiply the value by the game’s time scale.

Bindings

Add a binding to an action, then click its input button and press the key, button or stick you want; click the button again to stop listening. A binding’s Source is one of:

• Key: a keyboard key, with optional modifier keys;
• Mouse button, Mouse axis (horizontal or vertical movement, or the wheel) or Mouse movement (both directions at once);
• Gamepad button, Gamepad axis (a trigger, or one axis of a stick) or Gamepad stick (a whole stick);
• Four keys: four keys as one stick, the usual W, A, S and D, set as Left, Right, Down and Up, with Normalize (on) keeping diagonals as long as straight moves;
• Touch button or Touch stick: an area of the screen, set by Area X, Area Y, Area Width and Area Height as fractions of the screen from 0 to 1. A touch stick deflects fully over its Radius (0.15).

A binding can Invert its value or Scale it (a negative scale flips it), and an analog binding has a Dead Zone (0.15) below which it reads as none. A gamepad binding reads any connected pad, or one chosen by its number under Gamepad.

On a touch screen, the touch areas show on screen once a finger has touched it, so a player on a phone or a tablet can see where the controls are.

Action sets

Sets group actions that belong together: one for walking about, one for driving, one for menus. When two enabled sets have an action of the same name, the set with the higher Priority answers. Scripts can switch sets as the game changes mode (below).

The page will not save a map the game cannot read, and says why in the status bar. That happens when a set or an action has no name, when an action that is not a Button has an interaction, or when a binding cannot feed its action: an analog input on a Button, a stick on a 1D axis, or anything but a two-part input on a 2D axis.

Reading actions

Luau

function Player:onUpdate(dt)
    if Input.wasPressed("Jump") then
        Log.info("jump")
    end
    local sneaking = Input.isDown("Sneak")
    local move = Input.value2D("Move") -- move.x and move.y, each from -1 to 1
    local zoom = Input.value("Zoom")   -- a 1D axis action
end

AngelScript

void onUpdate(double dt)
{
    if (Input::wasPressed("Jump"))
    {
        Log::info("jump");
    }
    bool sneaking = Input::isDown("Sneak");
    Float2@ move = Input::value2D("Move"); // move.x and move.y, each from -1 to 1
    float zoom = Input::value("Zoom");     // a 1D axis action
}

• isDown(action) is true while it is held.
• wasPressed(action) and wasReleased(action) are true on the one frame it changed.
• value(action) reads a 1D axis. value2D(action) reads a 2D axis, and valueX(action) and valueY(action) read one part of it.
• An action name the map does not have reads as not pressed, and 0.

Switching sets

Luau

Input.pushSet("Menu")   -- only the Menu set answers now
Input.popSet()          -- back to what answered before
Input.enableSet("Driving", true)

AngelScript

Input::pushSet("Menu");   // only the Menu set answers now
Input::popSet();          // back to what answered before
Input::enableSet("Driving", true);

pushSet(name) makes one set the only one that answers, for a pause menu over the game, and popSet() undoes it. enableSet(name, enabled) turns a set on or off beside the others.

Rumble

Input.rumble(low, high, seconds) (Input::rumble in AngelScript) shakes the first gamepad. low drives the heavy, low-frequency motor and high the light one, each from 0 to 1. To shake another pad, give its number first, counting from 0: rumble(1, low, high, seconds). stopRumble() stops every pad.