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
- Open the UI Document that holds your HUD.
- 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.
- 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.
- Pick the input slot it drives (Output for a joystick, Input Slot for a button).
- 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.
| Property | Default | Description |
|---|---|---|
| Visibility | Touch Devices Only | When the control shows. See Visibility. |
| Output | Touch Left Stick | The input slots the stick drives. See the table below. |
| Floating | off | Off: 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). |
| Radius | 80 px | How far the knob travels from the centre. Full deflection is reached here. The base is drawn Radius × 2 wide. |
| Dead Zone | 0.15 | Fraction of the radius that reads as 0. |
| Knob Size | 72 px | Size of the knob. |
| Idle Opacity | 0.5 | Opacity of the whole control while no finger holds it. |
| Knob Color | light grey | Colour of the knob. |
| Knob Texture | none | Optional texture for the knob. |
| Value Binding | empty | Optional 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.
| Output | Input slots |
|---|---|
| Touch Left Stick | touch_stick_left_negx, touch_stick_left_posx, touch_stick_left_negy, touch_stick_left_posy |
| Touch Right Stick | touch_stick_right_negx, touch_stick_right_posx, touch_stick_right_negy, touch_stick_right_posy |
| Gamepad Left Stick | The left stick of controller 0, so existing gamepad bindings work as they are. |
| Gamepad Right Stick | The 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.
| Property | Default | Description |
|---|---|---|
| Visibility | Touch Devices Only | When the control shows. |
| Input Slot | touch_button_0 | The 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
| Visibility | Shows |
|---|---|
| Always | Always. |
| Touch Devices Only | On devices with a touch screen. Also while the UI Document is being edited (not simulated), and when the cvar GameUi.ShowTouchControls is on. |
| Never | Never. 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
| Problem | Fix |
|---|---|
| The controls do not show on the desktop | Expected for Touch Devices Only. Turn on GameUi.ShowTouchControls, or set Visibility to Always. |
| The stick moves but the character does not | Bind the stick's slots (or the gamepad stick, for the Gamepad outputs) to your movement action. |
| The stick reacts only near its centre | Enlarge 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 ignored | Lower Dead Zone. |
| A button stays down after the finger slid away | Intended: the slot is held until that finger lifts. |