> 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 de proximidade permitem que entidades reajam a eventos de botão quando um jogador entra, está perto e está aproximadamente virado para elas, sem exigir que aponte o cursor para a entidade.

Os eventos de pointer tradicionais usam ray-casting: o jogador tem de apontar o cursor para o collider de uma entidade antes de poder premir um botão para acionar o evento. Os eventos de proximidade, em vez disso, verificam entidades que estão dentro de uma área definida à volta do avatar, independentemente de para onde o cursor do jogador está apontado.

A área interativa considerada para interações de proximidade é uma ampla fatia triangular de uma esfera, projetada para a frente a partir da posição do jogador. Ao contrário dos eventos de pointer, 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 lógica personalizada mais específica, talvez queiras lidar com os dados em bruto e usar a [Avançado](/creator/content-creator-pt/scenes-sdk7/interatividade/eventos-de-botao/advanced-button-events.md) abordagem.

Para que uma entidade seja interativa, tem de ter um [collider](/creator/content-creator-pt/scenes-sdk7/fundamentos-de-conteudo-3d/colliders.md). Veja [obstáculos](/creator/content-creator-pt/scenes-sdk7/interatividade/eventos-de-botao/click-events.md#obstacles) para mais detalhes.

## Registar callbacks de proximidade

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

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

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

```ts
pointerEventsSystem.onProximityDown(
    {
        entity: myEntity,
        opts: {
            button: InputAction.IA_PRIMARY,
            hoverText: 'Prima E',
            maxDistance: 5,
        },
    },
    function () {
        console.log('Jogador pressionou o botão perto da entidade')
    }
)
```

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

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

{% hint style="warning" %}
**📔 Nota**: Apenas um `onProximityDown` e um `onProximityUp` pode ser registado por entidade. Depois de adicionados, continuam a escutar até serem removidos. Não chames estes dentro de um ciclo de sistema, pois isso iria continuar a reescrever o comportamento.
{% endhint %}

## Tipos de eventos de proximidade

Dois novos valores foram adicionados ao `PointerEventType` enum:

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

Estes podem ser usados com um `PointerEvents` component e o `inputSystem` para a [abordagem baseada em sistema](/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 por proximidade usando o `InteractionType.PROXIMITY` campo.

## Prioridade

Quando várias entidades estão dentro do alcance e podem responder ao mesmo input, apenas uma é ativada, a mais próxima por defeito. Usa o `prioridade` campo para controlar qual tem precedência. Entidades com um **número mais alto** como valor de prioridade respondem primeiro.

Se o jogador estiver simultaneamente dentro do alcance de uma entidade com uma interação de proximidade e o cursor do jogador estiver apontado para uma entidade que tenha uma interação de pointer, a entidade com a interação de pointer tem sempre prioridade. Mais uma vez, apenas uma entidade é ativada.

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

pointerEventsSystem.onProximityDown(
    {
        entity: floorEntity,
        opts: {
            button: InputAction.IA_PRIMARY,
            hoverText: 'Pisa aqui',
            maxDistance: 5,
            priority: 1,
        },
    },
    function () {
        console.log('Chão ativado')
    }
)
```

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

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

## Opções

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

* `botão`: Qual botão escutar. Consulta [Botões de pointer](/creator/content-creator-pt/scenes-sdk7/interatividade/eventos-de-botao/click-events.md#pointer-buttons) para ver as opções suportadas.
* `maxDistance`: Distância máxima desde o **avatar** até à entidade, em metros. 10 por defeito.
* `hoverText`: Texto a mostrar na UI quando o jogador está perto da entidade.
* `showHighlight`: Se true, mostra um destaque de contorno na entidade quando o jogador está dentro do alcance. *true* por defeito.
* `showFeedback`: Se true, mostra feedback de hover, pairando à volta do centro da entidade. *true* por defeito.
* `prioridade`: Resolve conflitos quando várias entidades estão em proximidade. Valores mais altos têm precedência. Se várias entidades tiverem o mesmo valor de prioridade, é escolhida a mais próxima.

`maxPlayerDistance` é um alias descontinuado de `maxDistance`. Ambos medem a distância a partir do avatar, por isso usa `maxDistance` em novas cenas.

### O que conta como estar dentro do alcance

Os eventos de proximidade medem a partir do **centro da cápsula do jogador**, aproximadamente à altura do peito, até ao ponto mais próximo no collider da entidade. Isso fica cerca de um metro acima de onde um clique do cursor mede, por isso o mesmo ponto pode apresentar uma distância ligeiramente diferente em cada caminho.

A distância por si só não chega. Para disparar um evento de proximidade, o jogador também tem de:

* Estar **virado para** a entidade, dentro de um cone de cerca de 120 graus à sua frente.
* Ter uma **linha de visão desobstruída** para ela, sem nada no meio.

{% hint style="warning" %}
**📔 Nota**: Os eventos de proximidade ignoram `maxCameraDistance`. Onde a câmera está não faz diferença. Só a distância, a direção para a qual o avatar está virado e a linha de visão são considerados. Consulta [Limites de distância](/creator/content-creator-pt/scenes-sdk7/interatividade/eventos-de-botao/register-callback.md#distance-limits) para ver como o limite da câmera funciona nos eventos de cursor.
{% endhint %}

## Remover callbacks

Para remover um callback de proximidade, usa a função remove 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 de proximidade

Usa `pointerEventsSystem.onProximityEnter` para executar um callback quando o jogador entra no alcance de proximidade da entidade, e `pointerEventsSystem.onProximityLeave` quando sai. Isto pode ser usado para mostrar dicas de feedback adicionais ao jogador, 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',
            maxDistance: 5,
        },
    },
    function () {
        console.log('O jogador entrou na proximidade')
    }
)

pointerEventsSystem.onProximityLeave(
    {
        entity: myEntity,
        opts: {
            button: InputAction.IA_POINTER,
            hoverText: 'Perto',
            maxDistance: 5,
        },
    },
    function () {
        console.log('O jogador saiu da proximidade')
    }
)
```

## Exemplo: porta de proximidade

O exemplo seguinte abre ou fecha uma porta quando o jogador prime um botão enquanto está por perto, sem precisar de 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',
            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.