Interface IInputBindingManager

Defines the contract for the input binding subsystem, which handles runtime rebinding, per-profile persistence, conflict detection, and JSON export/import of binding overrides.

Namespace: Scylla.Input

Assembly: ScyllaInput.dll

Syntax

public interface IInputBindingManager

Remarks

The binding manager works on top of Unity's Input System. It stores overrides only - the authoritative default bindings remain defined in the project's InputActionAsset. Only deviations from those defaults are persisted and reapplied at runtime.

The standard implementation is InputBindingManager, which is created and owned by ScyllaInput. Consumers access it through this interface to keep code testable and decoupled from the concrete class.

Profile system: bindings are grouped under named profiles (e.g., "default", "player2"). The active profile is tracked by CurrentProfileID and used as the implicit target for SaveBindings(string), LoadBindings(string), and HasSavedBindings(string) when no explicit profile ID is provided.

Persistence: the manager delegates all I/O to an IBindingStorage backend. The default backend is PlayerPrefsBindingStorage; call SetStorage(IBindingStorage) before or after Initialize(IInputActionManager, IInputContextManager) to switch to a different one (e.g., JSONFileBindingStorage for modding support).

Events: both C# event delegates and Scylla SEX events are fired for key operations. C# events are suitable for tight UI bindings; SEX events (InputRebindStartedEvent, InputRebindCompletedEvent, InputRebindCancelledEvent, InputBindingsSavedEvent, InputBindingsLoadedEvent) are preferred for decoupled game systems.

Properties

CurrentProfileID

Gets the identifier of the currently active binding profile.

Declaration

string CurrentProfileID { get; }

Property Value

Type	Description
string	A non-null, non-empty string. Defaults to `"default"` after construction. Change this value by calling SetCurrentProfile(string).

CurrentRebindOperation

Gets the InputRebindOperation that is currently waiting for player input, or null if no rebind is active.

Declaration

InputRebindOperation CurrentRebindOperation { get; }

Property Value

Type	Description
InputRebindOperation	A non-null operation object while IsRebinding is `true`; `null` at all other times, including immediately after the operation completes (the reference is cleared by InputBindingManager as part of cleanup).

IsInitialized

Gets a value indicating whether Initialize(IInputActionManager, IInputContextManager) has been called and completed successfully.

Declaration

bool IsInitialized { get; }

Property Value

Type	Description
bool	`true` once the manager is ready to accept rebind and override requests; `false` before Initialize(IInputActionManager, IInputContextManager) or after Shutdown(). Attempting most operations while `false` logs a warning and returns immediately without effect.

IsRebinding

Gets a value indicating whether an interactive rebind operation is currently waiting for player input.

Declaration

bool IsRebinding { get; }

Property Value

Type	Description
bool	`true` if CurrentRebindOperation is non-null and its IsActive flag is set; `false` otherwise. Only one rebind can be active at a time - calling StartRebind(string, int) while this is `true` logs a warning and returns `null`.

Methods

CancelRebind()

Cancels the currently active rebind operation, restoring the original binding path and firing the appropriate completion events with success = false.

Declaration

void CancelRebind()

Remarks

This is a no-op if IsRebinding is false; a warning is logged in that case. Internally delegates to Cancel() on CurrentRebindOperation.

ClearBindingOverride(string, int)

Removes the runtime override from a specific action binding, reverting it to the default path defined in the InputActionAsset.

Declaration

void ClearBindingOverride(string actionID, int bindingIndex)

Parameters

Type	Name	Description
string	actionID	The name of the action whose override should be cleared. Must not be null or empty, and must correspond to a registered action.
int	bindingIndex	Zero-based index of the binding from which to remove the override. Must be in the range `[0, action.bindings.Count)`.

DeleteProfile(string)

Permanently removes the saved binding data for the given profile from the configured IBindingStorage backend.

Declaration

void DeleteProfile(string profileID)

Parameters

