> 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/register-callback.md).

# Registrar Callback

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

A forma mais simples de gerir eventos de botão é registar uma função de callback para uma entidade específica. Sempre que essa entidade é alvo de uma interação com um botão específico, a função de callback é chamada.

Se precisar de adicionar o mesmo comportamento a várias entidades semelhantes, considere usar a abordagem [baseada em System](https://docs.decentraland.org/creator/content-creator-pt/scenes-sdk7/interatividade/eventos-de-botao/system-based-events.md) em vez de adicionar callbacks a cada entidade. A abordagem baseada em System pode ser mais eficiente, pois permite iterar sobre uma lista de entidades semelhantes.

A abordagem de registar callbacks é especialmente útil se quiser descrever um comportamento que afeta uma única entidade, pois é mais direta.

{% hint style="warning" %}
**📔 Nota**:\
Para que uma entidade seja interativa, **tem** de ter um [collider](https://docs.decentraland.org/creator/content-creator-pt/scenes-sdk7/fundamentos-de-conteudo-3d/colliders.md). Consulte [obstacles](https://docs.decentraland.org/creator/content-creator-pt/scenes-sdk7/interatividade/eventos-de-botao/click-events.md#obstacles) para obter mais informações.
{% endhint %}

## Premir o ponteiro

Use `pointerEventsSystem.onPointerDown()` para detetar o premir de um botão específico.

Esta instrução requer dois parâmetros:

* `data`: Um objeto que contém o seguinte:
  * `entity`: A entidade a gerir
  * `opts`: Um objeto com dados adicionais opcionais:
    * `button`: O botão a detetar. Consulte [Botões do ponteiro](https://docs.decentraland.org/creator/content-creator-pt/scenes-sdk7/interatividade/eventos-de-botao/click-events.md#pointer-buttons) para ver as opções suportadas. Se não for especificado nenhum botão, são detetados todos os botões, incluindo os botões de movimento, como avançar e saltar.
    * `maxDistance`: A distância máxima entre a entidade e o **avatar**, em metros. O valor predefinido é 10. Consulte [Limites de distância](#distance-limits).
    * `maxCameraDistance`: A distância máxima entre a entidade e a **câmara ativa**, em metros. Não está definido por predefinição. Consulte [Limites de distância](#distance-limits).
    * `hoverText`: O texto a apresentar na dica de feedback ao passar o cursor. O valor predefinido é "Interagir".
    * `showFeedback`: Se for false, oculta tanto a dica ao passar o cursor como o contorno realçado desta entidade. *true* por predefinição.
    * `showHighlight`: Se for true, os jogadores verão o contorno realçado quando passarem o cursor sobre a entidade. *true* por predefinição. Este valor só é considerado se `showFeedback` for *true*.
* `cb`: Uma função de callback a executar sempre que ocorrer um evento de botão premido enquanto aponta para a entidade

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

O comando acima mantém a função de callback registada, que será chamada sempre que ocorrer o evento de botão associado. Tenha em atenção que a callback tem de ser uma função síncrona; `async` não são suportadas aqui e resultam num erro.

{% hint style="warning" %}
**📔 Nota**:\
Só pode ser registado um `pointerEventsSystem.onPointerDown` por entidade. Depois de adicionado, continuará a escutar eventos até o listener ser removido. Não o execute repetidamente dentro de um sistema, pois isso reescreveria continuamente o comportamento dos eventos do ponteiro.
{% endhint %}

## Feedback ao passar o cursor

É muito importante dar aos jogadores algum tipo de indicação de que é possível interagir com uma entidade.

Ao registar uma ação de entrada com o `EventsSystem`, por predefinição, os jogadores verão:

* Um contorno luminoso na entidade
* Uma indicação ao passar o cursor, junto ao cursor, com um ícone do botão que têm de premir e o texto «Interagir».

É possível ativar, desativar e personalizar estes elementos.

O feedback ao passar o cursor na UI apresenta um ícone diferente consoante a entrada selecionada no campo `button` . No PC, apresenta um ícone com `E` para `InputAction.IA_PRIMARY`, um `F` para `InputAction.IA_SECONDARY`e um rato para `InputAction.IA_POINTER`.

Altere o texto modificando o valor de `hoverText` . Mantenha este texto curto, para que seja rápido de ler e não ocupe demasiado espaço no ecrã.

```ts
pointerEventsSystem.onPointerDown(
	{
		entity: myEntity,
		opts: { button: InputAction.IA_PRIMARY, hoverText: 'Open door' },
	},
	function () {
		// abrir a porta
	}
)
```

Para ocultar a indicação ao passar o cursor, mas manter o contorno luminoso, defina o valor de `hoverText` como "".

```ts
pointerEventsSystem.onPointerDown(
  {entity: myEntity, opts: { button: InputAction.IA_PRIMARY, hoverText: ''}},
  function () {
    console.log("clicked on surprise interactive item")
  }
)
```

Para ocultar o contorno luminoso, mas manter a indicação ao passar o cursor, defina `showHighlight` como *false*.

```ts
pointerEventsSystem.onPointerDown(
	{
		entity: myEntity,
		opts: {
			button: InputAction.IA_PRIMARY,
			hoverText: 'Open door',
			showHighlight: false,
		},
	},
	function () {
		console.log('opened secret door')
	}
)
```

Para ocultar tanto a indicação ao passar o cursor como o contorno luminoso, defina `showFeedback` como *false* . Ao fazer isso, o cursor não mostra ícones, texto nem qualquer destaque nas bordas.

```ts
pointerEventsSystem.onPointerDown(
  {entity: myEntity, opts: { button: InputAction.IA_PRIMARY, showFeedback: false}},
  function () {
    console.log("opened secret door")
  }
)
```

### Alterar o feedback existente

Ao registar uma ação de entrada com o `EventsSystem`, isto cria um componente `PointerEvents` e adiciona-o à entidade interativa em segundo plano. Este componente controla o comportamento da indicação de passagem do cursor na UI. Para alterar o comportamento do feedback ao passar o cursor, modifique este componente. Consulte [Mostrar feedback](https://docs.decentraland.org/creator/content-creator-pt/scenes-sdk7/interatividade/eventos-de-botao/system-based-events.md#show-feedback) para saber mais sobre como lidar com este componente.

```ts
const hoverFeedback = PointerEvents.getMutable(myEntity)

if (hoverFeedback.pointerEvents[0]?.eventInfo) {
	hoverFeedback.pointerEvents[0].eventInfo.hoverText = 'Close door'
}
```

## Limites de distância

Por predefinição, um jogador só pode interagir com uma entidade quando o seu **avatar** está a menos de 10 metros dela. Se o jogador estiver demasiado longe, o efeito de destaque da entidade fica vermelho em vez de verde e os eventos do ponteiro não são acionados.

Use `maxDistance` para alterar esse alcance:

```ts
// Só é possível clicar quando o avatar do jogador está a menos de 5 metros
pointerEventsSystem.onPointerDown(
	{ entity: myEntity, opts: { maxDistance: 5 } },
	function () {
		console.log('clicked entity')
	}
)
```

### Limitar pela distância da câmara

`maxCameraDistance` mede a distância a partir da **câmara atualmente ativa** em vez do avatar. Isto é útil quando a sua cena usa uma [Virtual Camera](https://docs.decentraland.org/creator/content-creator-pt/scenes-sdk7/fundamentos-de-conteudo-3d/camera.md#using-virtual-cameras) colocada longe do jogador e pretende que seja possível clicar na entidade com base no que a câmara consegue ver.

```ts
// Só é possível clicar quando a câmara ativa está a menos de 15 metros
pointerEventsSystem.onPointerDown(
	{ entity: myEntity, opts: { maxCameraDistance: 15 } },
	function () {
		console.log('clicked entity')
	}
)
```

### Como os dois limites são combinados

As duas opções são verificações independentes. As verificações executadas dependem das opções que definir:

| O que definir              | O que é necessário para o jogador                        |
| -------------------------- | -------------------------------------------------------- |
| Nenhuma                    | Avatar a menos de 10 metros (predefinição)               |
| `maxDistance` apenas       | Avatar a menos de `maxDistance`                          |
| `maxCameraDistance` apenas | Câmara a menos de `maxCameraDistance`                    |
| Ambas                      | **Qualquer uma** basta que uma verificação seja aprovada |

Definir ambas é uma forma de dizer «perto o suficiente para se aproximar a pé, **ou** perto o suficiente para a ver claramente":

```ts
// Clicável quando o avatar estiver a menos de 3 metros OU a câmara a menos de 20 metros
pointerEventsSystem.onPointerDown(
	{ entity: myEntity, opts: { maxDistance: 3, maxCameraDistance: 20 } },
	function () {
		console.log('clicked entity')
	}
)
```

{% hint style="warning" %}
**📔 Nota**: `maxCameraDistance` requer `@dcl/sdk` versão 7.28.0 ou posterior. O suporte já está disponível no Explorer baseado em Bevy. Se a sua cena tiver de se comportar de forma idêntica em todos os clientes atualmente, use `maxDistance` e considere `maxCameraDistance` uma melhoria.
{% endhint %}

### maxPlayerDistance está obsoleto

`maxPlayerDistance` é um alias obsoleto de `maxDistance`: ambos medem a distância a partir do avatar. Use `maxDistance` em cenas novas.

Se uma cena definir ambos, será usado o valor **maior** dos dois como limite de distância do avatar.

## Ao soltar o botão do ponteiro

Use `pointerEventsSystem.onPointerUp` para registar uma função de callback que é chamada quando o jogador indicado solta o botão enquanto aponta para a entidade.

```ts
pointerEventsSystem.onPointerUp(
	{
		entity: myEntity,
		opts: { button: InputAction.IA_PRIMARY, hoverText: 'Button up' },
	},
	function () {
		console.log('button up')
	}
)
```

Esta instrução requer dois parâmetros:

* `data`: Um objeto que contém o seguinte:
  * `entity`: A entidade a gerir
  * `opts`: Um objeto com dados adicionais opcionais:
    * `button`: O botão a detetar. Consulte [Botões do ponteiro](https://docs.decentraland.org/creator/content-creator-pt/scenes-sdk7/interatividade/eventos-de-botao/click-events.md#pointer-buttons) para ver as opções suportadas. Se não for especificado nenhum botão, são detetados todos os botões, incluindo os botões de movimento, como avançar e saltar.
    * `hoverText`: O texto a apresentar na dica de feedback ao passar o cursor. O valor predefinido é "Interagir".
    * `showFeedback`: se for false, oculta a dica de passar o cursor sobre esta entidade. *true* por predefinição.
    * `maxDistance`: a distância máxima, em metros, a que o avatar do jogador pode estar da entidade e ainda interagir com ela. O valor predefinido é 10. Se o jogador estiver demasiado longe, não haverá feedback ao passar o cursor e os eventos do ponteiro não funcionarão. Consulte [Limites de distância](#distance-limits).
* `cb`: uma função de callback a executar sempre que ocorrer um evento de soltar o botão enquanto se aponta para a entidade.

É possível registar dois callbacks diferentes na mesma entidade: um para `pointerEventsSystem.onPointerDown` e outro para `pointerEventsSystem.onPointerUp`. A entidade só pode registar um callback de cada tipo; consulte [Processar vários botões](#handle-multiple-buttons) para detetar botões diferentes num único callback.

{% hint style="warning" %}
**📔 Nota**: o feedback ao passar o cursor para um evento de soltar o botão só é apresentado enquanto o botão estiver premido. Se o jogador apontar para a entidade sem manter o botão premido, não verá feedback ou verá o feedback do evento de premir o botão, caso exista.
{% endhint %}

## Entrada e saída do cursor

Use `pointerEventsSystem.onPointerHoverEnter` para executar um callback quando o cursor do jogador começar a apontar para uma entidade, e `pointerEventsSystem.onPointerHoverLeave` quando o cursor deixar de apontar para ele.

```ts
pointerEventsSystem.onPointerHoverEnter(
    {
        entity: myEntity,
        opts: { button: InputAction.IA_POINTER },
    },
    function () {
        console.log('Cursor started hovering over entity')
    }
)

pointerEventsSystem.onPointerHoverLeave(
    {
        entity: myEntity,
        opts: { button: InputAction.IA_POINTER },
    },
    function () {
        console.log('Cursor stopped hovering over entity')
    }
)
```

Estes callbacks são úteis para efeitos personalizados ao passar o cursor, como reproduzir um som ou animar a entidade quando o jogador aponta para ela.

## Remover callbacks

Para remover uma função de callback, use a função de remoção correspondente:

```ts
pointerEventsSystem.removeOnPointerDown(myEntity)
pointerEventsSystem.removeOnPointerUp(myEntity)
pointerEventsSystem.removeOnPointerHoverEnter(myEntity)
pointerEventsSystem.removeOnPointerHoverLeave(myEntity)
```

Depois de removido, o feedback ao passar o cursor sobre a entidade deixa de ser apresentado e a entidade deixa de ser interativa.

Cada função de remoção elimina apenas a entrada adicionada pela função de registo correspondente. Registar e remover repetidamente o mesmo callback não deixa entradas obsoletas na entidade.

## Interações por proximidade

Para interações acionadas pela proximidade do jogador, em vez de pela direção do cursor, consulte [**Proximity Events**](https://docs.decentraland.org/creator/content-creator-pt/scenes-sdk7/interatividade/eventos-de-botao/proximity-events.md). O `pointerEventsSystem` inclui helpers equivalentes (`onProximityDown`, `onProximityUp`, `onProximityEnter`, e `onProximityLeave`) que seguem o mesmo padrão das funções descritas nesta página.

Uma entidade pode ter um handler do cursor e um handler de proximidade para o mesmo tipo de evento. Ambos os callbacks são executados, cada um quando a respetiva condição é cumprida.

### Dados da ação de entrada

Obtenha dados de uma ação de entrada, como o botão premido, a entidade atingida, a direção e o comprimento do raio, etc. Consulte ([Consulte a documentação](https://github.com/decentraland/docs/tree/main/README.md)) para ver uma descrição de todos os dados disponíveis.

Para obter estes dados, passe um parâmetro à função de callback. Este parâmetro contém a estrutura de dados completa com informações sobre o evento de entrada.

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

### Processar vários botões

Não é possível registar mais do que um `onPointerDown` numa única entidade. Idealmente, deve usar a abordagem baseada em [Systems](https://docs.decentraland.org/creator/content-creator-pt/scenes-sdk7/interatividade/eventos-de-botao/system-based-events.md) , pois permite processar tantas entradas diferentes quantas quiser e apresentar uma indicação de feedback da UI ao passar o cursor para cada botão.

Em alternativa, pode usar a abordagem de registo de callbacks e definir o campo `button` como `InputAction.IA_ANY`.

```ts
pointerEventsSystem.onPointerDown(
  {entity: myEntity, opts: { button: InputAction.IA_ANY}},
  function (cmd) {
      if(cmd.button === InputAction.IA_POINTER){
        // do X
      } else if (cmd.button === InputAction.IA_PRIMARY){
        // fazer Y
      }
  }
)
```

Esta abordagem não é ideal, pois a dica apresentada ao passar o cursor mostra uma única string e não especifica que ação ativar. Tenha em atenção que isto fará com que a função de callback seja executada para cada ação de entrada, incluindo as teclas de movimento, pelo que terá de filtrar apenas as ações pretendidas.


---

# 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/register-callback.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.
