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

# Eventos de Proximidade

Detecte quando um jogador entra ou sai da proximidade de uma entity.

As interações por proximidade permitem que as entidades reajam a eventos de botão quando o jogador se aproxima e está mais ou menos virado para elas, sem precisar apontar o cursor para a entidade.

Os eventos de ponteiro tradicionais usam ray casting: o jogador precisa apontar o cursor para o Collider de uma entidade antes de poder premir um botão para acionar o evento. Já os eventos de proximidade verificam se há entidades dentro de uma determinada área à volta do Avatar, independentemente da direção para a qual o cursor do jogador está apontado.

A área interativa considerada para as interações por proximidade é uma ampla secção triangular de uma esfera, projetada para a frente a partir da posição do jogador. Ao contrário dos eventos de ponteiro, a direção para a qual o Avatar está virado é importante, independentemente da direção para a qual a câmara está virada.

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 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 [obstáculos](https://docs.decentraland.org/creator/content-creator-pt/scenes-sdk7/interatividade/eventos-de-botao/click-events.md#obstacles) para obter mais detalhes.

## Registar callbacks de proximidade

O `pointerEventsSystem` inclui funções auxiliares para eventos de proximidade, seguindo o mesmo padrão dos [callbacks de eventos de ponteiro](https://docs.decentraland.org/creator/content-creator-pt/scenes-sdk7/interatividade/eventos-de-botao/register-callback.md).

### Premir botões por proximidade

Use `pointerEventsSystem.onProximityDown` para detetar quando o jogador prime um botão dentro do alcance. Ao contrário de `onPointerDown`, esta função não exige que o jogador aponte o cursor para a entidade.

```ts
pointerEventsSystem.onProximityDown(
    {
        entity: myEntity,
        opts: {
            button: InputAction.IA_PRIMARY,
            hoverText: 'Press E',
            maxDistance: 5,
        },
    },
    function () {
        console.log('Player pressed button near entity')
    }
)
```

Use `pointerEventsSystem.onProximityUp` para detetar quando o jogador solta um botão dentro do alcance.

```ts
pointerEventsSystem.onProximityUp(
    {
        entity: myEntity,
        opts: {
            button: InputAction.IA_PRIMARY,
            hoverText: 'Release E',
            maxDistance: 5,
        },
    },
    function () {
        console.log('Player released button near entity')
    }
)
```

{% hint style="warning" %}
**📔 Nota**: Só é possível registar um `onProximityDown` e um `onProximityUp` por entidade. Depois de adicionados, continuam à escuta até serem removidos. Não os chame dentro de um loop de sistema, pois isso reescreveria continuamente o comportamento.
{% endhint %}

## Tipos de evento de proximidade

Foram adicionados dois novos valores ao `PointerEventType` enum:

* `PET_PROXIMITY_ENTER`: acionado quando o jogador se aproxima até ficar dentro do alcance de proximidade da entidade.
* `PET_PROXIMITY_LEAVE`: acionado quando o jogador sai do alcance de proximidade da entidade.

Estes valores podem ser usados com um componente `PointerEvents` e o `inputSystem` para a [abordagem baseada em sistema](https://docs.decentraland.org/creator/content-creator-pt/scenes-sdk7/interatividade/eventos-de-botao/system-based-events.md#proximity-events). Esta abordagem também permite premir botões por proximidade através do campo `InteractionType.PROXIMITY` .

## Prioridade

Quando várias entidades estão dentro do alcance e podem responder à mesma entrada, apenas uma é ativada: por padrão, a mais próxima. Use o campo `priority` para controlar qual delas tem precedência. As entidades com um **valor mais alto** de prioridade respondem primeiro.

Se o jogador estiver dentro do alcance de uma entidade com uma interação por proximidade e o cursor do jogador estiver apontando para uma entidade que tenha uma interação por ponteiro, a entidade com a interação por ponteiro sempre terá prioridade. Novamente, apenas uma entidade é ativada.

```ts
pointerEventsSystem.onProximityDown(
    {
        entity: doorEntity,
        opts: {
            button: InputAction.IA_PRIMARY,
            hoverText: 'Abrir porta',
            maxDistance: 5,
            priority: 2,
        },
    },
    function () {
        console.log('Door activated')
    }
)

pointerEventsSystem.onProximityDown(
    {
        entity: floorEntity,
        opts: {
            button: InputAction.IA_PRIMARY,
            hoverText: 'Step here',
            maxDistance: 5,
            priority: 1,
        },
    },
    function () {
        console.log('Floor activated')
    }
)
```

No exemplo acima, se ambas as entidades estiverem dentro do alcance, a entidade da porta responde porque tem a prioridade mais alta.

O campo `priority` também pode ser definido nas propriedades de um componente `PointerEvents` .

## Opções

As funções auxiliares de proximidade aceitam as mesmas opções que suas equivalentes de ponteiro:

* `button`: qual botão deve ser monitorado. 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 compatíveis.
* `maxDistance`: distância máxima entre o **avatar** do jogador e a entidade, em metros. O padrão é 10.
* `hoverText`: texto a ser exibido na UI quando o jogador estiver perto da entidade.
* `showHighlight`: se for true, destaca o contorno da entidade quando o jogador estiver ao alcance. *true* por padrão.
* `showFeedback`: se for true, exibe um feedback ao passar o cursor, que paira próximo ao centro da entidade. *true* por padrão.
* `priority`: resolve conflitos quando várias entidades estão próximas. Valores mais altos têm precedência. Se várias entidades tiverem o mesmo valor de prioridade, será escolhida a mais próxima.

`maxPlayerDistance` é um alias obsoleto de `maxDistance`. Ambos medem a distância a partir do avatar, então use `maxDistance` em cenas novas.

### O que significa estar ao alcance

Os eventos de proximidade medem a distância entre o **centro da cápsula do jogador**, aproximadamente à altura do peito, e o ponto mais próximo do collider da entidade. Esse ponto fica cerca de um metro acima de onde a distância é medida em um clique do cursor, então o mesmo local pode apresentar uma distância ligeiramente diferente em cada caso.

A distância, por si só, não é suficiente. Para acionar um evento de proximidade, o jogador também precisa:

* Estar **voltado para** a entidade, dentro de um cone de aproximadamente 120 graus à sua frente.
* Ter uma **linha de visão desobstruída** até ela, sem nada no caminho.

{% hint style="warning" %}
**📔 Nota**: os eventos de proximidade ignoram `maxCameraDistance`. A posição da câmera não faz diferença. Apenas a distância, a orientação e a linha de visão do Avatar são consideradas. 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 saber como o limite da câmera funciona nos eventos de cursor.
{% endhint %}

## Remover callbacks

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

```ts
pointerEventsSystem.removeOnProximityDown(myEntity)
pointerEventsSystem.removeOnProximityUp(myEntity)
pointerEventsSystem.removeOnProximityEnter(myEntity)
pointerEventsSystem.removeOnProximityLeave(myEntity)
```

Depois de removida, a entidade deixa de reagir a esse evento de proximidade.

## Entrada e saída da proximidade

Use `pointerEventsSystem.onProximityEnter` para executar um callback quando o jogador entrar no raio de proximidade da entidade, e `pointerEventsSystem.onProximityLeave` quando sair dele. Isso pode ser usado para mostrar dicas de feedback adicionais ao jogador, como um som ou uma animação quando for possível interagir com um item.

```ts
pointerEventsSystem.onProximityEnter(
    {
        entity: myEntity,
        opts: {
            button: InputAction.IA_POINTER,
            hoverText: 'Nearby',
            maxDistance: 5,
        },
    },
    function () {
        console.log('Player entered proximity')
    }
)

pointerEventsSystem.onProximityLeave(
    {
        entity: myEntity,
        opts: {
            button: InputAction.IA_POINTER,
            hoverText: 'Nearby',
            maxDistance: 5,
        },
    },
    function () {
        console.log('Player left proximity')
    }
)
```

## Exemplo: porta por proximidade

O exemplo a seguir abre ou fecha uma porta quando o jogador prime um botão enquanto está por perto, sem precisar apontar para a porta.

```ts
const doorPivot = engine.addEntity()
Transform.create(doorPivot, { position: Vector3.create(3, 0, 4) })

const door = engine.addEntity()
GltfContainer.create(door, { src: 'assets/door.glb' })
Transform.create(door, { position: Vector3.create(-1, 0, 0), parent: doorPivot })

let isDoorOpen = false
const closedRot = Quaternion.fromEulerDegrees(0, 0, 0)
const openRot = Quaternion.fromEulerDegrees(0, 90, 0)

pointerEventsSystem.onProximityDown(
    {
        entity: door,
        opts: {
            button: InputAction.IA_PRIMARY,
            hoverText: 'Open / Close',
            maxDistance: 5,
            priority: 1,
        },
    },
    function () {
        if (isDoorOpen) {
            Tween.setRotate(doorPivot, openRot, closedRot, 700)
            isDoorOpen = false
        } else {
            Tween.setRotate(doorPivot, closedRot, openRot, 700)
            isDoorOpen = true
        }
    }
)
```


---

# 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/proximity-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.
