Eventos de clic

Aprende cómo gestionar los clics de usuario en tu escena.

Una scene de Decentraland puede detectar acciones de input de todos los botones que se usan para controlar el avatar del jugador. Esto incluye clics del puntero, varios botones de acción y las teclas que se usan para mover al avatar. Los eventos de botón pueden provenir de un mouse y un teclado en el cliente de escritorio, de los controles en pantalla en la app móvil, desde un controlador de VR, o desde otros dispositivos de input — el SDK interpreta todos de la misma manera.

Puedes detectar acciones de input contra una entity. Esto implica presionar un botón mientras el cursor del jugador apunta al collider de esa entity. También puedes detectar global evento de input, que implica presionar o activar el input en cualquier momento, sin tener en cuenta hacia dónde apunta el pointer.

📔 Nota: Las Entities deben tener un collider para responder a acciones de input. MeshRenderer los modelos también deben recibir un MeshCollider componente. Los modelos de un GltfContainer pueden tener su propia geometría de colisión incorporada, o se les puede configurar para usar su geometría visible; también se les puede dar un MeshCollider componente.

Hay varias formas distintas de manejar acciones de input, según el caso de uso.

• Registrar un callback: La forma más fácil de agregar interacción a una única entity. Escribe una sola instrucción para configurar una función de callback y feedback de hover.

• Basado en Systems: Ideal para manejar múltiples Entities con comportamiento similar. Usa un system para iterar sobre entities similares y consultar las acciones de input de cada una, manejándolas todas con la misma lógica. El feedback de hover debe configurarse por separado. Este enfoque también es necesario para manejar acciones de input globales.

• Avanzado: Lee los datos de respuesta sin procesar en cada entity, incluidos los sellos de tiempo y un historial de eventos de input. Esto puede ser útil para definir patrones de interacción personalizados.

Usa el Scene Editor en Creator Hub

La forma más fácil de manejar eventos de click en una entity es usar el Scene Editor. Usa la opción sin código On Click o On Input Action Triggers en un item para llamar acciones al hacer click sobre él. O usa On Global Click, On Global Primary o On Global Secondary Triggers para reaccionar a eventos de botón globales. Ver Haz cualquier item smart.

Ejemplo simple

Para detectar clics en una entity, usa pointerEventsSystem.onPointerDown.

pointerEventsSystem.onPointerDown(
	{
		entity: myEntity,
		opts: { button: InputAction.IA_PRIMARY, hoverText: 'Click' },
	},
	function () {
		console.log('clicked entity')
	}
)

Consulta Registrar un callback para más información.

Feedback de hover

Es importante hacer que los jugadores sepan que una entity es interactiva. De lo contrario, podrían perder por completo la experiencia que construiste. No es una buena experiencia hacer click en todos los objetos con la esperanza de que alguno responda.

Cuando usas el Registrar un callback método, se muestran dos tipos de feedback cada vez que el jugador pasa el cursor sobre el objeto:

• El borde de la entity se resalta (solo en el cliente de escritorio Decentraland 2.0). El resaltado es verde si la entity está lo suficientemente cerca para hacer click, rojo si la entity está demasiado lejos.

• Aparece un hint de hover cerca del cursor con texto de UI, señalando qué ocurrirá si hacen click.

Cuando se usa el Basado en Systems método, puedes lograr los mismos resultados agregando un PointerEvents componente a las entities clicables.

Tanto el resaltado de la entity como el hint de hover pueden desactivarse mediante propiedades en estos métodos y componentes.

También podrías implementar hints avanzadas personalizadas, por ejemplo podrías reproducir un sonido, hacer que la entity cambie de color, gire o aumente de tamaño mientras se le apunta, etc. Sea lo que sea que hagas, asegúrate de que sea un signo claro.

Obstáculos

Los eventos de botón lanzan rayos que solo interactúan con la primera entity en su trayectoria que esté suscrita a la collision layer de pointer events. Esto es así mientras la entity esté dentro de sus límites de distancia. Si la entity define límites de distancia tanto para la camera como para el avatar, basta con que una de las dos esté lo suficientemente cerca.

Para que un ray de un pointer event intercepte una entity, debe cumplirse una de estas condiciones:

• El modelo debe contener mallas collider.

• El GltfContainer debe configurarse para usar la geometría visible con collision masks.

• La entity debe tener un componente MeshCollider.

Si el collider de otra entity se interpone en el camino de la entity con la que el jugador quiere interactuar, el jugador no podrá hacer click en la entity que está detrás, a menos que esa entity no tenga collider, o que este collider esté configurado para no responder a la collision layer de pointer events.

// entity clicable
const clickableEntity = engine.addEntity()
MeshRenderer.setBox(clickableEntity)
MeshCollider.setBox(clickableEntity)
Transform.create(clickableEntity, { position: Vector3.create(8, 1, 8) })

