Getting Started

✋🏻 Preamble

This guide will consider that you have just followed the Installation Guide, and understand the basic concept of what InputLayres is meant to achieve as described here.

If you encounter any issues during installation, please feel free to ask for help before proceeding with this guide.

🏗️ Configuration

Before actually implementing anything, the first step of using InputLayers should be to plan out how you wish to make use of it.

In other words: how will you configure your layers and set their priorities according to your project's specific needs?

Here is an example of how to approach this question:

1. Try to identify all the different UIs or components of your project that will need to react to user inputs.
   • The goal is to ensure that each of these components should be the only one to receive inputs at all when it is active (aka. input exclusivity).
   • In the case of UIs, this should include each popup, tab, panel, etc. as long as they are meant to receive input exclusivity.
   • Other examples of components may include multiple characters that can be controlled separately, or switching between two control schemes for a given character/entity.
2. Identify which ones will need to always take precedent (or "cover up") over others.
   • These groups will become your Priorities.
   • If you are unsure whether you need to make use of priorities, do not worry; you can easily rearrange layers down the line.

Each component will then require a uniquely named Layer placed into a specific Priorities level, as explained below; but first, we must prepare actual inputs using the built-in Unity system:

Preparing ActionMaps🔗

InputLayers is designed to make use of Unity's InputSystem🔗 regardless of how you wish to configure it. However, you will still need to use it to configure the actual inputs you wish to make use of before being able to assign them to InputLayers through the built-in UI.

This system is based around creating InputActionMaps🔗 that contain your input configurations; and though there are no set rules on how to best do this, here are a few things to keep in mind about using them with InputLayers:

• InputLayers is designed to let you use a single Action🔗 for a given input, and re-use it across multiple layers.
  • So for example, if you use Enter/×/□ for your "validation" input; you can configure it as a single Action🔗 that will be used for yes/continue/confirm/next across all of your UIs.
• All Actions🔗 will automatically have their Enable() and Disable() methods called by the InputLayers system; so you will not usually be handling this manually.
• InputLayers uses Action🔗 names as a reference; so if you rename any; it may break your InputLayers configuration.
  This could lead to having to manually reassign every LayeredAction you have configured in your project.

Setting up Layers

You are now ready to start setting up your Layers and Priorities!

In order to create and configure these, an editor window is made available in the dropdown menu at the top of Unity under Window/UI/InputLayers:

This will open up the InputLayers configuration window:

Above is the default configuration for InputLayers. This configuration is designed for use in the included sample scenes. Unless you wish to explore these scenes to better understand how InputLayers can be used; you should now clear everything but the IL_ScriptableRefs reference. and start configuring your own setup:

1. In the following section, you should reference the ActionMaps🔗 that you have configured.
   
   • You may reference however many you wish.
2. In the Layers section, you should set up the number of PriorityLayers you wish to use by clicking the + button in the bottom right:
   
3. Within a given PriorityLayer, you can then add an InputLayer using the dedicated button:
   
4. Name your layer:
   
   • Important: each layer must have a unique name.

A completed setup will look something like this (but probably with many more layers):

✅ Actually Using It

InputLayers is now fully configured and ready to use. The next step is going to be setting up LayeredActions for your UIs and components so they can properly react to inputs whenever their corresponsing InputLayer is active.

There are two approaches to doing this: you can either set them up for use directly using Unity's inspector, or you can simply include LayeredActions as properties inside your own scripts.

If you are comfortable with coding, and it fits with your workflow, it may be best to go with the second option, which will make debugging significantly easier and is a bit more optimized.

– OPTION 1: Unity Inspector

This step is quite straightforward: for every button or object that you wish to trigger with inputs filtered by InputLayers, simply add the IL_LayeredAction.cs component to it.

The Layered Action section will allow you to select one of the InputActions🔗 and one of the InputLayers that you previously configured.
Whenever the InputAction🔗 is triggered, it will execute the OnEventTriggered() UnityEvent🔗 below IF the selected InputLayers is active.

For more information regarding the Action Event Type dropdown; please refer to the Unity InputSystem documentation on Action Callbacks🔗.

You will be able to control both the chosen InputLayer and InputActions🔗 either automatically when the OnStart() or OnDestroy() event methods are called using the various toggles, or manually using the following methods:

