> 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/system-based-events.md).

# Eventos Baseados em System

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

Se a sua scene tiver várias Entities semelhantes, todas ativadas usando a mesma lógica, pode escrever um único System que percorra todas elas e descreva esse comportamento apenas uma vez. Esta é também a abordagem mais eficiente e mais orientada a [dados](https://docs.decentraland.org/creator/content-creator-pt/scenes-sdk7/arquitetura/data-oriented-programming.md) .

Também pode usar um System para detetar [eventos de input globais](#global-input-events), para que a scene reaja sempre que uma tecla é premida, sem ter em conta para onde o cursor do jogador está apontado.

Se apenas pretende clicar ou premir um botão numa única Entity para a ativar, a forma mais fácil é usar a abordagem [Registar um callback](https://docs.decentraland.org/creator/content-creator-pt/scenes-sdk7/interatividade/eventos-de-botao/register-callback.md) .

Para definir uma lógica personalizada mais específica, talvez queira lidar com os dados em bruto e usar a abordagem [Avançada](https://docs.decentraland.org/creator/content-creator-pt/scenes-sdk7/interatividade/eventos-de-botao/advanced-button-events.md) .

Para que uma Entity seja interativa, tem de ter um [collider](https://docs.decentraland.org/creator/content-creator-pt/scenes-sdk7/fundamentos-de-conteudo-3d/colliders.md). Consulte [obstáculos](https://docs.decentraland.org/creator/content-creator-pt/scenes-sdk7/interatividade/eventos-de-botao/click-events.md#obstacles) para obter mais detalhes. Isto também se aplica aos eventos de clique por proximidade.

## Utilizar um System

Verifique se ocorreram eventos de botão executando uma das funções auxiliares no namespace de input `inputSystem` em cada tick dentro de um [System](https://docs.decentraland.org/creator/content-creator-pt/scenes-sdk7/arquitetura/systems.md).

Por exemplo, o System seguinte utiliza a função `inputSystem.isTriggered()` para verificar se houve um clique do ponteiro. Em cada tick, verifica se o botão foi premido. Se `inputSystem.isTriggered()` devolver *true*, o System executa uma lógica personalizada em resposta.

```ts
engine.addSystem(() => {
	if (inputSystem.isTriggered(InputAction.IA_POINTER, PointerEventType.PET_DOWN)) {
		// Logic in response to button press
	}
})
```

As seguintes funções auxiliares estão disponíveis no namespace `inputSystem` e podem ser chamadas de forma semelhante em cada tick:

* `inputSystem.isTriggered`: Devolve true se tiver ocorrido uma ação de input desde o último tick.
* `inputSystem.isPressed`: Devolve true se um input estiver a ser premido no momento. Devolverá true em cada tick até o botão ser novamente libertado.
* `inputSystem.getInputCommand`: Devolve um objeto com dados sobre a ação de input.

Consulte as secções abaixo para obter mais detalhes sobre cada uma.

Ao processar eventos de botão numa Entity, forneça sempre feedback ao jogador, para que saiba que é possível interagir com a Entity. Se adicionar um componente `PointerEvents` a uma Entity, os jogadores verão uma indicação quando passarem o cursor sobre essa Entity. Consulte [Mostrar feedback](#show-feedback) para saber como adicionar indicações ao passar o cursor sobre Entities interativas.

### Eventos de input globais

Utilize `inputSystem.isTriggered` para detetar eventos de premir e libertar botões em qualquer um dos inputs monitorizados pelo SDK.

```ts
engine.addSystem(() => {
	if (
		inputSystem.isTriggered(InputAction.IA_POINTER, PointerEventType.PET_DOWN)
	) {
		// Logic in response to button press
	}
})
```

O exemplo acima verifica se o botão foi premido, independentemente da posição do apontador ou das Entities que possam estar no seu caminho.

`inputSystem.isTriggered()` devolve *true* apenas se o botão indicado tiver sido premido no tick atual do ciclo do jogo. Se o botão não tiver sido premido ou já estivesse premido no tick anterior, devolve *false*.

{% hint style="warning" %}
**📔 Nota**: O jogador tem de estar dentro dos limites da Scene para que o evento do apontador seja detetado. O cursor do jogador também tem de estar bloqueado; os botões premidos quando o cursor está livre não são detetados.

Todas as Entities com que pretenda interagir têm de ter um componente [`PointerEvents` e um](#show-feedback) e um [collider](https://docs.decentraland.org/creator/content-creator-pt/scenes-sdk7/fundamentos-de-conteudo-3d/colliders.md).
{% endhint %}

A função `inputSystem.isTriggered` recebe os seguintes argumentos obrigatórios:

* `InputAction`: O input a detetar, como valor do `InputAction` enum. Consulte [Botões do apontador](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.
* `PointerEventType`: O tipo de evento a detetar, como valor do `PointerEventType` enum. Consulte [Tipos de eventos do apontador](https://docs.decentraland.org/creator/content-creator-pt/scenes-sdk7/interatividade/eventos-de-botao/click-events.md#types-of-pointer-events) para ver as opções suportadas.

### Ativar uma Entity

Para detetar eventos de botões enquanto aponta para uma Entity específica, passe um terceiro argumento opcional para `inputSystem.isTriggered` para especificar a Entity a verificar.

```ts
// Give entity a PointerEvents component
PointerEvents.create(myEntity, {
	pointerEvents: [
		{
			eventType: PointerEventType.PET_DOWN,
			eventInfo: {
				button: InputAction.IA_PRIMARY,
				showFeedback: false,
			},
		},
	],
})

// create system
engine.addSystem(() => {
	if (
		inputSystem.isTriggered(
			InputAction.IA_POINTER,
			PointerEventType.PET_DOWN,
			myEntity
		)
	) {
		// Logic in response to button press on myEntity
	}
})
```

O exemplo acima verifica em cada tick se uma Entity única, definida diretamente no código, foi premida com o botão do apontador (botão esquerdo do rato).

A função `inputSystem.isTriggered` recebe os seguintes argumentos:

* `InputAction`: O input a detetar, como valor do `InputAction` enum. Consulte [Botões do apontador](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.
* `PointerEventType`: O tipo de evento a detetar, como valor do `PointerEventType` enum. Consulte [Tipos de eventos do apontador](https://docs.decentraland.org/creator/content-creator-pt/scenes-sdk7/interatividade/eventos-de-botao/click-events.md#types-of-pointer-events) para ver as opções suportadas.
* `Entity` *(opcional)*: A Entity na qual verificar estes eventos. Se não for fornecido nenhum valor, verifica os cliques globais no botão, independentemente da posição para onde o cursor do jogador apontava.

Note que, neste exemplo, também estamos a adicionar um componente `PointerEvents` à Entity com que queremos interagir. Este passo é necessário: sem este componente, a Entity não será detetável por nenhuma das funções de `inputSystem`. consulte [Mostrar feedback](#show-feedback) para obter mais detalhes sobre o `PointerEvents` componente.

{% hint style="warning" %}
**📔 Observação**: e um [collider](https://docs.decentraland.org/creator/content-creator-pt/scenes-sdk7/fundamentos-de-conteudo-3d/colliders.md). Consulte [obstáculos](https://docs.decentraland.org/creator/content-creator-pt/scenes-sdk7/interatividade/eventos-de-botao/click-events.md#obstacles) para obter mais detalhes.
{% endhint %}

Se houver várias entities com as quais o jogador pode interagir da mesma maneira, considere usar `inputSystem.getInputCommand`. Esse comando retorna informações sobre um comando global de clique, incluindo o ID da entity. Você pode usar isso para executar uma única função que possa lidar com todas elas.

```ts
engine.addSystem(() => {
	const result = inputSystem.getInputCommand(
		InputAction.IA_POINTER,
		PointerEventType.PET_DOWN
	)
	if (result) {
		if (result.hit?.entityId === myEntity) {
			// handle click
		}
	}
})
```

{% hint style="warning" %}
**📔 Observação**: Cada entity com a qual você quiser interagir precisa ter um componente [`PointerEvents` e um](#show-feedback) e um [collider](https://docs.decentraland.org/creator/content-creator-pt/scenes-sdk7/fundamentos-de-conteudo-3d/colliders.md).
{% endhint %}

Consulte [Dados da ação de entrada](#data-from-input-action) para obter mais informações. Esse método também fornece dados mais detalhados sobre o acerto do evento de pointer.

### Soltar o botão de entrada

Você também pode verificar eventos de liberação do pointer de maneira semelhante, usando `PointerEventType.PET_UP`.

```ts
engine.addSystem(() => {
	if (
		inputSystem.isTriggered(
			InputAction.IA_POINTER,
			PointerEventType.PET_UP,
			myEntity
		)
	) {
		// Logic in response to button up while pointing at myEntity
	}
})
```

{% hint style="warning" %}
**📔 Observação**: Ao verificar eventos de liberação do pointer em uma entity específica, não se considera para onde o cursor estava apontando quando o botão foi pressionado. Só é considerado para onde o cursor está apontando quando o botão é solto.

Lembre-se também de que a entity precisa ter um componente [`PointerEvents` e um](#show-feedback) e um [collider](https://docs.decentraland.org/creator/content-creator-pt/scenes-sdk7/fundamentos-de-conteudo-3d/colliders.md).
{% endhint %}

### Verificar se os botões estão pressionados

Verifique se um botão está sendo pressionado usando `inputSystem.isPressed()` dentro de um system.

```ts
engine.addSystem(() => {
	if (inputSystem.isPressed(InputAction.IA_POINTER)) {
		// Logic in response to button being held down
	}
})
```

`inputSystem.isPressed()` retorna *true* se o botão estiver sendo mantido pressionado, independentemente de quando foi pressionado e de para onde o cursor do jogador estiver apontando. Caso contrário, retorna *false*.

A `inputSystem.isPressed` função aceita um único argumento:

* `InputAction`: O input a detetar, como valor do `InputAction` enum. Consulte [Botões do apontador](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.

### Processar várias Entities

Se a sua Scene tiver várias Entities afetadas da mesma forma por Pointer Events, faz sentido escrever um System que percorra todas elas.

```ts
engine.addSystem(() => {
	const activatedEntites = engine.getEntitiesWith(PointerEvents)
	for (const [entity] of activatedEntites) {
		if (
			inputSystem.isTriggered(
				InputAction.IA_POINTER,
				PointerEventType.PET_DOWN,
				entity
			)
		) {
			// Logic in response to interacting with an entity
		}
	}
})
```

Este exemplo usa uma [consulta de Component](https://docs.decentraland.org/creator/content-creator-pt/scenes-sdk7/arquitetura/querying-components.md) para percorrer todas as Entities com um Component `PointerEvents` . Em seguida, verifica cada uma dessas Entities com `inputSystem.isTriggered`, percorrendo-as uma a uma. Se for detetada uma ação de input em qualquer uma destas Entities, executa uma lógica personalizada.

Em vez de percorrer *todas* as Entities com um Component `PointerEvents` num único System, pode preferir escrever Systems diferentes para processar as Entities que devem comportar-se de formas distintas. A abordagem recomendada é identificar diferentes tipos de Entities com [Components personalizados](https://docs.decentraland.org/creator/content-creator-pt/scenes-sdk7/arquitetura/custom-components.md)e percorrê-las em Systems separados.

```ts
engine.addSystem(() => {
	const activatedDoors = engine.getEntitiesWith(IsDoor, PointerEvents)
	for (const [entity] of activatedDoors) {
		if (
			inputSystem.isTriggered(
				InputAction.IA_POINTER,
				PointerEventType.PET_DOWN,
				entity
			)
		) {
			openDoor(entity)
		}
	}
})

engine.addSystem(() => {
	const pickedUpGems = engine.getEntitiesWith(IsGem, PointerEvents)
	for (const [entity] of pickedUpGems) {
		if (
			inputSystem.isTriggered(
				InputAction.IA_POINTER,
				PointerEventType.PET_DOWN,
				entity
			)
		) {
			pickUp(entity)
		}
	}
})
```

Este exemplo tem um System que percorre todas as Entities com um Component personalizado chamado `IsDoor` e outro que percorre todas as Entities com um Component personalizado chamado `isGem`. Em ambos os Systems, verifica cada Entity correspondente para ver se foi ativada com o botão do ponteiro.

Esta forma de organizar o código da sua Scene é muito [orientada a dados](https://docs.decentraland.org/creator/content-creator-pt/scenes-sdk7/arquitetura/data-oriented-programming.md) e deverá resultar numa utilização muito eficiente dos recursos de memória.

\## Vários botões numa Entity

Ao utilizar helpers como `pointerEventsSystem.onPointerDown`, cada Entity está limitada a um único tipo de evento. Não é possível registar dois eventos de botão diferentes. Esta limitação não existe quando se utilizam eventos baseados em Systems. Por exemplo, eis uma Entity com a qual os jogadores podem interagir premindo E e F, sendo cada tecla responsável por funcionalidades diferentes.

```ts
    engine.addSystem(() => {
        if (inputSystem.isTriggered(InputAction.IA_PRIMARY, PointerEventType.PET_DOWN, myEntity)) {
            // react to E
        }
        if (inputSystem.isTriggered(InputAction.IA_SECONDARY, PointerEventType.PET_DOWN, myEntity)) {
            // react to F
        }
    })
```

## Mostrar feedback

Para apresentar sugestões de UI ao apontar para uma Entity, utilize as propriedades do Component `PointerEvents` da Entity.

```ts
// criar entidade
const myEntity = engine.addEntity()

// adiciona um componente PointerEvents à entidade
PointerEvents.create(myEntity, {
	pointerEvents: [
		{
			eventType: PointerEventType.PET_DOWN,
			eventInfo: {
				button: InputAction.IA_POINTER,
			},
		},
	],
})
```

Sempre que o cursor do jogador apontar para os Colliders desta entidade, a UI apresentará uma dica ao passar o cursor, indicando que é possível interagir com a entidade. Consulte as secções abaixo para saber o que pode configurar.

{% hint style="warning" %}
**📔 Nota**: O `PointerEvents` componente apenas trata da apresentação do feedback ao passar o cursor. Para tratar os eventos dos botões com lógica personalizada, consulte [Using-a-system](#using-a-system).
{% endhint %}

O `PointerEvents` componente requer pelo menos uma definição de evento do ponteiro. Cada definição de evento do ponteiro pode ser configurada com o seguinte:

* `eventType`: O tipo de evento a escutar, como um valor do enum `PointerEventType` . Consulte [Tipos de eventos do ponteiro](https://docs.decentraland.org/creator/content-creator-pt/scenes-sdk7/interatividade/eventos-de-botao/click-events.md#types-of-pointer-events) para ver as opções suportadas.
* `eventInfo`: Um objeto que pode conter os seguintes campos:
  * `button` (*obrigatório*): A entrada a escutar, como um valor do enum `InputAction`  . 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.
  * `hoverText` *(opcional)*: O texto a apresentar na dica de feedback ao passar o cursor. O valor predefinido é "Interact".
  * `showFeedback` *(opcional)*: Se for false, oculta tanto a dica ao passar o cursor como o realce do contorno desta entidade. *true* por predefinição.
  * `showHighlight` *(opcional)*: Se for true, os jogadores verão o realce do contorno quando passarem o cursor sobre a entidade. *true* por predefinição. Este valor só é tido em conta se `showFeedback` for *true*.
  * `maxDistance` *(opcional)*: A distância máxima a que o **avatar** do jogador pode estar da entidade e ainda interagir com ela, em metros. O valor predefinido é *10 metros*. Consulte [Distância máxima](#max-distance).
  * `maxCameraDistance` *(opcional)*: A que distância a **câmara ativa** pode estar da entidade e continuar a interagir com ela, em metros. Não está definido por predefinição. Consulte [Distância máxima](#max-distance).
  * `priority` *(opcional)*: Determina qual entidade prevalece quando várias se sobrepõem. Os valores mais altos têm precedência. *0* por predefinição.

Um único `PointerEvents` componente pode conter várias definições de eventos de ponteiro, que podem detetar eventos diferentes para botões diferentes. Cada entidade só pode ter *um* `PointerEvents` componente, mas este pode incluir vários objetos na sua `pointerEvents` matriz, um para cada evento a que responder.

```ts
PointerEvents.create(NPCEntity, {
	pointerEvents: [
		{
			eventType: PointerEventType.PET_DOWN,
			eventInfo: {
				button: InputAction.IA_POINTER,
				hoverText: 'Cumprimentar',
			},
		},
		{
			eventType: PointerEventType.PET_DOWN,
			eventInfo: {
				button: InputAction.IA_PRIMARY,
				hoverText: 'Estrangular',
			},
		},
		{
			eventType: PointerEventType.PET_UP,
			eventInfo: {
				button: InputAction.IA_PRIMARY,
				hoverText: 'Parar de estrangular',
			},
		},
		{
			eventType: PointerEventType.PET_DOWN,
			eventInfo: {
				button: InputAction.IA_SECONDARY,
				hoverText: 'Dar joia',
			},
		},
	],
})
```

Os jogadores verão várias etiquetas, uma para cada evento de ponteiro, apresentadas radialmente à volta do cursor.

O exemplo abaixo combina a utilização de `PointerEvents` para apresentar sugestões ao passar o cursor, com um sistema que processa efetivamente a ação do jogador através de lógica personalizada.

```ts
// criar entidade
const myEntity = engine.addEntity()

// dar feedback ao passar o cursor sobre a entidade
PointerEvents.create(myEntity, {
	pointerEvents: [
		{
			eventType: PointerEventType.PET_DOWN,
			eventInfo: {
				button: InputAction.IA_POINTER,
				hoverText: 'Abrir',
			},
		},
	],
})

// processar eventos de clique na entidade
engine.addSystem(() => {
	if (
		inputSystem.isTriggered(
			InputAction.IA_POINTER,
			PointerEventType.PET_DOWN,
			myEntity
		)
	) {
		// Lógica personalizada em resposta a uma ação de entrada
	}
})
```

### Feedback ao passar o cursor

Quando um jogador passa o cursor sobre um item com um componente `PointerEvents` , vê:

* Um contorno realçado na entidade
* Uma sugestão junto ao cursor, com um ícone do botão que deve premir e o texto «Interagir».

Estes elementos podem ser ativados ou desativados e personalizados.

O feedback apresentado na UI ao passar o cursor mostra um ícone diferente, consoante a entrada selecionada no campo `button` . No PC, é apresentado um ícone com um `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
// criar entidade
const chest = engine.addEntity()

// adiciona um componente PointerEvents à entidade
PointerEvents.create(chest, {
	pointerEvents: [
		{
			eventType: PointerEventType.PET_DOWN,
			eventInfo: {
				button: InputAction.IA_POINTER,
				hoverText: 'Abrir',
			},
		},
	],
})
```

No exemplo acima, o evento de ponteiro inclui um valor para `hoverText`. Este campo define a string a apresentar na UI enquanto o jogador aponta para a entidade. Por predefinição, esta string é *Interagir*.

{% hint style="info" %}
**💡 Sugestão**: A string `hoverText` deve descrever a ação que ocorre ao interagir. Por exemplo: `Abrir`, `Ativar`, `Agarrar`, `Selecionar`. Estas strings devem ser tão curtas quanto possível, para não desviarem demasiado a atenção do jogador.
{% endhint %}

Se uma entidade tiver vários eventos de ponteiro, as sugestões ao passar o cursor para cada um deles são apresentadas radialmente em torno do cursor.

O `hoverText` de um evento de ponteiro `.UP` só é apresentado enquanto o jogador mantém premida a tecla correspondente e aponta para a entidade.

Se uma entidade tiver um evento de ponteiro `DOWN` e também um evento de ponteiro `UP` a sugestão da ação `DOWN` é apresentada enquanto o botão não está premido. A sugestão muda para a do evento `UP` apenas quando o botão é premido e continua premido.

```ts
// criar entidade
const entity = engine.addEntity()

// adiciona um componente PointerEvents à entidade
PointerEvents.create(entity, {
	pointerEvents: [
		{
			eventType: PointerEventType.PET_DOWN,
			eventInfo: {
				button: InputAction.IA_POINTER,
				hoverText: 'Arrastar',
			},
		},
		{
			eventType: PointerEventType.PET_UP,
			eventInfo: {
				button: InputAction.IA_POINTER,
				hoverText: 'Largar',
			},
		},
	],
})
```

Para ocultar a sugestão ao passar o cursor, mas manter o realce do contorno, defina o valor de `hoverText` como "".

```ts
// criar entidade
const chest = engine.addEntity()

// adiciona um componente PointerEvents à entidade
PointerEvents.create(chest, {
	pointerEvents: [
		{
			eventType: PointerEventType.PET_DOWN,
			eventInfo: {
				button: InputAction.IA_POINTER,
				hoverText: '',
			},
		},
	],
})
```

Para ocultar o realce do contorno, mas manter a sugestão ao passar o cursor, defina `showHighlight` como *false*.

```ts
// criar entidade
const chest = engine.addEntity()

// adiciona um componente PointerEvents à entidade
PointerEvents.create(chest, {
	pointerEvents: [
		{
			eventType: PointerEventType.PET_DOWN,
			eventInfo: {
				button: InputAction.IA_POINTER,
				hoverText: 'Abrir porta',
				showHighlight: false,
			},
		},
	],
})
```

Para ocultar tanto a sugestão ao passar o cursor como o realce do contorno, defina `showFeedback` como *false*. Neste caso, o cursor não apresenta ícones, texto nem qualquer realce do contorno. Também pode simplesmente remover o componente `PointerEvents` da entidade.

```ts
// criar entidade
const chest = engine.addEntity()

// adiciona um componente PointerEvents à entidade
PointerEvents.create(chest, {
	pointerEvents: [
		{
			eventType: PointerEventType.PET_DOWN,
			eventInfo: {
				button: InputAction.IA_POINTER,
				showFeedback: false,
			},
		},
	],
})
```

### Distância máxima

Algumas entidades podem ser interativas intencionalmente apenas a curta distância. Se um jogador estiver demasiado longe de uma entidade, a sugestão ao passar o cursor não será apresentada junto ao cursor.

Por predefinição, só é possível clicar nas entidades quando o **avatar** do jogador está a uma distância de *10 metros* da entidade. Pode alterar esse alcance definindo a `maxDistance` propriedade de um evento de ponteiro.

```ts
// criar entidade
const myEntity = engine.addEntity()

// adiciona um componente PointerEvents à entidade
PointerEvents.create(myEntity, {
	pointerEvents: [
		{
			eventType: PointerEventType.PET_DOWN,
			eventInfo: {
				button: InputAction.IA_POINTER,
				maxDistance: 6,
			},
		},
	],
})

// implement a system to handle the pointer event
engine.addSystem(() => {
	// fetch data about the pointer event
	const cmd = inputSystem.getInputCommand(
		InputAction.IA_POINTER,
		PointerEventType.PET_DOWN,
		myEntity
	)

	// check if the click was close enough
	if (cmd && cmd.hit && cmd.hit.length < 6) {
		// do something
	}
})
```

O exemplo acima define a distância máxima para as indicações ao passar o cursor como *6 metros*. Certifique-se de que a lógica que trata as ações de entrada também segue as mesmas regras. Consulte [Dados de uma ação de entrada](#data-from-input-action) para saber como obter a distância de uma ação de entrada.

`maxDistance` é medido a partir do **avatar**, pelo que se comporta da mesma forma na primeira e na terceira pessoa.

Para limitar a interação com base na distância da **câmara ativa** em vez disso, use `maxCameraDistance`. Se definir ambos, basta que uma das verificações seja satisfeita. Consulte [Limites de distância](https://docs.decentraland.org/creator/content-creator-pt/scenes-sdk7/interatividade/eventos-de-botao/register-callback.md#distance-limits) para ver o conjunto completo de regras.

{% hint style="warning" %}
**📔 Nota**: `maxPlayerDistance` é um alias obsoleto de `maxDistance`. Ambos medem a distância a partir do avatar, por isso use `maxDistance` em novas cenas.
{% endhint %}

## Indicações personalizadas avançadas

O `PointerEvents` component permite adicionar facilmente indicações de UI quando o cursor do jogador começa a passar sobre uma entidade. Em geral, é bom que as indicações se comportem de forma consistente com o que os jogadores estão habituados a ver noutras cenas de Decentraland. No entanto, em alguns casos, pode querer indicar de uma forma personalizada que algo é interativo. Por exemplo, pode reproduzir um som subtil quando o jogador começa a passar o cursor sobre a entidade. Também pode mostrar um contorno luminoso à volta da entidade enquanto o cursor passa sobre ela e ocultá-lo quando deixar de o fazer. Também pode ser utilizado para mecânicas de jogo específicas.

Use a `inputSystem.isTriggered()` função juntamente com os eventos `PointerEventType.PET_HOVER_ENTER` e `PointerEventType.PET_HOVER_LEAVE` para executar comportamentos personalizados sempre que o cursor do jogador começa a apontar para o collider da entidade e sempre que deixa de apontar para ele.

O exemplo abaixo aumenta o tamanho das entidades para *1.5* quando o cursor começa a apontar para o respetivo collider e repõe o tamanho em *1* quando o cursor deixa de apontar para elas.

```ts
engine.addSystem(() => {
	const meshEntities = engine.getEntitiesWith(MeshRenderer)
	for (const [entity] of meshEntities) {
		if (
			inputSystem.isTriggered(
				InputAction.IA_POINTER,
				PointerEventType.PET_HOVER_ENTER,
				entity
			)
		) {
			Transform.getMutable(entity).scale = Vector3.create(1.5, 1.5, 1.5)
		}

		if (
			inputSystem.isTriggered(
				InputAction.IA_POINTER,
				PointerEventType.PET_HOVER_LEAVE,
				entity
			)
		) {
			Transform.getMutable(entity).scale = Vector3.create(1, 1, 1)
		}
	}
})
```

{% hint style="warning" %}
**📔 Observação**: Cada entity com a qual você quiser interagir precisa ter um componente [`PointerEvents` e um](#show-feedback) e um [collider](https://docs.decentraland.org/creator/content-creator-pt/scenes-sdk7/fundamentos-de-conteudo-3d/colliders.md).
{% endhint %}

## Eventos de proximidade

Verifique se há pressões de botões de proximidade, independentemente da direção para a qual o cursor aponta, usando `PET_DOWN` numa Entity que usa `InteractionType.PROXIMITY`. Defina o campo `interactionType` na definição do evento de ponteiro, junto a `eventInfo`, para marcar o evento como baseado em proximidade.

Consulte [**Eventos de proximidade**](https://docs.decentraland.org/creator/content-creator-pt/scenes-sdk7/interatividade/eventos-de-botao/proximity-events.md) para obter mais detalhes, incluindo as funções auxiliares disponíveis.

```ts
PointerEvents.create(myEntity, {
	pointerEvents: [
		{
			eventType: PointerEventType.PET_DOWN,
			eventInfo: {
				button: InputAction.IA_PRIMARY,
				hoverText: 'Press E',
				maxDistance: 5
			},
			interactionType: InteractionType.PROXIMITY,
		},
	],
})

engine.addSystem(() => {
	if (inputSystem.isTriggered(InputAction.IA_PRIMARY, PointerEventType.PET_DOWN, myEntity)) {
		console.log('Player pressed button near entity')
	}
})
```

Com auxiliares como `pointerEventsSystem.onProximityDown`, uma Entity pode ter um handler de cursor e um handler de proximidade ao mesmo tempo, e ambos os callbacks são executados. O que não é possível é registar dois botões diferentes para o mesmo handler. Os eventos baseados em System não têm essa limitação: define-se uma entrada por comportamento. Por exemplo, aqui está uma Entity com a qual é possível interagir apontando o cursor e premindo E, ou aproximando-se e premindo E sem apontar para ela com o cursor.

```ts
	PointerEvents.create(myEntity, {
        pointerEvents: [
            {
                eventType: PointerEventType.PET_DOWN,
                eventInfo: {
                    button: InputAction.IA_POINTER,
                    hoverText: 'Clicar',
                    maxDistance: 15,
                },
                interactionType: InteractionType.CURSOR,
            },
            {
                eventType: PointerEventType.PET_DOWN,
                eventInfo: {
                    button: InputAction.IA_PRIMARY,
                    hoverText: 'Press E',
                    maxDistance: 15,
                },
                interactionType: InteractionType.PROXIMITY,
            },
        ],
    })
    
    engine.addSystem(() => {
        if (inputSystem.isTriggered(InputAction.IA_POINTER, PointerEventType.PET_DOWN, myEntity)) {
            console.log('Player clicked at entity')
        }
        if (inputSystem.isTriggered(InputAction.IA_PRIMARY, PointerEventType.PET_DOWN, myEntity)) {
            console.log('Player pressed button near entity')
        }
    })
```

Também pode usar `inputSystem.isTriggered()` com os tipos de evento `PET_PROXIMITY_ENTER` e `PET_PROXIMITY_LEAVE` para reagir quando um jogador entra ou sai do raio de proximidade de uma Entity. Isto é útil para apresentar feedback adicional para Entities ativadas por proximidade, por exemplo, reproduzindo um som ou uma animação.

Para que isto funcione, a Entity tem de ter um componente `PointerEvents` com o tipo de evento de proximidade correspondente definido.

```ts
PointerEvents.create(myEntity, {
	pointerEvents: [
		{
			eventType: PointerEventType.PET_PROXIMITY_ENTER,
			eventInfo: {
				button: InputAction.IA_POINTER,
				maxDistance: 5,
			},
		},
		{
			eventType: PointerEventType.PET_PROXIMITY_LEAVE,
			eventInfo: {
				button: InputAction.IA_POINTER,
				maxDistance: 5,
				showFeedback: false,
			},
		},
	],
})

engine.addSystem(() => {
	if (inputSystem.isTriggered(InputAction.IA_POINTER, PointerEventType.PET_PROXIMITY_ENTER, myEntity)) {
		console.log('Player entered proximity')
	}
	if (inputSystem.isTriggered(InputAction.IA_POINTER, PointerEventType.PET_PROXIMITY_LEAVE, myEntity)) {
		console.log('Player left proximity')
	}
})
```

## Dados da ação de input

Obtenha dados de uma ação de input, como o botão que foi premido, a Entity atingida, a direção e o comprimento do raio, etc. Consulte ([Consultar 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, use `inputSystem.getInputCommand`. Esta função devolve a estrutura de dados completa com informações sobre o evento de entrada.

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

Se não existir nenhuma ação de entrada que corresponda à consulta, então `inputSystem.getInputCommand` devolve *null*. Certifique-se de que trata este cenário na sua lógica.

### Distância máxima de clique

Para impor uma distância máxima, de modo que uma Entity só possa ser clicada a curta distância, obtenha a `hit.length` propriedade dos dados do evento.

```ts
// implement a system to handle the pointer event
engine.addSystem(() => {
	// fetch data about the pointer event
	const cmd = inputSystem.getInputCommand(
		InputAction.IA_POINTER,
		PointerEventType.PET_DOWN,
		myEntity
	)

	// check if the click was close enough
	if (cmd && cmd.hit && cmd.hit.length < 6) {
		// do something
	}
})
```

{% hint style="warning" %}
**📔 Nota**: Se ignorar eventos que ocorram a grande distância, certifique-se de que define o parâmetro `maxDistance` no componente `PointerEvents` para que o comportamento seja consistente.
{% endhint %}

### Meshes diferentes dentro de um modelo

Muitas vezes, os modelos 3D *.glTF* são compostos por vários meshes, cada um com um nome interno próprio. Todos os eventos de botão incluem informações sobre o mesh específico em que foi clicado, pelo que pode usar estas informações para desencadear comportamentos de clique diferentes em cada caso.

Para ver como são denominados os meshes dentro do modelo, tem de abrir o modelo 3D com uma ferramenta de edição, como o [Blender](https://www.blender.org/) , por exemplo.

![](https://2402076176-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoPnXBby9S6MrsW83Y9qZ%2Fuploads%2Fgit-blob-e2fc19b4253833aec3e79f338177b0c6657fb696%2Fmesh-names.webp?alt=media)

{% hint style="info" %}
**💡 Sugestão**: Também pode descobrir o nome do mesh clicado registando-o e consultando-o na consola.
{% endhint %}

A propriedade `meshName` está disponível no objeto `hit` devolvido pelo evento de clique.

No exemplo abaixo, temos um modelo de casa que inclui um mesh com o nome `firePlace`. Queremos acender a lareira apenas quando o respetivo mesh for clicado.

```ts
engine.addSystem(() => {
	const cmd = inputSystem.getInputCommand(
		InputAction.IA_POINTER,
		PointerEventType.PET_DOWN,
		myEntity
	)
	if (cmd && cmd.hit?.meshName === 'firePlace') {
		// acender o fogo
	}
})
```

{% hint style="warning" %}
**📔 Nota**: Isto só se aplica a eventos baseados no ponteiro, não a eventos baseados na proximidade, pois, nesse caso, todos os meshes do modelo podem estar simultaneamente próximos do jogador.
{% endhint %}


---

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

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

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

```
GET https://docs.decentraland.org/creator/content-creator-pt/scenes-sdk7/interatividade/eventos-de-botao/system-based-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.
