Repository navigation
Home
Please refer to the Installation Guide for instructions on how to add InputLayers to your Unity project.
InputLayers is a system built on top of Unity's native Input System🔗. More specifically, it is meant to extend the functionality and usability of Input Actions🔗 (referred to as InputActions across this documentation).
The following documentation and accompanying guides require a basic understanding of the InputActions system and how it is configured/used. I will try to be as clear as possible, but I strongly recommend that you first familiarize yourself with InputActions before proceeding.
You can also find a short video introduction🔗 on YouTube that covers the core concepts and shows them in action.
At its core, InputLayers is about letting you easily have multiple systems/UIs/controllers/… react to the same InputAction without:
- Having to manually enable/disable input handling for one system if another has taken over.
- Having to create and configure dozens of ActionMaps🔗 with the same InputActions assigned to them just to manage inputs for all your systems/UIs/controllers/…
- Risking the integrity of your input system anytime a new system or UI is added to the game.
To achieve this, InputLayers lets you configure Layers sorted into Priorities using a dedicated editor window.
You then use LayeredActions which belong to a specific Layer in place of the default InputActions.
Each LayeredAction points to a specific InputAction you have created in the default editor window, and will react to the InputAction being triggered.
However, the LayeredAction will only register the input and take effect if the Layer it is attached to is active.
At most one layer is the current active layer. Other layers can remain enabled in the stack without receiving input. Within a priority, the most recently activated layer takes over; deactivating it reveals the previous enabled layer.
Priorities simply let you ensure that some layers always take priority over others, regardless of when they were activated. In essence, each priority has its own stack of active layers.
Higher-numbered priorities take precedence. LayeredActions also reject input on the frame a layer becomes active, preventing the same input from immediately passing through to the newly selected layer.
The best way to understand how this works and how it can be used is through examples. Let's start with a simple example that doesn't take Priorities into account:
Note: This example is illustrated in the `IL_Sample_Basic` example scene available as an optional element of the InputLayers package.
Let's imagine a simple UI with 2 main components:
- A simple element that can be interacted with; let's say a circle that appears and disappears when the
Enterkey is pressed. - A main menu that can be opened/closed using the
Escapekey, and which contains a single option that can be interacted with using theEnterkey.
In a "dumb" implementation of this system, if the same InputAction is used for toggling the circle and for activating the option in the main menu; then if the menu is open and no extra safeguard is put in place, the Enter key would both toggle the circle and activate the menu option.
Now let's configure 2 layers using InputLayers:
-
Base, the layer we use for our base interactions (here, toggling the circle and opening the menu). -
Popup, the layer that will handle inputs for when the menu is open.
Since LayeredActions are only active when their corresponding layer is active (on top of the stack), we simply have to:
- Start with the Base layer active (using the
Start()method somewhere in our code). - Have the actions to open/close our menu respectively enable/disable our
Popuplayer. - Handle toggling the circle using the
Baselayer. - Handle activating the menu option using the
Popuplayer. - Make sure that the action to open/close the menu exists both in the
BaseandPopuplayers, so it can be both opened and closed.
This will ensure that pressing the Enter key will only affect the systems relevant to the system/UI that is currently visible on screen.
Suppose Gameplay and Inventory are in priority 0, and Pause is in priority 1:
- Activate
Gameplaywhen the game begins. - Activate
Inventorywhen its panel opens. It coversGameplaybecause it was activated later in the same priority. - Activate
Pausewhen pausing. It covers both lower-priority layers, even if one is activated again afterward. - Deactivate
Pausewhen resuming. The top enabled layer in priority0takes over. - Deactivate
Inventorywhen closing it to return input toGameplay.
Closing a panel does not deactivate a layer by itself. Connect panel visibility changes to the corresponding Activate() and Deactivate() calls.
If you have any questions or need help understanding these core concepts, feel free to start a discussion.
InputLayers is designed to work great whether you prefer using C# directly, or using the unity inspector.
I will go over the basic components of using InputLayers in both scenarios. But first, here is some basic info about how you can configure InputLayers:
InputLayers is based around Priorities and Layers.
In order to create and configure these, an editor window is made available in the Unity menu:
You can open this window using the Window/UI/InputLayers dropdown menu at the top of Unity.
For more information about using and configuring this window, check out the Getting Started guide.
Though InputLayers may be better suited as a C# tool for your code, it can also be entirely used within the Unity Inspector.
This means you can control layers and register layered inputs directly from within the Unity Editor window. Two scripts are made available for this purpose:
This script controls a selected layer. It can activate it in Start() and deactivate it in OnDestroy(), or you can call Activate() and Deactivate() from code or a UnityEvent🔗.
This script exposes a LayeredAction and a UnityEvent in the Inspector.
It lets you assign an InputAction to a layer. Its toggles can activate the layer in Awake(), enable the input in Start(), and clean up in OnDestroy(). Manual methods are also available:
ActivateLayer()DeactivateLayer()Enable()Disable()-
DisableActionMap()(Removes this wrapper's map registration; disables the map only after its last registration is removed.)
Hiding or disabling a GameObject does not automatically deactivate its layer. Call DeactivateLayer() when closing a panel if the object is not destroyed.
When using InputLayers through code directly, you will mainly be dealing with two elements:
By including a serialized LayeredAction field your scripts, the Inspector will expose some dropdowns allowing you to assign a Unity InputAction🔗 to a specific Layer.
This will allow you to manage both your InputAction directly, and control the associated layer using the LayeredAction's public _layer field.
When multiple LayeredActions share a layer, one owner should activate/deactivate it using an instance, such as
_confirmAction._layer.Activate()and_confirmAction._layer.Deactivate().
Use Enable() and Disable(), usually in Start() and OnDestroy(), to register/unregister InputAction callbacks. Unlike the component's Enable(), a plain LayeredAction.Enable() does not enable the underlying input unless you pass enableMap: true or enableAction: true.
Subscribe to onPerformedEvent, onStartedEvent, or onCanceledEvent with Subscribe(callback, false) and dispose the returned token during cleanup. These are BindableActions, not C# events. See Unity's action callbacks for the phase differences.
This allows you to run some code when the action is performed AND the layer it is assigned to is currently active.
For analog values, use LayeredAction_Float, LayeredAction_Vector2, or LayeredAction_Vector3. They notify on each selected update tick while input is non-default, and once with the default value when that loop detects input stopping. See stateful polling behavior.
This singleton ScriptableObject stores InputLayers configuration and runtime state. You can use it to:
- React to events such as
r_onActiveLayerChangedorr_onCurrentPriorityLayerChanged. - Access core systems such as the
r_prioritieslist which contains the hierarchy of priorities/layers defined in the main InputLayers configuration window. - Check what layers/priorities are currently active using
r_activeLayerandr_activePriorityLayer.
Note: Members starting with
r_are static (for example,IL_ScriptableRefs.r_activeLayer). Instance methods useInstance, as inIL_ScriptableRefs.Instance.GetLayerByName("Base"). The editor-onlyGetLayerNames()method is also static despite having nor_prefix.
The steps on how to install InputLayers.
Covers all the basic ways to use InputLayers.
Describes some of the underlying systems used by InputLayers that you may wish to make use of.
Core InputLayers scripts are stored under Assets/Lowry/UI/InputLayers/_Scripts/, including its Stateful and ScriptableObjects subfolders:
All other included files are dependencies, custom editor displays, and tools used for the sample scenes that you are unlikely to need to interact with directly.
👉🏻 Download InputLayers on the Unity Asset Store!