> 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/eventos-de-botao/click-events.md).

# Eventos de Clique

Saiba como lidar com cliques de usuário na sua scene.

Uma cena de Decentraland pode detetar ações de entrada de todos os botões usados para controlar o avatar do jogador. Estas incluem cliques do ponteiro, vários botões de ação e as teclas usadas para mover o avatar. Os eventos dos botões podem ter origem num rato e teclado no cliente para computador, nos controlos apresentados no ecrã da [app para dispositivos móveis](https://docs.decentraland.org/creator/content-creator-pt/criar-para-mobile/cliente-movel/overview.md), num controlador de RV ou noutros dispositivos de entrada — o SDK interpreta todos da mesma forma.

Pode detetar ações de entrada dirigidas a uma entidade. Isto implica premir um botão enquanto o cursor do jogador aponta para o Collider dessa entidade. Também pode detetar um evento de entrada *global* , que implica ativar a entrada em qualquer momento, sem ter em conta para onde o ponteiro está apontado.

{% hint style="warning" %}
**📔 Nota**: As entidades têm de ter um [Collider](https://docs.decentraland.org/creator/content-creator-pt/scenes-sdk7/fundamentos-de-conteudo-3d/colliders.md) para responderem a ações de entrada. `MeshRenderer` também têm de receber um componente `MeshCollider` . Os modelos de um `GltfContainer` podem ter a sua própria geometria de colisão incorporada ou ser configurados para usar a geometria visível. Também podem receber um `MeshCollider` componente.
{% endhint %}

Há várias formas de processar ações de entrada, dependendo do caso de utilização.

* [**Registar um callback**](https://docs.decentraland.org/creator/content-creator-pt/scenes-sdk7/interatividade/eventos-de-botao/register-callback.md): A forma mais fácil de adicionar interação a uma única entidade. Escreva uma única instrução para configurar uma função callback e o feedback ao passar o cursor.
* [**Baseada em System**](https://docs.decentraland.org/creator/content-creator-pt/scenes-sdk7/interatividade/eventos-de-botao/system-based-events.md): Ideal para processar várias entidades com comportamentos semelhantes. Use um System para iterar pelas entidades semelhantes e consultar as ações de entrada de cada uma, processando-as todas com a mesma lógica. O feedback ao passar o cursor tem de ser configurado separadamente. Esta abordagem também é necessária para processar ações de entrada globais.
* [**Avançado**](https://docs.decentraland.org/creator/content-creator-pt/scenes-sdk7/interatividade/eventos-de-botao/advanced-button-events.md): Leia os dados da resposta bruta de cada entidade, incluindo marcas temporais e um histórico de eventos de entrada. Isto pode ser útil para definir padrões de interação personalizados.

## Use o Scene Editor no Creator Hub

A forma mais fácil de processar eventos de clique numa entidade é usar o Scene Editor. Use os **Ao clicar** ou **Ao executar uma ação de entrada** Triggers sem código num item para chamar ações ao clicar nele. Ou use **Ao clicar globalmente**, **Ao executar uma ação primária global** ou **Ao executar uma ação secundária global** Triggers para reagir a eventos globais dos botões. Consulte [Tornar qualquer item inteligente](https://docs.decentraland.org/creator/content-creator-pt/scene-editor/interatividade/make-any-item-smart.md).

## Exemplo simples

Para detetar cliques numa entidade, use `pointerEventsSystem.onPointerDown`.

```ts
pointerEventsSystem.onPointerDown(
	{
		entity: myEntity,
		opts: { button: InputAction.IA_PRIMARY, hoverText: 'Click' },
	},
	function () {
		console.log('clicked entity')
	}
)
```

Consulte [**Registar um callback**](https://docs.decentraland.org/creator/content-creator-pt/scenes-sdk7/interatividade/eventos-de-botao/register-callback.md) para obter mais informações.

## Feedback ao passar o cursor

É importante dar a conhecer aos jogadores que uma entidade é interativa. Caso contrário, podem não descobrir a experiência que criou. Não é uma boa experiência clicar em todos os objetos na esperança de que algum reaja.

Quando usa o método [**Registar um callback**](https://docs.decentraland.org/creator/content-creator-pt/scenes-sdk7/interatividade/eventos-de-botao/register-callback.md) , são apresentados dois tipos de feedback sempre que o jogador passa o cursor sobre o objeto:

* O contorno da entidade é realçado (apenas no cliente Decentraland 2.0 para computador). O realce fica verde se a entidade estiver suficientemente perto para poder clicar nela e vermelho se estiver demasiado longe.
* É apresentada uma dica junto ao cursor com texto de UI que indica o que acontecerá se o jogador clicar.

Ao usar o [**Com base em sistemas**](https://docs.decentraland.org/creator/content-creator-pt/scenes-sdk7/interatividade/eventos-de-botao/system-based-events.md) Com este método, pode obter os mesmos resultados adicionando um `PointerEvents` component às Entities clicáveis.

Tanto o realce da Entity como a dica apresentada ao passar o cursor podem ser desativados através de propriedades destes métodos e Components.

O contorno realça a Entity cujo Collider está sob o cursor, bem como todos os filhos dessa Entity. Nunca contorna a Entity ascendente nem as respetivas Entities irmãs. Só as formas de um `MeshRenderer` e os modelos de um `GltfContainer` são contornados; `o texto de` TextShape

Também pode implementar [dicas personalizadas avançadas](https://docs.decentraland.org/creator/content-creator-pt/scenes-sdk7/interatividade/eventos-de-botao/system-based-events.md#advanced-custom-hints), por exemplo, pode reproduzir um som ou fazer com que a Entity mude de cor, rode ou aumente de tamanho enquanto o cursor está sobre ela, entre outras coisas. Seja o que for que faça, certifique-se de que é um indicador claro.

## Obstáculos

Os eventos de botão lançam raios que só interagem com a primeira Entity no seu percurso que esteja subscrita à camada de colisão dos eventos de ponteiro. Isto aplica-se desde que a Entity esteja dentro dos limites de distância. Se a Entity definir limites de distância para a câmara e para o Avatar, basta que esteja suficientemente perto de uma delas.

Registe o evento de ponteiro na mesma Entity que tem o Collider. Um evento de ponteiro registado numa Entity ascendente, ou numa Entity filha sem Collider próprio, nunca é acionado.

Para que o raio de um evento de ponteiro intersete uma Entity, esta tem de cumprir uma das seguintes condições:

* O modelo tem de conter [Meshes de Collider](https://docs.decentraland.org/creator/content-creator-pt/modelacao-3d-e-animacoes/colliders.md).
* O `GltfContainer` tem de estar configurado para usar a [geometria visível com máscaras de colisão](https://docs.decentraland.org/creator/content-creator-pt/scenes-sdk7/fundamentos-de-conteudo-3d/colliders.md#colliders-on-3d-models).
* A Entity tem de ter um [Component MeshCollider](https://docs.decentraland.org/creator/content-creator-pt/scenes-sdk7/fundamentos-de-conteudo-3d/colliders.md).

Se o Collider de outra Entity estiver no caminho da Entity com a qual o jogador quer interagir, o jogador não poderá clicar na Entity que está atrás, a menos que esta não tenha Collider ou que o Collider esteja configurado para não responder à camada de colisão dos eventos de ponteiro.

```ts
// Entity clicável
const clickableEntity = engine.addEntity()
MeshRenderer.setBox(clickableEntity)
MeshCollider.setBox(clickableEntity)
Transform.create(clickableEntity, { position: Vector3.create(8, 1, 8) })

pointerEventsSystem.onPointerDown(
	{
		entity: clickableEntity,
		opts: {
			button: InputAction.IA_POINTER,
			hoverText: 'Clicar',
		},
	},
	function () {
		console.log('clicked entity')
		const t = Transform.getMutable(clickableEntity)
		t.scale.y += 0.2
	}
)

// não bloqueia cliques
const nonBlocker = engine.addEntity()
MeshRenderer.setBox(nonBlocker)
MeshCollider.setBox(nonBlocker, ColliderLayer.CL_PHYSICS)
Transform.create(nonBlocker, { position: Vector3.create(10, 1, 8) })

// bloqueia cliques
const blocker = engine.addEntity()
MeshRenderer.setBox(blocker)
MeshCollider.setBox(blocker, ColliderLayer.CL_POINTER)
Transform.create(blocker, { position: Vector3.create(8, 1, 10) })
```

{% hint style="warning" %}
**📔 Nota**: Para além de intercetar um evento de ponteiro, uma Entity também precisa de ter um `PointerEvents` Component. O `pointerEventsSystem` os helpers também tratam deste requisito.
{% endhint %}

## Botões do ponteiro

As seguintes entradas podem ser processadas por qualquer uma das abordagens de deteção de eventos de entrada.

* `InputAction.IA_POINTER`: **botão esquerdo do rato** num computador, **botão de interação** em dispositivos móveis.
* `InputAction.IA_PRIMARY`: **E** tecla num computador, **botão E** em dispositivos móveis.
* `InputAction.IA_SECONDARY`: **F** tecla num computador, **botão F** em dispositivos móveis.
* `InputAction.IA_ACTION_3`: **1** tecla num computador, **botão 1** em dispositivos móveis. *Oculto por predefinição em dispositivos móveis (SDK 7.32.0+) — use-o apenas se a sua cena o mostrar com `TouchScreenControls`.*
* `InputAction.IA_ACTION_4`: **2** tecla num computador, **botão 2** em dispositivos móveis. *Oculto por predefinição em dispositivos móveis (SDK 7.32.0+) — use-o apenas se a sua cena o mostrar com `TouchScreenControls`.*
* `InputAction.IA_ACTION_5`: **3** tecla num computador, **botão 3** em dispositivos móveis. *Oculto por predefinição em dispositivos móveis (SDK 7.32.0+) — use-o apenas se a sua cena o mostrar com `TouchScreenControls`.*
* `InputAction.IA_ACTION_6`: **4** tecla num computador, **botão 4** em dispositivos móveis. *Oculto por predefinição em dispositivos móveis (SDK 7.32.0+) — use-o apenas se a sua cena o mostrar com `TouchScreenControls`.*
* `InputAction.IA_JUMP`: **Barra de espaço** tecla num computador, **botão de salto** em dispositivos móveis.
* `InputAction.IA_FORWARD`: **W** tecla num computador.
* `InputAction.IA_LEFT`: **A** tecla num computador.
* `InputAction.IA_RIGHT`: **D** tecla num computador.
* `InputAction.IA_BACKWARD`: **S** tecla num computador.
* `InputAction.IA_WALK`: **Control** tecla num computador.
* `InputAction.IA_MODIFIER`: **Shift** tecla num computador.

Cada `InputAction` é abstraída da entrada literal do teclado para que possa ser associada a diferentes entradas, consoante o dispositivo. Pelo mesmo motivo, nem todos os botões do teclado podem ser monitorizados para eventos de botão; apenas os botões utilizados para movimento e interação. Esta limitação intencional garante que o conteúdo é compatível entre o computador, o [cliente para dispositivos móveis](https://docs.decentraland.org/creator/content-creator-pt/criar-para-mobile/cliente-movel/overview.md), e dispositivos futuros, como comandos de RV e outros comandos de jogos.

{% hint style="warning" %}
**📱 Dispositivos móveis**: No [cliente para dispositivos móveis](https://docs.decentraland.org/creator/content-creator-pt/criar-para-mobile/cliente-movel/overview.md), cada ação de entrada pode ser associada a um botão no ecrã, mas, por predefinição, são apresentados apenas três botões: `IA_POINTER` (botão de interação), `IA_PRIMARY` (botão E) e `IA_JUMP`. `IA_SECONDARY` (F) e `IA_ACTION_3`–`IA_ACTION_6` (os `1`/`2`/`3`/`4` botões) ficam ocultos inicialmente (SDK 7.32.0 e versões posteriores; SDKs mais antigos mostram os oito, com os últimos agrupados num menu de excesso acessível através de "+"). Ao criar conteúdo para dispositivos móveis, dê preferência a `IA_POINTER`, `IA_PRIMARY` e `IA_JUMP` para as ações principais. Se precisar do botão F ou de um botão numerado, apresente-o com [Controlos no ecrã](https://docs.decentraland.org/creator/content-creator-pt/scenes-sdk7/interatividade/touch-screen-controls.md). Consulte [Entrada em dispositivos móveis](https://docs.decentraland.org/creator/content-creator-pt/criar-para-mobile/desenvolver/input-on-mobile.md).
{% endhint %}

## Tipos de eventos de ponteiro

Cada entrada pode gerar os seguintes tipos de eventos de ponteiro. Cada um dos seguintes é um valor da `PointerEventType` enumeração.

* `PET_DOWN`: O jogador prime um botão específico enquanto o cursor aponta para o collider da Entity.
* `PET_UP`: O jogador solta um botão específico enquanto o cursor aponta para o collider da Entity.
* `PET_HOVER_ENTER`: O cursor do jogador começa a apontar para o Collider da Entity.
* `PET_HOVER_LEAVE`: O cursor do jogador deixa de apontar para o Collider da Entity.
* `PET_PROXIMITY_ENTER`: O jogador entra no raio de proximidade da Entity, independentemente da direção para a qual está a olhar.
* `PET_PROXIMITY_LEAVE`: O jogador sai do raio de proximidade da Entity.

Consulte [**Eventos de proximidade**](https://docs.decentraland.org/creator/content-creator-pt/scenes-sdk7/interatividade/eventos-de-botao/proximity-events.md) para saber como usar interações baseadas em proximidade.

## Dados de uma ação de entrada

Todas as ações de entrada incluem dados sobre o evento, incluindo informações como o botão que foi ativado e para onde o Pointer estava a apontar nesse momento.

É possível obter as seguintes informações de qualquer evento de entrada:

* `analog`: Número opcional, presente apenas em eventos de uma entrada analógica (como um joystick), que guarda o valor analógico da entrada.
* `button`: O ID do botão que foi premido. O número corresponde ao enum `InputAction` , que lista todos os botões disponíveis.
* `state`: Tipo de evento de ponteiro, do enum `PointerEventType`. *0* refere-se a `PointerEventType.PET_UP`, *1* a `PointerEventType.PET_DOWN`, *2* a `PointerEventType.PET_HOVER_ENTER`, *3* a `PointerEventType.PET_HOVER_LEAVE`, *4* a `PointerEventType.PET_PROXIMITY_ENTER`, *5* a `PointerEventType.PET_PROXIMITY_LEAVE`
* `timestamp`: Um [timestamp Lamport](https://en.wikipedia.org/wiki/Lamport_timestamp) para identificar cada evento de botão.

  > Nota: este timestamp não é calculado com base na hora atual. Pense nele como um contador que começa em 0 e aumenta em 1 a cada evento.
* `hit`: Um objeto que contém os seguintes dados sobre o evento de colisão:
  * `entityId`: O número de ID da entidade atingida pelo raio.
  * `meshName`: *String* com o nome interno da malha específica do modelo 3D atingida. Isto é útil quando um modelo 3D é composto por várias malhas.
  * `globalOrigin`: *Vector3* para a posição de origem do raio (em relação à cena)
  * `direction`: *Vector3* com o vetor de direção do raio, em coordenadas globais
  * `position`: *Vector3* para a posição em que o raio intersectou a entidade atingida (em relação à cena)
  * `length`: Comprimento do raio desde a sua origem até à posição em que ocorreu a colisão com a entidade.
  * `normalHit`: *Vector3* com um vetor de direção normalizado, que descreve o ângulo da normal do impacto no espaço global.

A forma de aceder a estes dados depende da abordagem usada para processar as ações de entrada.

Com a abordagem [**Registar um callback**](https://docs.decentraland.org/creator/content-creator-pt/scenes-sdk7/interatividade/eventos-de-botao/register-callback.md) , o primeiro parâmetro passado à função callback contém toda esta estrutura de dados.

```ts
pointerEventsSystem.onPointerDown({ entity: myEntity }, function (cmd) {
	console.log(cmd.hit?.entityId)
})
```

Com a abordagem [**baseada em System**](https://docs.decentraland.org/creator/content-creator-pt/scenes-sdk7/interatividade/eventos-de-botao/system-based-events.md) , use `inputSystem.getInputCommand()` para obter estes dados.

```ts
engine.addSystem(() => {
	const cmd = inputSystem.getInputCommand(
		InputAction.IA_POINTER,
		PointerEventType.PET_DOWN,
		myEntity
	)
	if (cmd) {
		console.log(cmd.hit?.entityId)
	}
})
```

{% hint style="warning" %}
**📔 Nota**: Para além de intercetar um evento de ponteiro, uma Entity também precisa de ter um `PointerEvents` Component. O `pointerEventsSystem` os helpers também tratam deste requisito.
{% endhint %}

Com a abordagem [**Avançada**](https://docs.decentraland.org/creator/content-creator-pt/scenes-sdk7/interatividade/eventos-de-botao/advanced-button-events.md) , o `PointerEventsResult` contém uma lista com o histórico recente de todos os eventos do Pointer ocorridos nessa Entity.

```ts
engine.addSystem(() => {
	for (const [entity] of engine.getEntitiesWith(PointerEventsResult)) {
		const pointerEvents = PointerEventsResult.get(entity)

		for (const event of pointerEvents) {
			console.log(event.hit?.entityId)
		}
	}
})
```

## Bloquear ou desbloquear o cursor

{% hint style="info" %}
**💡 Nota**: `PointerLock` é um conceito do cliente para computador (cursor do rato bloqueado ou desbloqueado). Não tem efeito na [aplicação móvel](https://docs.decentraland.org/creator/content-creator-pt/criar-para-mobile/cliente-movel/overview.md), onde a entrada é feita por toque.
{% endhint %}

Os jogadores no cliente para computador do Decentraland podem alternar entre dois modos de interação distintos com o cursor:

* Cursor bloqueado: mover o rato desloca a câmara, e os eventos de clique ocorrem na mira ao centro do ecrã
* Cursor desbloqueado: o cursor move-se livremente, sem depender da câmara, e os jogadores podem clicar em qualquer parte do ecrã para interagir com o espaço 3D ou com a UI

Estes modos de interação são ideais para diferentes tipos de mecânicas de jogo, e pode querer fazer com que os jogadores adotem um ou outro, consoante o que melhor se adequa à sua Scene. Também pode querer garantir temporariamente que o cursor do jogador está desbloqueado para permitir a interação com uma UI. Isto é especialmente útil para jogadores novos que não estão familiarizados com este controlo.

Para alterar o estado do cursor do jogador, use `PointerLock` componente na `engine.CameraEntity` entidade.

```ts
import {PointerLock} from '@dcl/sdk/ecs'
    
PointerLock.createOrReplace(engine.CameraEntity, {isPointerLocked: false})
```

{% hint style="warning" %}
**📔 Nota**: O engine fornece um `PointerLock` componente na `engine.CameraEntity` por predefinição. Use `createOrReplace()` ou `getMutable()` em vez de `create()`, que gera um erro se o componente já existir.
{% endhint %}

Também pode consultar o estado do cursor do jogador lendo o estado do componente `PointerLock` .

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

const isPointerLocked = PointerLock.getOrNull(engine.CameraEntity)?.isPointerLocked
```

Use a função `.onChange` para reagir a alterações no estado do ponteiro. O exemplo seguinte garante que o cursor está sempre desbloqueado.

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

export function main() {

    PointerLock.createOrReplace(engine.CameraEntity, {isPointerLocked: false});

    PointerLock.onChange(engine.CameraEntity, (pointerLock) => {
		    if (!pointerLock) return
		    if(pointerLock.isPointerLocked){
			    PointerLock.getMutable(engine.CameraEntity).isPointerLocked = false
		   }
	})
}
```


---

# 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/eventos-de-botao/click-events.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.
