From 42a007ea0a8650d72ae06cb8fbba17a1fd96a0de Mon Sep 17 00:00:00 2001 From: Eibriel Date: Mon, 6 Jul 2026 17:31:28 -0300 Subject: [PATCH 01/10] controls customization --- creator/SUMMARY.md | 2 + .../touch-controls/custom-main-action.svg | 6 + .../images/touch-controls/hide-joystick.svg | 6 + .../touch-controls/touch-controls-default.svg | 6 + .../touch-controls/ui-input-binding.svg | 6 + creator/sdk7/2d-ui/ui_input_binding.md | 80 +++++++++++++ .../building-for-mobile/input-on-mobile.md | 6 + .../interactivity/touch-screen-controls.md | 111 ++++++++++++++++++ 8 files changed, 223 insertions(+) create mode 100644 creator/images/touch-controls/custom-main-action.svg create mode 100644 creator/images/touch-controls/hide-joystick.svg create mode 100644 creator/images/touch-controls/touch-controls-default.svg create mode 100644 creator/images/touch-controls/ui-input-binding.svg create mode 100644 creator/sdk7/2d-ui/ui_input_binding.md create mode 100644 creator/sdk7/interactivity/touch-screen-controls.md diff --git a/creator/SUMMARY.md b/creator/SUMMARY.md index d019510e..24494dfe 100644 --- a/creator/SUMMARY.md +++ b/creator/SUMMARY.md @@ -150,12 +150,14 @@ * [Raycasting](sdk7/interactivity/raycasting.md) * [Runtime Data](sdk7/interactivity/runtime-data.md) * [Skybox Control](sdk7/interactivity/skybox-control.md) + * [On-screen Controls](sdk7/interactivity/touch-screen-controls.md) * [User Data](sdk7/interactivity/user-data.md) * [2D UI](sdk7/2d-ui/) * [Onscreen UI](sdk7/2d-ui/onscreen-ui.md) * [UI Positioning](sdk7/2d-ui/ui-positioning.md) * [UI Background](sdk7/2d-ui/ui_background.md) * [UI Button Events](sdk7/2d-ui/ui_button_events.md) + * [UI Input Binding](sdk7/2d-ui/ui_input_binding.md) * [UI Special Types](sdk7/2d-ui/ui_special_types.md) * [UI Text](sdk7/2d-ui/ui_text.md) * [Dynamic UI](sdk7/2d-ui/dynamic-ui.md) diff --git a/creator/images/touch-controls/custom-main-action.svg b/creator/images/touch-controls/custom-main-action.svg new file mode 100644 index 00000000..cc3d10cd --- /dev/null +++ b/creator/images/touch-controls/custom-main-action.svg @@ -0,0 +1,6 @@ + + + SCREENSHOT PLACEHOLDER + Central button with a custom icon and action + Replace with a real screenshot + diff --git a/creator/images/touch-controls/hide-joystick.svg b/creator/images/touch-controls/hide-joystick.svg new file mode 100644 index 00000000..efccf2b6 --- /dev/null +++ b/creator/images/touch-controls/hide-joystick.svg @@ -0,0 +1,6 @@ + + + SCREENSHOT PLACEHOLDER + Controls with the native joystick hidden + Replace with a real screenshot + diff --git a/creator/images/touch-controls/touch-controls-default.svg b/creator/images/touch-controls/touch-controls-default.svg new file mode 100644 index 00000000..aca934e6 --- /dev/null +++ b/creator/images/touch-controls/touch-controls-default.svg @@ -0,0 +1,6 @@ + + + SCREENSHOT PLACEHOLDER + Default on-screen controls (joystick + gamepad) + Replace with a real screenshot + diff --git a/creator/images/touch-controls/ui-input-binding.svg b/creator/images/touch-controls/ui-input-binding.svg new file mode 100644 index 00000000..e2fdfd41 --- /dev/null +++ b/creator/images/touch-controls/ui-input-binding.svg @@ -0,0 +1,6 @@ + + + SCREENSHOT PLACEHOLDER + Custom UI button bound to an input action + Replace with a real screenshot + diff --git a/creator/sdk7/2d-ui/ui_input_binding.md b/creator/sdk7/2d-ui/ui_input_binding.md new file mode 100644 index 00000000..3c3e93f1 --- /dev/null +++ b/creator/sdk7/2d-ui/ui_input_binding.md @@ -0,0 +1,80 @@ +--- +description: Bind input actions to your own UI elements so they drive player input. +--- + +# UI Input Binding + +The `UiInputBinding` component binds a UI entity to one or more `InputAction`s. While that element is pressed — by touch or pointer — the listed actions are held down, driving both the local player's input (movement, jumping) and any scene `InputAction` listeners, exactly like the native on-screen buttons. + +This lets you build your own touch controls out of UI elements. It's typically combined with [On-screen Controls](../interactivity/touch-screen-controls.md): hide the native buttons, then provide your own. + +{% hint style="info" %} +**📔 Note**: The screenshot on this page is a placeholder and will be replaced with a real capture. +{% endhint %} + +![Custom UI button bound to an input action](../images/touch-controls/ui-input-binding.svg) + +## Usage + +Add a `uiInputBinding` prop to any UI element in your `.tsx` UI, listing the actions to hold down while the element is pressed: + +```tsx +import { InputAction } from '@dcl/sdk/ecs' +import { Button } from '@dcl/sdk/react-ecs' + +// A custom on-screen button that moves the player forward while held +export const forwardButton = () => ( +