diff --git a/creator/SUMMARY.md b/creator/SUMMARY.md index d019510..24494df 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/control-ordering.jpg b/creator/images/touch-controls/control-ordering.jpg new file mode 100644 index 0000000..67ed40e Binary files /dev/null and b/creator/images/touch-controls/control-ordering.jpg differ diff --git a/creator/images/touch-controls/custom-main-action.jpg b/creator/images/touch-controls/custom-main-action.jpg new file mode 100644 index 0000000..766350d Binary files /dev/null and b/creator/images/touch-controls/custom-main-action.jpg differ diff --git a/creator/images/touch-controls/touch-controls-default.jpg b/creator/images/touch-controls/touch-controls-default.jpg new file mode 100644 index 0000000..0a69ce0 Binary files /dev/null and b/creator/images/touch-controls/touch-controls-default.jpg differ diff --git a/creator/images/touch-controls/ui-input-binding.jpg b/creator/images/touch-controls/ui-input-binding.jpg new file mode 100644 index 0000000..0d29b83 Binary files /dev/null and b/creator/images/touch-controls/ui-input-binding.jpg differ diff --git a/creator/sdk7/2d-ui/onscreen-ui.md b/creator/sdk7/2d-ui/onscreen-ui.md index bc74a07..36324a8 100644 --- a/creator/sdk7/2d-ui/onscreen-ui.md +++ b/creator/sdk7/2d-ui/onscreen-ui.md @@ -117,6 +117,7 @@ The following components are available to use in a `UiEntity`: * `uiBackground` * `uiText` * `onClick` +* [`uiInputBinding`](ui_input_binding.md) — hold input actions while the element is pressed, to build custom controls Like with HTML tags, you can define components as self-closing or nest one within another. 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 0000000..8d5516c --- /dev/null +++ b/creator/sdk7/2d-ui/ui_input_binding.md @@ -0,0 +1,75 @@ +--- +description: Bind input actions to your own UI elements so they drive player input. +--- + +# UI Input Binding + +`UiInputBinding` turns any UI element into a control button. Bind an element to one or more [`InputAction`](../interactivity/button-events/click-events.md#pointer-buttons)s, and while it's pressed — by touch or pointer — those actions are held down, driving both the local player's input (movement, jumping) and any scene [`InputAction`](../interactivity/button-events/click-events.md#pointer-buttons) listeners, exactly like the native on-screen buttons. + +Use it to build your own touch controls. It's typically paired with [On-screen Controls](../interactivity/touch-screen-controls.md): hide the native buttons, then put your own in their place. + +
A retro-style gamepad assembled from custom UI elements, each wired to an input action

A fully custom gamepad built from UI elements — each button is a UI entity bound to an input action

+ +## Bind an action to a UI element + +Add a `uiInputBinding` prop to any element in your `.tsx` UI and list the actions to hold while it's pressed. The prop is available on every UI element ([`UiEntity`](onscreen-ui.md#ui-entities), [`Button`](onscreen-ui.md#ui-entities), [`Label`](onscreen-ui.md#ui-entities), …), just like `uiTransform` and `uiBackground`. + +**A button that moves the player forward while held:** + +```tsx +import { InputAction } from '@dcl/sdk/ecs' +import { Button } from '@dcl/sdk/react-ecs' + +export const forwardButton = () => ( +