pointerEventsSystem.onPointerDown(
	{
		entity: clickableEntity,
		opts: {
			button: InputAction.IA_POINTER,
			hoverText: 'Click',
		},
	},
	function () {
		console.log('clicked entity')
		const t = Transform.getMutable(clickableEntity)
		t.scale.y += 0.2
	}
)

// no bloquea clicks
const nonBlocker = engine.addEntity()
MeshRenderer.setBox(nonBlocker)
MeshCollider.setBox(nonBlocker, ColliderLayer.CL_PHYSICS)
Transform.create(nonBlocker, { position: Vector3.create(10, 1, 8) })

// bloquea clicks
const blocker = engine.addEntity()
MeshRenderer.setBox(blocker)
MeshCollider.setBox(blocker, ColliderLayer.CL_POINTER)
Transform.create(blocker, { position: Vector3.create(8, 1, 10) })

📔 Nota: Para que una entity no solo intercepte un pointer event, sino que también devuelva datos, la entity también necesita tener un PointerEvents componente. El pointerEventsSystem helpers también se encargan de este requisito.

botones de puntero

Las siguientes entradas pueden manejarse con cualquiera de los enfoques para detectar eventos de input.

• InputAction.IA_POINTER: botón izquierdo del mouse en una computadora, botón de interacción en móvil.

• InputAction.IA_PRIMARY: E tecla en una computadora, botón E en móvil.

• InputAction.IA_SECONDARY: F tecla en una computadora, botón F en móvil.

• InputAction.IA_ACTION_3: 1 tecla en una computadora, botón 1 en móvil. No es fácil de alcanzar en móvil; no se recomienda para la interacción en móvil.

• InputAction.IA_ACTION_4: 2 tecla en una computadora, botón 2 en móvil. No es fácil de alcanzar en móvil; no se recomienda para la interacción en móvil.

• InputAction.IA_ACTION_5: 3 tecla en una computadora, botón 3 en móvil. No es fácil de alcanzar en móvil; no se recomienda para la interacción en móvil.

• InputAction.IA_ACTION_6: 4 tecla en una computadora, botón 4 en móvil. No es fácil de alcanzar en móvil; no se recomienda para la interacción en móvil.

• InputAction.IA_JUMP: Space tecla en una computadora, botón de salto en móvil.

• InputAction.IA_FORWARD: W tecla en una computadora.

• InputAction.IA_LEFT: A tecla en una computadora.

• InputAction.IA_RIGHT: D tecla en una computadora.

• InputAction.IA_BACKWARD: S tecla en una computadora.

• InputAction.IA_WALK: Control tecla en una computadora.

• InputAction.IA_MODIFIER: Shift tecla en una computadora.

Cada InputAction se abstrae del input literal del teclado para que pueda mapearse a distintos inputs según el dispositivo. Por la misma razón, no todos los botones del teclado pueden rastrearse para eventos de botón, solo los botones que se usan para movimiento e interacción. Esta limitación intencional garantiza que el contenido sea compatible en desktop, el cliente móvily dispositivos futuros como controladores de VR y otros controles de juego.

📱 Móvil: En el cliente móvil, todas las acciones de input están disponibles, pero IA_ACTION_3–IA_ACTION_6 (los 1/2/3/4 botones) están escondidos detrás de un menú secundario y no son fáciles de alcanzar durante el juego. Al diseñar para móvil, prioriza IA_POINTER (botón de interacción), IA_PRIMARY (botón E), y IA_SECONDARY (botón F) para tus acciones clave. Ver Input en dispositivos móviles.

Tipos de pointer events

Cada input puede producir los siguientes tipos de pointer events. Cada uno de los siguientes es un valor en el PointerEventType enum.

• PET_DOWN: El jugador presiona un botón específico mientras el cursor apunta al collider de la entity.

• PET_UP: El jugador suelta un botón específico mientras el cursor apunta al collider de la entity.

• PET_HOVER_ENTER: El cursor del jugador empieza a apuntar al collider de la entity.

• PET_HOVER_LEAVE: El cursor del jugador deja de apuntar al collider de la entity.

• PET_PROXIMITY_ENTER: El jugador entra caminando en el rango de proximidad de la entity, sin importar hacia dónde esté mirando.

• PET_PROXIMITY_LEAVE: El jugador sale del rango de proximidad de la entity.

Consulta Eventos de proximidad para saber cómo usar interacciones basadas en proximidad.

Datos de una acción de input

Todas las acciones de input incluyen datos sobre el evento, incluyendo cosas como el botón que fue activado y hacia dónde apuntaba el pointer en ese momento.

La siguiente información puede obtenerse de cualquier evento de input:

• analog: Número opcional, solo presente en eventos de un input analógico (como un joystick), que almacena el valor analógico del input.

• button: Qué id de botón fue presionado. El número corresponde al InputAction enum, que enumera todos los botones disponibles.

