For the complete documentation index, see llms.txt. This page is also available as Markdown.

Movimiento del ratón

Reacciona al movimiento del ratón del jugador en tiempo real para controlar gestos de arrastre, girar objetos o dirigir cámaras personalizadas.

Tu scene puede leer el movimiento bruto del mouse del player en cada frame, y usarlo para impulsar interacciones en tiempo real: gestos de drag y swipe, girando o deslizand objects mientras el player los arrastra, o controlando una cámara personalizada como en un shooter en primera persona.

Para hacer esto, lee la screenDelta propiedad del PrimaryPointerInfo component en engine.RootEntity. Esta propiedad es un Vector2 que informa cuántos píxeles se movió el mouse desde el último frame. Los valores positivos de x significan que el mouse se movió a la derecha; los valores positivos de y significan que se movió hacia arriba, coincidiendo con el origen de la pantalla en la esquina inferior izquierda. En los frames en que el mouse no se mueve, ambos valores son 0.

import { engine, PrimaryPointerInfo } from '@dcl/sdk/ecs'

engine.addSystem(() => {
	const delta = PrimaryPointerInfo.getOrNull(engine.RootEntity)?.screenDelta
	if (!delta) return
	console.log(`mouse moved: ${delta.x}, ${delta.y}`)
})

Dado que screenDelta solo contiene el movimiento de un solo frame, léelo siempre dentro de un system, para que ningún movimiento pase desapercibido entre frames.

El movimiento del mouse mientras el cursor está bloqueado

screenDelta se comporta de manera diferente de las otras propiedades de PrimaryPointerInfo cuando el cursor está bloqueado: screenCoordinates se congela en el centro de la pantalla y worldRayDirection siempre reporta el rayo en el centro de la pantalla, pero screenDelta sigue reportando el movimiento bruto del mouse en cada frame. Esto lo convierte en la única forma de leer el movimiento del mouse mientras el cursor está bloqueado, que es exactamente lo que necesitas para controles personalizados de camera o puntería.

Arrastra para girar un objeto

El siguiente ejemplo permite al player girar un cubo arrastrando el mouse lateralmente mientras mantiene presionado el botón del puntero:

El mismo patrón funciona para cualquier interacción de drag: desliza una entity a lo largo de un riel usando delta.x como desplazamiento, recorre una animación, o detecta un swipe rápido comprobando valores de delta grandes.

Controles de cámara mouselook

Porque screenDelta sigue funcionando mientras el cursor está bloqueado, puedes usarlo para crear controles mouselook para una cámara virtual. Para hacerlo, acumula el movimiento del mouse en ángulos de yaw y pitch, y luego aplícalos a la rotación de la camera en cada frame.

En el siguiente ejemplo, el player hace clic en una caja para cambiar a una cámara virtual que puede controlar con el mouse, y presiona el botón secundario (F o clic derecho) para volver a la camera predeterminada. Mientras la cámara virtual está activa, la scene también bloquea el cursor y congela el avatar con un InputModifier, para que el player no camine sin ver mientras controla la camera.

Algunas cosas a tener en cuenta de este ejemplo:

  • El system resta delta.y del pitch, de modo que mover el mouse hacia arriba incline la camera hacia arriba. Invierte ese signo si prefieres controles verticales invertidos.

  • El pitch se limita a un rango de -85 a 85 grados, así que la camera nunca puede volcarse hacia atrás.

  • El SENSITIVITY constant expresa grados de rotación por píxel de movimiento del mouse; ajústala a tu gusto.

💡 Consejo: El player puede desbloquear el cursor en cualquier momento presionando Esc o haciendo clic derecho, lo que hace que la camera deje de responder al mouse. Siempre ofrece a los players una forma clara de salir por completo del modo de camera, como el botón secundario en el ejemplo anterior. También puedes volver a bloquear el cursor desde el código, consulta Bloquear o desbloquear el cursor.

Temas relacionados

Para leer la posición absoluta del cursor en la pantalla en lugar de su movimiento, usa la screenCoordinates propiedad del mismo component. Consulta Comprobar la posición del cursor del player.

Para averiguar qué entity está bajo el cursor, combina la worldRayDirection propiedad con un raycast. Consulta Raycasting.

💡 Consejo: Para ver ejemplos funcionales del estado del pointer, consulta la 0,5-primary-cursor-info escena de prueba, que lee PrimaryPointerInfo cada frame y alimenta worldRayDirection en un raycast; 31,20-pointer-lock-control, que solicita y libera la captura del cursor escribiendo PointerLock.isPointerLocked; y 32,20-virtual-camera-mouse-look, que muestra screenDelta que sigue reportando movimiento mientras screenCoordinates está congelado en el centro de la pantalla durante el bloqueo.

Última actualización