Eventos de clic

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

Una escena de Decentraland puede detectar acciones de entrada de todos los botones que se usan para controlar el avatar del jugador. Estos incluyen clics del puntero, varios botones de acción y las teclas que se usan para mover el avatar. Los eventos de botones pueden provenir de un ratón, una pantalla táctil, un controlador de VR u otro dispositivo; todos son interpretados de la misma manera por el SDK.

Puedes detectar acciones de entrada contra una entidad. Esto implica presionar un botón mientras el cursor del jugador apunta al collider de esa entidad. También puedes detectar global evento de entrada, que implica activar la entrada en cualquier momento, sin considerar hacia dónde apunta el puntero.

📔 Nota: Las entidades deben tener un collider para responder a acciones de entrada. MeshRenderer a los modelos también se les debe dar un MeshCollider componente. Los modelos desde un GLTFContainer pueden tener su propia geometría de colisión embebida, o pueden configurarse para usar su geometría visible; también se les puede dar un MeshCollider componente.

Hay varias formas diferentes de manejar las acciones de entrada, dependiendo del caso de uso.

• Registrar un callback: La forma más fácil de añadir interacción a una sola entidad. Escribe una sola instrucción para configurar una función callback y retroalimentación al pasar el cursor.

• Basado en System: Ideal para manejar múltiples entidades con comportamiento similar. Usa un system para iterar sobre entidades similares y consultar acciones de entrada en cada una, manejándolas todas con la misma lógica. La retroalimentación al pasar el cursor debe configurarse por separado. Este enfoque también es requerido para manejar acciones de entrada globales.

• Avanzado: Lee los datos de respuesta crudos en cada entidad, incluyendo marcas de tiempo e historial de eventos de entrada. 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 clic en una entidad es usar el Scene Editor. Usa los Triggers sin código On Click u On Input Action en un ítem para llamar acciones al hacer clic en él. O usa On Global Click, On Global Primary u On Global Secondary Triggers para reaccionar a eventos de botones globales. Ver Haz cualquier ítem smart.

Ejemplo simple

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

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

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

Retroalimentación al pasar el cursor

Es importante hacer que los jugadores sean conscientes de que una entidad es interactiva. De lo contrario, podrían perderse por completo la experiencia que creaste. No es una buena experiencia estar haciendo clic en cada objeto con la esperanza de que uno responda.

Cuando usas el Registrar un callback método, se muestran dos tipos de retroalimentación siempre que el jugador pasa su cursor sobre el objeto:

• Se resalta el borde de la entidad (solo en el cliente Decentraland 2.0 Desktop). El resaltado es verde si la entidad está lo suficientemente cerca para hacer clic, rojo si la entidad está demasiado lejos.

• Aparece una pista de hover cerca del cursor con texto UI, indicando lo que sucederá si hacen clic.

Al usar el Basado en System método, puedes lograr los mismos resultados añadiendo un PointerEvents componente a las entidades clicables.

Tanto el resaltado de la entidad como la pista de hover pueden deshabilitarse mediante propiedades en estos métodos y componentes.

También podrías implementar pistas personalizadas avanzadas, por ejemplo podrías reproducir un sonido, hacer que la entidad cambie de color, gire o se agrande mientras se apunta a ella, etc. Hagas lo que hagas, asegúrate de que sea un indicador claro.

Obstáculos

Los eventos de botones lanzan rays que solo interactúan con la primera entidad en su trayectoria que esté suscrita a la capa de colisión de eventos del puntero. Esto es cierto siempre que la entidad esté más cerca que sus límites de distancia tanto del avatar como de la cámara.

Para que una entidad sea interceptada por el ray de un evento de puntero, ya sea:

• El modelo debe contener mallas collider.

• El GLTFContainer debe configurarse para usar la geometría visible con máscaras de colisión.

• La entidad debe tener un componente MeshCollider.

Si el collider de otra entidad está en el camino de la entidad con la que el jugador quiere interactuar, el jugador no podrá hacer clic en la entidad que está detrás, a menos que la entidad no tenga collider o que ese collider esté configurado para no responder a la capa de colisión de eventos del puntero.

// entidad 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 bloqueador para clics
const nonBlocker = engine.addEntity()
MeshRenderer.setBox(nonBlocker)
MeshCollider.setBox(nonBlocker, ColliderLayer.CL_PHYSICS)
Transform.create(nonBlocker, { position: Vector3.create(10, 1, 8) })

// bloqueador para clics
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 entidad no solo intercepte un evento de puntero, sino que también devuelva datos, la entidad además necesita tener un PointerEvents componente. Los pointerEventsSystem helpers también se encargan de este requisito.

Botones del puntero

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

