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 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.

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

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.

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 "+".

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.

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.

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:

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:

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):

TouchScreenControls.hide([InputAction.IA_SECONDARY, InputAction.IA_JUMP])

Ocultar o mostrar todos los botones — vacía el HUD o restablécelo:

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:

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	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.
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	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 (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 Los valores aquí son los mismos que se usan en todo Input en dispositivos móviles y Eventos de clic. 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

IA_ANY y IA_MODIFIER son valores meta: no se asignan a un botón y no pueden usarse aquí.

Ejemplo

Para ocultar el joystick, ocultar los botones numerados y darle al botón central jump un icono personalizado incluido en tu escena:

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' } } },
			},
		],
	})
}

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.

Relacionado

• Vinculación de entrada de UI

• Input en dispositivos móviles

• Eventos de clic

• Detecta la plataforma desde el código