Scripting API

Scripting API

InputActions

Class in Abyss.Core, from Abyss.Core.

A game's input actions in their maps: settings/input.json beside the game's assets, which a game's code reads through World.Input.

public sealed class InputActions

Remarks

A game asks whether Jump was pressed rather than whether Space or a gamepad's South button was. Each action is a ActionType.Button, ActionType.Axis or ActionType.Vector2, bound to keys, mouse, gamepad buttons and sticks, the strongest binding winning each frame. Maps are switched on and off as a whole for each player; where two that are on bind one key, the one of higher InputMap.Priority claims it, so a menu's Cancel on Escape keeps a game's Pause on Escape from firing behind it.

A game with no input.json has InputActions.Default: Player — Move, Look, Jump, Interact — on, and UI — Navigate, Submit, Cancel, Point, Click, Scroll — off, above it. Every map, action and binding keeps an identity of sixteen hexadecimal digits, which stays with it as it is renamed. The engine checks a file as this does (abyss_core::input::actions::ActionSet).

Constructors

InputActions

public InputActions()

No maps at all; see InputActions.Default for what a game starts with.

Properties

Maps

public IReadOnlyList<InputMap> Maps { get; }

Its maps, in order.

AllActions

public IEnumerable<InputAction> AllActions { get; }

Every map's actions, one map's after another's: the order the engine reads them in.

Methods

Default

public static InputActions Default()

What a game that has said nothing has: Player on — Move on W A S D, the arrows and the left stick; Look on the mouse and the right stick; Jump on Space and South; Interact on E and West — and UI off, above it — Navigate on the arrows, the left stick and the pad's arrows; Submit on Enter and South; Cancel on Escape and East; Point, Click and Scroll on the mouse. Its identities are the same every time, worked out from its names, so what a player rebinds of a game that says nothing is theirs again as the game starts again.

FileIn

public static string FileIn(string game)

Where a game keeps it: settings/input.json in its folder.

Parameters

  • game

Read

public static InputActions Read(string game)

A game's actions; InputActions.Default for one with no input.json.

Parameters

  • game

Exceptions

  • FormatException: The file is not actions this build reads, saying why.
  • IOException: The file is there and cannot be read.

Parse

public static InputActions Parse(string json)

Actions from their text.

Parameters

  • json

Exceptions

  • FormatException: It is not actions this build reads, saying where and why.

ToJson

public string ToJson()

The actions as their file holds them, which the engine reads as it is.

Write

public void Write(string game)

Writes the actions into a game's folder.

Parameters

  • game

Copy

public InputActions Copy()

A copy, to change without changing this: every identity the same.

AddMap

public InputMap AddMap(string name, int priority = 0, bool enabled = true)

Adds a map called name after the others.

Parameters

  • name
  • priority
  • enabled

Returns The map added.

Exceptions

  • ArgumentException: There is a map so called, or the name is blank.

Map

public InputMap? Map(string name)

The map called name, or null.

Parameters

  • name

RemoveMap

public bool RemoveMap(string name)

Takes away the map called name and its actions.

Parameters

  • name

Returns Whether there was one.

RemoveMap

public bool RemoveMap(InputMap map)

Takes map away, and its actions.

Parameters

  • map

Returns Whether it was one of its maps.

AddMap

public InputMap AddMap()

Adds a map after the others: New Map, numbered where that is taken, on at start, of priority zero.

RenameMap

public string RenameMap(InputMap map, string name)

Calls map name, trimmed and numbered where another map is called that; a name of nothing but spaces leaves it as it was.

Parameters

  • map
  • name

Returns What it is called now.

MoveMap

public bool MoveMap(InputMap map, int to)

Moves map to to among the maps.

Parameters

  • map
  • to

Returns Whether it moved.

DuplicateMap

public InputMap DuplicateMap(InputMap map)

A copy of map after it, its actions and bindings copied, every identity its own, its name numbered.

Parameters

  • map

Find

public InputAction? Find(string path)

The action path names — Player/Jump, or Jump where one map alone has an action so called — or null for none.

Parameters

  • path

Exceptions

  • ArgumentException: More than one map has an action of the name, and the path does not say which.

CodeNameOf

public string CodeNameOf(InputAction action)

What the game's code calls action, as the build writes it from the file: Actions.Player.Jump.

Parameters

  • action

Exceptions

  • ArgumentException: It is none of these actions'.

CodeNameOf

public string CodeNameOf(InputMap map)

What the game's code calls map, as the build writes it: Actions.Maps.UI.

Parameters

  • map

Exceptions

  • ArgumentException: It is none of these maps.

NewId

public static ulong NewId()

A new identity no map, action or binding is likely ever to have had: random, and never zero.

Constants

FileName

public const string FileName = "input.json"

The file, under the game's settings folder.

PathName

public const string PathName = "settings/input.json"

What it is called in a game's folder and in its pack: settings/input.json.

CurrentVersion

public const int CurrentVersion = 1

The version of the file this build writes, and the newest it reads.

PlayerMap

public const string PlayerMap = "Player"

The game's map, which InputActions.Default has on.

UiMap

public const string UiMap = "UI"

The interface's map, which InputActions.Default has off, above InputActions.PlayerMap.

UiPriority

public const int UiPriority = 10

The interface's map's priority in InputActions.Default.