• InputAction.IA_POINTER: botón izquierdo del ratón en una computadora.

• InputAction.IA_PRIMARY: tecla E en una computadora.

• InputAction.IA_SECONDARY: tecla F en una computadora.

• InputAction.IA_ACTION_3: 1 en una computadora.

• InputAction.IA_ACTION_4: 2 en una computadora.

• InputAction.IA_ACTION_5: 3 en una computadora.

• InputAction.IA_ACTION_6: 4 en una computadora.

• InputAction.IA_JUMP: Space en una computadora.

• InputAction.IA_FORWARD: W en una computadora.

• InputAction.IA_LEFT: A en una computadora.

• InputAction.IA_RIGHT: D en una computadora.

• InputAction.IA_BACKWARD: S en una computadora.

• InputAction.IA_WALK: Control en una computadora.

• InputAction.IA_MODIFIER: Shift en una computadora.

Cada InputAction está abstraído de la entrada literal del teclado para que pueda asignarse a entradas diferentes dependiendo del dispositivo. Por esta misma razón, no todas las teclas del teclado pueden rastrearse para eventos de botón, solo las teclas que se usan para movimiento e interacción. Esta limitación intencional es para asegurar que todo el contenido sea compatible en el futuro con controladores de VR, otros tipos de controladores de juego y dispositivos móviles.

Tipos de eventos de puntero

Cada entrada puede producir los siguientes tipos de eventos de puntero. Cada uno de los siguientes es un valor en el PointerEventType enum.

• DOWN: El jugador presiona una tecla específica mientras tiene el cursor apuntando al collider de la entidad.

• UP: El jugador suelta una tecla específica mientras tiene el cursor apuntando al collider de la entidad.

• HOVER_ENTER: El cursor del jugador comienza a apuntar al collider de la entidad.

• HOVER_LEAVE: El cursor del jugador deja de apuntar al collider de la entidad.

Datos de una acción de entrada

Todas las acciones de entrada incluyen datos sobre el evento, incluyendo cosas como el botón que se activó y hacia dónde apuntaba el puntero en ese momento.

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

• analog: Bandera para marcar si el evento es de una entrada analógica o digital. Las entradas digitales tienen un valor de 1, las entradas analógicas (como un joystick) tienen un valor de 0.

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

• state: Tipo de evento de puntero, del enum PointerEventType. 0 se refiere a PointerEventType.PET_DOWN, 1 a PointerEventType.PET_UP, 2 a PointerEventType.PET_HOVER_ENTER, 3 a PointerEventType.PET_HOVER_LEAVE

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

  Nota: Esta marca de tiempo no está numerada en función del tiempo actual. Piénsala como un contador que comienza en 0 y se incrementa en 1 por cada evento.

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

  • entityId: Número de id de la entidad que fue alcanzada por el rayo.

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

  • origin: Vector3 para la posición donde se origina el rayo (relativa a la escena)

  • position: Vector3 para la posición donde el rayo se intersectó con la entidad impactada (relativa a la escena)

  • length: Longitud del rayo desde su origen hasta la posición donde ocurrió el impacto contra la entidad.

  • normalHit: Quaternion para el ángulo de la normal del impacto en el espacio mundial.

A estos datos se accede de diferentes maneras dependiendo del enfoque que estés usando para manejar las acciones de entrada.

Usando el Registrar un callback enfoque, el primer parámetro pasado 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 System 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 entidad no solo intercepte un evento de puntero, sino que también devuelva datos, la entidad además necesita tener un PointerEvents componente. Los pointerEventsSystem helpers también se encargan de este requisito.

Usando el Avanzado enfoque, el PointerEventsResults contiene un array con un historial reciente de todos los eventos de puntero contra esa entidad.

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

		if (poninterEvents.commands.length > 0) {
			console.log(poninterEvents.commands[0].hit.entityId)
		}
	}
})

Bloquear o desbloquear el cursor

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 ratón desplaza la cámara y los eventos de clic ocurren en la cruz central de la pantalla; mover el ratón o el puntero directamente

• Cursor desbloqueado: el cursor es libre para moverse independientemente de la cámara, y los jugadores pueden hacer clic en cualquier parte de la pantalla para interactuar con el espacio 3D o la UI

Estos modos de interacción son ideales para diferentes tipos de mecánicas de juego, y puede que quieras que los jugadores adopten uno u otro según lo que mejor funcione en tu escena. También puede que quieras asegurar momentáneamente que el cursor del jugador esté desbloqueado para permitirles 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 entidad.

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

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

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

PointerLock.create(engine.CameraEntity)

const isPointerLocked = PointerLock.get(engine.CameraEntity).isPointerLocked

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

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

export function main() {

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

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