Class InputActionsDocumentIO

Reads and writes InputActionsDocument files on disk with the encoding and durability an asset owned by another tool requires.

Inheritance

object

InputActionsDocumentIO

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.MemberwiseClone()

object.ReferenceEquals(object, object)

object.ToString()

Namespace: Scylla.Input

Assembly: ScyllaInput.dll

Syntax

public static class InputActionsDocumentIO

Remarks

Three details are handled here rather than left to callers, because getting any of them wrong corrupts a user's asset:

1. No byte order mark. Unity's writer emits none, and the framework's text-writing helper emits one by default, so writing goes through bytes rather than text. A mark found on read is stripped and reported.
2. The write is atomic. The document is written to a temporary file in the same directory and then moved into place, so an interrupted save cannot leave a truncated asset behind. The framework has no atomic-write helper, so this is assembled from the primitives that do exist.
3. A save whose bytes match what is already on disk does nothing at all. Opening an asset, looking at it and closing it must leave version control untouched.

Fields

FILE_EXTENSION

The file extension Unity uses for input action assets, without the dot.

Declaration

public const string FILE_EXTENSION = "inputactions"

Field Value

Type	Description
string

Methods

Load(string)

Loads and parses an input action asset.

Declaration

public static InputActionsDocument Load(string path)

Parameters

Type	Name	Description
string	path	Absolute or working-directory-relative file path.

Returns

Type	Description
InputActionsDocument	The parsed document.

Exceptions

Type	Condition
ArgumentException	Thrown when the path is null or empty.
SerializationException	Thrown when the file is not well-formed JSON.

MatchesFileOnDisk(string, byte[])

Reports whether a file already holds exactly these bytes.

Declaration

public static bool MatchesFileOnDisk(string path, byte[] bytes)

Parameters

Type	Name	Description
string	path	File path.
byte[]	bytes	Content to compare against.

Returns

Type	Description
bool	true when the file exists and its contents are identical.

ParseBytes(byte[], string)

Parses input action asset bytes, stripping a byte order mark when one is present.

Declaration

public static InputActionsDocument ParseBytes(byte[] bytes, string sourceDescription = null)

Parameters

Type	Name	Description
byte[]	bytes	The file contents.
string	sourceDescription	A path or other label used in the warning when a byte order mark is found. Optional.

Returns

Type	Description
InputActionsDocument	The parsed document.

Exceptions

Type	Condition
ArgumentException	Thrown when the byte array is null or empty.

Save(InputActionsDocument, string)

Writes a document to disk, atomically, and only when its bytes differ from what is already there.

Declaration

public static bool Save(InputActionsDocument document, string path)

Parameters

Type	Name	Description
InputActionsDocument	document	The document to write.
string	path	Absolute or working-directory-relative file path.

Returns

Type	Description
bool	true when the file was written, false when it already matched and was left alone.

Exceptions

Type	Condition
ArgumentNullException	Thrown when the document is null.
ArgumentException	Thrown when the path is null or empty.

TryLoad(string, out InputActionsDocument, out byte[], out string)

Attempts to load and parse an input action asset, also handing back the bytes that were on disk.

Declaration

public static bool TryLoad(string path, out InputActionsDocument document, out byte[] sourceBytes, out string error)

Parameters

Type	Name	Description
string	path	Absolute or working-directory-relative file path.
InputActionsDocument	document	The parsed document on success, otherwise null.
byte[]	sourceBytes	The file's contents on success, otherwise null.
string	error	A description of the failure on failure, otherwise null.

Returns

Type	Description
bool	true when the file was read and parsed.

Remarks

The source bytes are not the same as re-serializing the document. Parsing is lossless but writing is canonical, so a file carrying something Unity's own writer never emits, such as a trailing newline, comes back one byte shorter. A caller that wants to know whether the file has since changed underneath it has to remember what was actually read, not what the document would produce.

TryLoad(string, out InputActionsDocument, out string)

Attempts to load and parse an input action asset, reporting failure rather than throwing.

Declaration

public static bool TryLoad(string path, out InputActionsDocument document, out string error)

Parameters

Type	Name	Description
string	path	Absolute or working-directory-relative file path.
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 the file was read and parsed.

ValidatesAsActionAsset(InputActionsDocument, out string)

Checks that the Input System can load what this document would write.

Declaration

public static bool ValidatesAsActionAsset(InputActionsDocument document, out string error)

Parameters

Type	Name	Description
InputActionsDocument	document	The document about to be written.
string	error	Receives the reason it would not load, or null.

Returns

Type	Description
bool	true when the Input System accepts the document.

Remarks

The document layer is deliberately permissive, because refusing to represent a malformed file would mean refusing to open one for repair. The cost is that an editing bug can produce a file that saves cleanly, diffs cleanly, and throws the next time anything loads it. Parsing with Unity's own reader before writing is the cheapest guard against that: one parse per save is nothing next to the file write it precedes, and it fails while the user can still undo.

It catches what the reader rejects, which is less than it sounds. A map or an action with an empty name throws, and so does structurally malformed JSON. Semantic problems mostly do not: two maps sharing a name are silently merged into one, folding the second map's actions into the first. Nothing load-based can see that, so uniqueness and reference invariants are enforced by the editing commands and by the test harness rather than here.

WriteAtomic(string, byte[])

Writes bytes to a path through a temporary file in the same directory, so an interrupted write cannot truncate the destination.

Declaration

public static void WriteAtomic(string path, byte[] bytes)

Parameters

Type	Name	Description
string	path	Destination file path.
byte[]	bytes	Content to write.

Remarks

The staging file must sit on the same volume as the destination for the move to be a rename rather than a copy, which is why it goes in the destination's own directory rather than a system temporary folder.

See Also

InputActionsDocument