> 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/fundamentos-de-conteudo-3d/camera.md).

# Câmera

Saiba como controlar a câmera do jogador

Como criador, tem controlo total sobre a câmara do jogador. Por predefinição, os jogadores podem escolher livremente entre a perspetiva de primeira ou terceira pessoa enquanto exploram a sua Scene, mas pode impor um modo de câmara diferente.

As câmaras virtuais podem ser estáticas, rodar para estarem sempre viradas para o jogador ou outra Entity, ou ficar ligadas ao jogador ou a outra Entity, acompanhando-os sempre.

{% hint style="warning" %}
**📔 Nota**: Para alternar entre as câmaras predefinidas de primeira e terceira pessoa, consulte [Áreas de modificação da câmara](#1st-and-3rd-person-camera-modes).
{% endhint %}

## Modos de câmara de primeira e terceira pessoa

Normalmente, os jogadores podem alternar entre a câmara de primeira e terceira pessoa premindo V no teclado. Utilize uma `CameraModeArea` para impor o modo de câmara de primeira ou terceira pessoa a todos os jogadores que se encontrem numa área específica da sua Scene.

```ts
const entity = engine.addEntity()

CameraModeArea.create(entity, {
	area: Vector3.create(4, 3, 4),
	mode: CameraType.CT_FIRST_PERSON,
})
```

Se o modo de câmara atual de um jogador não corresponder ao modo da `CameraModeArea`, o jogador passará para esse modo de câmara. É apresentada uma notificação no ecrã para esclarecer que a alteração se deve à Scene. Enquanto estiverem dentro da área, os jogadores não podem alterar o modo de câmara. Quando um jogador sair da `CameraModeArea`, o modo de câmara é reposto para aquele que tinha antes de entrar.

Utilize `CameraModeArea` em regiões onde os jogadores teriam uma experiência significativamente melhor com um modo de câmara específico. Por exemplo, a primeira pessoa é ideal se o jogador precisar de clicar num objeto pequeno; a terceira pessoa pode ser útil para os jogadores repararem numa Entity que a sua Scene tenha colocado sobre a cabeça deles. Não parta do princípio de que os jogadores sabem como alternar entre modos de câmara: muitos jogadores principiantes podem não saber que têm essa opção ou não se lembrar da tecla correspondente.

{% hint style="warning" %}
**📔 Nota**: As áreas de modificação da câmara são afetadas pela *posição* e pela *rotação* do componente Transform da Entity que as contém, mas não são afetadas pela *escala*.
{% endhint %}

{% hint style="warning" %}
**📔 Nota**: Se houver sobreposição entre várias áreas de modificação da câmara, a última a ser instanciada pelo código da sua Scene terá prioridade sobre as restantes.
{% endhint %}

Ao criar um componente `CameraModeArea` tem de fornecer os seguintes valores:

* `area`: Tamanho da área de modificação
* `mode`: Modo de câmara a impor nesta área, a partir do enum `CameraType` .

Os modos de câmara suportados são:

* `CameraType.CT_FIRST_PERSON`
* `CameraType.CT_THIRD_PERSON`

### Consultar o modo de câmara

Pode consultar o modo de câmara do jogador usando o componente `CameraMode` na `engine.CameraEntity`.

```ts
const cameraMode = CameraMode.get(engine.CameraEntity)
if (cameraMode.mode === CameraType.CT_FIRST_PERSON) {
	console.log('The player is using the 1st person camera')
} else {
	console.log('The player is using the 3rd person camera')
}
```

Também pode subscrever as alterações ao modo de câmara usando o `onChange` função no `CameraMode` component.

```ts
CameraMode.onChange(engine.CameraEntity, (cameraMode) => {
	if (!cameraMode) return
	console.log('The player\'s camera mode changed to', cameraMode.mode)
})
```

## Utilizar câmaras virtuais

Para utilizar um comportamento de câmara personalizado na sua cena, precisa de duas coisas:

* Criar uma câmara virtual: crie uma entidade na sua cena e atribua-lhe um `VirtualCamera`.
* Atribuir essa câmara virtual: adicione um `MainCamera` component à [entidade reservada](https://docs.decentraland.org/creator/content-creator-pt/scenes-sdk7/arquitetura/entities-components.md#reserved-entities) `engine.CameraEntity`, com uma referência à entidade com o componente `VirtualCamera` component.

A câmara será então anexada à entidade com o componente `VirtualCamera` component. Se a entidade se mover ou rodar, a câmara move-se com ela.

```ts
function main() {
	const myCustomCamera = engine.addEntity()
	Transform.create(myCustomCamera, {
		position: Vector3.create(1, 2, 1),
	})
	VirtualCamera.create(myCustomCamera, {})

	const mainCamera = MainCamera.createOrReplace(engine.CameraEntity, {
		virtualCameraEntity: myCustomCamera,
	})
}
```

Neste exemplo, a câmara ficará sempre numa posição fixa na cena, desde que o jogador permaneça dentro dos limites da cena. Assim que o jogador sair dos limites da cena, o comportamento predefinido da câmara será restaurado.

### Campo de visão

Defina o campo de visão (FOV) de uma câmara virtual com a propriedade `fov` , em graus. Só se aplica enquanto esta câmara virtual estiver ativa.

```ts
const cinematicCamera = engine.addEntity()
Transform.create(cinematicCamera, {
	position: Vector3.create(8, 3, 2),
})
VirtualCamera.create(cinematicCamera, {
	fov: 45,
})
```

Um FOV mais estreito (valor mais baixo) aproxima a imagem, sendo útil para cenas cinematográficas ou para apontar. Um FOV mais amplo (valor mais alto) mostra uma área maior da cena, sendo útil para vistas panorâmicas.

{% hint style="warning" %}
**📔 Nota**: Defina `fov` em cada câmara virtual que criar. Se o omitir, não obterá um valor neutro de 60 graus: o cliente reutiliza instâncias de câmara agrupadas sem repor a lente, pelo que uma câmara sem `fov` mantém o campo de visão que uma câmara anterior definiu nessa instância. Uma câmara destinada a mostrar uma ampla vista aérea pode iniciar com o zoom muito aproximado.
{% endhint %}

A sua cena pode incluir quantas entidades quiser com um `VirtualCamera`component, e alternar dinamicamente entre várias câmaras virtuais à medida que o jogador se move ou realiza determinadas ações. Só uma câmara virtual está ativa de cada vez; esta é atribuída pelo componente `MainCamera` em `engine.CameraEntity`.

Para voltar ao comportamento padrão da câmera, defina o valor como `undefined` em `MainCamera.virtualCameraEntity`. O jogador fica livre para alternar entre as câmeras em 1ª e 3ª pessoa. Se quiser que o jogador use apenas um desses dois modos, você pode usar uma [área modificadora da câmera](#1st-and-3rd-person-camera-modes) para forçar um dos dois.

{% hint style="warning" %}
**📔 Nota**: libere a câmera com `undefined`, nunca com `0`. Somente um valor ausente devolve o controle ao jogador. O valor `0` é `engine.RootEntity`, que não tem `VirtualCamera`, então o Engine mantém a última câmera virtual ativa e o jogador fica preso nessa visualização.

Isso pode causar problemas no código que salva e restaura a câmera, porque `virtualCameraEntity` é opcional e, em uma `MainCamera` recém-criada, seu valor é `undefined`. Um fallback com `?? 0` ou `|| 0` converte isso em um `0` que será gravado novamente mais tarde. Verifique se a entidade existe antes de restaurá-la:

```ts
function restoreCamera(previous: Entity | undefined) {
	const camera = MainCamera.getMutableOrNull(engine.CameraEntity)
	if (!camera) return
	// Restore somente uma câmera que realmente exista; caso contrário, libere o controle
	camera.virtualCameraEntity = previous && VirtualCamera.has(previous) ? previous : undefined
}
```

{% endhint %}

{% hint style="warning" %}
**📔 Nota**: As áreas modificadoras da câmera só afetam o jogador quando não há câmeras virtuais ativas. Se a cena estiver usando uma câmera virtual e o jogador entrar em uma área modificadora da câmera, nada acontece.

Se um modelo 3D incluir um nó `camera` como parte do seu conteúdo, ele não poderá ser usado pelo SDK. Você precisa criar todas as câmeras como entidades com o SDK.
{% endhint %}

```ts
function main() {
	// câmera virtual personalizada
	const myCustomCamera = engine.addEntity()
	Transform.create(myCustomCamera, {
		position: Vector3.create(1, 2, 1),
	})
	VirtualCamera.create(myCustomCamera, {})

	const mainCamera = MainCamera.createOrReplace(engine.CameraEntity, {
		virtualCameraEntity: myCustomCamera,
	})

	// cubo clicável
	const clickCube = engine.addEntity()
	Transform.create(clickCube, { position: Vector3.create(8, 0, 8) })
	MeshRenderer.setBox(clickCube)
	MeshCollider.setBox(clickCube)
	pointerEventsSystem.onPointerDown(
		{
			entity: clickCube,
			opts: { button: InputAction.IA_POINTER, hoverText: 'Reset camera' },
		},
		() => {
			// redefinir a câmera para o comportamento padrão
			const mainCamera = MainCamera.getMutable(engine.CameraEntity)
			mainCamera.virtualCameraEntity = undefined
		}
	)
}
```

{% hint style="info" %}
**💡 Dica**: Quando a câmera se afasta do avatar, geralmente é uma boa prática também congelar os movimentos do avatar. Assim, o jogador não se move às cegas em direção a obstáculos. Veja [Modificadores de entrada](https://docs.decentraland.org/creator/content-creator-pt/scenes-sdk7/interatividade/avatares/locomotion.md#freeze-the-player)
{% endhint %}

Para permitir que o jogador controle uma câmara virtual com o rato, leia a `screenDelta` propriedade do componente `PrimaryPointerInfo` para ver a distância percorrida pelo cursor em cada frame e, em seguida, aplicar esse movimento à rotação da câmara. Isto também funciona quando o cursor está bloqueado. Consulte [Movimento do rato](https://docs.decentraland.org/creator/content-creator-pt/scenes-sdk7/interatividade/mouse-movement.md) para ver um exemplo completo de controlo da câmara com o rato.

## Vista aérea

Pode usar uma câmara virtual para observar a cena de cima. Esta pode ser uma variação divertida da perspetiva normal do seu avatar e permitir diferentes mecânicas de jogo.

Evite posicionar a câmara a apontar exatamente para baixo. Em vez disso, incline-a sempre ligeiramente; até 1 grau é suficiente. Isto deve-se ao facto de os controlos de direção do jogador se basearem na perspetiva da câmara, e não na orientação do avatar. Se a câmara estiver numa vista aérea perfeitamente vertical, não é claro qual é cada direção. Uma inclinação impercetível de 1 grau é suficiente para definir uma direção para a frente.

```ts
function main() {
	// câmara em vista aérea
	const myCustomCamera = engine.addEntity()
	Transform.create(myCustomCamera, {
		position: Vector3.create(8, 5, 8),
		rotation: Quaternion.fromEulerDegrees(91, 0, 0),
		// Nota: a rotação é de 91º, não de 90º
	})
	VirtualCamera.create(myCustomCamera, {})

	const mainCamera = MainCamera.createOrReplace(engine.CameraEntity, {
		virtualCameraEntity: myCustomCamera,
	})
}
```

## Campo de visão

Pode definir um campo de visão (FOV) personalizado para uma câmara virtual através da propriedade `fov` O valor é expresso em graus. Defina-o sempre: não existe um valor predefinido a utilizar. Uma câmara sem `fov` herda a lente deixada por uma câmara anterior que tenha utilizado a mesma instância do conjunto.

```ts
VirtualCamera.create(myCustomCamera, {
	fov: 90,
})
```

Um FOV mais amplo (valor mais elevado) mostra mais da cena de uma só vez e cria uma sensação de velocidade, o que pode ser útil em jogos de corridas. Um FOV mais estreito (valor mais baixo) aproxima a imagem e é útil para apontar ou obter planos cinematográficos.

### Alterar o nível de zoom

O cliente lê `fov` apenas no momento em que uma câmara se torna ativa. Alterar `fov` na câmara que já está ativa não produz qualquer efeito.

Para aplicar zoom, crie uma câmara virtual para cada nível de zoom e alterne a propriedade `MainCamera.virtualCameraEntity` entre elas:

```ts
import { engine, MainCamera, Transform, VirtualCamera } from '@dcl/sdk/ecs'
import { Vector3 } from '@dcl/sdk/math'

// Duas câmaras no mesmo local, uma com grande angular e outra com zoom
const position = Vector3.create(8, 2, 8)

const wideCamera = engine.addEntity()
Transform.create(wideCamera, { position })
VirtualCamera.create(wideCamera, { fov: 70 })

const zoomedCamera = engine.addEntity()
Transform.create(zoomedCamera, { position })
VirtualCamera.create(zoomedCamera, { fov: 30 })

// Alterne entre elas para aplicar zoom
function zoomIn() {
	MainCamera.createOrReplace(engine.CameraEntity, { virtualCameraEntity: zoomedCamera })
}

function zoomOut() {
	MainCamera.createOrReplace(engine.CameraEntity, { virtualCameraEntity: wideCamera })
}
```

Atribuir novamente a câmara que já está ativa também não produz qualquer efeito; por isso, alterne para uma entidade diferente de cada vez.

## Transições de câmara

Sempre que a cena muda de uma câmara virtual para outra, ou entre o comportamento predefinido da câmara e as câmaras virtuais, os jogadores veem uma transição. A posição, a rotação e quaisquer outros parâmetros da câmara virtual mudam suavemente ao longo de um período de tempo.

As definições de transição de uma câmara virtual determinam como é feita a transição *para* essa câmara, relativamente a qualquer outra câmara na cena, incluindo a predefinida. Não afetam a forma como faz a transição *para* fora dessa câmara.

Voltando à câmara do próprio jogador, quando limpa a `virtualCameraEntity` da `MainCamera`, é sempre aplicada uma transição fixa de 0,5 segundos, com aceleração e desaceleração. O `defaultTransition` da câmara virtual que abandona não altera esse valor.

```ts
VirtualCamera.create(myCustomCamera1, {
	defaultTransition: { transitionMode: VirtualCamera.Transition.Time(6) },
})
```

{% hint style="info" %}
**💡 Sugestão**: para evitar uma transição e mudar instantaneamente para uma câmara, defina o tempo ou a velocidade da transição como 0.
{% endhint %}

Consoante o seu caso de utilização, poderá preferir definir a velocidade da transição em vez da duração:

* **Tempo fixo**: define a duração da transição; a câmara mover-se-á à velocidade necessária para concluir o percurso nesse período de tempo.
* **Velocidade fixa**: define a velocidade a que pretende que a câmara virtual se mova durante a transição; a duração dependerá da distância. O valor de velocidade é interpretado como **metros por segundo**.

Seguem-se exemplos de ambos os modos de transição:

```ts
// duração fixa
VirtualCamera.create(myCustomCamera1, {
	defaultTransition: { transitionMode: VirtualCamera.Transition.Time(6) },
})

// velocidade fixa
VirtualCamera.create(myCustomCamera1, {
	defaultTransition: { transitionMode: VirtualCamera.Transition.Speed(3) },
})
```

Segue-se um exemplo completo com duas câmaras virtuais e as transições entre elas:

```ts
function main() {
	// câmara virtual personalizada 1
	const myCustomCamera1 = engine.addEntity()
	Transform.create(myCustomCamera1, {
		position: Vector3.create(1, 2, 1),
	})
	VirtualCamera.create(myCustomCamera1, {
		defaultTransition: { transitionMode: VirtualCamera.Transition.Time(1) },
	})

	// câmara virtual personalizada 2
	const myCustomCamera2 = engine.addEntity()
	Transform.create(myCustomCamera2, {
		position: Vector3.create(1, 2, 1),
	})
	VirtualCamera.create(myCustomCamera2, {
		defaultTransition: { transitionMode: VirtualCamera.Transition.Time(3) },
	})

	const mainCamera = MainCamera.createOrReplace(engine.CameraEntity, {
		virtualCameraEntity: myCustomCamera1,
	})

	// cubo clicável
	const clickCube = engine.addEntity()
	Transform.create(clickCube, { position: Vector3.create(8, 0, 8) })
	MeshRenderer.setBox(clickCube)
	MeshCollider.setBox(clickCube)
	pointerEventsSystem.onPointerDown(
		{
			entity: clickCube,
			opts: { button: InputAction.IA_POINTER, hoverText: 'Reset camera' },
		},
		() => {
			// redefinir a câmera para o comportamento padrão
			const mainCamera = MainCamera.getMutable(engine.CameraEntity)
			mainCamera.virtualCameraEntity =
				mainCamera.virtualCameraEntity == myCustomCamera1
					? myCustomCamera2
					: myCustomCamera1
		}
	)
}
```

As transições seguem sempre uma linha reta, sem ter em conta quaisquer obstáculos no percurso. Em alternativa, pode criar uma transição manualmente utilizando outra câmara virtual como intermediária, o que lhe dará controlo total sobre os movimentos. Esta câmara virtual intermediária pode executar um [Tween](https://docs.decentraland.org/creator/content-creator-pt/scenes-sdk7/fundamentos-de-conteudo-3d/move-entities.md#move-between-two-points) da posição da primeira câmara para a posição da segunda ou seguir um percurso mais personalizado que evite obstáculos ou faça um desvio cinematográfico.

## Seguir a câmara

Pode configurar uma câmara virtual para que esteja sempre virada na direção do jogador ou de uma entidade específica na cena. A posição da câmara permanecerá estática, mas a sua rotação mudará para manter sempre essa entidade ao centro.

Isto pode ser conseguido com a propriedade `lookAtEntity` no componente `VirtualCamera` . Para seguir o jogador, utilize a [entidade reservada](https://docs.decentraland.org/creator/content-creator-pt/scenes-sdk7/arquitetura/entities-components.md#reserved-entities) `engine.PlayerEntity`.

```ts
const myCustomCamera1 = engine.addEntity()
Transform.create(myCustomCamera1, {
	position: Vector3.create(1, 2, 1),
})
VirtualCamera.create(myCustomCamera1, {
	lookAtEntity: engine.PlayerEntity,
})
```

Se uma entidade estiver a ser seguida pela câmara, isto só altera a rotação, não a posição da câmara.

À medida que a câmara roda, o Transform da entidade com o `VirtualCamera` componente não se altera. No entanto, pode ler a rotação da câmara a partir do Transform em `engine.CameraEntity`. A rotação e a posição desta entidade serão absolutas, não serão condicionadas pelas da entidade com o `VirtualCamera` componente. A rotação deste Transform também é afetada pelo comportamento de `lookAtEntity` .

{% hint style="warning" %}
**📔 Nota**: Se configurar a câmara virtual com um `lookAtEntity` que faça referência à mesma entidade que contém a câmara virtual, ou à entidade `engine.CameraEntity` , o comportamento resultante será igual ao de não atribuir nenhuma entidade.
{% endhint %}

## Associar ao jogador

Outra utilização da câmara virtual é seguir o jogador a uma distância ou ângulo personalizados, associando uma câmara virtual à entidade do jogador. Tenha em conta que o jogador não pode alterar livremente a rotação da câmara; neste caso, a rotação da câmara ficará fixa à da câmara virtual. Isto pode ser útil, por exemplo, em jogos de corridas, nos quais se espera que o jogador olhe sempre em frente.

```ts
function main() {
	const myCustomCamera = engine.addEntity()
	Transform.create(myCustomCamera, {
		position: Vector3.create(0, 1, 5),
		parent: engine.PlayerEntity,
	})
	VirtualCamera.create(myCustomCamera, {
		defaultTransition: { transitionMode: VirtualCamera.Transition.Time(2) },
	})

	const mainCamera = MainCamera.createOrReplace(engine.CameraEntity, {
		virtualCameraEntity: myCustomCamera,
	})
}
```

## Câmaras e Colliders

Quando a câmara do jogador se move no modo de terceira pessoa, pode ou não ser bloqueada pelos Colliders, consoante as camadas de colisão atribuídas às entidades. Tenha isto em conta ao conceber a sua Scene; poderá querer impedir que a câmara atravesse paredes ou outras entidades.

Consulte [Colliders](https://docs.decentraland.org/creator/content-creator-pt/scenes-sdk7/fundamentos-de-conteudo-3d/colliders.md#cameras-and-colliders) para obter mais informações sobre como configurar Colliders para a sua Scene.

## Modo de observação (câmara de observador)

Pode criar um modo de observação que muda o jogador do movimento normal do Avatar para uma câmara de movimento livre ou que segue outros jogadores. Isto é útil para funções de observador em jogos competitivos, câmaras de realização para eventos em direto ou sistemas de repetição.

Este padrão combina várias funcionalidades do SDK:

| Funcionalidade                | API do SDK                                | Finalidade                                             |
| ----------------------------- | ----------------------------------------- | ------------------------------------------------------ |
| Vista de câmara personalizada | `VirtualCamera` + `MainCamera`            | Substitui a câmara do jogador                          |
| Imobilizar o Avatar           | `InputModifier` (`disableAll: true`)      | Liberta WASD para controlar a câmara                   |
| Acompanhar jogadores na Scene | `onEnterScene` / `onLeaveScene`           | Cria uma lista de alvos a seguir                       |
| Controlos da câmara           | `inputSystem.isPressed(InputAction.IA_*)` | WASD para inclinação/rotação horizontal, E/F para zoom |
| Controlo da câmara com o rato | `PrimaryPointerInfo.screenDelta`          | Rodar a câmara com o rato                              |

### Arquitetura do rig da câmara

Use um **rig de duas entidades** para manter o yaw e o pitch independentes:

```
rigRoot (entidade)           -- posição no mundo + rotação yaw
└── rigCamera (filha)      -- rotação pitch + deslocamento orbital
    └── VirtualCamera
```

`rigRoot` controla o yaw (rotação para a esquerda/direita) e é interpolado em direção ao alvo a seguir ou ao pivô da câmara livre. `rigCamera` controla o pitch (inclinação para cima/baixo) e a distância orbital em relação à raiz. Separar o yaw e o pitch por dois Transforms simplifica os cálculos de ângulos de Euler.

### Ativar e desativar

```ts
// Ativar o modo de observação
const rigRoot = engine.addEntity()
Transform.create(rigRoot, {
  position: Vector3.create(8, 8, 8),
  rotation: Quaternion.fromEulerDegrees(0, 0, 0),
})

const rigCamera = engine.addEntity()
Transform.create(rigCamera, { parent: rigRoot })
VirtualCamera.create(rigCamera, {})

MainCamera.createOrReplace(engine.CameraEntity, { virtualCameraEntity: rigCamera })
InputModifier.createOrReplace(engine.PlayerEntity, {
  mode: InputModifier.Mode.Standard({ disableAll: true }),
})
```

```ts
// Desativar o modo de observação
// IMPORTANTE: limpar MainCamera ANTES de remover a entidade VirtualCamera.
// Se remover a entidade primeiro, o motor continua associado a uma entidade inexistente
// e a câmara passa a mostrar os pés do jogador.
const mainCamera = MainCamera.getMutableOrNull(engine.CameraEntity)
if (mainCamera) mainCamera.virtualCameraEntity = undefined

engine.removeEntity(rigCamera)
engine.removeEntity(rigRoot)

InputModifier.createOrReplace(engine.PlayerEntity, {
  mode: InputModifier.Mode.Standard({ disableAll: false }),
})
```

{% hint style="danger" %}
**Aviso:** Limpe sempre `MainCamera.virtualCameraEntity` antes de remover a entidade da câmara. Remover primeiro a entidade deixa o motor a apontar para uma referência inexistente, fazendo com que a câmara deixe de funcionar.
{% endhint %}

### Limites da câmara

O motor desativa as `VirtualCamera` entidades que se deslocam para fora dos limites dos parcels da cena. Se a câmara sair da área da cena, deixa silenciosamente de funcionar. Em cada frame, limite a posição da câmara à caixa delimitadora alinhada pelos eixos (AABB), deixando uma pequena margem.

```ts
// Exemplo de limites para uma cena com um parcel 1x1 (16 m x 16 m)
const BOUNDS_MIN = Vector3.create(0, 0, 0)
const BOUNDS_MAX = Vector3.create(16, 20, 16)
const BOUNDS_MARGIN = 0.5
```

Em cenas maiores, defina os limites de acordo com os parcels de `scene.json` da cena. O limite de altura da cena é de 330 metros, independentemente do número de parcels. Uma cena com parcels 4x4 poderia usar `Vector3.create(64, 330, 64)`.

### Seguir jogadores

Use `onEnterScene` e `onLeaveScene` para criar uma lista atualizada de jogadores na sua scene. Depois, os jogadores podem alternar entre os alvos a seguir usando teclas (por exemplo, `IA_ACTION_3` e `IA_ACTION_4`). Ao seguir um jogador, a raiz do rig interpola em direção à posição de Transform do jogador seguido, e a câmara filha orbita a uma distância configurável.

```ts
import { onEnterScene, onLeaveScene } from '@dcl/sdk/src/players'

const playerEntities = new Map<string, Entity>()
let playerIds: string[] = []

onEnterScene((player) => {
  if (!player) return
  playerIds.push(player.userId)
  playerEntities.set(player.userId, player.entity)
})

onLeaveScene((userId) => {
  if (!userId) return
  playerIds = playerIds.filter((id) => id !== userId)
  playerEntities.delete(userId)
})
```

Para seguir um jogador em cada frame, interpole a raiz do rig em direção à posição dele:

```ts
const followEntity = playerEntities.get(followTargetId)
if (followEntity) {
  const targetPos = Transform.get(followEntity).position
  const rootTransform = Transform.getMutable(rigRoot)
  rootTransform.position = Vector3.lerp(
    rootTransform.position,
    Vector3.add(targetPos, Vector3.create(0, 1, 0)),
    0.1
  )
}
```

Consulte [Jogador entra ou sai da scene](https://docs.decentraland.org/creator/content-creator-pt/scenes-sdk7/interatividade/event-listeners.md#player-enters-or-leaves-scene) para saber mais sobre `onEnterScene` e `onLeaveScene`.

### Controlo da câmara com o rato durante a observação

Leia `PrimaryPointerInfo.screenDelta` em cada frame para rodar a câmara com o rato. Isto funciona quando o ponteiro está bloqueado. Consulte [Movimento do rato](https://docs.decentraland.org/creator/content-creator-pt/scenes-sdk7/interatividade/mouse-movement.md) para ver um exemplo completo de controlo da câmara com o rato.

```ts
const MOUSE_SENSITIVITY = 0.15 // graus por píxel
let yaw = 0
let pitch = 45

function spectateMouseLook() {
  const isLocked = PointerLock.getOrNull(engine.CameraEntity)?.isPointerLocked ?? false
  if (!isLocked) return

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

  yaw = (yaw + delta.x * MOUSE_SENSITIVITY) % 360
  // delta.y aumenta para baixo, portanto mover o rato para cima produz um valor negativo: somá-lo inclina a câmara para cima; limite o valor para evitar inversões
  pitch = Math.max(-25, Math.min(80, pitch + delta.y * MOUSE_SENSITIVITY))
}
```

{% hint style="warning" %}
**Nota:** `screenDelta` só está disponível em computadores. Em dispositivos móveis, devolve sempre `0`.
{% endhint %}

### Implementação de referência completa

A [`33,20-spectate-mode`](https://github.com/decentraland/sdk7-test-scenes/tree/main/scenes/33,20-spectate-mode) cena de teste contém um módulo de observação independente em `src/spectate.ts`. Suporta os modos de câmara livre e de seguimento, controlos WASD + movimentos do rato, alternância entre jogadores, zoom da distância orbital, limitação aos limites e um HUD no ecrã que apresenta os controlos e o alvo seguido atualmente.

Para usar este módulo no seu próprio projeto:

1. Copie `src/spectate.ts` para a sua cena.
2. Atualize `PIVOT`, `BOUNDS_MIN`, e `BOUNDS_MAX` no início do ficheiro para corresponderem aos parcels da sua cena. Este é o erro de integração mais comum.
3. Ligue `toggleSpectate()` a qualquer trigger: uma entidade clicável, um botão de UI ou uma tecla.

{% hint style="info" %}
**💡 Sugestão**: Para ver exemplos funcionais de controlo da câmara, consulte a [`2,22-virtual-cameras`](https://github.com/decentraland/sdk7-test-scenes/tree/main/scenes/2,22-virtual-cameras) cena de teste, que alterna várias `VirtualCamera` entidades através de `MainCamera` incluindo `lookAtEntity` apontada para o jogador e uma câmara animada com tween; [`32,20-virtual-camera-mouse-look`](https://github.com/decentraland/sdk7-test-scenes/tree/main/scenes/32,20-virtual-camera-mouse-look), que controla uma câmara com movimentos do rato enquanto o ponteiro está bloqueado; [`33,20-spectate-mode`](https://github.com/decentraland/sdk7-test-scenes/tree/main/scenes/33,20-spectate-mode), que implementa uma câmara completa de observação com modos de seguimento e de câmara livre; e [`9,99-modifier-areas`](https://github.com/decentraland/sdk7-test-scenes/tree/main/scenes/9,99-modifier-areas), que força um modo de câmara dentro de um volume com `CameraModeArea`.
{% 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/fundamentos-de-conteudo-3d/camera.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.
