IInput

namespace Griff.Runtime;

public interface IInput

What gameplay code reads. “Pressed” and “released” are true for exactly one frame.

Properties

Actions

public abstract IReadOnlyCollection<string> Actions { get; }

The names of every action: the built-in ones, and any added with Bind or Rebind.

AnyPressed

public abstract InputBinding? AnyPressed { get; }

The key, mouse button or gamepad button pressed this frame, if any: for “press a key for Jump”.

Cursor

public abstract MouseCursor Cursor { get; set; }

What the mouse pointer looks like over the game, e.g. Input.Cursor = MouseCursor.Hand over something to click: the system’s own pointers, on the desktop and in a browser. It stays as it’s set (an adventure’s Walker sets it over hotspots by itself) and goes back to the arrow as each scene starts.

Horizontal

public abstract float Horizontal { get; }

-1..1 from A/D, the left/right arrows, the D-pad or the left stick.

IsGamepadConnected

public abstract bool IsGamepadConnected { get; }

True while a controller is plugged in.

IsMouseInView

public abstract bool IsMouseInView { get; }

False while the mouse is outside the game’s view (or hasn’t moved over it yet); buttons ignore it then.

IsMouseLocked

public abstract bool IsMouseLocked { get; }

True while the game has the mouse (see WantsMouseLock).

LeftStick

public abstract Vector2 LeftStick { get; }

Left stick, each axis -1..1 with a dead zone applied. Up is positive.

LeftTrigger

public abstract float LeftTrigger { get; }

How far the left trigger is pulled, 0..1.

MouseDelta

public abstract Vector2 MouseDelta { get; }

How far the mouse moved this frame, in pixels (right and up are positive), for turning a first-person view. It keeps counting while the game has the mouse (IsMouseLocked), however far it goes.

MouseOnScreen

public virtual Vector2? MouseOnScreen { get; }

Where the mouse is on the game’s view, from -1 to 1 each way (the middle 0, up and right positive), or null when it was put straight in the world (a test’s mouse). MouseWorld is found through the camera as it was last drawn, a step behind while it moves; this isn’t, so a camera that moves by the mouse (a drag, zooming toward it, scrolling at the screen’s edge) goes by this and the camera as it is now.

MouseWorld

public abstract Vector2 MouseWorld { get; }

Mouse position in world units.

Move

public abstract Vector2 Move { get; }

Horizontal and Vertical together, never longer than 1, so moving diagonally isn’t faster: body.Velocity = Input.Move * Speed.

RightStick

public abstract Vector2 RightStick { get; }

Right stick, each axis -1..1 with a dead zone applied. Up is positive.

RightTrigger

public abstract float RightTrigger { get; }

How far the right trigger is pulled, 0..1.

Scroll

public abstract float Scroll { get; }

How far the mouse wheel turned this frame, in notches: positive away from the player (scrolling up).

Touches

public virtual IReadOnlyList<TouchPoint> Touches { get; }

Every finger on a touch screen this frame, each where it is in world units, those lifted this frame included (their Released set) and those that went down marked Pressed. The first finger is also the mouse (a tap is a left click), so code that only needs one pointer reads the mouse; this is for several at once, as rhythm lanes and on-screen pads take them. Empty without a touch screen.

TypedText

public abstract string TypedText { get; }

The characters typed this frame, in the keyboard’s layout (with Shift, accents and so on).

UsingGamepad

public abstract bool UsingGamepad { get; }

True when the controller was used more recently than the keyboard and mouse, e.g. to show “Press A” rather than “Press Space”.

Vertical

public abstract float Vertical { get; }

-1..1 from S/W, the down/up arrows, the D-pad or the left stick (up is positive).

WantsMouseLock

public abstract bool WantsMouseLock { get; set; }

Set it to ask for the mouse, as a first-person game does: once the player clicks the game, the cursor is hidden and kept inside it so MouseDelta never runs out, until Esc (or switching away) gives it back. A first-person game’s First Person Movement asks for it by itself.

Methods

AimFrom

public abstract Vector2 AimFrom(Vector2 origin)

Which way the player is aiming from origin, as a direction of length 1: the right stick, or with a controller and the right stick at rest, the way the left stick points; otherwise towards the mouse. Zero when there’s nothing to aim with.

AimFrom

public abstract Vector2 AimFrom(Vector3 origin)

Bind

public abstract void Bind(string action, params InputBinding[] bindings)

Sets the keys and buttons that trigger action, replacing any it had, e.g. Bind("Dash", Key.LeftShift, Key.K, GamepadButton.B). A new name makes a new action. These are the game’s own controls; a player’s choice made with Rebind takes priority over them.

BindingsOf

public abstract IReadOnlyList<InputBinding> BindingsOf(string action)

The keys and buttons that trigger action, e.g. to show them in a controls screen.

IsDown

public abstract bool IsDown(string action)

True while any of the action’s keys or buttons is held, e.g. IsDown("Fire"). Games start with Jump, Fire, Attack, Dash, Interact, Pause and EndTurn; Bind changes them or adds more.

IsDown

public abstract bool IsDown(Key key)

IsDown

public abstract bool IsDown(MouseButton button)

IsDown

public abstract bool IsDown(GamepadButton button)

Rebind

public abstract void Rebind(string action, params InputBinding[] bindings)

The player’s own choice of keys and buttons for action, from a controls screen. It’s saved straight away (in SaveData), comes back next time the game runs, and takes priority over Bind. Pair it with AnyPressed to rebind to whatever the player presses next.

ResetBindings

public abstract void ResetBindings(string? action = null)

Forgets the player’s Rebind choices for action, or for every action.

Rumble

public abstract void Rumble(float strength = 0.5f, float seconds = 0.2f)

Shakes the controller at strength (0..1) for seconds of real time. While one rumble is going, another makes it at least as strong and as long as both. Does nothing without a controller.

TypeInto

public abstract string TypeInto(string text, int maxLength = 2147483647)

text with this frame’s typing applied: typed characters added and Backspace (held, it repeats) taking them off, up to maxLength. For name entry: Name = Input.TypeInto(Name, 12).

WasPressed

public abstract bool WasPressed(string action)

True on the frame any of the action’s keys or buttons goes down, e.g. WasPressed("Jump").

WasPressed

public abstract bool WasPressed(Key key)

WasPressed

public abstract bool WasPressed(MouseButton button)

WasPressed

public abstract bool WasPressed(GamepadButton button)

WasPressed

public abstract bool WasPressed(string action, float buffer)

True if the action was pressed within the last buffer seconds and this hasn’t returned true for that press yet. A jump pressed a moment before landing still jumps: if (body.IsGrounded && Input.WasPressed("Jump", buffer: 0.15f)). Each press counts once, so it can’t jump twice.

WasReleased

public abstract bool WasReleased(string action)

True on the frame the action stops being held (the last of its keys and buttons is let go).

WasReleased

public abstract bool WasReleased(GamepadButton button)

WasReleased

public abstract bool WasReleased(Key key)

WasReleased

public abstract bool WasReleased(MouseButton button)