[AddComponentMenu("Input/On-Screen Stick")]
[HelpURL("https://docs.unity3d.com/Packages/com.unity.inputsystem@1.13/manual/OnScreen.html#on-screen-sticks")]
public class OnScreenStick : OnScreenControl, IPointerDownHandler, IPointerUpHandler, IDragHandler, IEventSystemHandler

Remarks

The OnScreenStick works by simulating events from the device specified in the controlPath property. Some parts of the Input System, such as the PlayerInput component, can be set up to auto-switch neverAutoSwitchControlSchemes to a new device when input from them is detected. When a device is switched, any currently running inputs from the previously active device are cancelled. In the case of OnScreenStick, this can mean that the UnityEngine.EventSystems.IPointerUpHandler.OnPointerUp(UnityEngine.EventSystems.PointerEventData) method will be called and the stick will jump back to center, even though the pointer input has not physically been released.

To avoid this situation, set the useIsolatedInputActions property to true. This will create a set of local Input Actions to drive the stick that are not cancelled when device switching occurs. You might also need to ensure, depending on your case, that the Mouse, Pen, Touchsceen and/or XRController devices are not used in a concurent control schemes of the simulated device.

Properties

behaviour

Defines how the onscreen stick will move relative to it's origin and the press position.

Declaration

public OnScreenStick.Behaviour behaviour { get; set; }

Property Value

Type	Description
OnScreenStick.Behaviour

controlPathInternal

Accessor for the controlPath of the component. Must be implemented by subclasses.

Declaration

protected override string controlPathInternal { get; set; }

Property Value

Type	Description
string

Overrides

OnScreenControl.controlPathInternal

Remarks

Moving the definition of how the control path is stored into subclasses allows them to apply their own InputControlAttribute attributes to them and thus set their own layout filters.

dynamicOriginRange

Defines the circular region where the onscreen control may have it's origin placed.

Declaration

public float dynamicOriginRange { get; set; }

Property Value

Type	Description
float

Remarks

This only applies if behaviour is set to ExactPositionWithDynamicOrigin. When the first press is within this region, then the control will appear at that position and have it's origin of motion placed there. Otherwise, if pressed outside of this region the control will ignore it. This property defines the radius of the circular region. The center point being defined by the component position in the scene.

movementRange

The distance from the onscreen control's center of origin, around which the control can move.

Declaration

public float movementRange { get; set; }

Property Value

Type	Description
float

useIsolatedInputActions

Prevents stick interactions from getting cancelled due to device switching.

Declaration

public bool useIsolatedInputActions { get; set; }

Property Value

Type	Description
bool

Remarks

This property is useful for scenarios where the active device switches automatically based on the most recently actuated device. A common situation where this happens is when using a PlayerInput component with Auto-switch set to true. Imagine a mobile game where an on-screen stick simulates the left stick of a gamepad device. When the on-screen stick is moved, the Input System will see an input event from a gamepad and switch the active device to it. This causes any active actions to be cancelled, including the pointer action driving the on screen stick, which results in the stick jumping back to the center as though it had been released.

In isolated mode, the actions driving the stick are not cancelled because they are unique Input Action instances that don't share state with any others.

Methods

OnDrag(PointerEventData)

Callback to handle OnDrag UI events.

Declaration

public void OnDrag(PointerEventData eventData)

Parameters

Type	Name	Description
PointerEventData	eventData

OnPointerDown(PointerEventData)

Callback to handle OnPointerDown UI events.

Declaration

public void OnPointerDown(PointerEventData eventData)

Parameters

Type	Name	Description
PointerEventData	eventData

OnPointerUp(PointerEventData)

Callback to handle OnPointerUp UI events.

Declaration

public void OnPointerUp(PointerEventData eventData)

Parameters

Type	Name	Description
PointerEventData	eventData

Implements

UnityEngine.EventSystems.IPointerDownHandler

UnityEngine.EventSystems.IPointerUpHandler

UnityEngine.EventSystems.IDragHandler

UnityEngine.EventSystems.IEventSystemHandler