Class ScyllaInputAction

Wraps a Unity InputAction with Scylla-specific state tracking, callback routing, and modifier-key disambiguation support.

Inheritance

object

ScyllaInputAction

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.MemberwiseClone()

object.ReferenceEquals(object, object)

Namespace: Scylla.Input

Assembly: ScyllaInput.dll

Syntax

public class ScyllaInputAction

Remarks

Each ScyllaInputAction is created and owned by the ScyllaInputActionMap that contains it, which in turn is managed by InputActionManager. Do not construct instances directly outside of these classes.

Event routing: Unity InputAction callbacks (performed, started, canceled) are intercepted internally. Before raising OnPerformed or OnStarted, the optional Scylla.Input.ScyllaInputAction.ShouldSuppress delegate is consulted. If suppression is requested (e.g., because a modifier-key sibling is a better match), the Scylla event is silently discarded. OnCanceled is always raised regardless of suppression to ensure callers can clean up state.

Value reading: Use ReadFloat() or ReadVector2() for the most common value types; they handle control-type mismatches gracefully. Use ReadValueSafe<T>() for other struct types when a mismatch is possible, or ReadValue<T>() when the type is guaranteed to match.

Modifier disambiguation: ModifierDepth, NeedsModifierCheck, and Scylla.Input.ScyllaInputAction.TriggerControlPaths are computed by InputActionManager after the map is registered and are not meaningful before that point.

Constructors

ScyllaInputAction(InputAction, string)

Initializes a new ScyllaInputAction that wraps the specified Unity InputAction.

Declaration

public ScyllaInputAction(InputAction unityAction, string mapID)

Parameters

Type	Name	Description
InputAction	unityAction	The Unity `InputAction` to wrap. Must not be `null`.
string	mapID	The ID of the ScyllaInputActionMap that owns this action. `null` is treated as an empty string.

Remarks

The constructor subscribes to the Unity action's performed, started, and canceled callbacks immediately and builds the initial binding list via RefreshBindings().

Exceptions

Type	Condition
ArgumentNullException	Thrown when `unityAction` is `null`.

Properties

ActionID

Gets the unique string identifier for this action.

Declaration

public string ActionID { get; }

Property Value

Type	Description
string	Matches the `name` of the underlying Unity `InputAction`. When two actions in different maps share the same name, the InputActionManager stores the second one under the fully qualified form `"MapID/ActionID"` in its own dictionary, but this property always returns the plain action name.

ActionType

Gets the Unity InputActionType of this action.

Declaration

public InputActionType ActionType { get; }

Property Value

Type	Description
InputActionType	One of `Button`, `Value`, or `PassThrough` as defined in the underlying Unity asset.

BindingCount

Gets the total number of bindings registered for this action.

Declaration

public int BindingCount { get; }

Property Value

Type	Description
int	A non-negative integer. Composite bindings and their individual parts are each counted as separate entries, matching Unity's flat binding list layout.

Bindings

Gets the read-only list of bindings associated with this action.

Declaration

public IReadOnlyList<ScyllaInputBinding> Bindings { get; }

Property Value

Type	Description
IReadOnlyList<ScyllaInputBinding>	Each element represents one entry from `InputAction.bindings`, wrapped in a ScyllaInputBinding. The list is rebuilt by RefreshBindings(). Never `null`; may be empty.

DisplayName

Gets the human-readable display name for this action.

Declaration

public string DisplayName { get; }

Property Value

Type	Description
string	Currently identical to ActionID (the Unity action name). Reserved for future localization or custom display name support.

ExpectedControlType

Gets the expected control type string from the underlying Unity action (e.g., "Button", "Axis", "Vector2").

Declaration

public string ExpectedControlType { get; }

Property Value

Type	Description
string	The raw string from `InputAction.expectedControlType`, or an empty string if the underlying action is `null`.

IsEnabled

Gets a value indicating whether the underlying Unity action is currently enabled.

Declaration

public bool IsEnabled { get; }