• state: Tipo de pointer event, del enum PointerEventType. 0 se refiere a PointerEventType.PET_UP, 1 a PointerEventType.PET_DOWN, 2 a PointerEventType.PET_HOVER_ENTER, 3 a PointerEventType.PET_HOVER_LEAVE, 4 a PointerEventType.PET_PROXIMITY_ENTER, 5 a PointerEventType.PET_PROXIMITY_LEAVE

• timestamp: Un timestamp de Lamport para identificar cada evento de botón.

  Nota: Este timestamp no está numerado en función del tiempo actual. Piensa en él como un contador que empieza en 0 y se incrementa en 1 por cada evento.

• hit: Un objeto que contiene los siguientes datos sobre el evento de hit:

  • entityId: Número de id de la entity que fue impactada por el ray.

  • meshName: String con el nombre interno de la malla específica del modelo 3D que fue impactada. Esto es útil cuando un modelo 3D está compuesto por múltiples mallas.

  • globalOrigin: Vector3 para la posición desde donde se origina el ray (relativa a la scene)

  • direction: Vector3 con el vector de dirección del ray, en coordenadas globales

  • position: Vector3 para la posición donde el ray intersectó con la entity impactada (relativa a la scene)

  • length: Longitud del ray desde su origen hasta la posición donde ocurrió el hit contra la entity.

  • normalHit: Vector3 con un vector de dirección normalizado, que describe el ángulo de la normal del hit en el espacio mundial.

Estos datos se acceden de distintas maneras según el enfoque que estés usando para manejar acciones de input.

Usando el Registrar un callback enfoque, el primer parámetro que se pasa a la función callback contiene toda esta estructura de datos.

pointerEventsSystem.onPointerDown({ entity: myEntity }, function (cmd) {
	console.log(cmd.hit?.entityId)
})

Usando el Basado en Systems enfoque, usa inputSystem.getInputCommand() para obtener estos datos.

engine.addSystem(() => {
	const cmd = inputSystem.getInputCommand(
		InputAction.IA_POINTER,
		PointerEventType.PET_DOWN,
		myEntity
	)
	if (cmd) {
		console.log(cmd.hit?.entityId)
	}
})

📔 Nota: Para que una entity no solo intercepte un pointer event, sino que también devuelva datos, la entity también necesita tener un PointerEvents componente. El pointerEventsSystem helpers también se encargan de este requisito.

Usando el Avanzado enfoque, el PointerEventsResult contiene una lista con un historial reciente de todos los pointer events contra esa entity.

engine.addSystem(() => {
	for (const [entity] of engine.getEntitiesWith(PointerEventsResult)) {
		const pointerEvents = PointerEventsResult.get(entity)

		for (const event of pointerEvents) {
			console.log(event.hit?.entityId)
		}
	}
})

Bloquear o desbloquear el cursor

💡 Nota: PointerLock es un concepto del cliente de escritorio (cursor del mouse bloqueado o desbloqueado). No tiene efecto en el app móvil, donde el input se basa en el tacto.

Los jugadores en el cliente de escritorio de Decentraland pueden alternar entre dos modos de interacción distintos con su cursor:

• Cursor bloqueado: mover el mouse desplaza la cámara y los eventos de click ocurren en la mira, en el centro de la pantalla

• Cursor desbloqueado: el cursor puede moverse libremente e independientemente de la cámara, y los jugadores pueden hacer click en cualquier parte de la pantalla para interactuar ya sea con el espacio 3D o con la UI

Estos modos de interacción son ideales para distintos tipos de mecánicas de juego, y quizá quieras hacer que los jugadores adopten uno u otro según lo que mejor se adapte a tu scene. También puede que quieras asegurar momentáneamente que el cursor del jugador esté desbloqueado para permitirle interactuar con una UI; esto es especialmente útil para jugadores nuevos que no están familiarizados con cómo se controla esto.

Para cambiar el estado del cursor del jugador, usa el PointerLock componente en la engine.CameraEntity entity.

import {PointerLock} from '@dcl/sdk/ecs'
    
PointerLock.createOrReplace(engine.CameraEntity, {isPointerLocked: false})

📔 Nota: El engine proporciona un PointerLock componente en la engine.CameraEntity por defecto. Usa createOrReplace() o getMutable() en lugar de create(), que lanza un error si el componente ya existe.

También puedes consultar el estado del cursor del jugador leyendo el PointerLock estado del componente.

import {PointerLock} from '@dcl/sdk/ecs'

const isPointerLocked = PointerLock.getOrNull(engine.CameraEntity)?.isPointerLocked

Usa la .onChange función para reaccionar a cambios en el estado del pointer. El siguiente ejemplo fuerza a que el cursor esté siempre desbloqueado.

import {PointerLock} from '@dcl/sdk/ecs'

export function main() {

    PointerLock.createOrReplace(engine.CameraEntity, {isPointerLocked: false});

    PointerLock.onChange(engine.CameraEntity, (pointerLock) => {
		    if (!pointerLock) return
		    if(pointerLock.isPointerLocked){
			    PointerLock.getMutable(engine.CameraEntity).isPointerLocked = false
		   }
	})
}