Mouse Movement

React to the player's mouse movement in real time, to drive drag gestures, spin objects, or steer custom cameras.

Your scene can read the player's raw mouse movement on every frame, and use it to drive real-time interactions: drag and swipe gestures, spinning or sliding objects as the player drags them, or steering a custom camera like in a first-person shooter.

To do this, read the screenDelta property of the PrimaryPointerInfo component on engine.RootEntity. This property is a Vector2 that reports how many pixels the mouse moved since the last frame. Positive x values mean the mouse moved right, positive y values mean it moved up, matching the screen's origin at the bottom-left corner. On frames where the mouse doesn't move, both values are 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}`)
})

Since screenDelta only holds the movement of a single frame, always read it inside a system, so no movement goes unnoticed between frames.

Mouse movement while the cursor is locked

screenDelta behaves differently from the other properties of PrimaryPointerInfo when the cursor is locked: screenCoordinates freezes at the screen center and worldRayDirection always reports the ray at the center of the screen, but screenDelta keeps reporting the raw mouse movement on every frame. This makes it the only way to read mouse movement while the cursor is locked, which is exactly what you need for custom camera or aiming controls.

Drag to rotate an object

The following example lets the player spin a cube by dragging the mouse sideways while holding the pointer button down:

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(() => {
        // only rotate while the pointer button is held down
        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)
        )
    })
}

The same pattern works for any drag interaction: slide an entity along a rail using delta.x as an offset, scrub through an animation, or detect a quick swipe by checking for large delta values.

Mouselook camera controls

Because screenDelta keeps working while the cursor is locked, you can use it to build mouselook controls for a virtual camera. To do this, accumulate the mouse movement into yaw and pitch angles, then apply them to the camera's rotation on every frame.

In the following example, the player clicks a box to switch to a virtual camera that they can steer with the mouse, and presses the secondary button (F or right-click) to return to the default camera. While the virtual camera is active, the scene also locks the cursor and freezes the avatar with an input modifier, so the player doesn't walk around blindly while steering the camera.

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'

// degrees of camera rotation per pixel of mouse movement
const SENSITIVITY = 0.15

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

export function main() {
    // the entity that the camera follows
    cameraEntity = engine.addEntity()
    Transform.create(cameraEntity, { position: Vector3.create(8, 3, 8) })
    VirtualCamera.create(cameraEntity, {
        defaultTransition: { transitionMode: VirtualCamera.Transition.Time(0.5) },
    })

    // click this box to enter mouselook mode
    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: 'Control camera' },
        },
        () => activateCamera(true)
    )

    // steer the camera with the 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
        // clamp pitch so the camera can't flip over
        pitch = Math.max(-85, Math.min(85, pitch - delta.y * SENSITIVITY))

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

    // exit mouselook mode with the secondary button
    engine.addSystem(() => {
        if (!cameraActive) return
        if (inputSystem.isTriggered(InputAction.IA_SECONDARY, PointerEventType.PET_DOWN)) {
            activateCamera(false)
        }
    })
}

function activateCamera(active: boolean) {
    cameraActive = active

    // assign or release the virtual camera
    MainCamera.createOrReplace(engine.CameraEntity, {
        virtualCameraEntity: active ? cameraEntity : undefined,
    })

    // freeze the avatar while the camera is being steered
    InputModifier.createOrReplace(engine.PlayerEntity, {
        mode: InputModifier.Mode.Standard({ disableAll: active }),
    })

    // lock the cursor, so the mouse steers the camera right away
    PointerLock.createOrReplace(engine.CameraEntity, { isPointerLocked: active })
}

A few things to note about this example:

• The system subtracts delta.y from the pitch, so that moving the mouse up tilts the camera up. Flip that sign if you prefer inverted vertical controls.
• The pitch is clamped to a range of -85 to 85 degrees, so the camera can never flip over backwards.
• The SENSITIVITY constant expresses degrees of rotation per pixel of mouse movement, tweak it to taste.

Related topics

To read the cursor's absolute position on the screen instead of its movement, use the screenCoordinates property of the same component. See Check the player's cursor position.

To find out which entity is under the cursor, combine the worldRayDirection property with a raycast. See Raycasting.