Property Value

Type	Description
bool	`true` if the Unity action's `enabled` property is `true`; otherwise `false`. Returns `false` when the underlying action is `null`.

IsPressed

Gets a value indicating whether the action's trigger control is currently held down.

Declaration

public bool IsPressed { get; }

Property Value

Type	Description
bool	`true` if the underlying Unity action reports `IsPressed()`; otherwise `false`.

LastActiveControl

Gets the InputControl (specific button, axis, or key) that most recently triggered this action, or null if the action has not yet been triggered.

Declaration

public InputControl LastActiveControl { get; }

Property Value

Type	Description
InputControl	Updated on every Unity callback alongside LastActiveDevice.

LastActiveDevice

Gets the InputDevice that most recently triggered this action, or null if the action has not yet been triggered.

Declaration

public InputDevice LastActiveDevice { get; }

Property Value

Type	Description
InputDevice	Updated on every `performed`, `started`, and `canceled` callback from Unity, regardless of whether the Scylla event was suppressed.

LastPerformedTime

Gets the Time.timeAsDouble-equivalent timestamp at which this action was most recently performed.

Declaration

public double LastPerformedTime { get; }

Property Value

Type	Description
double	Set from `InputAction.CallbackContext.time` in the `performed` callback. Remains `0` until the action has been performed at least once.

MapID

Gets the ID of the ScyllaInputActionMap that owns this action.

Declaration

public string MapID { get; }

Property Value

Type	Description
string	The map name as provided to the constructor. Never `null`; may be empty if the action was created without an owning map.

ModifierDepth

Gets the modifier depth of this action, indicating how many modifier keys are required by its most complex composite binding.

Declaration

public int ModifierDepth { get; }

Property Value

Type Description

Type	Description
int	`0` - simple binding with no modifier keys (e.g., just `Space`). `1` - one-modifier composite (e.g., `Ctrl+Z` via `ButtonWithOneModifier`). `2` - two-modifier composite (e.g., `Ctrl+Shift+Z` via `ButtonWithTwoModifiers`). Computed by InputActionManager via Scylla.Input.ScyllaInputAction.ComputeModifierMetadata() when the owning map is registered. Zero until that point.

int

0 - simple binding with no modifier keys (e.g., just Space).
1 - one-modifier composite (e.g., Ctrl+Z via ButtonWithOneModifier).
2 - two-modifier composite (e.g., Ctrl+Shift+Z via ButtonWithTwoModifiers).

Computed by InputActionManager via Scylla.Input.ScyllaInputAction.ComputeModifierMetadata() when the owning map is registered. Zero until that point.

NeedsModifierCheck

Gets or sets a value indicating whether this action must consult the Scylla.Input.ScyllaInputAction.ShouldSuppress delegate before firing its Scylla callbacks.

Declaration

public bool NeedsModifierCheck { get; }

Property Value

Type	Description
bool	Set to `true` by Scylla.Input.InputActionManager.UpdateModifierDisambiguation() when a sibling action that shares a trigger key has a strictly higher ModifierDepth. When `false`, suppression is skipped entirely, avoiding the Scylla.Input.InputActionManager.CountHeldKeyboardModifiers() overhead on every callback.

UnityAction

Gets the underlying Unity InputAction that this object wraps.

Declaration

public InputAction UnityAction { get; }

Property Value

Type	Description
InputAction	The Unity action supplied to the constructor. Never `null`.

ValueType

Gets the expected runtime Type for values read from this action.

Declaration

public Type ValueType { get; }

Property Value

Type	Description
Type	Resolved from the Unity action's `expectedControlType` string by looking up `UnityEngine.{controlType}` in `UnityEngine.CoreModule`. Defaults to `typeof(float)` when the type cannot be resolved or when `expectedControlType` is `null` or empty.

WasCanceledThisFrame

Gets a value indicating whether the action was released (entered the Canceled phase) during the current frame.

Declaration

public bool WasCanceledThisFrame { get; }

