> For the complete documentation index, see [llms.txt](https://docs.decentraland.org/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.decentraland.org/creator/content-creator-es/scenes-sdk7/interactividad/touch-screen-controls.md). # On-screen Controls Configura los controles táctiles nativos en pantalla para tu scene. En el cliente móvil, los jugadores interactúan con tu escena a través de un conjunto de controles nativos en pantalla: un joystick virtual, una mira y un gamepad de botones. El `TouchScreenControls` componente permite que tu escena reconfigure ese HUD: despejarlo, ocultar el joystick o la mira, cambiar lo que hace el botón central grande, reemplazar el glifo de un botón por tu propio icono, u ocultar los botones por completo y sustituirlos por tu propia UI.
The default mobile HUD: virtual joystick on the left, gamepad buttons on the right

Los controles predeterminados en pantalla, antes de cualquier personalización

{% hint style="info" %} El componente se aplica automáticamente mientras el jugador está dentro de tu escena y vuelve a los valores predeterminados (nada oculto, jump como botón central) en el momento en que salen; así que las escenas que no lo usan no se ven afectadas. Solo afecta a las plataformas con controles nativos en pantalla: en escritorio no hace nada y no tiene efecto en VR. {% endhint %} ## Cómo funciona el diseño de los botones Los botones del gamepad forman una única **pila de prioridad**. El orden es fijo: 1. `IA_JUMP` 2. `IA_POINTER` 3. `IA_PRIMARY` (E) 4. `IA_SECONDARY` (F) 5. `IA_ACTION_3` (1) 6. `IA_ACTION_4` (2) 7. `IA_ACTION_5` (3) 8. `IA_ACTION_6` (4) Las posiciones en pantalla también son fijas. Los **visibles** botones llenan esas posiciones de arriba de la pila hacia abajo, así que lo que cambias es *qué* botones están visibles y *cuál va primero*, no su orden. | Cuando tú… | Los controles… | | ------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Ocultar un botón** (cualquier botón, incluido jump) | Cada botón de menor prioridad sube para llenar el hueco. Oculta jump y `IA_POINTER` ocupa el lugar central. | | **Dejar la pila como está** | El primer botón (`IA_JUMP`) | | **Definir un botón principal** con `mainAction` | Esa acción pasa al frente y se convierte en el botón central; cada otro botón mantiene su orden normal. | | **Definir un botón principal que también esté oculto** | Ocultar prevalece: el botón sigue oculto. | | **Dejar visibles 5 o menos botones** | Todos se muestran directamente (el botón central más hasta cuatro alrededor); no hay menú "+". | | **Dejar visibles más de 5 botones** | El "+" ocupa el último espacio, así que cuatro se muestran directamente (el botón central más tres) y el resto queda detrás del alternador de desbordamiento "+". |
Three HUDs showing the gamepad reflowing as the number of visible buttons changes

Cómo se redistribuyen los botones según la cantidad visible. Izquierda (7 botones): el botón principal, un arco de 1–3 y el "+" que contiene el desbordamiento (4–7) en una columna que asciende. Centro (5 botones): el mismo arco, con una columna de desbordamiento más corta (4–5) detrás del "+". Derecha (4 botones): los cuatro se muestran directamente y el "+" desaparece.

{% hint style="info" %} Así también puedes mostrar los `1`/`2`/`3`/`4` botones, que de otro modo quedan ocultos detrás del "+": oculta suficientes botones de mayor prioridad para reducir la cantidad visible a cinco o menos, y se mostrarán directamente. {% endhint %} ## Tareas comunes `TouchScreenControls` incluye un conjunto de helpers de conveniencia. Cada uno escribe el componente en el RootEntity de la escena (donde el cliente lo lee) y lo combina con el valor actual, así que puedes llamarlos desde cualquier lugar. `RootEntity` (donde el cliente lo lee) **Cambiar el botón principal** — haz que el botón central grande active una acción diferente: ```ts import { TouchScreenControls, InputAction } from '@dcl/sdk/ecs' export function main() { TouchScreenControls.setMainAction(InputAction.IA_PRIMARY) } ``` **Ocultar el joystick o la mira** — elimina el stick de movimiento y/o la retícula de apuntado, y vuélvelos a mostrar con sus `mostrar` equivalentes: ```ts TouchScreenControls.hideJoystick() TouchScreenControls.hideCrosshair() // y para volver a mostrarlos: TouchScreenControls.showJoystick() TouchScreenControls.showCrosshair() ``` **Ocultar botones específicos** — pasa las acciones que quieras quitar (el resto sube en cascada): ```ts TouchScreenControls.hide([InputAction.IA_SECONDARY, InputAction.IA_JUMP]) ``` **Ocultar o mostrar todos los botones** — vacía el HUD o restablécelo: ```ts TouchScreenControls.hideAll() TouchScreenControls.showAll() ``` `showAll()` solo afecta a los botones del gamepad — no restaura un joystick o una mira ocultos. Usa `showJoystick()` / `showCrosshair()` para eso. **Reemplazar el icono de un botón** — para tener control total (iconos personalizados, varios cambios a la vez), escribe el componente sin procesar en `engine.RootEntity`: ```ts import { engine, TouchScreenControls, InputAction } from '@dcl/sdk/ecs' export function main() { TouchScreenControls.createOrReplace(engine.RootEntity, { hideCrosshair: true, mainAction: InputAction.IA_PRIMARY, touchInputs: [ { inputAction: InputAction.IA_PRIMARY, icon: { tex: { $case: 'texture', texture: { src: 'images/grab.png' } } }, }, ], }) } ``` Los helpers de un vistazo: | Helper | Qué hace | | ----------------------- | --------------------------------------------------------------------------------------------------------------- | | `setMainAction(action)` | Establece qué acción activa el botón central grande. | | `hideJoystick()` | Oculta el joystick virtual nativo. | | `showJoystick()` | Muestra de nuevo el joystick virtual nativo. | | `hideCrosshair()` | Oculta la mira / retícula en pantalla. | | `showCrosshair()` | Muestra de nuevo la mira / retícula en pantalla. | | `hide(actions)` | Oculta los botones del gamepad indicados (se combinan con la configuración actual). | | `hideAll()` | Oculta todos los botones del gamepad. | | `showAll()` | Muestra todos los botones del gamepad (borra la lista de botones ocultos). Hace **no** afecta al joystick/mira. | ## Propiedades Escríbelos directamente cuando uses `createOrReplace`: | Propiedad | Tipo | Descripción | | --------------- | --------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `hideJoystick` | *boolean* | Oculta el joystick virtual nativo de movimiento. | | `hideCrosshair` | *boolean* | Oculta la mira / retícula en pantalla. | | `mainAction` | [*InputAction*](/creator/content-creator-es/scenes-sdk7/interactividad/button-events/click-events.md#pointer-buttons) | Desplaza esta acción al frente de la pila, convirtiéndola en el botón central grande; los demás botones mantienen su orden. Solo son válidas las acciones del gamepad (ver abajo). Cuando no se define, el primer botón visible (`IA_JUMP` por defecto) va primero. Consulta [Cómo funciona el diseño de los botones](#how-the-button-layout-works). | | `touchInputs` | *array* | Anulaciones por botón. Un botón que no aparece en la lista conserva su valor predeterminado (se muestra, con su glifo predeterminado). | Cada `touchInputs` entrada tiene: | Campo | Tipo | Descripción | | ------------- | --------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `inputAction` | [*InputAction*](/creator/content-creator-es/scenes-sdk7/interactividad/button-events/click-events.md#pointer-buttons) | Qué botón en pantalla configura esta entrada. | | `hide` | *boolean* | Oculta este botón. El valor predeterminado es `false` (visible). Cualquier botón puede ocultarse, **incluido `IA_JUMP`** — el resto sube en cascada para ocupar su lugar. | | `icon` | [*TextureUnion*](/creator/content-creator-es/scenes-sdk7/2d-ui/ui_background.md#background) (opcional) | Reemplaza el glifo del botón con una imagen de la escena. Usa la `variante texture con un src asignado al contenido (una imagen incluida en tu escena) —` texture `src` (una imagen incluida en tu escena) — `{ tex: { $case: 'texture', texture: { src: 'images/grab.png' } } }`. Solo se admiten rutas de contenido de la escena (no URLs externas ni texturas de avatar o video). En el botón jump, esto reemplaza todos sus estados dinámicos (jump / double-jump / glide). Si la ruta no puede resolverse, se usa el glifo integrado. | ## Qué acciones se asignan a qué botones El [`InputAction`](/creator/content-creator-es/scenes-sdk7/interactividad/button-events/click-events.md#pointer-buttons) Los valores aquí son los mismos que se usan en todo [Input en dispositivos móviles](/creator/content-creator-es/crear-para-movil/desarrollar/input-on-mobile.md) y [Eventos de clic](/creator/content-creator-es/scenes-sdk7/interactividad/button-events/click-events.md). Estas son las acciones que se asignan a botones en pantalla: | InputAction | Botón en pantalla | | ------------------------------------------------------------- | ---------------------------------------- | | `IA_JUMP` | El botón central grande (predeterminado) | | `IA_POINTER` | El botón de interacción | | `IA_PRIMARY` | El botón E | | `IA_SECONDARY` | El botón F | | `IA_ACTION_3` / `IA_ACTION_4` / `IA_ACTION_5` / `IA_ACTION_6` | Los botones 1 / 2 / 3 / 4 | {% hint style="warning" %} `IA_ANY` y `IA_MODIFIER` son valores meta: no se asignan a un botón y no pueden usarse aquí. {% endhint %} ## Ejemplo Para ocultar el joystick, ocultar los botones numerados y darle al botón central jump un icono personalizado incluido en tu escena: ```ts import { engine, TouchScreenControls, InputAction } from '@dcl/sdk/ecs' export function main() { TouchScreenControls.createOrReplace(engine.RootEntity, { hideJoystick: true, touchInputs: [ { inputAction: InputAction.IA_ACTION_3, hide: true }, { inputAction: InputAction.IA_ACTION_4, hide: true }, { inputAction: InputAction.IA_ACTION_5, hide: true }, { inputAction: InputAction.IA_ACTION_6, hide: true }, { inputAction: InputAction.IA_JUMP, icon: { tex: { $case: 'texture', texture: { src: 'images/banana.png' } } }, }, ], }) } ```
A mobile HUD with the joystick hidden and the central jump button showing a custom banana icon

El resultado: el joystick desaparece, los botones numerados quedan ocultos (así que el "+" desaparece) y el botón jump recibe un nuevo icono

Para reemplazar por completo los controles nativos, ocúltalos aquí y crea tus propios botones táctiles con [Vinculación de entrada de UI](/creator/content-creator-es/scenes-sdk7/2d-ui/ui_input_binding.md). ## Relacionado * [Vinculación de entrada de UI](/creator/content-creator-es/scenes-sdk7/2d-ui/ui_input_binding.md) * [Input en dispositivos móviles](/creator/content-creator-es/crear-para-movil/desarrollar/input-on-mobile.md) * [Eventos de clic](/creator/content-creator-es/scenes-sdk7/interactividad/button-events/click-events.md) * [Detecta la plataforma desde el código](/creator/content-creator-es/crear-para-movil/desarrollar/detect-platform.md) --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.decentraland.org/creator/content-creator-es/scenes-sdk7/interactividad/touch-screen-controls.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.