> 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/user-data.md).

# Dados do utilizador

Obtenha dados dos jogadores à medida que interagem com a sua cena.

## Posição e rotação do jogador

Use o `PlayerEntity` e a `CameraEntity` para saber a posição e a rotação do jogador, verificando os componentes `Transform` .

```ts
function getPlayerPosition() {
	if (!Transform.has(engine.PlayerEntity)) return
	if (!Transform.has(engine.CameraEntity)) return

	//posição do jogador
	const playerPos = Transform.get(engine.PlayerEntity).position

	//rotação do jogador
	const playerRot = Transform.get(engine.PlayerEntity).rotation

	//posição da câmera
	const CameraPos = Transform.get(engine.CameraEntity).position

	//rotação da câmera
	const CameraRot = Transform.get(engine.CameraEntity).rotation

	console.log('playerPos: ', playerPos)
	console.log('playerRot: ', playerRot)
	console.log('cameraPos: ', CameraPos)
	console.log('cameraRot: ', CameraRot)
}

engine.addSystem(getPlayerPosition)
```

* **Posição de PlayerEntity**: A posição do Avatar, à altura do peito. Aproximadamente 0,88 metros acima do chão.
* **Rotação de PlayerEntity**: A direção para a qual o Avatar está virado, expressa como um quaternion.
* **Posição de CameraEntity**:
  * Em 1.ª pessoa: igual à posição do Avatar, mas ao nível dos olhos. Aproximadamente 1,75 metros acima do chão.
  * Em 3.ª pessoa: pode variar consoante os movimentos da câmera.
* **Rotação de PlayerEntity**:
  * Em 1.ª pessoa: semelhante à direção para a qual o Avatar está virado, expressa como um quaternion. Pode estar ligeiramente arredondada de forma diferente da rotação do jogador.
  * Em 3.ª pessoa: pode variar consoante os movimentos da câmera.

