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 Create > Input Map in the Assets panel, and make it the project’s map in Project > Project Settings…, on the Startup tab, as Default input map. A new map has a Gameplay set with four actions and no bindings yet: Move, Look, Jump and Fire.

Double-click the map to open its page. A map holds action sets; a set holds actions; an action holds bindings.

Actions

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

• Button: down or up. Jump, fire, interact.
• Axis1D: one value from -1 to 1. Throttle, zoom.
• Axis2D: 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 a time, 0.3 seconds unless you change it), Tap (counts on release, if released within that time) or Double Tap (counts on a second press within that time).

Bindings

To bind, click a binding’s key cap and press the key, button or stick you want. A binding reads one of:

• a keyboard key, with optional modifier keys;
• a mouse button, mouse axis or mouse movement;
• a gamepad button, axis (a trigger, or one direction of a stick) or a whole stick;
• four keys as one stick (Composite2D), the usual W, A, S and D;
• a touch area of the screen, as a button or a stick.

A binding can Invert its value or Scale it, has a Dead Zone (0.15) below which a stick counts as centred, and for gamepads reads any pad unless you name one.

On a touch screen, the touch areas show on screen once a finger has touched it, so a phone or tablet player 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 map is checked when you save it: an action or set with no name, or a binding that cannot feed its action (a stick on a Button), is an error.

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")   -- an Axis1D 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");     // an Axis1D 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 an Axis1D; value2D(action) an Axis2D, or valueX and valueY one part of it.

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 makes one set the only one that answers, for a pause menu over the game; popSet undoes it. enableSet 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 motor and high the light one, each from 0 to 1. Give a gamepad number first to shake another pad, and stopRumble() stops them all.