> For the complete documentation index, see [llms.txt](https://docs.decentraland.org/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.decentraland.org/creator/content-creator-pt/scenes-sdk7/interatividade/mouse-movement.md).

# Movimento do rato

Reaja ao movimento do rato do jogador em tempo real, para acionar gestos de arrastar, girar objetos ou controlar câmeras personalizadas.

A sua cena pode ler o movimento bruto do rato do jogador em cada frame e usá-lo para controlar interações em tempo real: gestos de arrastar e deslizar, objetos que rodam ou deslizam enquanto o jogador os arrasta, ou controlar uma câmara personalizada, como num jogo de tiro na primeira pessoa.

Para isso, leia a `screenDelta` propriedade do `PrimaryPointerInfo` componente em `engine.RootEntity`. Esta propriedade é um `Vector2` que indica quantos píxeis o rato se moveu desde o último frame. Valores positivos de `x` significam que o rato se moveu para a direita; valores positivos de `y` significam que se moveu para baixo, de acordo com a origem do ecrã no canto superior esquerdo — o mesmo espaço de coordenadas que `UiTransform` e `UiCanvasInformation`. Nos frames em que o rato não se move, ambos os valores são 0.

```ts
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}`)
})
```

Como `screenDelta` contém apenas o movimento de um único frame, leia-o sempre dentro de um [system](https://docs.decentraland.org/creator/content-creator-pt/scenes-sdk7/arquitetura/systems.md), para que nenhum movimento passe despercebido entre frames.

{% hint style="warning" %}
**📔 Nota**: Evite referenciar `engine.RootEntity` durante o carregamento inicial da cena, pois isso pode causar erros se as Entities ainda não tiverem sido inicializadas. Para evitar este problema, referencie sempre a Entity dentro de um system. Estará sempre disponível, porque a primeira execução do system ocorre quando a cena já está devidamente inicializada.
{% endhint %}

{% hint style="warning" %}
**📔 Nota**: O que é descrito neste documento só se aplica a jogadores em computador. Na [aplicação para dispositivos móveis](https://docs.decentraland.org/creator/content-creator-pt/criar-para-mobile/cliente-movel/overview.md), a entrada é baseada no toque e não existe um cursor de movimento livre, por isso `screenDelta` indica sempre 0. Consulte [Entrada em dispositivos móveis](https://docs.decentraland.org/creator/content-creator-pt/criar-para-mobile/desenvolver/input-on-mobile.md) para saber como funciona a entrada em dispositivos táteis, e [Detetar a plataforma](https://docs.decentraland.org/creator/content-creator-pt/criar-para-mobile/desenvolver/detect-platform.md) para disponibilizar controlos alternativos aos jogadores em dispositivos móveis.
{% endhint %}

## Movimento do rato quando o cursor está bloqueado

`screenDelta` comporta-se de forma diferente das outras propriedades de `PrimaryPointerInfo` quando o cursor está [bloqueado](https://docs.decentraland.org/creator/content-creator-pt/scenes-sdk7/interatividade/eventos-de-botao/click-events.md#lock-or-unlock-the-cursor): `screenCoordinates` fica fixo no centro do ecrã e `worldRayDirection` indica sempre o raio no centro do ecrã, mas `screenDelta` continua a comunicar o movimento bruto do rato em cada frame. Isto torna-o a única forma de ler o movimento do rato quando o cursor está bloqueado, exatamente o que é necessário para controlos personalizados da câmara ou da mira.

## Arraste para rodar um objeto

O exemplo seguinte permite ao jogador rodar um cubo arrastando o rato para os lados enquanto mantém o botão do ponteiro premido:

```ts
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(() => {
		// rodar apenas enquanto o botão do ponteiro estiver premido
		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)
		)
	})
}
```

O mesmo padrão funciona para qualquer interação de arrastar: deslizar uma entidade ao longo de uma calha usando `delta.x` como deslocamento, percorrer uma animação ou detetar um deslize rápido verificando se os valores de delta são elevados.

## Controlos da câmara com movimento do rato

Como `screenDelta` continua a funcionar quando o cursor está bloqueado, pode usá-lo para criar controlos de movimento do rato para uma [câmara virtual](https://docs.decentraland.org/creator/content-creator-pt/scenes-sdk7/fundamentos-de-conteudo-3d/camera.md#using-virtual-cameras). Para isso, acumule o movimento do rato nos ângulos de guinada e inclinação e, em seguida, aplique-os à rotação da câmara em cada frame.

No exemplo seguinte, o jogador clica numa caixa para mudar para uma câmara virtual que pode controlar com o rato e prime o botão secundário (*F* ou clica com o botão direito) para voltar à câmara predefinida. Enquanto a câmara virtual está ativa, a cena também bloqueia o cursor e imobiliza o avatar com um [modificador de entrada](https://docs.decentraland.org/creator/content-creator-pt/scenes-sdk7/interatividade/avatares/locomotion.md#freeze-the-player), para que o jogador não ande às cegas enquanto controla a câmara.

```ts
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'

