Enable actions

Actions have an enabled state, so you can enable or disable them to suit different situations.

Project wide actions

If you use the recommended project-wide actions workflow, the Input System enables all the actions in the project wide asset, in every action map, when your app starts. In the Unity Editor, it enables them each time you enter Play mode. You don't need to enable them yourself.

The Input System enables project wide actions automatically only when both of the following are true:

Other actions

Actions defined anywhere else start in a disabled state, and you must enable them before they respond to input. This includes the following actions:

  • Actions in an action asset that you haven't assigned as project wide, such as an asset that your script references in a serialized field.
  • Actions that you create in code.

For example, enable the action map you need in your script's OnEnable method, and disable it in OnDisable.

You can enable actions individually, or as a group by enabling the action map that contains them.

// Enable a single action.
lookAction.Enable();

// Enable an entire action map.
gameplayActions.Enable();

Behavior when enabled

When you enable an action, the Input System resolves its bindings, unless it has already done so and the set of devices that the action can use hasn't changed. For more information, refer to Binding resolution.

You can't change certain aspects of the configuration, such as an action's bindings, while an action is enabled. To stop actions or action maps from responding to input, call Disable.

While an action is enabled, it monitors the controls that it's bound to. If a bound control changes state, the action processes the change. If the change represents an interaction change, the action creates a response. This processing happens during the Input System update. Depending on the update mode in the Input System settings, the update runs once every frame, once every fixed update, or only when you run it manually.

Switch between action maps

Because the Input System enables every action map in the project wide asset, actions in different maps can respond to the same input at the same time. For example, a gamepad button might trigger both a gameplay action and a UI action.

To use only one action map at a time, disable the maps you don't need, and enable the one you do. For example, when you open a menu, call InputSystem.actions.FindActionMap("Player").Disable() and InputSystem.actions.FindActionMap("UI").Enable(). When you close the menu, do the reverse.

If you use the Player Input component, call PlayerInput.SwitchCurrentActionMap to switch maps. It disables the component's current action map and enables the one you specify, but doesn't change any other action maps. If the component uses the project wide asset, disable the maps you don't need first, as described in Get started with the Player Input component.

Overlapping bindings and action priority

When several enabled actions share the same physical control, such as a B key action and a Shift+B composite action, the Input System can use either complexity-based or priority-based resolution to decide which action responds first. You configure both modes in Project Settings > Input System Package, under Improved Shortcut Support.

Each action has a Priority property, which can be from 0 to 65535. If you set a value outside this range, the Input System clamps it. A higher value means a higher priority, and the Input System notifies higher-priority actions first.

The Priority value applies to all bindings on that action. Serialized priority is always stored on the asset; at runtime it's used only when Priority Consumption is enabled. In that case, the Priority field is also shown in the Input Actions Editor.

When action priority resolution is active:

  • The Input System notifies higher-priority actions before lower-priority actions on the same control.
  • When an action reaches the Performed phase, priority 0 doesn't mark the input event as handled, so lower-priority actions in the same overlap group can still respond on that event.
  • Any priority greater than zero can mark the event as handled and suppress lower-priority actions in the same group for that event.
  • Actions with the same priority don't suppress each other. Both can perform in the same update if their bindings fire.

To set the priority in code, use the Priority property:

fireAction.Priority = 10;
reloadAction.Priority = 5;

You can also edit the Priority field on an action in the Input Actions Editor when Priority Consumption is enabled.

For information about composite shortcuts and complexity ordering, refer to Multiple input sequences (such as keyboard shortcuts).