InputState

namespace Griff.Runtime;

public sealed class InputState : IHostInput, IInput

The input every host feeds (IHostInput) and every game reads (IInput): call SetKey/SetMouseButton as events arrive and EndFrame after each game tick. The game calls BeginFrame at the start of each.

Properties

Actions

public IReadOnlyCollection<string> Actions { get; }

The names of every action, built in, bound or rebound.

AnyPressed

public InputBinding? AnyPressed { get; }

Cursor

public MouseCursor Cursor { get; set; }

GamepadCount

public int GamepadCount { get; }

How many controllers are plugged in.

Horizontal

public float Horizontal { get; }

IsGamepadConnected

public bool IsGamepadConnected { get; set; }

True while any controller is plugged in. Setting it says whether the first is (a platform with one controller); SetGamepadConnected says so of each.

IsMouseInView

public bool IsMouseInView { get; set; }

Set by the platform as the mouse enters and leaves the view. True by default, for tests and headless runs.

IsMouseLocked

public bool IsMouseLocked { get; set; }

Set by the platform while it holds the mouse for the game (see WantsMouseLock).

LeftStick

public Vector2 LeftStick { get; }

The left stick of any controller (the first held off its middle), each axis -1..1. Up is positive.

LeftTrigger

public float LeftTrigger { get; }

How far any controller’s left trigger is pulled (the furthest), 0..1.

MouseDelta

public Vector2 MouseDelta { get; }

MouseOnScreen

public Vector2? MouseOnScreen { get; set; }

MouseWorld

public Vector2 MouseWorld { get; set; }

Move

public Vector2 Move { get; }

RightStick

public Vector2 RightStick { get; }

The right stick of any controller (the first held off its middle), each axis -1..1. Up is positive.

RightTrigger

public float RightTrigger { get; }

How far any controller’s right trigger is pulled (the furthest), 0..1.

RumbleStrength

public float RumbleStrength { get; }

How hard the controller should be shaking right now, 0..1. The platform reads it each frame.

Scroll

public float Scroll { get; }

Touches

public IReadOnlyList<TouchPoint> Touches { get; }

TypedText

public string TypedText { get; }

UsingGamepad

public bool UsingGamepad { get; }

Vertical

public float Vertical { get; }

WantsMouseLock

public bool WantsMouseLock { get; set; }

Methods

AddMouseDelta

public void AddMouseDelta(Vector2 pixels)

Adds mouse movement, in pixels (right and up are positive), for MouseDelta.

AddScroll

public void AddScroll(float notches)

Adds mouse wheel movement, in notches (positive is scrolling up).

AddText

public void AddText(string text)

Adds typed characters. Control characters are ignored; Backspace goes through TypeBackspace.

AimFrom

public Vector2 AimFrom(Vector2 origin)

AimFrom

public Vector2 AimFrom(Vector3 origin)

BeginFrame

public void BeginFrame(float realSeconds)

Starts a game frame realSeconds after the last one: dates this frame’s presses (which arrived since the last frame) for buffered WasPressed, and counts down any rumble.

Bind

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

BindingsOf

public IReadOnlyList<InputBinding> BindingsOf(string action)

ConnectedGamepad

public int ConnectedGamepad(int nth)

The platform’s number for the nth controller plugged in (from 0: the first plugged in is 0, whatever slot it’s in), or -1 if there aren’t that many.

EndFrame

public void EndFrame()

HoldGamepadButton

public void HoldGamepadButton(int index, GamepadButton button, bool down)

Holds (or lets go of) button on controller index as if pressed on it, over what the controller itself says: for tests, agents and demos playing as a second player’s controller. A controller with a button held this way counts as plugged in from then on.

IsDown

public bool IsDown(GamepadButton button)

IsDown

public bool IsDown(string action)

IsDown

public bool IsDown(Key key)

IsDown

public bool IsDown(MouseButton button)

IsDown

public bool IsDown(int index, GamepadButton button)

True while button is held on controller index.

IsGamepadConnectedAt

public bool IsGamepadConnectedAt(int index)

True while controller index is plugged in (or has had a button held by HoldGamepadButton).

LeftStickOf

public Vector2 LeftStickOf(int index)

Controller index’s left stick, with the dead zone applied.

LeftTriggerOf

public float LeftTriggerOf(int index)

How far controller index’s left trigger is pulled, 0..1.

MouseMoved

public void MouseMoved()

Called by the platform when the mouse moves over the game: the player has switched to the mouse.

PlaceTouches