Type	Name	Description
string	profileID	The non-null, non-empty profile ID to delete. A warning is logged and the call is ignored if `profileID` is null or empty.

Remarks

This method does not change CurrentProfileID or modify the in-memory binding state. It only removes data from the storage layer.

ExportBindingsAsJSON()

Serializes all current binding overrides to a pretty-printed JSON string without writing to any storage backend.

Declaration

string ExportBindingsAsJSON()

Returns

Type Description

Type	Description
string	A JSON string containing only the overridden bindings (actions using their default path are omitted). The root object includes a version field, the current profile ID, a UTC timestamp in ISO 8601 round-trip format, and an array of override records. Returns `null` if the manager is not initialized. Returns a valid (but sparse) JSON object with an empty override array if no bindings have been changed from their defaults.

string

A JSON string containing only the overridden bindings (actions using their default path are omitted). The root object includes a version field, the current profile ID, a UTC timestamp in ISO 8601 round-trip format, and an array of override records. Returns null if the manager is not initialized. Returns a valid (but sparse) JSON object with an empty override array if no bindings have been changed from their defaults.

Remarks

This method is the inverse of ImportBindingsFromJSON(string). The output is also the exact payload stored by SaveBindings(string).

GetAllProfiles()

Returns the identifiers of every profile for which the configured IBindingStorage backend has saved binding data.

Declaration

IReadOnlyList<string> GetAllProfiles()

Returns

Type	Description
IReadOnlyList<string>	A non-null, read-only list of profile ID strings, or an empty list if no storage backend is configured or no profiles have been saved.

GetBindingDisplayString(string, int)

Returns a human-readable display string for the specified binding, suitable for showing in a key-mapping UI (e.g., "Space" for "<Keyboard>/space").

Declaration

string GetBindingDisplayString(string actionID, int bindingIndex = 0)

Parameters

Type	Name	Description
string	actionID	The name of the action to query. Must not be null or empty, and must correspond to a registered action.
int	bindingIndex	Zero-based index of the binding to format. Defaults to `0`.

Returns

Type	Description
string	A localized display string generated by Unity's Input System, or `null` if the manager is not initialized, `actionID` is null/empty/not found, or `bindingIndex` is out of range.

GetBindingPath(string, int)

Returns the effective Unity Input System control path currently mapped to the specified binding, respecting any runtime override that has been applied.

Declaration

string GetBindingPath(string actionID, int bindingIndex = 0)

Parameters

Type	Name	Description
string	actionID	The name of the action to query. Must not be null or empty, and must correspond to a registered action.
int	bindingIndex	Zero-based index of the binding within the action to query. Defaults to `0`.

Returns

Type	Description
string	A Unity Input System control path such as `"<Keyboard>/space"`, or `null` if the manager is not initialized, `actionID` is null/empty/not found, or `bindingIndex` is out of range.

GetConflicts(string, string)

Returns all bindings across every registered action map whose effective path matches path, optionally excluding one action by name. When an IInputContextManager was provided during Initialize(IInputActionManager, IInputContextManager), action maps belonging to contexts that share the same ExclusionGroup as the excluded action's context are also skipped, preventing false-positive conflicts between mutually exclusive input modes.

Declaration

IReadOnlyList<BindingConflict> GetConflicts(string path, string excludeActionID = null)

Parameters

Type	Name	Description
string	path	The Unity Input System control path to search for conflicts (e.g., `"<Keyboard>/space"`). Path comparison is case-insensitive. Returns an empty list immediately if null or empty.
string	excludeActionID	An optional action name to exclude from the scan. Pass the ID of the action being rebound so that its own existing binding is not reported as a conflict with itself. Pass `null` to include all actions.

Returns

Type	Description
IReadOnlyList<BindingConflict>	A non-null, read-only list of BindingConflict instances describing every binding that currently occupies `path`. The list is empty if no conflicts exist, the manager is not initialized, or `path` is null/empty. Composite binding containers are excluded from the scan.

