> 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

As interações de proximidade permitem que entities reajam a eventos de botão quando um player entra, está perto e, de forma aproximada, está a encará-la, sem exigir que aponte o cursor para a entity.

Os eventos de ponteiro tradicionais usam ray-casting: o player precisa apontar o cursor para o collider de uma entity antes de poder pressionar um botão para disparar o evento. Os eventos de proximidade, por outro lado, verificam entities que estão dentro de uma determinada área ao redor do avatar, independentemente de para onde o cursor do player esteja apontando.

A área interativa considerada para interações de proximidade é uma larga fatia triangular de uma esfera, projetando-se para a frente a partir da posição do player. 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âmera está virada.

Para definir uma custom logic mais específica, talvez você queira lidar com os dados brutos e usar o [Advanced](/creator/content-creator-pt/scenes-sdk7/interatividade/eventos-de-botao/advanced-button-events.md) abordagem.

Para que uma entity seja interativa, ela deve ter um [collider](/creator/content-creator-pt/scenes-sdk7/essenciais-de-conteudo-3d/colliders.md). Veja [obstacles](/creator/content-creator-pt/scenes-sdk7/interatividade/eventos-de-botao/click-events.md#obstacles) para mais detalhes.

## Registrar callbacks de proximidade

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

### Pressões de botão de proximidade

Use `pointerEventsSystem.onProximityDown` para detetar pressões de botão enquanto o player está dentro do alcance. Ao contrário de `onPointerDown`, isto não exige que o player aponte o cursor para a entity.

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

Use `pointerEventsSystem.onProximityUp` para detetar quando o player solta um botão enquanto está dentro do alcance.

```ts
pointerEventsSystem.onProximityUp(
    {
        entity: myEntity,
        opts: {
            button: InputAction.IA_PRIMARY,
            hoverText: 'Soltar E',
            maxPlayerDistance: 5,
        },
    },
    function () {
        console.log('Player soltou o botão perto da entity')
    }
)
```

{% hint style="warning" %}
**📔 Nota**: Apenas um `onProximityDown` e um `onProximityUp` podem ser registados por entity. Depois de adicionados, continuam a escutar até serem removidos. Não chame isto dentro de um loop de System, pois isso reescreveria o comportamento constantemente.
{% endhint %}

## Tipos de eventos de proximidade

Foram adicionados dois novos valores ao `PointerEventType` enum:

* `PET_PROXIMITY_ENTER`: Disparado quando o player entra no alcance de proximidade da entity.
* `PET_PROXIMITY_LEAVE`: Disparado quando o player sai do alcance de proximidade da entity.

Estes podem ser usados com um `PointerEvents` component e a `inputSystem` para as [abordagem baseada em system](/creator/content-creator-pt/scenes-sdk7/interatividade/eventos-de-botao/system-based-events.md#proximity-events). Essa abordagem também suporta pressões de botão de proximidade usando o `InteractionType.IT_PROXIMITY` campo.

## Prioridade

Quando várias entities estão dentro do alcance e podem responder à mesma entrada, apenas uma é ativada, por padrão a mais próxima. Use o `prioridade` campo para controlar qual tem precedência. Entities com um **número maior** como valor de prioridade respondem primeiro.

Se o player estiver ao mesmo tempo dentro do alcance de uma entity com interação de proximidade e o cursor do player estiver apontando para uma entity que tem uma interação de ponteiro, a entity com a interação de ponteiro recebe sempre prioridade. Novamente, apenas uma entity é ativada.

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

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

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

O `prioridade` campo também pode ser definido nas propriedades de um `PointerEvents` component.

## Opções

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

* `button`: Qual botão ouvir. Veja [Pointer buttons](/creator/content-creator-pt/scenes-sdk7/interatividade/eventos-de-botao/click-events.md#pointer-buttons) para opções suportadas.
* `maxDistance`: Distância máxima desde o **camera** do player até à entity, em metros.
* `maxPlayerDistance`: Distância máxima desde o **avatar** até à entity, em metros. Esta é a definição mais relevante para eventos de proximidade.
* `hoverText`: Texto a exibir na UI quando o player está perto da entity.
* `showHighlight`: Se verdadeiro, mostra um destaque na borda da entity quando o player está dentro do alcance. *true* por padrão.
* `showFeedback`: Se verdadeiro, mostra feedback de hover, pairando à volta do centro da entity. *true* por padrão.
* `prioridade`: Resolve conflitos quando várias entities estão em proximidade. Valores mais altos têm precedência. Se várias entities tiverem o mesmo valor de prioridade, é escolhida a mais próxima.

## 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 entity deixa de reagir a esse evento de proximidade.

## Entrada e saída de proximidade

Use `pointerEventsSystem.onProximityEnter` para executar um callback quando o player entra no alcance de proximidade da entity, e `pointerEventsSystem.onProximityLeave` quando sai. Isto pode ser usado para mostrar dicas de feedback extra ao player, por exemplo um som ou uma animação quando um item pode ser interagido.

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

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

## Exemplo: porta por proximidade

O exemplo seguinte abre ou fecha uma porta quando o player pressiona um botão enquanto está 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: 'Abrir / Fechar',
            maxPlayerDistance: 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 dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.decentraland.org/creator/content-creator-pt/scenes-sdk7/interatividade/eventos-de-botao/proximity-events.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.