module Eagle::Input

Overview

Keyboard, mouse and gamepad state you can check from anywhere, plus an action map so game code talks about "jump" instead of specific keys.

There are two ways to read input:

• Polling with Input: "is this key held?", "was it pressed this frame?". This is what movement and most gameplay wants.
• Events through App#input and Node#input, which suit menus and text entry.

.down? is true every frame the input is held. .pressed? and .released? are true only on the frame it changed, so use them for one-shot actions like jumping or firing.

Actions bind any mix of keys, mouse buttons, gamepad buttons and stick directions to a name. Map them once in App#load, then ask about the action:

Input.map "left", Key::A, Key::Left, Input.axis(GamepadAxis::LeftX, -1)
Input.map "right", Key::D, Key::Right, Input.axis(GamepadAxis::LeftX, 1)
Input.map "up", Key::W, Key::Up, Input.axis(GamepadAxis::LeftY, -1)
Input.map "down", Key::S, Key::Down, Input.axis(GamepadAxis::LeftY, 1)
Input.map "jump", Key::Space, GamepadButton::A
Input.map "fire", MouseButton::Left, GamepadButton::RightShoulder

class Player < Node2D
  def process(dt : Float32) : Nil
    move = Input.vector("left", "right", "up", "down") # analog on sticks, digital on keys
    self.position += move * 200 * dt
    puts "jump!" if Input.pressed?("jump")
    look_at(Input.mouse) if Input.down?("fire")
  end
end

Defined in:

Class Method Summary

• .actions : Hash(String, Array(Binding))

  Every action and its bindings, for building a controls menu.

• .alt? : Bool

  True while either alt/option key is held.

• .any_pressed? : Bool

  True if any key, mouse button or gamepad button went down this frame.

• .axis(a : GamepadAxis, sign : Int32 = 1, threshold : Number = 0.5) : AxisBinding

  --- actions --- Builds a stick-direction binding for .map.

• .axis(negative : String, positive : String) : Float32

  Combines two actions into one value from -1 to 1: positive minus negative.

• .bindings(action : String) : Array(Binding)

  The bindings for one action.

• .ctrl? : Bool

  True while either control key is held.

• .down?(k : Key) : Bool

  --- keyboard --- True every frame while the key is held.

• .down?(action : String) : Bool

  True while any binding of the action is held.

• .gamepad(index : Int32 = 0) : Gamepad | Nil

  The controller at index in connection order, or nil.

• .gamepads : Array(Gamepad)

  --- gamepads --- Every connected controller.

• .map(action : String, *bindings : Binding) : Nil

  Binds one or more inputs to an action name.

• .mods : KeyMod

  Modifier keys currently held (shift, ctrl, alt, gui).

• .mouse : Vec2

  --- mouse --- Mouse position in window coordinates.

• .mouse_delta : Vec2

  How far the mouse moved this frame.

• .mouse_down?(b : MouseButton = MouseButton::Left) : Bool

  True while the mouse button is held.

• .mouse_pressed?(b : MouseButton = MouseButton::Left) : Bool

  True on the frame the mouse button went down.

• .mouse_released?(b : MouseButton = MouseButton::Left) : Bool

  True on the frame the mouse button went up.

• .pressed?(k : Key) : Bool

  True only on the frame the key went down.

• .pressed?(action : String) : Bool

  True on the frame any binding of the action went down.

• .released?(k : Key) : Bool

  True only on the frame the key went up.

• .released?(action : String) : Bool

  True on the frame any binding of the action went up.

• .reset : Nil

  Clears everything: held keys and buttons, the mouse, known gamepads and all action mappings.

• .shift? : Bool

  True while either shift key is held.

• .strength(action : String) : Float32

  How strongly the action is held, from 0 to 1.

• .text : String

  Text typed this frame, when text input is enabled.

• .text_input=(v : Bool)

  Turns OS text input on or off.

• .unmap(action : String) : Nil

  Removes an action and all its bindings, for example before rebinding controls.

• .vector(left : String, right : String, up : String, down : String, normalize : Bool = true) : Vec2

  Combines four actions into a direction vector.

• .wheel : Vec2

  Scroll amount this frame.

Class Method Detail

steer = Input.axis("left", "right") # -1 for left, 1 for right

Input.map "pause", Key::Escape, Key::P, GamepadButton::Start