HasBindingOverride(string, int)

Determines whether a runtime binding override is currently applied to the specified binding slot.

Declaration

bool HasBindingOverride(string actionID, int bindingIndex = 0)

Parameters

Type	Name	Description
string	actionID	The name of the action to check. Must not be null or empty.
int	bindingIndex	Zero-based index of the binding to check. Defaults to `0`.

Returns

Type	Description
bool	`true` if an override path has been set on the binding (i.e., the player has changed the default); `false` if the binding still uses its default path, the manager is not initialized, `actionID` is null/empty/not found, or `bindingIndex` is out of range.

HasConflict(string, string)

Determines whether any binding currently occupies the given input path, optionally excluding one action from the check.

Declaration

bool HasConflict(string path, string excludeActionID = null)

Parameters

Type	Name	Description
string	path	The Unity Input System control path to check (e.g., `"<Keyboard>/space"`). Path comparison is case-insensitive. Returns `false` immediately if null or empty.
string	excludeActionID	An optional action name to exclude. Typically set to the action being rebound so its own current binding does not generate a self-conflict. Pass `null` to include all actions.

Returns

Type	Description
bool	`true` if GetConflicts(string, string) would return at least one entry for `path`; `false` otherwise.

HasSavedBindings(string)

Checks whether the configured IBindingStorage backend has saved binding data for the given profile.

Declaration

bool HasSavedBindings(string profileID = null)

Parameters

Type	Name	Description
string	profileID	The profile ID to check, or `null` / empty string to check CurrentProfileID. Defaults to `null`.

Returns

Type	Description
bool	`true` if the storage backend reports that binding data exists for the resolved profile; `false` if no storage is configured or the profile has no saved data.

ImportBindingsFromJSON(string)

Deserializes a JSON string previously produced by ExportBindingsAsJSON() and applies the contained overrides to the live action set.

Declaration

void ImportBindingsFromJSON(string json)

Parameters

Type	Name	Description
string	json	A non-null, non-empty JSON string in the format produced by ExportBindingsAsJSON(). If the string is malformed or cannot be parsed, an error is logged and no overrides are applied.

Remarks

Before applying the imported overrides, all current in-memory overrides are cleared via ResetAllToDefaults() to guarantee a clean state. If an action named in the JSON is no longer registered, a warning is logged for that entry and processing continues with the remaining overrides.

This method does not fire OnBindingsLoaded or the corresponding SEX event - those are fired only by LoadBindings(string).

Initialize(IInputActionManager, IInputContextManager)

Initializes the binding manager with the given action manager, sets up the default storage backend if none has been configured, and attempts to auto-load the default profile from storage.

Declaration

void Initialize(IInputActionManager actionManager, IInputContextManager contextManager = null)

Parameters

Type	Name	Description
IInputActionManager	actionManager	The IInputActionManager that the binding manager will use to resolve action names, enumerate action maps, and apply or remove binding overrides. Must not be `null`.
IInputContextManager	contextManager	Optional IInputContextManager used by GetConflicts(string, string) to resolve ExclusionGroup relationships. When provided, conflict detection skips bindings from action maps that belong to mutually exclusive contexts (contexts sharing the same non-empty exclusion group). Pass `null` to disable exclusion-group-aware conflict detection.

Remarks

If SetStorage(IBindingStorage) has not been called before Initialize, a PlayerPrefsBindingStorage is created automatically.

The manager then checks whether saved binding data exists for the "default" profile and, if so, loads it automatically. Auto-load failures (e.g., corrupt JSON) are caught, logged as errors, and treated as non-fatal; initialization still completes and IsInitialized becomes true.

Calling Initialize a second time while already initialized logs a warning and returns immediately without re-initializing.

LoadBindings(string)

Reads previously saved binding data for the specified profile from the configured IBindingStorage backend and applies the overrides to the live action set.

Declaration

