Interface IControlSchemeManager

Defines the contract for a control scheme manager that tracks and switches between named input device groupings such as keyboard/mouse, gamepad, and touch.

Namespace: Scylla.Input
Assembly: ScyllaInput.dll
Syntax
public interface IControlSchemeManager
Remarks

A control scheme (ControlScheme) represents a named grouping of compatible input devices together with display metadata such as an icon set ID and a human-readable name. The manager is responsible for registering schemes, selecting which scheme is currently active, and optionally detecting scheme changes automatically based on which physical input device the player most recently used.

On initialization via Initialize(IInputBridgeManager), the manager registers the two built-in default schemes (keyboard/mouse and gamepad) and selects the active scheme based on whether a gamepad is currently connected. Callers may register additional schemes - for example, a touch scheme or a custom scheme - using RegisterScheme(ControlScheme). Custom schemes must use a ControlSchemeType of Custom to avoid collisions with the built-in type-indexed lookup used by GetSchemeByType(ControlSchemeType).

When AutoDetectionEnabled is true, calling Update() once per frame polls the IInputBridgeManager for significant input on each device class and switches the active scheme accordingly. The SwitchCooldown, GamepadStickThreshold, GamepadTriggerThreshold, and MouseDeltaThreshold thresholds prevent spurious switching caused by analog drift or simultaneous multi-device activity.

Every scheme switch - whether triggered automatically or via SetActiveScheme(string) / SetActiveScheme(ControlSchemeType) - fires both the OnSchemeChanged delegate event and a ControlSchemeChangedEvent through the Scylla Event eXchange System (SEX).

Properties

ActiveScheme

Gets the currently active control scheme, or null if no scheme is active.

Declaration
ControlScheme ActiveScheme { get; }
Property Value
Type Description
ControlScheme

The ControlScheme that was last set via auto-detection or an explicit call to SetActiveScheme(string) / SetActiveScheme(ControlSchemeType). Returns null before Initialize(IInputBridgeManager) is called or after all schemes have been unregistered.

ActiveSchemeType

Gets the ControlSchemeType of the currently active scheme.

Declaration
ControlSchemeType ActiveSchemeType { get; }
Property Value
Type Description
ControlSchemeType

The type category of the active scheme. Returns Unknown when ActiveScheme is null (i.e., before initialization or when no schemes are registered).

AutoDetectionEnabled

Gets or sets a value indicating whether the manager should automatically switch the active scheme based on recent input device activity each time Update() is called.

Declaration
bool AutoDetectionEnabled { get; set; }
Property Value
Type Description
bool

true to enable automatic scheme detection; false to require manual calls to SetActiveScheme(string) or SetActiveScheme(ControlSchemeType). Defaults to true.
Remarks

When enabled, Update() polls the IInputBridgeManager for gamepad axis/button activity and keyboard/mouse activity each frame. The scheme only switches if the detected input type differs from the currently active type and the SwitchCooldown period has elapsed since the last switch.

DetectedGamepadType

Gets the manufacturer/platform type of the gamepad that was most recently identified by the auto-detection system.

Declaration
GamepadType DetectedGamepadType { get; }
Property Value
Type Description
GamepadType

A GamepadType value indicating whether the connected gamepad is an Xbox, PlayStation, Nintendo, Steam, or Generic controller. The value is updated whenever the active scheme switches to a Gamepad scheme or whenever the underlying gamepad device changes. Returns Generic when no gamepad is connected.
See Also

GamepadStickThreshold

Gets or sets the minimum stick axis magnitude required to register gamepad stick movement as significant input during auto-detection.

Declaration
float GamepadStickThreshold { get; set; }
Property Value
Type Description
float

A value in the range [0, 1], clamped automatically. Defaults to 0.2. Gamepad left- or right-stick input whose squared magnitude falls below this threshold squared is ignored.
Remarks

Increasing this threshold makes the auto-detection less sensitive to analog stick drift and minor controller vibration, at the cost of requiring more deliberate stick movement to trigger a scheme switch.

GamepadTriggerThreshold

Gets or sets the minimum analog value required on either gamepad trigger to register trigger input as significant during auto-detection.

Declaration
float GamepadTriggerThreshold { get; set; }
Property Value
Type Description
float

