> 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-es/scenes-sdk7/interactividad/eventos-de-button/proximity-events.md).

# Eventos de proximidad

Detecta cuándo un jugador entra o sale de la proximidad de una entidad.

Las interacciones de proximidad permiten que las entities reaccionen a eventos de botón cuando un jugador entra, está cerca y mira aproximadamente hacia ellas, sin que necesiten apuntar el cursor a la entity.

Los eventos de pointer tradicionales usan raycasting: el jugador debe apuntar su cursor al collider de una entity antes de poder presionar un botón para activar el evento. En cambio, los eventos de proximidad comprueban si hay entities dentro de un área dada alrededor del avatar, sin importar hacia dónde apunte el cursor del jugador.

El área interactiva considerada para las interacciones de proximidad es una amplia sección triangular de una esfera, proyectada hacia delante desde la posición del jugador. A diferencia de los pointer events, la dirección hacia la que mira el avatar es importante, independientemente de la dirección hacia la que mira la cámara.

Para definir una lógica personalizada más específica, quizás quieras trabajar con los datos sin procesar y usar el [Avanzado](/creator/content-creator-es/scenes-sdk7/interactividad/eventos-de-button/advanced-button-events.md) enfoque.

Para que una entity sea interactiva, debe tener un [collider](/creator/content-creator-es/scenes-sdk7/fundamentos-del-contenido-3d/colliders.md). Consulta [obstáculos](/creator/content-creator-es/scenes-sdk7/interactividad/eventos-de-button/click-events.md#obstacles) para más detalles.

## Registrar callbacks de proximidad

El `pointerEventsSystem` incluye funciones auxiliares para eventos de proximidad, siguiendo el mismo patrón que [callbacks de eventos de pointer](/creator/content-creator-es/scenes-sdk7/interactividad/eventos-de-button/register-callback.md).

### Pulsaciones de botón de proximidad

Usa `pointerEventsSystem.onProximityDown` para detectar pulsaciones de botón mientras el jugador está dentro del rango. A diferencia de `onPointerDown`, esto no requiere que el jugador apunte su cursor a la entity.

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

Usa `pointerEventsSystem.onProximityUp` para detectar cuándo el jugador suelta un botón mientras está dentro del rango.

```ts
pointerEventsSystem.onProximityUp(
    {
        entity: myEntity,
        opts: {
            button: InputAction.IA_PRIMARY,
            hoverText: 'Suelta E',
            maxDistance: 5,
        },
    },
    function () {
        console.log('El jugador soltó el botón cerca de la entity')
    }
)
```

{% hint style="warning" %}
**📔 Nota**: Solo una `onProximityDown` y una `onProximityUp` puede registrarse por entity. Una vez agregadas, siguen escuchando hasta que se eliminan. No llames a estas dentro de un loop de un System, ya que eso mantendría reescribiendo el comportamiento.
{% endhint %}

## Tipos de eventos de proximidad

Se han agregado dos valores nuevos a `PointerEventType` enum:

* `PET_PROXIMITY_ENTER`: Se activa cuando el jugador camina dentro del rango de proximidad de la entity.
* `PET_PROXIMITY_LEAVE`: Se activa cuando el jugador sale del rango de proximidad de la entity.

Se pueden usar con un `PointerEvents` Component y el `inputSystem` para el [enfoque basado en System](/creator/content-creator-es/scenes-sdk7/interactividad/eventos-de-button/system-based-events.md#proximity-events). Ese enfoque también admite pulsaciones de botón de proximidad usando el `InteractionType.PROXIMITY` campo.

## Prioridad

Cuando varias entities están dentro del rango y podrían responder a la misma entrada, solo se activa una, por defecto la más cercana. Usa el `priority` campo para controlar cuál tiene precedencia. Las entities con un **número mayor** como valor de prioridad responden primero.

Si el jugador está tanto dentro del rango de una entity con una interacción de proximidad como si el cursor del jugador está apuntando a una entity que tiene una interacción de pointer, siempre se da prioridad a la entity con la interacción de pointer. De nuevo, solo se activa una entity.

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

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

En el ejemplo anterior, si ambas entities están dentro del rango, la entity de la puerta responde porque tiene la prioridad más alta.

El `priority` campo también se puede establecer en las propiedades de un `PointerEvents` componente.

## Opciones

Las funciones auxiliares de proximidad aceptan las mismas opciones que sus equivalentes de pointer:

* `botón`: Qué botón escuchar. Ver [Botones del puntero](/creator/content-creator-es/scenes-sdk7/interactividad/eventos-de-button/click-events.md#pointer-buttons) para las opciones compatibles.
* `maxDistance`: Distancia máxima desde la posición del jugador **avatar** a la entity, en metros. 10 por defecto.
* `hoverText`: Texto para mostrar en la UI cuando el jugador está cerca de la entity.
* `showHighlight`: Si es true, muestra un resaltado en el borde de la entity cuando el jugador está dentro del rango. *true* por defecto.
* `showFeedback`: Si es true, muestra feedback de hover alrededor del centro de la entity. *true* por defecto.
* `priority`: Resuelve conflictos cuando varias entities están en proximidad. Los valores más altos tienen precedencia. Si varias entities tienen el mismo valor de prioridad, se elige la más cercana.

`maxPlayerDistance` es un alias obsoleto de `maxDistance`. Ambos miden la distancia desde el avatar, así que usa `maxDistance` en nuevas Scenes.

### Qué cuenta como estar dentro del rango

Los eventos de proximidad miden desde el **centro de la cápsula del jugador**, aproximadamente a la altura del pecho, hasta el punto más cercano del collider de la entity. Eso está aproximadamente un metro por encima de donde mide un clic del cursor, por lo que el mismo punto puede registrar una distancia ligeramente diferente en cada ruta.

La distancia por sí sola no es suficiente. Para activar un evento de proximidad, el jugador también debe:

* Estar **mirando hacia** la entity, dentro de un cono de aproximadamente 120 grados delante de ella.
* Tener **una línea de visión despejada** hacia ella, sin nada en medio.

{% hint style="warning" %}
**📔 Nota**: Los eventos de proximidad ignoran `maxCameraDistance`. Donde esté situada la cámara no hace ninguna diferencia. Solo se consideran la distancia, la orientación y la línea de visión del avatar. Ver [Límites de distancia](/creator/content-creator-es/scenes-sdk7/interactividad/eventos-de-button/register-callback.md#distance-limits) para saber cómo funciona el límite de la cámara en los cursor events.
{% endhint %}

## Eliminar callbacks

Para eliminar un callback de proximidad, usa la función de eliminación correspondiente:

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

Una vez eliminado, la entity ya no reacciona a ese evento de proximidad.

## Entrada y salida de proximidad

Usa `pointerEventsSystem.onProximityEnter` para ejecutar un callback cuando el jugador entra en el rango de proximidad de la entity, y `pointerEventsSystem.onProximityLeave` cuando sale. Esto se puede usar para mostrar pistas de feedback adicionales al jugador, por ejemplo un sonido o una animación cuando se puede interactuar con un item.

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

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

## Ejemplo: puerta de proximidad

El siguiente ejemplo abre o cierra una puerta cuando el jugador presiona un botón mientras está cerca, sin necesidad de apuntar a la puerta.

```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 / Cerrar',
            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-es/scenes-sdk7/interactividad/eventos-de-button/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.