void LoadBindings(string profileID = null)

Parameters

Type	Name	Description
string	profileID	The profile slot to read from, or `null` / empty string to use CurrentProfileID. Defaults to `null`.

Remarks

Internally calls ImportBindingsFromJSON(string) which first calls ResetAllToDefaults() to clear any in-memory overrides before applying the stored ones. If the profile has no saved data the method logs an informational message and returns without modifying any bindings.

After successful application, OnBindingsLoaded and the SEX event InputBindingsLoadedEvent are fired.

ResetAllToDefaults()

Removes all runtime binding overrides from every action in every registered action map, restoring each to the default path from the InputActionAsset.

Declaration

void ResetAllToDefaults()

Remarks

Equivalent to calling ResetToDefaults(string) with a null actionID. This is also called internally by ImportBindingsFromJSON(string) before applying the imported overrides, to ensure a clean slate.

ResetToDefaults(string)

Removes all runtime binding overrides from the specified action, or from all registered actions when actionID is null or empty.

Declaration

void ResetToDefaults(string actionID = null)

Parameters

Type	Name	Description
string	actionID	The name of a specific action to reset, or `null` / empty string to reset every action across all registered action maps. Defaults to `null`.

Remarks

This method delegates to ResetAllToDefaults() when actionID is null or empty. Changes take effect immediately but are not persisted; call SaveBindings(string) afterwards if the reset should survive the session.

SaveBindings(string)

Serializes all current binding overrides to JSON and writes them to the configured IBindingStorage backend under the specified profile.

Declaration

void SaveBindings(string profileID = null)

Parameters

Type	Name	Description
string	profileID	The profile slot to write into, or `null` / empty string to use CurrentProfileID. Defaults to `null`.

Remarks

Only overrides are saved - actions that still use their default binding are not written. The JSON payload is produced by ExportBindingsAsJSON().

After a successful write, OnBindingsSaved and the SEX event InputBindingsSavedEvent are fired. If the manager is not initialized or no storage backend is configured, a warning is logged and the method returns without saving.

SetBindingOverride(string, int, string)

Programmatically applies a binding override to a specific action binding, bypassing interactive rebinding.

Declaration

void SetBindingOverride(string actionID, int bindingIndex, string path)

Parameters

Type	Name	Description
string	actionID	The name of the action to modify. Must not be null or empty, and must correspond to a registered action.
int	bindingIndex	Zero-based index of the binding to override. Must be in the range `[0, action.bindings.Count)`.
string	path	The Unity Input System control path to set as the override (e.g., `"<Keyboard>/space"`). Pass an empty string or `null` to effectively disable the binding without removing the override record. To remove the override entirely, use ClearBindingOverride(string, int) instead.

Remarks

This method is useful for programmatic remapping (e.g., applying a saved preset) and does not fire rebind events. Changes take effect immediately on the underlying Unity action. Call SaveBindings(string) afterwards to persist the change.

SetCurrentProfile(string)

Changes the active profile without loading or saving any data.

Declaration

void SetCurrentProfile(string profileID)

Parameters

Type	Name	Description
string	profileID	The non-null, non-empty profile ID to set as current. Call LoadBindings(string) afterwards to apply the stored bindings for the new profile. A warning is logged and the call is ignored if `profileID` is null or empty.

SetStorage(IBindingStorage)

Replaces the active IBindingStorage backend used for all subsequent save and load operations.

Declaration

void SetStorage(IBindingStorage storage)

Parameters

Type	Name	Description
IBindingStorage	storage	The new storage backend to use, or `null` to clear the current backend. When `null` is passed, subsequent calls to SaveBindings(string) and LoadBindings(string) will log a warning and do nothing.

Remarks

Swapping the storage backend does not migrate previously saved data. If the manager has already auto-loaded a default profile, that data remains applied in memory; only future persistence operations are redirected to the new backend.

Shutdown()

