Movimiento del mouse

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

Tu escena puede leer el movimiento bruto del mouse del jugador en cada frame, y usarlo para impulsar interacciones en tiempo real: gestos de arrastre y deslizamiento, hacer girar o deslizar objetos mientras el jugador los arrastra, o controlar una cámara personalizada como en un shooter en primera persona.

Para hacer esto, lee la screenDelta propiedad de la PrimaryPointerInfo component en engine.RootEntity. Esta propiedad es un Vector2 que informa cuántos píxeles se movió el mouse desde el último frame. Valores positivos de x significan que el mouse se movió a la derecha, 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 los 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 se movió: ${delta.x}, ${delta.y}`)
})

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

📔 Nota: Evita referirte a la engine.RootEntity entity en la carga inicial de la escena, porque eso puede provocar errores si las entities aún no se han inicializado. Para evitar este problema, haz siempre referencia a la entity dentro de un system. Siempre estará disponible, porque la primera ejecución del system se llama una vez que la escena ya está correctamente inicializada.

📔 Nota: Lo que se describe en este documento solo es relevante para los jugadores en desktop. En la app móvil, la entrada se basa en toque y no hay un cursor que se pueda mover libremente, así que screenDelta siempre reporta 0. Consulta Entrada en dispositivos móviles para entender cómo funciona la entrada en dispositivos táctiles, y Detectar plataforma para ofrecer controles alternativos a los jugadores de mobile.

El movimiento del mouse mientras el cursor está bloqueado

screenDelta se comporta de forma diferente a 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 de cámara o de puntería personalizados.

Arrastra para girar un objeto

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

import {
	engine,
	InputAction,
	inputSystem,
	MeshCollider,
	MeshRenderer,
	PrimaryPointerInfo,
	Transform,
} from '@dcl/sdk/ecs'
import { Quaternion, Vector3 } from '@dcl/sdk/math'

const DRAG_SENSITIVITY = 0.5

export function main() {
	const cube = engine.addEntity()
	Transform.create(cube, { position: Vector3.create(8, 1, 8) })
	MeshRenderer.setBox(cube)
	MeshCollider.setBox(cube)

	engine.addSystem(() => {
		// gira solo mientras se mantenga presionado el botón del puntero
		if (!inputSystem.isPressed(InputAction.IA_POINTER)) return

		const delta = PrimaryPointerInfo.getOrNull(engine.RootEntity)?.screenDelta
		if (!delta || delta.x === 0) return

		const transform = Transform.getMutable(cube)
		transform.rotation = Quaternion.multiply(
			transform.rotation,
			Quaternion.fromEulerDegrees(0, delta.x * DRAG_SENSITIVITY, 0)
		)
	})
}

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

Controles de cámara mouselook

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

En el siguiente ejemplo, el jugador 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 cámara predeterminada. Mientras la cámara virtual está activa, la escena también bloquea el cursor y congela el avatar con un InputModifier, para que el jugador no camine a ciegas mientras controla la cámara.

import {
	engine,
	Entity,
	InputAction,
	InputModifier,
	inputSystem,
	MainCamera,
	MeshCollider,
	MeshRenderer,
	PointerEventType,
	pointerEventsSystem,
	PointerLock,
	PrimaryPointerInfo,
	Transform,
	VirtualCamera,
} from '@dcl/sdk/ecs'
import { Quaternion, Vector3 } from '@dcl/sdk/math'

// grados de rotación de la cámara por píxel de movimiento del mouse
const SENSITIVITY = 0.15

let cameraEntity: Entity
let cameraActive = false
let yaw = 0
let pitch = 0

export function main() {
	// la Entity que la cámara sigue
	cameraEntity = engine.addEntity()
	Transform.create(cameraEntity, { position: Vector3.create(8, 3, 8) })
	VirtualCamera.create(cameraEntity, {
		defaultTransition: { transitionMode: VirtualCamera.Transition.Time(0.5) },
	})

	// haz clic en esta caja para entrar en modo mouselook
	const box = engine.addEntity()
	Transform.create(box, { position: Vector3.create(8, 1, 4) })
	MeshRenderer.setBox(box)
	MeshCollider.setBox(box)
	pointerEventsSystem.onPointerDown(
		{
			entity: box,
			opts: { button: InputAction.IA_POINTER, hoverText: 'Controlar cámara' },
		},
		() => activateCamera(true)
	)

	// controla la cámara con el mouse
	engine.addSystem(() => {
		if (!cameraActive) return
		if (!PointerLock.getOrNull(engine.CameraEntity)?.isPointerLocked) return

		const delta = PrimaryPointerInfo.getOrNull(engine.RootEntity)?.screenDelta
		if (!delta) return

		yaw += delta.x * SENSITIVITY
		// limita pitch para que la cámara no pueda darse vuelta
		pitch = Math.max(-85, Math.min(85, pitch - delta.y * SENSITIVITY))

		Transform.getMutable(cameraEntity).rotation = Quaternion.fromEulerDegrees(pitch, yaw, 0)
	})

	// salir del modo mouselook con el botón secundario
	engine.addSystem(() => {
		if (!cameraActive) return
		if (inputSystem.isTriggered(InputAction.IA_SECONDARY, PointerEventType.PET_DOWN)) {
			activateCamera(false)
		}
	})
}

function activateCamera(active: boolean) {
	cameraActive = active

	// asigna o libera la cámara virtual
	MainCamera.createOrReplace(engine.CameraEntity, {
		virtualCameraEntity: active ? cameraEntity : undefined,
	})

	// congela el avatar mientras se controla la cámara
	InputModifier.createOrReplace(engine.PlayerEntity, {
		mode: InputModifier.Mode.Standard({ disableAll: active }),
	})

	// bloquea el cursor, para que el mouse controle la cámara de inmediato
	PointerLock.createOrReplace(engine.CameraEntity, { isPointerLocked: active })
}

Algunas cosas a tener en cuenta sobre este ejemplo:

• El system resta delta.y del pitch, para que mover el mouse hacia arriba incline la cámara 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 cámara nunca podrá darse vuelta hacia atrás.

• La SENSITIVITY constante expresa grados de rotación por píxel de movimiento del mouse, ajústala a tu gusto.

💡 Consejo: El jugador puede desbloquear el cursor en cualquier momento presionando Esc o haciendo clic derecho, lo que hace que la cámara deje de responder al mouse. Siempre ofrece a los jugadores una forma clara de salir por completo del modo cámara, 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 Comprueba la posición del cursor del jugador.

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