> 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). # Controles en pantalla Configura los controles táctiles nativos en pantalla para tu escena. En el cliente móvil, los jugadores interactúan con tu scene 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 scene reconfigure ese HUD: simplificarlo, ocultar el joystick o la mira, cambiar lo que hace el gran botón central, sustituir el glifo de un botón por tu propio icono, u ocultar por completo los botones y reemplazarlos con tu propia UI.
The default mobile HUD: virtual joystick on the left, gamepad buttons on the right

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

{% hint style="info" %} El componente se aplica automáticamente mientras el jugador está dentro de tu scene y vuelve a los valores predeterminados (nada oculto, salto como botón central) en el momento en que sale; por lo tanto, las scenes que no lo usan no se ven afectadas. Solo afecta a las plataformas con controles nativos en pantalla: no hace nada en desktop y no tiene efecto en VR. {% endhint %} ## Cómo funciona el diseño de los botones Los botones del gamepad forman una sola **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 desde la parte superior de la pila hacia abajo, así que lo que cambias es *cuáles* botones son visibles y *cuál*lidera, no su orden. | Cuando tú… | Los controles… | | --------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Ocultar un botón** (cualquier botón, incluido salto) | Cada botón de menor prioridad sube para ocupar el hueco. Oculta salto y `IA_POINTER` ocupa el lugar central. | | **Dejar la pila intacta** | El primer botón (`IA_JUMP`) es el gran botón central; los siguientes botones llenan las ranuras que lo rodean. | | **Establecer un botón principal** con `mainAction` | Esa acción pasa al frente y se convierte en el botón central; todos los demás botones mantienen su orden normal. | | **Establecer un botón principal que también está oculto** | Ocultar gana — el botón sigue oculto. | | **Dejar visibles 5 botones o menos** | 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 la última ranura, así que cuatro se muestran directamente (el botón central más tres) y el resto queda detrás del control de desbordamiento "+". |
Three HUDs showing the gamepad reflowing as the number of visible buttons changes

Así es como se reacomodan los botones según la cantidad visible. Izquierda (7 botones): el botón principal, un arco de 1–3 y el "+" que mantiene el desbordamiento (4–7) en una columna que sube hacia arriba. 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í es también como muestras los `1`/`2`/`3`/`4` botones, que de otro modo quedarían escondidos detrás del "+": oculta suficientes botones de mayor prioridad para llevar la cantidad visible a cinco o menos, y se mostrarán directamente. {% endhint %} ## Tareas comunes `TouchScreenControls` incluye un conjunto de ayudas prácticas. Cada una escribe el componente en el `RootEntity` (donde el client lo lee) y se fusiona con el valor actual, por lo que puedes llamarlas desde cualquier lugar. **Cambiar el botón principal** — haz que el gran botón central active una acción distinta: ```ts import { TouchScreenControls, InputAction } from '@dcl/sdk/ecs' export function main() { TouchScreenControls.setMainAction(InputAction.IA_PRIMARY) } ``` **Ocultar el joystick o la mira** — quita el joystick de movimiento y/o la mira de apuntado, y tráelos de vuelta con sus `mostrar` contrapartes: ```ts TouchScreenControls.hideJoystick() TouchScreenControls.hideCrosshair() // y para volver a mostrarlos: TouchScreenControls.showJoystick() TouchScreenControls.showCrosshair() ``` **Ocultar botones específicos** — pasa las acciones que quieres eliminar (el resto se desplaza hacia arriba): ```ts TouchScreenControls.hide([InputAction.IA_SECONDARY, InputAction.IA_JUMP]) ``` **Ocultar o mostrar todos los botones** — limpia 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' } } }, }, ], }) } ``` Las ayudas de un vistazo: | Ayuda | Qué hace | | ----------------------- | ------------------------------------------------------------------------------------------------------------- | | `setMainAction(action)` | Define qué acción activa el gran botón central. | | `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 dados (se fusiona 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). No **no** afecta al joystick/mira. | ## Propiedades Escribe estos 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/eventos-de-button/click-events.md#pointer-buttons) | Desplaza esta acción al frente de la pila, convirtiéndola en el gran botón central; los demás botones conservan 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) lidera. 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 (mostrado, con su glifo predeterminado). | Cada `touchInputs` la entrada tiene: | Campo | Tipo | Descripción | | ------------- | ------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `inputAction` | [*InputAction*](/creator/content-creator-es/scenes-sdk7/interactividad/eventos-de-button/click-events.md#pointer-buttons) | Qué botón en pantalla configura esta entrada. | | `hide` | *boolean* | Oculta este botón. El valor predeterminado es `false` (mostrado). Cualquier botón puede ocultarse, **incluyendo `IA_JUMP`** — el resto se desplaza hacia arriba para ocupar su lugar. | | `icono` | [*TextureUnion*](/creator/content-creator-es/scenes-sdk7/ui-2d/ui_background.md#background) (opcional) | Sustituye el glifo del botón por una imagen de la scene. Usa la `texture` variante con una imagen mapeada al contenido `src` (una imagen incluida en tu scene) — `{ tex: { $case: 'texture', texture: { src: 'images/grab.png' } } }`. Solo se admiten rutas de contenido de la scene (no URLs externas, avatares ni texturas de video). Para el botón de salto, esto reemplaza todos sus estados dinámicos (salto / doble salto / planeo). Si no se puede resolver la ruta, se usa el glifo integrado. | ## Qué acciones se asignan a qué botones El [`InputAction`](/creator/content-creator-es/scenes-sdk7/interactividad/eventos-de-button/click-events.md#pointer-buttons) los valores aquí son los mismos que se usan en [Entrada en móvil](/creator/content-creator-es/desarrollar-para-movil/desarrollar/input-on-mobile.md) y [Eventos de clic](/creator/content-creator-es/scenes-sdk7/interactividad/eventos-de-button/click-events.md). Estas son las acciones que se asignan a los botones en pantalla: | InputAction | Botón en pantalla | | ------------------------------------------------------------- | -------------------------------------- | | `IA_JUMP` | El gran botón central (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, apartar los botones numerados y darle al botón central de salto un icono personalizado incluido en tu scene: ```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 se ocultan (por lo que el "+" desaparece), y el botón de salto cambia de icono

Para reemplazar por completo los controles nativos, ocúltalos aquí y crea tus propios botones táctiles con [Vinculación de entrada de la UI](/creator/content-creator-es/scenes-sdk7/ui-2d/ui_input_binding.md). ## Relacionados * [Vinculación de entrada de la UI](/creator/content-creator-es/scenes-sdk7/ui-2d/ui_input_binding.md) * [Entrada en móvil](/creator/content-creator-es/desarrollar-para-movil/desarrollar/input-on-mobile.md) * [Eventos de clic](/creator/content-creator-es/scenes-sdk7/interactividad/eventos-de-button/click-events.md) * [Detecta la plataforma desde el código](/creator/content-creator-es/desarrollar-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 by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` 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 what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. 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.