public void PlaceTouches(Func<Vector2, Vector2> toWorld)

Puts the fingers given on the screen in the world, through toWorld (the view as it is now).

PressedOn

public GamepadButton? PressedOn(int index)

The first button pressed on controller index this frame, if any.

Rebind

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

ReleaseAll

public void ReleaseAll()

Releases everything, e.g. when the game window loses focus.

ResetBindings

public void ResetBindings(string? action = null)

RightStickOf

public Vector2 RightStickOf(int index)

Controller index’s right stick, with the dead zone applied.

RightTriggerOf

public float RightTriggerOf(int index)

How far controller index’s right trigger is pulled, 0..1.

Rumble

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

Rumble

public void Rumble(int index, float strength, float seconds)

Shakes controller index alone (a player’s own), as Rumble shakes every controller.

RumbleStrengthOf

public float RumbleStrengthOf(int index)

How hard controller index should be shaking now, 0..1: its own rumble or every controller’s. The platform reads it each frame.

SetGamepad

public void SetGamepad(IEnumerable<GamepadButton> down, Vector2 leftStick)

Sets the first controller’s state for this frame (called by the platform each tick).

SetGamepad

public void SetGamepad(IEnumerable<GamepadButton> down, Vector2 leftStick, Vector2 rightStick, float leftTrigger = 0f, float rightTrigger = 0f)

Sets the first controller’s state for this frame (called by the platform each tick). Triggers are 0..1.

SetGamepad

public void SetGamepad(int index, IEnumerable<GamepadButton> down, Vector2 leftStick, Vector2 rightStick, float leftTrigger = 0f, float rightTrigger = 0f)

Sets controller index’s state for this frame (0 to MaxGamepads - 1, the platform’s own numbering; called by it each tick). Triggers are 0..1. What the game reads by itself (IsDown, the sticks, the actions) is every controller at once; a player at this machine reads their own (see LocalPlayers).

SetGamepadConnected

public void SetGamepadConnected(int index, bool connected)

Says whether controller index is plugged in (called by the platform as controllers come and go). Unplugged, it stops counting as plugged in even if HoldGamepadButton pretended it was.

SetKey

public void SetKey(Key key, bool down)

SetMouseButton

public void SetMouseButton(MouseButton button, bool down)

SetTouch

public void SetTouch(int id, Vector2 at, bool down, bool onScreen = false)

A finger went down, moved or was lifted. at is in world units, or with onScreen where it is on the view (from -1 to 1 across it, up positive), which PlaceTouches puts in the world.

StopRumble

public void StopRumble()

Stops any rumble straight away, e.g. when the game pauses or stops.

TypeBackspace

public void TypeBackspace()

Records a Backspace for TypeInto, including the repeats while it’s held.

TypeInto

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

UseControls

public void UseControls(IReadOnlyDictionary<string, IReadOnlyList<InputBinding>> controls)

Uses the project’s controls (from the editor’s Controls window) as the game’s own: each action in controls gets those bindings, like Bind. Calling it again with a changed set (the controls edited while the game runs) puts back built-in actions it no longer changes and drops actions it no longer has, leaving anything scripts bound alone.

UseSaveData

public void UseSaveData(SaveData saveData)

Keeps the player’s Rebind choices in saveData, replacing the current ones with those saved there. The game calls this whenever its save data is set.

WasPressed

public bool WasPressed(GamepadButton button)

WasPressed

public bool WasPressed(string action)

WasPressed

public bool WasPressed(Key key)

WasPressed

public bool WasPressed(MouseButton button)

WasPressed

public bool WasPressed(string action, float buffer)

WasPressed

public bool WasPressed(int index, GamepadButton button)

True on the frame button goes down on controller index.

WasReleased

public bool WasReleased(GamepadButton button)

WasReleased

public bool WasReleased(string action)

WasReleased

public bool WasReleased(Key key)

WasReleased

public bool WasReleased(MouseButton button)

WasReleased

public bool WasReleased(int index, GamepadButton button)

True on the frame button is let go on controller index.

Fields

BindingsSaveKey

public const string BindingsSaveKey

Where the player’s Rebind choices are kept in SaveData.

DeadZone

public const float DeadZone

Stick movement smaller than this is ignored, so a resting stick doesn’t drift.

MaxGamepads

public const int MaxGamepads

How many controllers it keeps apart: up to four, as XInput and most browsers give.

TriggerDeadZone

public const float TriggerDeadZone

A trigger pulled less than this reads as 0.