A value in the range [0, 1], clamped automatically. Defaults to 0.1. Trigger values at or below this threshold are ignored to prevent hair-trigger sensitivity from causing unwanted scheme switches.

IsInitialized

Gets a value indicating whether Initialize(IInputBridgeManager) has been called and the manager is ready to process input.

Declaration
bool IsInitialized { get; }
Property Value
Type Description
bool

true after a successful call to Initialize(IInputBridgeManager); false before initialization or after Shutdown() has been called.

MouseDeltaThreshold

Gets or sets the minimum mouse movement delta magnitude (in pixels) required to register mouse movement as significant input during auto-detection.

Declaration
float MouseDeltaThreshold { get; set; }
Property Value
Type Description
float

A non-negative pixel delta. Values below zero are silently raised to zero. Defaults to 5.0 pixels per frame.
Remarks

Small mouse deltas caused by optical sensor noise or minor accidental movement can be filtered out by raising this value. Lowering it makes the auto-detection more responsive to subtle mouse movement.

SwitchCooldown

Gets or sets the minimum number of seconds that must elapse between automatic scheme switches.

Declaration
float SwitchCooldown { get; set; }
Property Value
Type Description
float

A non-negative number of seconds. The value is clamped to zero from below; negative values are silently raised to zero. Defaults to 0.3 seconds.
Remarks

This cooldown prevents rapid scheme toggling that can occur when the player uses both a gamepad and a keyboard simultaneously (for example, when glancing at a keyboard shortcut while holding a gamepad). The clock is measured against Time.realtimeSinceStartupAsDouble and is unaffected by game pause or time scale.

Methods

GetAllSchemes()

Returns a read-only view of all currently registered control schemes in registration order.

Declaration
IReadOnlyList<ControlScheme> GetAllSchemes()
Returns
Type Description
IReadOnlyList<ControlScheme>

A IReadOnlyList<T> of ControlScheme instances. The list is empty before Initialize(IInputBridgeManager) is called or if all schemes have been unregistered.

GetScheme(string)

Returns the registered ControlScheme with the specified ID.

Declaration
ControlScheme GetScheme(string schemeID)
Parameters
Type Name Description
string schemeID

The SchemeID to look up. Null or empty values always return null.
Returns
Type Description
ControlScheme

The matching ControlScheme, or null if no scheme with that ID is registered.

GetSchemeByType(ControlSchemeType)

Returns the first registered ControlScheme whose SchemeType matches schemeType.

Declaration
ControlScheme GetSchemeByType(ControlSchemeType schemeType)
Parameters
Type Name Description
ControlSchemeType schemeType

The ControlSchemeType to look up.
Returns
Type Description
ControlScheme

The primary ControlScheme for that type, or null if no scheme of that type is registered.
Remarks

Only the scheme that was registered first for a given type is stored in the type-keyed index. If the primary scheme is unregistered, the next scheme of the same type is promoted. Use GetScheme(string) to retrieve schemes by their exact ID when multiple schemes share a type.

HasScheme(string)

Determines whether a scheme with the specified ID is currently registered.

Declaration
bool HasScheme(string schemeID)
Parameters
Type Name Description
string schemeID

The SchemeID to test. Null or empty values always return false.
Returns
Type Description
bool

true if a scheme with schemeID is registered; false otherwise.

Initialize(IInputBridgeManager)

Initializes the control scheme manager with the given bridge manager and registers the built-in default keyboard/mouse and gamepad schemes.

Declaration
void Initialize(IInputBridgeManager bridgeManager)
Parameters
Type Name Description
IInputBridgeManager bridgeManager

The IInputBridgeManager instance that will be queried for device state during auto-detection and gamepad type identification. Must not be null.
Remarks

After initialization, the active scheme is determined by whether a gamepad is currently connected (IsGamepadConnected()). Calling this method more than once is safe but logs a warning and returns without re-initializing.

RegisterScheme(ControlScheme)

Registers a ControlScheme with the manager so that it can be selected as the active scheme.

Declaration
bool RegisterScheme(ControlScheme scheme)
Parameters
Type Name Description
ControlScheme scheme

The control scheme to register. Must not be null and must have a SchemeID that is not already registered.
Returns
Type Description
bool