{% hint style="warning" %}
**📔 Nota**: evite fazer referência a `engine.PlayerEntity` ou a `engine.CameraEntity` durante o carregamento inicial da cena, pois isso pode causar erros se as entidades ainda não tiverem sido inicializadas. Para evitar esse problema, use-as dentro da função `main()` ou numa função chamada indiretamente por `main()`. Também pode encapsular o comportamento num bloco async [`executeTask` 。](https://docs.decentraland.org/creator/content-creator-pt/scenes-sdk7/padroes-de-programacao/async-functions.md#the-executetask-function).

Outra opção é fazer referência a estas entidades dentro de um sistema. Nesse caso, estarão sempre disponíveis, pois a primeira execução do sistema ocorre quando a cena já está devidamente inicializada.
{% endhint %}

## Obter todos os jogadores

Todos os jogadores na cena têm um componente `Transform` Este componente é só de leitura nos Avatars. Para obter as posições de todos os jogadores, [percorra todas as entidades com](https://docs.decentraland.org/creator/content-creator-pt/scenes-sdk7/interatividade/user-data.md) um `PlayerIdentityData` componente.

```ts
import { PlayerIdentityData } from '@dcl/sdk/ecs'

for (const [entity, data, transform] of engine.getEntitiesWith(
	PlayerIdentityData,
	Transform
)) {
	console.log('Player data: ', { entity, data, transform })
}
```

O código acima percorre todas as entidades que têm um `Transform` e um `PlayerIdentityData` componente e regista os respetivos dados. Pode usar este mesmo método para obter quaisquer dados disponíveis de todos os jogadores.

Consulte [Ouvintes de eventos](https://docs.decentraland.org/creator/content-creator-pt/scenes-sdk7/interatividade/event-listeners.md#player-enters-or-leaves-scene) para saber como detetar e reagir quando novos jogadores entram na cena.

## Obter dados do jogador

Use `getPlayer()` para obter dados sobre o jogador atual ou qualquer outro jogador na cena.

```ts
import { getPlayer } from '@dcl/sdk/src/players'

export function main() {
	createCube(5, 1, 5)

	let myPlayer = getPlayer()

	if (myPlayer) {
		console.log('Name : ', myPlayer.name)
		console.log('UserId : ', myPlayer.userId)
	}
}
```

`getPlayer()` devolve o seguinte:

* `name`: *(string)* O nome de utilizador do jogador, tal como é apresentado aos outros no mundo
* `userId`: *(string)* Uma string que identifica o jogador. Para jogadores ligados com uma wallet, corresponde ao endereço da wallet, escrito em minúsculas. Para contas de convidado, é um identificador gerado localmente.
* `isGuest`: *(boolean)* Indica se o jogador tem uma chave pública. *True* se o jogador for uma conta de convidado sem chave pública.
* `position`: *(Vector3)* A posição do Avatar na cena.
* `avatar`: Um objeto aninhado com dados sobre o Avatar base e a aparência do jogador.
* `wearables`: Um array de identificadores de cada wearable que o jogador está a usar atualmente. Por exemplo, `urn:decentraland:off-chain:base-avatars:green_hoodie`. Todos os wearables têm um identificador semelhante, mesmo que sejam NFTs.
* `emotes`: Um array de identificadores de cada emote que o jogador tem atualmente equipado na roda de acesso rápido.
* `entity`: Uma referência à entidade do jogador. Pode ser útil passá-la a outras funções ou adicionar componentes personalizados a ela.

O `avatar` objeto contém as seguintes informações aninhadas:

* `bodyShapeUrn`: Um identificador do formato geral do corpo do avatar. Pode ser `urn:decentraland:off-chain:base-avatars:BaseFemale` para o feminino ou `urn:decentraland:off-chain:base-avatars:BaseMale` para o masculino.
* `skinColor`: A cor da pele do jogador como um `Color3`
* `eyesColor`: A cor dos olhos do jogador como um `Color3`
* `hairColor`: A cor do cabelo do jogador como um `Color3`
* `name`: O nome do jogador.

{% hint style="warning" %}
**📔 Nota**: Os dados do jogador podem não estar disponíveis no primeiro frame da cena, dependendo do tempo de carregamento. Deve verificar se os dados foram retornados e, caso contrário, tentar novamente alguns milissegundos depois.
{% endhint %}

```ts
import { getPlayer } from '@dcl/sdk/src/players'

export function main() {
	createCube(5, 1, 5)

	let myPlayer = getPlayer()

	if (myPlayer) {
		console.log('Is Guest: ', myPlayer.isGuest)
		console.log('Name : ', myPlayer.name)
		console.log('UserId : ', myPlayer.userId)
		console.log('Avatar shape : ', myPlayer.position)
		console.log('Avatar shape : ', myPlayer.avatar?.bodyShapeUrn)
		console.log('Avatar eyes color : ', myPlayer.avatar?.eyesColor)
		console.log('Avatar hair color : ', myPlayer.avatar?.hairColor)
		console.log('Wearables on : ', myPlayer.wearables)
		console.log('Emotes available : ', myPlayer.emotes)
	}
}
```

Para obter os dados de um jogador específico na cena, diferente do jogador atual, execute `getPlayer()` com um objeto que tenha uma propriedade `userId` .

```ts
import { getPlayer } from '@dcl/sdk/src/players'

for (const [entity, data, transform] of engine.getEntitiesWith(
	PlayerIdentityData,
	Transform
)) {
	let player = getPlayer({ userId: data.address })
	console.log('PLAYER : ', player?.name)
}
```

O trecho acima percorre todas as entidades que têm um componente `PlayerIdentityData` , ou seja, todas as entidades de avatar na cena. Em seguida, executa `getPlayer()` para essa entidade.

`getPlayer()` só pode obter dados de jogadores que estejam atualmente na mesma cena. Eles não precisam necessariamente estar no alcance visual, mas devem estar ligados à mesma ilha de comunicação. Para testar isto na pré-visualização, abra um segundo separador e inicie sessão com uma conta diferente, e faça com que ambos os jogadores permaneçam dentro da cena.

{% hint style="warning" %}
**📔 Nota**: Os IDs de utilizador devem estar sempre em minúsculas. Se copiar um endereço de carteira, certifique-se de que todos os caracteres estão em minúsculas.
{% endhint %}

## Dados de qualquer jogador

Para obter informações de qualquer jogador, faça uma chamada à [API REST](https://docs.decentraland.org/creator/content-creator-pt/scenes-sdk7/rede/network-connections.md#call-a-rest-api) para os servidores de conteúdo.

Estas informações são expostas no seguinte URL, acrescentando o ID de utilizador do jogador ao parâmetro do URL.

`https://peer.decentraland.org/lambdas/profile/<player user id>`

{% hint style="info" %}
**💡 Dica**: Experimente o URL num browser para ver como a resposta está estruturada.
{% endhint %}

As seguintes informações estão disponíveis nesta API:

* `displayName`: *(string)* O nome de utilizador do jogador, tal como é visto pelos outros no mundo
* `userId`: *(string)* Uma string UUID que identifica o jogador. Se o jogador tiver uma chave pública, este campo terá o mesmo valor que a chave pública.
* `hasConnectedWeb3`: *(boolean)* Indica se o jogador tem uma chave pública. *Verdadeiro* se o jogador tiver uma.
* `publicKey`: *(string)* A chave pública da carteira Ethereum do jogador. Se o jogador iniciar sessão como convidado, sem uma carteira associada, este campo será `null`.
* `avatar`: Um objeto aninhado com dados sobre a aparência do jogador.
* `version`: *(number)* Um número de versão que aumenta em um sempre que o jogador altera qualquer uma das suas definições. Utilize-o se encontrar dados em conflito, para saber qual é a versão mais recente.

{% hint style="warning" %}
**📔 Nota**: Para quaisquer transações Ethereum com o jogador, utilize sempre o campo `publicKey` em vez do campo `userId`, para evitar lidar com carteiras inexistentes.
{% endhint %}

O `avatar` objeto contém as seguintes informações aninhadas:

* `wearables`: `WearableId[]` Uma matriz de identificadores para cada um dos Wearables que o jogador está a usar. Por exemplo, `urn:decentraland:off-chain:base-avatars:green_hoodie`. Todos os Wearables têm um identificador semelhante, mesmo quando são NFTs.
* `bodyShape`: Um identificador da forma geral do corpo do Avatar. Pode ser `urn:decentraland:off-chain:base-avatars:BaseFemale` para feminino ou `urn:decentraland:off-chain:base-avatars:BaseMale` para masculino.
* `skin`: Um objeto com um campo `color` que contém a cor da pele do jogador como `{ r, g, b, a }` números entre 0 e 1.
* `hair`: Um objeto com um `color` campo que contém a cor do cabelo do jogador como `{ r, g, b, a }` números de 0 a 1.
* `eyes`: Um objeto com um campo `color` que contém a cor dos olhos do jogador como `{ r, g, b, a }` números de 0 a 1.
* `snapshots`: Um objeto aninhado com representações em base64 de imagens .jpg do jogador em várias resoluções.
  * `face256`: *string* O rosto do jogador como uma imagem de 256x256 píxeis.
  * `body`: *string* A imagem do jogador em resolução total, de pé e direito, com 512x1024 píxeis.

{% hint style="danger" %}
**❗Aviso** Os snapshots do avatar serão descontinuados no futuro e deixarão de ser devolvidos como parte dos dados do avatar. A abordagem recomendada é usar `AvatarTexture` em vez disso; consulte [Retratos de Avatar](https://docs.decentraland.org/creator/content-creator-pt/scenes-sdk7/fundamentos-de-conteudo-3d/materials.md#avatar-portraits).
{% endhint %}

Ao contrário de `getPlayer()`, esta opção não se limita apenas aos jogadores que estão atualmente na mesma Scene ou sequer no mesmo Server. Com esta abordagem, pode obter dados de qualquer jogador que tenha iniciado sessão nos servidores anteriormente.

Se souber a que Server está ligado o jogador cujos dados pretende consultar, pode obter dados mais atualizados enviando os pedidos para esse Server específico. Por exemplo, se o jogador mudar de roupa, essa informação fica disponível instantaneamente no Server do jogador, mas é provável que demore alguns minutos a propagar-se para o Server `peer.decentraland.org` .

`https://<player server>/lambdas/profile/<player user id>`

{% hint style="info" %}
**💡 Dica**: Pode obter o Server atual do jogador chamando `getRealm()` e lendo o campo `realmInfo.baseUrl` da resposta.
{% endhint %}

Este exemplo combina `myProfile.userId` e `getRealm()` para obter os dados do jogador diretamente do Server em que este se encontra:

```ts
import { getRealm } from '~system/Runtime'
import { myProfile } from '@dcl/sdk/network'

async function fetchPlayerData() {
	const { realmInfo } = await getRealm({})
	if (!realmInfo) return

	const url = `${realmInfo.baseUrl}/lambdas/profile/${myProfile.userId}`
	console.log('using URL: ', url)

	try {
		const response = await fetch(url)
		const json = await response.json()

		console.log('full response: ', json)
		console.log('player is wearing :', json.avatars[0].avatar.wearables)
	} catch {
		console.log('an error occurred while reaching for player data')
	}
}

fetchPlayerData()
```

## Componentes de dados do jogador

Em vez de usar `getPlayer()`, pode ler os dados diretamente de uma série de componentes que armazenam os dados em cada entidade de jogador. Existem os seguintes componentes:

* `PlayerIdentityData`: Armazena o endereço do jogador e uma propriedade `isGuest` para identificar contas de visitante.
* `AvatarBase`: Armazena dados sobre o avatar base, incluindo:
  * `name`: O nome do jogador.
  * `bodyShapeUrn`: Os IDs correspondentes ao tipo de corpo masculino ou feminino.
  * `skinColor`: A cor da pele do jogador como um `Color3`
  * `eyesColor`: A cor dos olhos do jogador como um `Color3`
  * `hairColor`: A cor do cabelo do jogador como um `Color3`
  * `talking`: *true* quando o jogador está a falar no chat de voz, *false* quando está em silêncio, *undefined* quando o cliente não deteta atividade de voz. Consulte [Detetar quando um jogador está a falar](#detect-when-a-player-is-speaking).
* `AvatarEquippedData`: A lista de wearables e emotes equipados.
  * `wearableUrns`: A lista de wearables que o jogador tem atualmente equipados.
  * `emoteUrns`: A lista de emotes que o jogador tem atualmente equipados na roda de acesso rápido.
* `AvatarEmoteCommand`: Informações sobre os emotes que o jogador está a executar atualmente. Inclui:
  * `emoteUrn`: A URN do último emote executado pelo jogador desde que entrou na cena
  * `loop`: True se o emote estiver em loop
  * `timestamp`: A hora em que este emote foi ativado

```ts
for (const [entity, data, base, attach, transform] of engine.getEntitiesWith(
	PlayerIdentityData,
	AvatarBase,
	AvatarEquippedData,
	Transform
)) {
	console.log('PLAYER DATA: ', { entity, data, transform, base, attach })
}
```

{% hint style="warning" %}
**📔 Nota**: Todos estes componentes são só de leitura. Não pode alterar os respetivos valores na cena.
{% endhint %}

## Detetar quando um jogador está a falar

Leia `talking` no `AvatarBase` componente para saber se alguém está a falar no chat de voz neste momento. Funciona para o jogador que está a executar a scene e para todos os outros jogadores nas proximidades.

```ts
import { AvatarBase, engine } from '@dcl/sdk/ecs'

// regista sempre que o jogador local começa ou deixa de falar
AvatarBase.onChange(engine.PlayerEntity, (base) => {
	console.log('talking: ', base?.talking)
})
```

`talking` tem três estados, não dois:

| Valor       | Significado                                                                                                                          |
| ----------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| `true`      | O jogador está a falar neste momento.                                                                                                |
| `false`     | O jogador não está a falar.                                                                                                          |
| `undefined` | O cliente não está a comunicar a atividade de voz deste jogador, por exemplo, porque o chat de voz nas proximidades está desativado. |

Este terceiro estado é importante: `undefined` significa «sem dados», não «silêncio». Verifique-o explicitamente, em vez de tratar qualquer valor diferente de`true` como silêncio.

```ts
import { AvatarBase, engine, PlayerIdentityData } from '@dcl/sdk/ecs'

function whoIsSpeaking() {
	for (const [player, base] of engine.getEntitiesWith(AvatarBase)) {
		if (base.talking === undefined) continue // sem dados de voz para este jogador
		if (base.talking) console.log(`${base.name} is speaking`)
	}
}

engine.addSystem(whoIsSpeaking)
```

Para colocar um marcador por cima da cabeça de um jogador que está a falar, associe-o com [`AvatarAttach`](https://docs.decentraland.org/creator/content-creator-pt/scenes-sdk7/fundamentos-de-conteudo-3d/entity-positioning.md#attach-to-other-players) usando o endereço de `PlayerIdentityData`. Não defina a entidade do jogador como entidade-pai: isso não funciona e o marcador acaba na origem da scene.

{% hint style="warning" %}
**📔 Nota**: `AvatarBase.talking` comunica a atividade real do chat de voz e não é possível escrever-lhe. É diferente de `AvatarShape.talking`, que é um sinalizador definido pela sua scene para mostrar barras verdes de voz junto de um [avatar NPC](https://docs.decentraland.org/creator/content-creator-pt/scenes-sdk7/interatividade/avatares/npc-avatars.md) que criou.
{% endhint %}

## Obter experiências portáteis

As experiências portáteis são essencialmente scenes que não estão limitadas a parcelas de terreno. Os jogadores podem levá-las consigo para qualquer lugar a que vão em Decentraland, acrescentando uma nova camada de conteúdo ao mundo. Os Smart Wearables são exemplos de experiências portáteis. Poderá querer saber se um jogador está a usar uma destas experiências, uma vez que um Smart Wearable pode permitir que os jogadores tenham capacidades que podem ser consideradas batota num jogo competitivo. Por exemplo, num jogo de plataformas, um jogador que use um jetpack tem uma vantagem muito injusta sobre os outros.

Enquanto criador de uma scene, poderá querer limitar o que os jogadores que usam experiências portáteis podem fazer na sua scene. Use `getPortableExperiencesLoaded()` para verificar se o jogador tem alguma experiência portátil ativada neste momento.

```ts
import { getPortableExperiencesLoaded } from '~system/PortableExperiences'

executeTask(async () => {
	let portableExperiences = await getPortableExperiencesLoaded({})
	console.log(portableExperiences.loaded)
})
```

`getPortableExperiencesLoaded()` devolve uma matriz de objetos; cada um destes objetos inclui um atributo `id` No caso dos wearables, o id é a URN do wearable.

## Obter informações detalhadas sobre os Wearables de um jogador

A função `getPlayer()` devolve apenas uma lista de IDs de Wearables, sem informações sobre cada um. Talvez queira verificar se o jogador tem algum Wearable de uma categoria específica (por exemplo, chapéus) ou de uma raridade específica (por exemplo, Mítico). Para isso, terá de obter informações mais detalhadas sobre os Wearables do jogador.

Faça uma chamada à [API REST](https://docs.decentraland.org/creator/content-creator-pt/scenes-sdk7/rede/network-connections.md#call-a-rest-api) para o seguinte URL, para obter uma lista completa e atualizada de todos os Wearables atualmente utilizáveis, com detalhes sobre cada um.

`${playerRealm.realmInfo.baseUrl}/lambdas/collections/wearables-by-owner/${userData.userId}?includeDefinitions`

{% hint style="warning" %}
**📔 Nota**: Para construir este URL, tem de obter o realm (provavelmente com `getRealm()`) e o ID do jogador (provavelmente com `getPlayer()`)
{% endhint %}

Esta funcionalidade pode ser utilizada em conjunto com a obtenção de informações sobre o jogador, para, por exemplo, só permitir que os jogadores entrem num local se estiverem a usar um Wearable da coleção de Halloween ou qualquer Wearable de raridade *lendária* .

{% hint style="info" %}
**💡 Dica**: Experimente o URL num browser para ver como a resposta está estruturada.
{% endhint %}

```ts
import { getPlayer } from '@dcl/sdk/src/players'
import { getRealm } from '~system/Runtime'

async function fetchWearablesData() {
	try {
		let userData = getPlayer()
		const realm = await getRealm({})
		if (!userData || !realm.realmInfo) return

		const url =
			`${realm.realmInfo?.baseUrl}/lambdas/collections/wearables-by-owner/${userData.userId}?includeDefinitions`.toString()
		console.log('using URL: ', url)

		let response = await fetch(url)
		let json = await response.json()

		console.log('full response: ', json)
	} catch {
		console.log('an error occurred while reaching for wearables data')
	}
}

executeTask(fetchWearablesData)
```

{% hint style="info" %}
**💡 Sugestão**: Pode obter ainda mais informações sobre Wearables específicos através da [API seguinte](https://decentraland.github.io/catalyst-api-specs/#tag/Lambdas/operation/searchWearables).
{% endhint %}

## Verificar o modo de câmara do jogador

Ao explorar Decentraland, os jogadores podem usar uma câmara na primeira ou na terceira pessoa. Verifique qual delas o jogador está a usar consultando o valor do componente `CameraMode` da entidade `engine.CameraEntity` .

```ts
function checkCameraMode() {
	if (!CameraMode.has(engine.CameraEntity)) return

	let cameraEntity = CameraMode.get(engine.CameraEntity)

	if (cameraEntity.mode == CameraType.CT_THIRD_PERSON) {
		console.log('The player is using the 3rd person camera')
	} else {
		console.log('The player is using the 1st person camera')
	}
}

engine.addSystem(checkCameraMode)
```

{% hint style="warning" %}
**📔 Nota**: As informações sobre a câmara só estão disponíveis para o jogador atual que está a executar a Scene. Não é possível consultar os dados da câmara de qualquer outro jogador.
{% endhint %}

O modo de câmara utiliza um valor do enum `CameraType` . São possíveis os seguintes valores:

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

O componente `CameraMode` da entidade `engine.CameraEntity` é só de leitura; não é possível forçar o jogador a alterar o modo de câmara através deste componente.

{% hint style="info" %}
**💡 Sugestão**: Para alterar o modo de câmara do jogador, use uma [área de modificação da câmara](https://docs.decentraland.org/creator/content-creator-pt/scenes-sdk7/fundamentos-de-conteudo-3d/camera.md#1st-and-3rd-person-camera-modes).
{% endhint %}

Saber qual é o modo de câmara pode ser muito útil para ajustar a mecânica da sua cena e torná-la mais confortável de usar nesse modo. Por exemplo, é mais difícil clicar em alvos pequenos na terceira pessoa.

{% hint style="warning" %}
**📔 Nota**: Evite fazer referência a `engine.CameraEntity` durante o carregamento inicial da cena, pois isso pode causar erros se as Entities ainda não tiverem sido inicializadas. Para evitar este problema, use estes elementos dentro da função `main()` ou numa função chamada indiretamente por `main()`. Também pode encapsular o comportamento numa função async [`executeTask` bloco](https://docs.decentraland.org/creator/content-creator-pt/scenes-sdk7/padroes-de-programacao/async-functions.md#the-executetask-function).

Outra opção é referenciar esta entidade num sistema. Estará sempre disponível, porque a primeira execução do sistema ocorre quando a cena já está devidamente inicializada.
{% endhint %}

## Verifique se o jogador tem o cursor bloqueado

Os jogadores podem alternar entre dois modos do cursor: *modo de cursor bloqueado* para controlar a câmara ou *modo de cursor desbloqueado* para mover o cursor livremente pela UI.

Os jogadores desbloqueiam o cursor ao clicar em *Botão direito do rato* ou prima a tecla *Esc* e volte a bloquear o cursor clicando em qualquer ponto do ecrã.

Verifique o `PointerLock` da [entidade de câmara](https://docs.decentraland.org/creator/content-creator-pt/scenes-sdk7/arquitetura/entities-components.md#reserved-entities) da cena para saber qual é o modo atual do cursor.

```ts
export function main() {
	const isLocked = PointerLock.get(engine.CameraEntity).isPointerLocked
	console.log(isLocked)
}
```

Consulte [Event listeners](https://docs.decentraland.org/creator/content-creator-pt/scenes-sdk7/interatividade/event-listeners.md#player-locks-or-unlocks-cursor) para saber como reagir facilmente a alterações no estado do cursor.

Também pode forçar o estado do cursor do jogador escrevendo no campo `isPointerLocked` do componente `PointerLock` em `engine.CameraEntity`. 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) para ver exemplos.

{% hint style="warning" %}
**📔 Nota**: Evite fazer referência a `engine.CameraEntity` durante o carregamento inicial da cena, pois isso pode causar erros se as Entities ainda não tiverem sido inicializadas. Para evitar este problema, use estes elementos dentro da função `main()` ou numa função chamada indiretamente por `main()`. Também pode encapsular o comportamento numa função async [`executeTask` bloco](https://docs.decentraland.org/creator/content-creator-pt/scenes-sdk7/padroes-de-programacao/async-functions.md#the-executetask-function).

Outra opção é referenciar a entidade dentro de um sistema. Ela estará sempre disponível, pois a primeira execução do sistema ocorre quando a cena já está devidamente inicializada.
{% endhint %}

## Verificar a posição do cursor do jogador

Use o `PrimaryPointerInfo` componente na `engine.RootEntity` para obter a posição do cursor do jogador. Isso pode ser usado em mecânicas como interações de arrastar e soltar, gestos de deslizar etc.

```ts
import { PrimaryPointerInfo } from '@dcl/sdk/ecs'

function CursorSystem() {
	const pointerInfo = PrimaryPointerInfo.get(engine.RootEntity)
	console.log(pointerInfo)
}

engine.addSystem(CursorSystem)
```

{% hint style="warning" %}
**📔 Nota**: Evite fazer referência a `engine.RootEntity` durante o carregamento inicial da cena, pois isso pode resultar em erros se as Entities ainda não tiverem sido inicializadas. Para evitar esse problema, faça sempre referência à Entity dentro de um System. Ela estará sempre disponível, porque a primeira execução do System ocorre quando a cena já está devidamente inicializada.
{% endhint %}

O `PrimaryPointerInfo` Component devolve um objeto com as seguintes propriedades:

* `screenCoordinates`: *(Vector2)* A posição do cursor na cena, expressa em píxeis. A origem é o canto superior esquerdo do ecrã, com `y` aumentando para baixo — o mesmo espaço de coordenadas que `UiTransform` e `UiCanvasInformation`. Quando o cursor está bloqueado, indica o centro do ecrã.
* `screenDelta`: *(Vector2)* A alteração da posição do cursor desde o último frame, expressa em píxeis. Consulte [Movimento do rato](https://docs.decentraland.org/creator/content-creator-pt/scenes-sdk7/interatividade/mouse-movement.md) para obter detalhes e exemplos.
* `worldRayDirection`: *(Vector3)* Um vetor que representa a direção do raio entre a câmara e o cursor. A origem é a posição da câmara. Utilize-o para calcular a posição do cursor no mundo.
* `pointerType`: 0 para `none`, 1 para `mouse`

{% hint style="info" %}
**💡 Sugestão**: Ao contrário das outras propriedades, `screenDelta` continua a indicar o movimento do rato mesmo 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). Isto torna-o ideal para interações em tempo real, como gestos de arrastar e controlos de câmara personalizados. Consulte [Movimento do rato](https://docs.decentraland.org/creator/content-creator-pt/scenes-sdk7/interatividade/mouse-movement.md).
{% endhint %}

{% hint style="info" %}
**Sugestão:** Para reagir a eventos simples de passagem do cursor sobre elementos da UI, poderá ser mais fácil utilizar os eventos `onMouseEnter` e `onMouseLeave` . Consulte [Eventos de botões da UI](https://docs.decentraland.org/creator/content-creator-pt/scenes-sdk7/ui-2d/ui_button_events.md#hover-feedback).
{% endhint %}

O `PrimaryPointerInfo` o componente é somente leitura; não é possível forçar o jogador a alterar a posição do cursor.

O exemplo a seguir mostra como exibir a posição do cursor em um elemento de UI.

***ficheiro ui.tsx:***

```tsx
import { UiEntity, ReactEcs } from '@dcl/sdk/react-ecs'
import { Color4 } from '@dcl/sdk/math'
import {cursorXpos, cursorYpos} from './index'

export const uiMenu = () => (
  <UiEntity
    uiTransform={{
			width: '100%',
			height: '100px',
			justifyContent: 'center',
			alignItems: 'center',
    }}
    uiText={{ value: `Cursor pos: `+  cursorXpos + `,` + cursorYpos, fontSize: 40 }}
    uiBackground={{ color: Color4.create(0.5, 0.8, 0.1, 0.6) }}
  />
)
```

***ficheiro index.ts:***

```ts
import { engine, PrimaryPointerInfo } from '@dcl/sdk/ecs'
import { ReactEcsRenderer } from '@dcl/sdk/react-ecs'
import { uiMenu } from './ui'

export function main() {
  ReactEcsRenderer.setUiRenderer(uiMenu)
}

export let cursorXpos: number | undefined = undefined
export let cursorYpos: number | undefined = undefined

function CursorSystem() {
  const pointerInfo = PrimaryPointerInfo.get(engine.RootEntity)
  console.log(pointerInfo)

  cursorXpos = pointerInfo.screenCoordinates?.x
  cursorYpos = pointerInfo.screenCoordinates?.y
}

engine.addSystem(CursorSystem)
```

Pode usar `worldRayDirection` para definir o campo `direction` de um raycast e verificar se uma entidade está na linha de visão do cursor. Consulte [Raycasting](https://docs.decentraland.org/creator/content-creator-pt/scenes-sdk7/interatividade/raycasting.md) para mais detalhes.


---

# 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/user-data.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.
