Input

Important Notes

• Input is not included with YUI, so you will need to download that and add it to your project first.
• YUI is designed to be compatible with Input 6.1.5 and future 6.x.x versions. It may also be compatible with prior 6.x.x versions.
• You should be generally familiar with how Input works before using this feature!

Summary

Support for Input comes in two parts:

1. Macros configure YUI's input support, such as which Input verbs to use for UI navigation
2. Enabling (and disabling) the navigation behavior at runtime in your game

In order to get gamepad navigation support, you will at minimum need to set the YUI_INPUT_LIB_ENABLED to true and

Macro Configuration

Once you have Input added to your project, you can configure YUI's support via the macros defined in the __YuiConfiguration__ script file in your project.

Enabling Input Support

// macro to control whether YUI should attempt to use Input 6 library for navigation and interaction
#macro YUI_INPUT_LIB_ENABLED false

This is the main macro that controls Input support. By default it will be false and YUI will not attempt to enable Input for UI navigation.

Once you set it to true, YUI will attempt to use Input to check for bindings as described in the macros below.

NOTE: Make sure you actually have Input added to your project before you turn this on!

Quick Setup Mode

// whether to use Quick Setup mode
// Automatically configures some verbs to work properly with the default profiles in __input_config_verbs
#macro YUI_INPUT_LIB_QUICK_SETUP true

Quick setup mode adds additional verb bindings to the default profiles to allow the keyboard_and_mouse and gamepad profiles so that they can support equivalent features (mainly for scrolling)

Directional navigation

// Map input verbs to YUI navigation actions
// The default values here match the default values in __input_config_verbs
#macro YUI_INPUT_VERB_LEFT "left"
#macro YUI_INPUT_VERB_RIGHT "right"
#macro YUI_INPUT_VERB_UP "up"
#macro YUI_INPUT_VERB_DOWN "down"

These macros configure the verbs YUI will use to check for directional navigation, which is what moves the current focus in the UI (e.g as which button will be activated)

Cursor-scoped Scrolling

// these are used for cursor-scoped scrolling (the thing being hovered)
// mouse/virtual cursor
#macro YUI_INPUT_VERB_SCROLL_UP "scroll_up"
#macro YUI_INPUT_VERB_SCROLL_DOWN "scroll_down"
#macro YUI_INPUT_VERB_SCROLL_LEFT "scroll_left"
#macro YUI_INPUT_VERB_SCROLL_RIGHT "scroll_right"

(These aren't currently used)

Focus-scoped Scrolling

// these are used for focus-scoped scrolling (the thing that is focused)
// keyboard/gamepad
#macro YUI_INPUT_VERB_PAD_SCROLL_UP "aim_up"
#macro YUI_INPUT_VERB_PAD_SCROLL_DOWN "aim_down"
#macro YUI_INPUT_VERB_PAD_SCROLL_LEFT "aim_left"
#macro YUI_INPUT_VERB_PAD_SCROLL_RIGHT "aim_right"

These macros configure the verbs YUI will use to check for scrolling the currently focused item. By default, __input_config_verbs binds these to the gamepad's right stick, which is one of the common ways gamepad scrolling support is set up in games.

NOTE: Left/Right scrolling is not currently connected but will be added in the future.

Quick Setup Mode (described above) will add bindings to the keyboard_and_mouse profile so that the Page Up and Page Down keys can also scroll the focused item.

Activate/Cancel

#macro YUI_INPUT_VERB_ACCEPT ["accept", "action"]
#macro YUI_INPUT_VERB_CANCEL "cancel"

• YUI_INPUT_VERB_ACCEPT controls which verb or verbs 'activate' the currently focused item. This is the equivalent of clicking the element with your mouse, such as clicking a button.
• YUI_INPUT_VERB_CANCEL doesn't do anything yet but is included for future features.

Runtime Control

Managing player input logic can be complicated, so YUI allows you to turn the Input support on and off at runtime.

By default it will be off until you manually turn it on:

YuiCursorManager.is_navigation_active = true;

Once this is enabled, YUI will use Input as you've configured it in the macros section above.

You may want to leave this on permanently depending on your project, but if you find that the UI navigation is conflicting with other logic at certain points you can then turn it back off:

YuiCursorManager.is_navigation_active = false;