Property Value

Type	Description
bool	`true` if `InputAction.WasReleasedThisFrame()` returns `true`; otherwise `false`.

WasPerformedThisFrame

Gets a value indicating whether the action was in the Performed phase at any point during the current frame.

Declaration

public bool WasPerformedThisFrame { get; }

Property Value

Type	Description
bool	`true` if `InputAction.WasPerformedThisFrame()` returns `true`; otherwise `false`.

WasStartedThisFrame

Gets a value indicating whether the action transitioned to the Started phase (button pressed down) during the current frame.

Declaration

public bool WasStartedThisFrame { get; }

Property Value

Type	Description
bool	`true` if `InputAction.WasPressedThisFrame()` returns `true`; otherwise `false`.

Methods

Disable()

Disables the underlying Unity InputAction, preventing it from receiving input events.

Declaration

public void Disable()

Remarks

Normally actions are enabled and disabled at the map level via Disable(). Use this method only when fine-grained per-action control is required. Has no effect if the underlying Unity action is null.

Enable()

Enables the underlying Unity InputAction, allowing it to receive input events.

Declaration

public void Enable()

Remarks

Normally actions are enabled and disabled at the map level via Enable(). Use this method only when fine-grained per-action control is required. Has no effect if the underlying Unity action is null.

GetBinding(int)

Returns the ScyllaInputBinding at the specified index within the binding list.

Declaration

public ScyllaInputBinding GetBinding(int index)

Parameters