• ActivateLayer()
• DeactivateLayer()
• Enable()
• Disable()
• DisableActionMap() (The action's parent ActionMap is automatically enabled when calling Enable().)

In some cases, you may need to control layers directly instead of having to reference an IL_LayeredAction; for this, you can simply use the IL_LayerToggle.cs component (more details here).

– OPTION 2: Code

When using InputLayers through code directly, for each script in which you wish to react to inputs filtered by InputLayers, simply include a serialized LayeredAction field like so:

// Example:
[SerializeField]
private LayeredAction _confirmAction;

This will give you the following view in the inspector:

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:

The Layered Action section corresponds to the _action field, and will allow you to select one of the InputActions🔗 and one of the InputLayers that you previously configured.
Whenever the InputAction🔗 is triggered, it will execute the OnEventTriggered() UnityEvent🔗 below IF the selected InputLayers is active.

In order for the LayeredAction to function, you will need to make use of the Enable() and Disable() methods (usually in your OnStart() and OnDestroy() event methods) to activate/deactivate them.

// Example
private void Start()
{
   _confirmAction.Enable();
}
private void OnDestroy()
{
   _confirmAction.Disable();
}

With an action enabled, you can register callbacks to react to the action being pressed using the following events:

• onPerformedEvent
• onStartedEvent
• onCanceledEvent

// Example
private void Start()
{
   //...
   _confirmAction.onPerformedEvent += OnConfirmActionPressed;
}
private void OnDestroy()
{
   _confirmAction.onPerformedEvent -= OnConfirmActionPressed;
   //...
}

private void OnConfirmActionPressed(CallbackContext context)
{
   // This will execute when the action is performed.
}

For more information about this system, please refer to the Unity InputSystem documentation on Action Callbacks🔗.

With this done, your code registered to one of these events will run when the action is performed AND the layer it is assigned to is currently active.

As for activating/deactivating the InputLayer itself, the simples way is to use the LayeredAction._layer.Activate(); and LayeredAction._layer.Deactivate(); methods:

// Example
private void Start()
{
   _confirmAction.layer.Activate();
   //...
}
private void OnDestroy()
{
   //...
   _confirmAction.layer.Deactivate();
}

If you have multiple LayeredActions assigned to the same InputLayer, then you will only need to call these methods once, and not for each individual LayeredAction.

Complete Example

[SerializeField]
private LayeredAction _confirmAction;

private void Start()
{
   _confirmAction.layer.Activate();
   _confirmAction.onPerformedEvent += OnConfirmActionPressed;
   _confirmAction.Enable();
}
private void OnDestroy()
{
   _confirmAction.Disable();
   _confirmAction.onPerformedEvent -= OnConfirmActionPressed;
   _confirmAction.layer.Deactivate();
}

private void OnConfirmActionPressed(CallbackContext context)
{
   // This will execute when the action is performed.
}

Handling Clicks

In the case of UI buttons, you may also wish to handle click events through the same code as other inputs. The following methods are available to trigger the events directly:

• PerformAction()
• StartAction()
• CancelAction()

// Example
[SerializeField]
private UIElements.Button _confirmButton;

private void Start()
{
   //...
   _confirmButton.clicked += OnConfirmButtonClicked;
}
private void OnDestroy()
{
   _confirmButton.clicked -= OnConfirmButtonClicked;
   //...
}

private void OnConfirmButtonClicked()
{
   _confirmAction.PerformAction();
}

This will ensure that even click inputs will only be processed if the correct layer is active.

Checking a Layer's Status

In some cases, you may wish to check whether an Inputlayer is active before running some code. This can be achieved in 2 ways:

– Checking an action's layer status

If you have a specific LayeredAction you wish to check with, you can simply do this:

// Example
if(_confirmAction._layer._isActive)
{
   // This code will only run when the corresponding layer is active.
}

– Reacting to active layer changes

Or, you can make use of the singleton ScriptableObject🔗 IL_ScriptableRefs to execute code whenever the currently active changes using the r_onActiveLayerChanged or r_onCurrentPriorityLayerChanged events.

// Example
private void Start()
{
   IL_ScriptableRefs.r_onactivelayerchanged += OnActiveInputlayerChanged;
}
private void OnDestroy()
{
   IL_ScriptableRefs.r_onactivelayerchanged -= OnActiveInputlayerChanged;
}

private void OnActiveInputlayerChanged(IL_Layer layer)
{
   // Here, you can react to which layer has been activated.
   // Only one layer can be active at any given time; so any other layers will necessarily be inactive.
}