Skip to content

IL_ScriptableRefs

Eric Lowry edited this page Nov 10, 2026 · 6 revisions

Namespace: Lowry.UI.InputLayers

public sealed class IL_ScriptableRefs : SingletonScriptableObject<IL_ScriptableRefs>

The main ScriptableObject🔗 used as a "singleton" static storage for input layers as a list of priorities.

💡General Information

This class serves three main functions:

  1. Storing user configuration for InputLayers as described here.
  2. Managing priority stacks and cached layer lookups, with editor validation of layer names.
  3. Triggering the events that allow other scripts to react to layer changes.

You will need to reference this script whenever you wish to interact directly with the hierarchy of priorities and layers, or have code react to layer activation/deactivation events.

Note: The r_ properties documented here are static (ex: IL_ScriptableRefs.r_activeLayer). The methods documented here are instance methods (ex: IL_ScriptableRefs.Instance.GetLayerByName("Base")). The prefix is a naming convention, not a general rule for every member. Keep one IL_ScriptableRefs asset: singleton discovery returns null if it finds none or multiple candidates. The InputLayers editor window creates the asset when missing; the runtime singleton lookup does not create it. In the Editor, a resolved singleton is also added to Player Settings' preloaded assets.

On enable, the asset clears activation stacks, map registrations, and its active-layer and priority fields, then builds its lookup caches. Editor subsystem registration also clears runtime state before play. ResetRuntimeState also resets the values stored in the corresponding change-notification delegates to null using SetValueWithoutNotify, without invoking callbacks or layer events. This reset does not disable InputActionMaps. Editor validation also rebuilds the caches. Direct changes to names or priority lists do not rebuild them automatically; RefreshStorage(true) requests a rebuild in the Editor only.

Continuous stateful-action polling uses the separate IL_InputLayersRuntimeManager component, not Unity update methods on this asset. That manager finds or creates its persistent scene object when its Instance is requested.

ℹ️ As this script is quite extensive, this documentation page only covers properties and methods that are deemed relevant to InputLayers users.

Transition callbacks

When selection changes, SetActive commits the layer and priority together and silently synchronizes both bindable caches before invoking callbacks. The notification order is:

  1. The new layer's onActivated, if there is a new layer. Its activation frame is recorded before its handlers run.
  2. The previous layer's onDeactivated, if there was a previous layer.
  3. r_onActiveLayerChanged, if the selected layer changed.
  4. r_onCurrentPriorityLayerChanged, if the selected priority changed.

Removing the final layer sets both selected values to null; no new-layer activation event is sent. Activating the already-selected layer sends none of these notifications and does not reset its activation frame.

Transition callbacks must not throw or synchronously activate/deactivate layers. Nested transitions are not queued or guarded and can interrupt the outer notification sequence. Schedule such layer changes after the current transition has completed.

📄Properties

r_actionsAssets

public static List<InputActionAsset> r_actionsAssets { get {...} set {...} }

The list of InputActionAsset files searched when resolving input actions and maps.

r_priorities

public static List<IL_PriorityLayer> r_priorities => Instance._priorities;

The main list of IL_Layers split into IL_PriorityLayers (aka. priorities). Later indices have higher priority. This exposes the mutable list; editing it directly does not refresh lookup caches or reconcile the active stack state.

r_activeLayer

public static IL_Layer r_activeLayer => Instance._activeLayer;

The currently selected layer, or null when all activation stacks are empty.
Only one layer can be active at a time.
Other layers in the activation stacks wait to be restored when higher layers are removed; layers that have never been activated are not queued.

r_activePriorityLayer

public static IL_PriorityLayer r_activePriorityLayer => Instance.__currPriorityLayer == null ? null : Instance._priorities[(int)Instance.__currPriorityLayer];

The currently selected priority: the last item in r_priorities with a non-empty activation stack, or null when all stacks are empty.

r_actionMaps

public static Dictionary<InputActionMap, List<LayeredAction>> r_actionMaps { get {...} set {...} }

Groups registered LayeredActions by the InputActionMap🔗 they requested to enable (see LayeredAction.Enable(bool, bool)). AddMap enables a map when registering an action. RemoveMap disables it and removes its dictionary entry when the last registration is removed. Changing this dictionary directly does not enable or disable maps; maps outside it are not automatically disabled.

📄Delegates

r_onActiveLayerChanged

public static BindableAction<IL_Layer> r_onActiveLayerChanged => Instance.onActiveLayerChanged;