Type	Name	Description
int	index	Zero-based index of the binding to retrieve. Composite bindings and their individual parts each occupy one index in the flat list (matching Unity's binding layout).

Returns

Type	Description
ScyllaInputBinding	The ScyllaInputBinding at `index`, or `null` if the index is outside the valid range `[0, BindingCount)`.

GetBindingDisplayString(int, HumanReadableStringOptions)

Returns a human-readable display string for the binding at the specified index.

Declaration

public string GetBindingDisplayString(int bindingIndex = 0, InputControlPath.HumanReadableStringOptions options = HumanReadableStringOptions.OmitDevice)

Parameters

Type	Name	Description
int	bindingIndex	Zero-based index of the binding whose display string to return. Defaults to `0` (the first binding).
InputControlPath.HumanReadableStringOptions	options	Formatting options forwarded to GetDisplayString(HumanReadableStringOptions). Defaults to `InputControlPath.HumanReadableStringOptions.OmitDevice`, which omits the device prefix (e.g., returns `"Space"` instead of `"Keyboard/Space"`).

Returns

Type	Description
string	The human-readable display string for the binding (e.g., `"Space"`, `"Left Stick/Up"`), or an empty string if `bindingIndex` is outside the valid range.

GetBindingsForGroup(string)

Returns all bindings that belong to the specified control scheme group.

Declaration

public IReadOnlyList<ScyllaInputBinding> GetBindingsForGroup(string group)

Parameters

Type	Name	Description
string	group	The control scheme group name to filter by (e.g., `"Keyboard"`, `"Gamepad"`). Case-insensitive. A `null` or empty value returns an empty list.

Returns

Type	Description
IReadOnlyList<ScyllaInputBinding>	A new IReadOnlyList<T> containing all ScyllaInputBinding instances that belong to `group`. Never `null`; may be empty.

Remarks

Group membership is determined by BelongsToGroup(string), which performs a case-insensitive substring match against the semicolon-separated Groups string of each binding (e.g., "Keyboard;Mouse"). This method allocates a new list on every call; cache the result if called frequently.

ReadFloat()

Reads the current float value of the action, handling control-type mismatches gracefully.

Declaration

public float ReadFloat()

Returns

Type	Description
float	The float value of the action, or `0f` if not available or the value type is incompatible with `float`.

Remarks

The method dispatches on the action's expectedControlType string to avoid InvalidOperationException from reading a typed value that does not match the control's actual output type:

"Vector2" - returns the magnitude of the 2D vector value.
"Vector3" - returns the magnitude of the 3D vector value.
"Axis", "Button", "Digital", "Analog", "Integer", or empty - reads as float directly.
Any other type - attempts a float read; returns 0f on InvalidOperationException.

Returns 0f when the underlying Unity action is null or disabled.

ReadValueSafe<T>()

Reads the current value of the action as the specified struct type, returning default(T) instead of throwing on a type mismatch.

Declaration

public T ReadValueSafe<T>() where T : struct

Returns

Type	Description
T	The current value cast to `T`; `default(T)` if the underlying Unity action is `null`, disabled, or the type does not match the control's output type.

Type Parameters

Name	Description
T	The struct type to read (e.g., `float`, `Vector2`, `Vector3`).

ReadValue<T>()

Reads the current value of the action as the specified struct type.

Declaration

public T ReadValue<T>() where T : struct

Returns

Type	Description
T	The current value cast to `T`, or `default(T)` if the underlying Unity action is `null` or disabled.

Type Parameters

Name	Description
T	The struct type that matches the action's control value (e.g., `float`, `Vector2`, `Vector3`).

Remarks

This method does not guard against type mismatches. If T does not match the action's control type, Unity will throw an InvalidOperationException. Use ReadValueSafe<T>() when the type match is not guaranteed, or ReadFloat() / ReadVector2() for the most common cases.

ReadVector2()

Reads the current Vector2 value of the action, handling control-type mismatches gracefully.

Declaration

public Vector2 ReadVector2()

Returns

Type	Description
Vector2	The `Vector2` value of the action, or `Vector2.zero` if not available or the value type is incompatible.

Remarks

The method dispatches on the action's expectedControlType string:

"Vector2" - reads and returns the value directly.
"Axis", "Button", "Digital", "Analog", or "Integer" - returns Vector2.zero because scalar types cannot be meaningfully promoted to a 2D vector.
Empty or unrecognized control type - attempts a Vector2 read; returns Vector2.zero on InvalidOperationException.

Returns Vector2.zero when the underlying Unity action is null or disabled.

RefreshBindings()

Rebuilds the Bindings list from the current state of UnityAction.

Declaration

public void RefreshBindings()

Remarks

Call this method after a rebind operation modifies the underlying Unity action's binding list so that the Scylla-side wrappers stay in sync. Clears the existing list and creates a new ScyllaInputBinding for every entry in InputAction.bindings.

ToString()

Returns a human-readable string representation of this action, including its map ID, action ID, display name, and action type.

Declaration

public override string ToString()

Returns

Type	Description
string	A string in the form `"[MapID/ActionID] DisplayName (ActionType)"`.

Overrides

object.ToString()

Events

OnCanceled

Raised when the action transitions to the Canceled phase (button released or value returned below the actuation threshold).

Declaration

public event Action<ScyllaInputAction> OnCanceled

Event Type

Type	Description
Action<ScyllaInputAction>

Remarks

This event is never suppressed by modifier disambiguation. Subscribers that track pressed or held state based on OnStarted must always receive this event to correctly reset their internal state, even when the corresponding OnStarted was suppressed.

OnPerformed

Raised when the action reaches the Performed phase (button pressed or value changed beyond the actuation threshold).

Declaration

public event Action<ScyllaInputAction> OnPerformed

Event Type

Type	Description
Action<ScyllaInputAction>

Remarks

Subject to modifier disambiguation: this event is suppressed when a sibling action registered in the same InputActionManager shares the same trigger control path and has a higher ModifierDepth, and the user is currently holding enough modifier keys to satisfy that sibling's binding. In that scenario, the more-specific binding takes priority.

OnStarted

Raised when the action transitions to the Started phase (button just pressed down).

Declaration

public event Action<ScyllaInputAction> OnStarted

Event Type

Type	Description
Action<ScyllaInputAction>

Remarks

Subject to the same modifier disambiguation suppression rules as OnPerformed. See the class-level remarks for details.