Cancels any active rebind operation, releases all resources, clears all event subscriptions, and resets IsInitialized to false.

Declaration

void Shutdown()

Remarks

After Shutdown returns, the manager can be safely discarded. It cannot be reused - a new instance must be created and initialized to resume binding management.

StartRebind(string, int)

Creates and immediately starts an interactive rebind operation for the specified action binding, returning the operation object so the caller can configure it further or subscribe to its events.

Declaration

InputRebindOperation StartRebind(string actionID, int bindingIndex = 0)

Parameters

Type	Name	Description
string	actionID	The name of the Unity Input System action to rebind (e.g., `"Jump"`, `"Fire"`). Must match an action registered with the IInputActionManager. Must not be null or empty.
int	bindingIndex	Zero-based index of the binding within the action's `bindings` collection to replace. Must be in the range `[0, action.bindings.Count)`. Defaults to `0`, which is the primary binding for simple actions.

Returns

Type	Description
InputRebindOperation	The newly created InputRebindOperation that is already listening for input, or `null` if the operation could not be started because the manager is not initialized, another rebind is already active, `actionID` is null/empty/not found, or `bindingIndex` is out of range.

Remarks

The returned operation can be configured via its fluent API before calling Start() - however, this implementation starts the operation automatically. Callers may still chain fluent calls on the returned object to adjust the filter or cancel path while the operation is running; refer to InputRebindOperation for supported options.

Subscribing to OnRebindStarted or OnComplete is the recommended way to react to the outcome rather than polling IsRebinding.

Update()

Called once per frame by the owning ScyllaInput module. The default implementation has no per-frame work; rebinding is driven entirely by Unity Input System callbacks.

Declaration

void Update()

UpdateRebind()

Performs per-frame update for the active rebind operation when modifier support is enabled. Must be called each frame while IsRebinding is true.

Declaration

void UpdateRebind()

Remarks

This method forwards to Update() on the CurrentRebindOperation. It has no effect when no rebind is active or when the active operation does not have modifier support enabled.

Events

OnBindingsLoaded

Raised after LoadBindings(string) successfully reads and applies binding data from the configured IBindingStorage backend.

Declaration

event Action<string> OnBindingsLoaded

Event Type

Type	Description
Action<string>

Remarks

The string argument is the profile ID that was loaded. A corresponding SEX event (InputBindingsLoadedEvent) is also published at the same time.

OnBindingsSaved

Raised after SaveBindings(string) successfully writes binding data to the configured IBindingStorage backend.

Declaration

event Action<string> OnBindingsSaved

Event Type

Type	Description
Action<string>

Remarks

The string argument is the profile ID that was saved. A corresponding SEX event (InputBindingsSavedEvent) is also published at the same time.

OnRebindCompleted

Raised when the active rebind operation terminates - either because the player pressed a valid input (success) or because the operation was cancelled or timed out (failure).

Declaration

event Action<InputRebindOperation, bool, string> OnRebindCompleted

Event Type

Type	Description
Action<InputRebindOperation, bool, string>

Remarks

The three parameters carried by this event are:

InputRebindOperationThe operation that completed. Its WasSuccessful and NewPath properties reflect the final state.
bool successtrue if a new binding was recorded; false if the operation was cancelled or timed out.
string newPathThe Unity Input System control path that was bound (e.g., "<Keyboard>/space"), or null if the rebind was not successful.

A corresponding SEX event (InputRebindCompletedEvent or InputRebindCancelledEvent) is also published to ScyllaEvents at the same time.

OnRebindStarted

Raised immediately after a rebind operation has been created and started via StartRebind(string, int). The operation is listening for input at this point.

Declaration

event Action<InputRebindOperation> OnRebindStarted

Event Type

Type	Description
Action<InputRebindOperation>

Remarks

A corresponding SEX event (InputRebindStartedEvent) is also published to ScyllaEvents at the same time. Subscribers should use one or the other, not both, to avoid double-handling.