Class InputActionsDocument

A Unity input action asset held as an editable document that can be written back exactly as it was read.

Inheritance
object
InputActionsDocument
Inherited Members
Namespace: Scylla.Input
Assembly: ScyllaInput.dll
Syntax
public sealed class InputActionsDocument
Remarks

This is a typed view over an InputJSONNode tree, not a copy of it. Every property reads and writes the backing node, so a map, action or binding that is never edited is re-emitted byte for byte, including any members this type does not model. Losslessness is therefore structural: there is no code path that could drop an unrecognized member, because there is no code that re-emits the document from modelled fields.

That matters because Unity's own serializer is lossy in this respect. InputActionAsset.ToJson() writes through a fixed set of structs and silently drops anything they do not declare, including Unity's own expectedControlLayout and passThrough, which its reader accepts. A document that survives a round trip here would not survive one through Unity's editor.

Output never carries a trailing newline, matching what Unity writes. One of the two assets shipped with the framework has one, so the first save of that file removes a single byte and every save afterwards is a no-op.

One deliberate limitation: string values are stored decoded, because the Core reader exposes no raw span. A document written with non-canonical escapes, such as an escaped forward slash or a \u escape standing in for a printable character, round-trips to the canonical spelling. The result is semantically identical but not byte-identical. No Unity-authored asset does this.

Constructors

InputActionsDocument(InputJSONNode)

Wraps an existing root node. Use Parse(string) or CreateEmpty(string) rather than calling this directly.

Declaration
public InputActionsDocument(InputJSONNode root)
Parameters
Type Name Description
InputJSONNode root

The root object node.
Exceptions
Type Condition
ArgumentNullException

Thrown when the root is null.
ArgumentException

Thrown when the root is not an object.

Properties

ControlSchemes

Gets the control schemes, in document order.

Declaration
public IReadOnlyList<InputControlSchemeNode> ControlSchemes { get; }
Property Value
Type Description
IReadOnlyList<InputControlSchemeNode>

Maps

Gets the action maps, in document order.

Declaration
public IReadOnlyList<InputActionMapNode> Maps { get; }
Property Value
Type Description
IReadOnlyList<InputActionMapNode>

Name

Gets or sets the asset name.

Declaration
public string Name { get; set; }
Property Value
Type Description
string

Root

Gets the backing tree. Structural edits made directly through this bypass the typed node lists, so call RebuildNodeCache() afterwards.

Declaration
public InputJSONNode Root { get; }
Property Value
Type Description
InputJSONNode

Version

Gets or sets the format version. The only numeric member in the format.

Declaration
public long Version { get; set; }
Property Value
Type Description
long

Methods

AddControlScheme(string, string)

Appends a new, empty control scheme.

Declaration
public InputControlSchemeNode AddControlScheme(string name, string bindingGroup = null)
Parameters
Type Name Description
string name

Scheme name.
string bindingGroup

Binding group, or null to reuse the name.
Returns
Type Description
InputControlSchemeNode

The new scheme.

AddMap(string, string)

Appends a new, empty action map.

Declaration
public InputActionMapNode AddMap(string name, string mapID)
Parameters
Type Name Description
string name

Map name.
string mapID

Stable GUID.
Returns
Type Description
InputActionMapNode

The new map.

Clone()

Produces an independent copy sharing no mutable state with this document.

Declaration
public InputActionsDocument Clone()
Returns
Type Description
InputActionsDocument

The copy.

CreateEmpty(string)

Creates an empty document with its members in the order Unity emits them, so an asset authored here is byte-identical to one Unity would have written.

Declaration
public static InputActionsDocument CreateEmpty(string name)
Parameters
Type Name Description
string name

The asset name.
Returns
Type Description
InputActionsDocument

The new document.

FindActionByID(string)

Finds an action by its stable GUID, searching every map.

Declaration
public InputActionNode FindActionByID(string actionID)
Parameters
Type Name Description
string actionID

The GUID, compared case-insensitively.
Returns
Type Description
InputActionNode

The action, or null when absent.

FindBindingByID(string)

Finds a binding by its stable GUID, searching every map.

Declaration
public InputBindingNode FindBindingByID(string bindingID)
Parameters
Type Name Description
string bindingID

The GUID, compared case-insensitively.
Returns
Type Description
InputBindingNode

The binding, or null when absent.

FindMapByID(string)

Finds a map by its stable GUID.

Declaration
public InputActionMapNode FindMapByID(string mapID)
Parameters
Type Name Description
string mapID

The GUID, compared case-insensitively so a hand-edited or merge-produced uppercase GUID still matches.
Returns
Type Description
InputActionMapNode

The map, or null when absent.

FindMapByName(string)

Finds a map by name.

Declaration
public InputActionMapNode FindMapByName(string name)
Parameters
Type Name Description
string name

The map name, compared case-insensitively.
Returns
Type Description
InputActionMapNode

The map, or null when absent.

FindMapForAction(InputActionNode)

Finds the map owning an action.

Declaration
public InputActionMapNode FindMapForAction(InputActionNode action)
Parameters
Type Name Description
InputActionNode action

The action to locate.
Returns
Type Description
InputActionMapNode

The owning map, or null.
Remarks

Actions carry no back-reference to their map, so this is a scan. It exists because nearly every structural edit needs the owning map and the alternative is the same double loop written out at every call site.

