Skip to main content
Version: Next (dev)

Game UI Touch Controls

Game UI has two elements for on-screen controls on phones and tablets: the Touch Joystick, a thumb stick, and the Touch Button. They do not call gameplay code themselves. Instead they drive input slots, exactly like a gamepad stick or button, so your existing input actions and input configuration work with them unchanged.

Game UI shows UI Document assets through a UI Canvas component. Touch controls are elements of a UI Document like any other: you place them on the canvas, give them a rect and a look, and the canvas handles the fingers.

Adding touch controls​

  1. Open the UI Document that holds your HUD.
  2. Add a Touch Joystick or Touch Button from the palette's Touch Controls group, or with Add Touch Joystick / Add Touch Button in the hierarchy's add menu.
  3. Size and anchor its rect. For a joystick the rect is the touch zone: a finger that lands anywhere inside it takes the stick. Make the zone generously large, for example the lower-left quarter of the screen.
  4. Pick the input slot it drives (Output for a joystick, Input Slot for a button).
  5. Bind that slot to an action in your input configuration or action map.

Touch Joystick​

A finger that goes down in the zone owns the stick until it lifts. The knob follows the finger up to Radius pixels from the centre. The stick value is 0 inside the dead zone and grows to 1 at the radius. On release the stick returns to the centre and reads 0.

PropertyDefaultDescription
VisibilityTouch Devices OnlyWhen the control shows. See Visibility.
OutputTouch Left StickThe input slots the stick drives. See the table below.
FloatingoffOff: the stick is centred in its zone. On: the stick centres where the finger lands (kept far enough from the zone's edges that the base fits).
Radius80 pxHow far the knob travels from the centre. Full deflection is reached here. The base is drawn Radius × 2 wide.
Dead Zone0.15Fraction of the radius that reads as 0.
Knob Size72 pxSize of the knob.
Idle Opacity0.5Opacity of the whole control while no finger holds it.
Knob Colorlight greyColour of the knob.
Knob TexturenoneOptional texture for the knob.
Value BindingemptyOptional blackboard entry that gets the stick value every frame as a Vec2 (x right, y up, length 0 to 1).

The base draws with the element's own brush (colour, texture, border, style). With solid brushes, base and knob are drawn round.

OutputInput slots
Touch Left Sticktouch_stick_left_negx, touch_stick_left_posx, touch_stick_left_negy, touch_stick_left_posy
Touch Right Sticktouch_stick_right_negx, touch_stick_right_posx, touch_stick_right_negy, touch_stick_right_posy
Gamepad Left StickThe left stick of controller 0, so existing gamepad bindings work as they are.
Gamepad Right StickThe right stick of controller 0.

Use the Gamepad outputs to make a touch stick behave like a controller without touching the input configuration. Use the Touch outputs when touch and gamepad need separate bindings, for example a different sensitivity.

Touch Button​

A Touch Button is a Game UI button that also holds an input slot down. The slot is down while the finger that went down on the button stays down, also when the finger slides off the button. The button's click event and click binding fire when the finger goes down.

PropertyDefaultDescription
VisibilityTouch Devices OnlyWhen the control shows.
Input Slottouch_button_0The slot the button holds down. touch_button_0 to touch_button_9 exist for touch controls, and any other slot name works too, for example controller0_button_a.

While the button's disabled binding is true, it takes no fingers.

Multi-touch​

Every finger belongs to the control it went down on until it lifts:

  • Several fingers can hold several sticks and buttons at once, for example moving with the left stick while holding a fire button.
  • A finger never presses a second control by sliding onto it.
  • A finger that went down outside every touch control never presses one. It is handed to the rest of the UI instead: on a device without a mouse, the first such finger acts as the mouse pointer for buttons, sliders and lists.

Visibility​

VisibilityShows
AlwaysAlways.
Touch Devices OnlyOn devices with a touch screen. Also while the UI Document is being edited (not simulated), and when the cvar GameUi.ShowTouchControls is on.
NeverNever. Use it to switch a control off from a state or binding.

On phones with a notch, rounded corners or system bars, touch controls are moved inside the screen's safe area (and shrunk if they are larger than it), so they stay reachable. Other elements are not moved.

Testing without a touch screen​

Set the cvar GameUi.ShowTouchControls to on. Controls set to Touch Devices Only then show on a desktop too, and the mouse drives them like a single finger.

Troubleshooting​

ProblemFix
The controls do not show on the desktopExpected for Touch Devices Only. Turn on GameUi.ShowTouchControls, or set Visibility to Always.
The stick moves but the character does notBind the stick's slots (or the gamepad stick, for the Gamepad outputs) to your movement action.
The stick reacts only near its centreEnlarge the element's rect: the rect is the touch zone. Turn on Floating to let the stick start where the thumb lands.
Small movements are ignoredLower Dead Zone.
A button stays down after the finger slid awayIntended: the slot is held until that finger lifts.

See Also​