true if the scheme was registered successfully; false if scheme is null or a scheme with the same SchemeID is already registered.
Remarks

For each ControlSchemeType, only the first registered scheme of that type becomes the primary lookup target for GetSchemeByType(ControlSchemeType) and SetActiveScheme(ControlSchemeType). Subsequent schemes of the same type are registered by ID only and can be activated via SetActiveScheme(string).

SetActiveScheme(ControlSchemeType)

Manually activates the first registered ControlScheme whose type matches schemeType, bypassing auto-detection cooldown and thresholds.

Declaration
bool SetActiveScheme(ControlSchemeType schemeType)
Parameters
Type Name Description
ControlSchemeType schemeType

The ControlSchemeType of the scheme to activate.
Returns
Type Description
bool

true if a scheme of the requested type was found and set as the active scheme; false if no scheme of that type is registered.
Remarks

This overload selects the type-keyed primary scheme (the first scheme of that type that was registered). If the target scheme is already active, no events are fired. On a successful switch, OnSchemeChanged is raised and a ControlSchemeChangedEvent is published via the Scylla Event eXchange System.

SetActiveScheme(string)

Manually activates the registered ControlScheme with the given ID, bypassing auto-detection cooldown and thresholds.

Declaration
bool SetActiveScheme(string schemeID)
Parameters
Type Name Description
string schemeID

The SchemeID of the scheme to activate.
Returns
Type Description
bool

true if the scheme was found and set as the active scheme; false if no scheme with schemeID is registered.
Remarks

If the requested scheme is already the active scheme, no events are fired and the method still returns true. On a successful switch, OnSchemeChanged is raised and a ControlSchemeChangedEvent is published via the Scylla Event eXchange System.

Shutdown()

Shuts down the control scheme manager, clears all registered schemes, and releases the reference to the IInputBridgeManager.

Declaration
void Shutdown()
Remarks

After shutdown, IsInitialized returns false and ActiveScheme is null. Calling Update() after shutdown is safe and has no effect. The manager can be re-initialized by calling Initialize(IInputBridgeManager) again.

UnregisterScheme(string)

Removes a previously registered ControlScheme from the manager.

Declaration
bool UnregisterScheme(string schemeID)
Parameters
Type Name Description
string schemeID

The SchemeID of the scheme to remove. Null or empty values are treated as not found and return false.
Returns
Type Description
bool

true if the scheme was found and removed; false if no scheme with schemeID is registered.
Remarks

If the unregistered scheme was the primary type-keyed entry for its ControlSchemeType, the manager promotes the next registered scheme of the same type to the primary slot. If the unregistered scheme was the active scheme, the manager falls back to the first remaining scheme in registration order, or sets ActiveScheme to null if no schemes remain.

Update()

Polls for input device activity and switches the active control scheme if a change is detected. Should be called once per frame from the owning module's update loop.

Declaration
void Update()
Remarks

This method is a no-op when IsInitialized is false or when AutoDetectionEnabled is false. The scheme switch is subject to the SwitchCooldown guard and the analog input thresholds defined by GamepadStickThreshold, GamepadTriggerThreshold, and MouseDeltaThreshold.

Events

OnGamepadTypeChanged

Occurs when the manager identifies a change in the connected gamepad's manufacturer or platform type.

Declaration
event Action<GamepadType> OnGamepadTypeChanged
Event Type
Type Description
Action<GamepadType>
Remarks

This event fires when DetectedGamepadType changes - for example, when the player unplugs an Xbox controller and connects a PlayStation controller, or when a gamepad is first connected after startup. The argument is the newly detected GamepadType. Listeners can use this to update button-prompt icons without needing to observe a full scheme change.

OnSchemeChanged

Occurs when the active control scheme changes, either through auto-detection or a manual call to SetActiveScheme(string) / SetActiveScheme(ControlSchemeType).

Declaration
event Action<ControlScheme, ControlScheme> OnSchemeChanged
Event Type
Type Description
Action<ControlScheme, ControlScheme>
Remarks

The first argument is the scheme that was previously active (may be null if no scheme was active before the switch). The second argument is the newly active scheme. This event fires in addition to the ControlSchemeChangedEvent published through the Scylla Event eXchange System, allowing listeners to choose either subscription mechanism.

See Also