FindMapForBinding(InputBindingNode)

Finds the map owning a binding.

Declaration
public InputActionMapNode FindMapForBinding(InputBindingNode binding)
Parameters
Type Name Description
InputBindingNode binding

The binding to locate.
Returns
Type Description
InputActionMapNode

The owning map, or null.

FindSchemeByName(string)

Finds a control scheme by name. Schemes carry no GUID, so name is the only key.

Declaration
public InputControlSchemeNode FindSchemeByName(string schemeName)
Parameters
Type Name Description
string schemeName

The scheme name, compared case-insensitively.
Returns
Type Description
InputControlSchemeNode

The scheme, or null when absent.

IndexOfControlScheme(InputControlSchemeNode)

Finds a control scheme's position in the document.

Declaration
public int IndexOfControlScheme(InputControlSchemeNode scheme)
Parameters
Type Name Description
InputControlSchemeNode scheme

The scheme to locate.
Returns
Type Description
int

The zero-based position, or -1 when it is not part of this document.

IndexOfMap(InputActionMapNode)

Finds a map's position in the document.

Declaration
public int IndexOfMap(InputActionMapNode map)
Parameters
Type Name Description
InputActionMapNode map

The map to locate.
Returns
Type Description
int

The zero-based position, or -1 when it is not part of this document.

InsertControlSchemeNode(int, InputJSONNode)

Inserts an existing control scheme node at a position.

Declaration
public InputControlSchemeNode InsertControlSchemeNode(int index, InputJSONNode schemeNode)
Parameters
Type Name Description
int index

Where to insert, clamped into range.
InputJSONNode schemeNode

The scheme node to adopt.
Returns
Type Description
InputControlSchemeNode

The wrapper for the inserted node.
Remarks

Scheme order is not cosmetic. Nothing at run time depends on it, but every view that lists schemes reads it, so it is the order the user sees in the matrix and anywhere else the columns appear.

Exceptions
Type Condition
ArgumentNullException

Thrown when the node is null.

InsertMap(int, string, string)

Creates an empty action map at a position.

Declaration
public InputActionMapNode InsertMap(int index, string name, string mapID)
Parameters
Type Name Description
int index

Where to insert, clamped into range.
string name

Map name.
string mapID

Stable GUID.
Returns
Type Description
InputActionMapNode

The new map.

InsertMapNode(int, InputJSONNode)

Inserts an existing map node at a position.

Declaration
public InputActionMapNode InsertMapNode(int index, InputJSONNode mapNode)
Parameters
Type Name Description
int index

Where to insert, clamped into range.
InputJSONNode mapNode

The map node to adopt.
Returns
Type Description
InputActionMapNode

The wrapper for the inserted node.
Remarks

Takes a raw node so duplicate and paste can carry a whole map across verbatim, including anything this layer does not model.

Exceptions
Type Condition
ArgumentNullException

Thrown when the node is null.

Parse(string)

Parses input action asset JSON.

Declaration
public static InputActionsDocument Parse(string json)
Parameters
Type Name Description
string json

The document text.
Returns
Type Description
InputActionsDocument

The parsed document.
Exceptions
Type Condition
ArgumentException

Thrown when the text is null or empty.
SerializationException

Thrown when the text is not well-formed JSON.

RebuildNodeCache()

Rebuilds the typed node lists from the backing tree. Call this after editing the tree directly through Root.

Declaration
public void RebuildNodeCache()

RemoveControlScheme(InputControlSchemeNode)

Removes a control scheme.

Declaration
public bool RemoveControlScheme(InputControlSchemeNode scheme)
Parameters
Type Name Description
InputControlSchemeNode scheme

The scheme to remove.
Returns
Type Description
bool

true when the scheme was found and removed.

RemoveControlSchemeAt(int)

Removes the control scheme at a position.

Declaration
public bool RemoveControlSchemeAt(int index)
Parameters
Type Name Description
int index

The position to remove.
Returns
Type Description
bool

true when something was removed.

RemoveMap(InputActionMapNode)

Removes an action map.

Declaration
public bool RemoveMap(InputActionMapNode map)
Parameters
Type Name Description
InputActionMapNode map

The map to remove.
Returns
Type Description
bool

true when the map was found and removed.

RemoveMapAt(int)

Removes the map at a position.

Declaration
public bool RemoveMapAt(int index)
Parameters
Type Name Description
int index

The position to remove.
Returns
Type Description
bool

true when something was removed.

ToBytes()

Serializes the document as UTF-8 bytes with no byte order mark, which is what Unity writes and therefore what must be written back.

Declaration
public byte[] ToBytes()
Returns
Type Description
byte[]

The encoded JSON text.

ToJSON()

Serializes the document, matching Unity's formatting.

Declaration
public string ToJSON()
Returns
Type Description
string

The JSON text, with no trailing newline.

TryParse(string, out InputActionsDocument, out string)

Attempts to parse input action asset JSON, reporting failure rather than throwing.

Declaration
public static bool TryParse(string json, out InputActionsDocument document, out string error)
Parameters
Type Name Description
string json

The document text.
InputActionsDocument document

The parsed document on success, otherwise null.
string error

A description of the failure on failure, otherwise null.
Returns
Type Description
bool

true when parsing succeeded.

See Also