A BindableAction notified after layer lifecycle callbacks when the selected layer changes. The callback argument is the selected layer, or null when the final layer is removed; the bindable itself is not null. Its cache is synchronized before lifecycle callbacks. Subscriptions invoke immediately by default. Runtime resets silently set the stored value to null.

r_onCurrentPriorityLayerChanged

public static BindableAction<int?> r_onCurrentPriorityLayerChanged => Instance.onCurrentPriorityLayerChanged;

A BindableAction notified after lifecycle and active-layer notifications when the selected priority changes. The callback argument is a nullable priority index, not the bindable itself. Its cache is synchronized before lifecycle callbacks. Removing the final layer sets this value to null. Subscriptions invoke immediately by default. Runtime resets silently set the stored value to null.

If not null, this int corresponds to an id within the r_priorities list.

📄Methods

AddMap(InputActionMap, LayeredAction)

public void AddMap (InputActionMap map, LayeredAction action) {...}

Adds a map/action reference in r_actionMaps, then calls map.Enable() to enable all actions in that map. A null map, null action, or already-registered pair is ignored. Enabling the whole map is intentional even when map.enabled is already true: individual actions may have been enabled without enabling the rest of the map. This is not a continuous check that keeps the map enabled.

Parameters:

  • map: The InputActionMap🔗 whose actions should be enabled.
  • action: The action to register for a given map.

RemoveMap(InputActionMap, LayeredAction)

public void RemoveMap (InputActionMap map, LayeredAction action) {...}

Removes the action's registration from r_actionMaps. When the registration list becomes empty, disables the map and removes its dictionary entry. A null map or an unregistered map/action pair is ignored.

Parameters:

  • map: The InputActionMap🔗 to no longer keep enabled for the sake of this action.
  • action: The action to unregister for a given map.

GetLayerByName(string)

public IL_Layer GetLayerByName (string name) {...}

Looks up a layer in the name cache; it does not scan the current priority lists.

Parameters:

  • name: The non-null name of the target layer. A null name causes ArgumentNullException.

Returns: The cached IL_Layer with that name, or null with a warning if no entry exists. Cache construction keeps the first layer encountered for each name.

GetPriority(IL_Layer)

public int? GetPriority (IL_Layer layer_) {...}

Gets a layer's cached zero-based priority index. The cache uses IL_Layer's name-based equality, not reference identity.

Returns: The cached index, or null if the argument is null or no cached entry exists.

📄Internal Methods

These methods are internal; use IL_Layer or InputLayer to activate and deactivate layers from your code.

ActivateLayer(IL_Layer)

internal bool? ActivateLayer (IL_Layer layer_) {...}

Pushes or moves a layer to the top of its priority's activation stack. It becomes selected if no higher priority is in use. Calling this for the already-selected layer returns true without repeating activation events or resetting the activation frame.

Activation updates only the target priority's stack. If that priority is at least as high as the selected priority, SetActive selects the requested layer; otherwise it remains stacked beneath the higher priority. The previous layer is taken from the global selected state, not the previous top of the target stack. See transition callbacks for notification order and handler requirements.

Note: This method is called when using IL_Layer.Activate().

Parameters:

  • layer_: The layer which should be activated.

Returns:

  • true when the layer has been activated (or was already active).
  • false when the layer has not been activated (it will still be added to the relevant stack).
  • null when the layer is null or absent from the priority cache.

DeactivateLayer(IL_Layer)

internal void DeactivateLayer (IL_Layer layer_) {...}

Searches priorities from highest to lowest using TryToDeactivate. Removing the selected layer restores the next layer in the same stack, or searches lower priorities for the highest non-empty stack. If no fallback exists, both selected values become null. Removing an absent or waiting layer leaves selection unchanged. See transition callbacks for notification order and handler requirements.

Note: This method is called when using IL_Layer.Deactivate().

Parameters:

  • layer_: The layer which should be deactivated.

TryToDeactivate(IL_Layer, int)

private int TryToDeactivate (IL_Layer layer_, int p) {...}

Inspects priority p and attempts to remove layer_ from its activation stack. Returns -1 if the priority does not contain the layer or has no stacked layers, -2 when no further search is needed, or p when the selected stack became empty and lower priorities must be searched. A same-priority replacement is selected immediately.

SetActive(IL_Layer, int?)

private void SetActive (IL_Layer layer, int? priority) {...}

Commits the selected layer and nullable priority index, synchronizes their bindable caches with SetValueWithoutNotify, then dispatches the transition callbacks. Both arguments are null when no layer remains. Explicit Invoke calls send change notifications only for the selected values that changed.

Clone this wiki locally