// graus de rotação da câmara por pixel de movimento do rato
const SENSITIVITY = 0.15

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

export function main() {
	// a entidade que a câmara segue
	cameraEntity = engine.addEntity()
	Transform.create(cameraEntity, { position: Vector3.create(8, 3, 8) })
	VirtualCamera.create(cameraEntity, {
		defaultTransition: { transitionMode: VirtualCamera.Transition.Time(0.5) },
	})

	// clique nesta caixa para entrar no modo de olhar com o mouse
	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)
	)

	// controle a câmera com o 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
		// limite o pitch para que a câmera não vire de cabeça para baixo
		pitch = Math.max(-85, Math.min(85, pitch + delta.y * SENSITIVITY))

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

	// saia do modo de olhar com o mouse usando o botão secundário
	engine.addSystem(() => {
		if (!cameraActive) return
		if (inputSystem.isTriggered(InputAction.IA_SECONDARY, PointerEventType.PET_DOWN)) {
			activateCamera(false)
		}
	})
}

function activateCamera(active: boolean) {
	cameraActive = active

	// atribua ou libere a câmera virtual
	MainCamera.createOrReplace(engine.CameraEntity, {
		virtualCameraEntity: active ? cameraEntity : undefined,
	})

	// congele o avatar enquanto a câmera é controlada
	InputModifier.createOrReplace(engine.PlayerEntity, {
		mode: InputModifier.Mode.Standard({ disableAll: active }),
	})

	// bloqueie o cursor para que o mouse controle a câmera imediatamente
	PointerLock.createOrReplace(engine.CameraEntity, { isPointerLocked: active })
}
```

Alguns pontos importantes sobre este exemplo:

* O sistema adiciona `delta.y` ao pitch. Mover o mouse para cima retorna um valor negativo de `delta.y`, o que reduz o pitch e inclina a câmera para cima. Inverta esse sinal se preferir controles verticais invertidos.
* O pitch é limitado ao intervalo de -85 a 85 graus, para que a câmera nunca vire para trás.
* A constante `SENSITIVITY` expressa os graus de rotação por pixel de movimento do mouse; ajuste-a como preferir.

{% hint style="info" %}
**💡 Dica**: O jogador pode desbloquear o cursor a qualquer momento pressionando *Esc* ou clicando com o botão direito, o que impede a câmera de responder ao mouse. Sempre ofereça aos jogadores uma forma clara de sair completamente do modo de câmera, como o botão secundário no exemplo acima. Também é possível bloquear o cursor novamente por código; consulte [Bloquear ou desbloquear o cursor](https://docs.decentraland.org/creator/content-creator-pt/scenes-sdk7/interatividade/eventos-de-botao/click-events.md#lock-or-unlock-the-cursor).
{% endhint %}

## Tópicos relacionados

Para ler a posição absoluta do cursor na tela, em vez do movimento, use a propriedade `screenCoordinates` do mesmo Component. Consulte [Verificar a posição do cursor do jogador](https://docs.decentraland.org/creator/content-creator-pt/scenes-sdk7/interatividade/user-data.md#check-the-players-cursor-position).

Para descobrir qual Entity está sob o cursor, combine o `worldRayDirection` propriedade com um raycast. Consulte [Raycasting](https://docs.decentraland.org/creator/content-creator-pt/scenes-sdk7/interatividade/raycasting.md).

{% hint style="info" %}
**💡 Dica**: Para ver exemplos práticos do estado do ponteiro, consulte a [`0,5-primary-cursor-info`](https://github.com/decentraland/sdk7-test-scenes/tree/main/scenes/0,5-primary-cursor-info) cena de teste, que lê `PrimaryPointerInfo` a cada frame e passa `worldRayDirection` a um raycast; [`31,20-pointer-lock-control`](https://github.com/decentraland/sdk7-test-scenes/tree/main/scenes/31,20-pointer-lock-control), que solicita e liberta a captura do cursor ao escrever `PointerLock.isPointerLocked`; e [`32,20-virtual-camera-mouse-look`](https://github.com/decentraland/sdk7-test-scenes/tree/main/scenes/32,20-virtual-camera-mouse-look), que mostra `screenDelta` a continuar a indicar movimento enquanto `screenCoordinates` fica fixo no centro do ecrã durante o bloqueio.
{% endhint %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.decentraland.org/creator/content-creator-pt/scenes-sdk7/interatividade/mouse-movement.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
