> 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-boton/proximity-events.md). # Eventos de proximidad Las interacciones de proximidad permiten que las entidades reaccionen a eventos de botón cuando un jugador entra, está cerca y aproximadamente orientado hacia ellas, sin requerir que apunte el cursor a la entidad. Los eventos de puntero tradicionales usan ray-casting: el jugador debe apuntar con el cursor a un collider de la entidad antes de poder presionar un botón para activar el evento. En cambio, los eventos de proximidad comprueban las entidades que están dentro de un área dada alrededor del avatar, independientemente de hacia dónde esté apuntando el cursor del jugador. El área interactiva considerada para las interacciones de proximidad es una amplia porción triangular de una esfera, proyectada hacia delante desde la posición del jugador. A diferencia de los eventos de puntero, la dirección hacia la que mira el avatar es importante, independientemente de la dirección hacia la que mira la cámara. Para establecer una lógica personalizada más específica, quizá quieras trabajar con los datos sin procesar y usar el [Advanced](/creator/content-creator-es/scenes-sdk7/interactividad/eventos-de-boton/advanced-button-events.md) enfoque. Para que una entidad sea interactiva, debe tener un [collider](/creator/content-creator-es/scenes-sdk7/conceptos-basicos-de-contenido-3d/colliders.md). Ver [obstáculos](/creator/content-creator-es/scenes-sdk7/interactividad/eventos-de-boton/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 puntero](/creator/content-creator-es/scenes-sdk7/interactividad/eventos-de-boton/register-callback.md). ### Pulsaciones del botón de proximidad Usa `pointerEventsSystem.onProximityDown` para detectar pulsaciones de botones mientras el jugador está dentro del rango. A diferencia de `onPointerDown`, esto no requiere que el jugador apunte su cursor a la entidad. ```ts pointerEventsSystem.onProximityDown( { entity: myEntity, opts: { button: InputAction.IA_PRIMARY, hoverText: 'Press E', maxPlayerDistance: 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: 'Soltar E', maxPlayerDistance: 5, }, }, function () { console.log('Player released button near entity') } ) ``` {% hint style="warning" %} **📔 Nota**: Solo uno `onProximityDown` y uno `onProximityUp` pueden registrarse por entidad. Una vez añadidos, siguen escuchando hasta que se eliminen. No los llames dentro de un bucle de sistema, ya que eso mantendría reescribiendo el comportamiento. {% endhint %} ## Tipos de eventos de proximidad Se han añadido dos nuevos valores a `PointerEventType` enum: * `PET_PROXIMITY_ENTER`: Se activa cuando el jugador entra en el rango de proximidad de la entidad. * `PET_PROXIMITY_LEAVE`: Se activa cuando el jugador sale del rango de proximidad de la entidad. Estos pueden usarse con un `PointerEvents` component y el `inputSystem` para las [enfoque basado en system](/creator/content-creator-es/scenes-sdk7/interactividad/eventos-de-boton/system-based-events.md#proximity-events). Ese enfoque también admite pulsaciones de botones de proximidad usando `InteractionType.IT_PROXIMITY` campo. ## Prioridad Cuando varias entidades están dentro del rango y podrían responder a la misma entrada, solo se activa una, la más cercana por defecto. Usa el campo `priority` para controlar cuál tiene prioridad. Las entidades con un **número más alto** como valor de prioridad responden primero. Si el jugador está tanto dentro del rango de una entidad con interacción de proximidad como si el cursor del jugador está apuntando a una entidad que tiene una interacción de puntero, la entidad con la interacción de puntero siempre tiene prioridad. De nuevo, solo se activa una entidad. ```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') } ) ``` En el ejemplo anterior, si ambas entidades están dentro del rango, la entidad de la puerta responde porque tiene la prioridad más alta. El `priority` el campo también puede establecerse en las propiedades de un `PointerEvents` componente. ## Opciones Las funciones auxiliares de proximidad aceptan las mismas opciones que sus equivalentes de puntero: * `botón`: Qué botón escuchar. Consulta [Botones de Pointer](/creator/content-creator-es/scenes-sdk7/interactividad/eventos-de-boton/click-events.md#pointer-buttons) para las opciones compatibles. * `maxDistance`: Distancia máxima desde el **camera** del jugador hasta la entidad, en metros. * `maxPlayerDistance`: Distancia máxima desde el **avatar** hasta la entidad, en metros. Esta es la configuración más relevante para los eventos de proximidad. * `hoverText`: Texto que se mostrará en la UI cuando el jugador esté cerca de la entidad. * `showHighlight`: Si es true, muestra un resaltado de borde en la entidad cuando el jugador está dentro del rango. *true* por defecto. * `showFeedback`: Si es true, muestra feedback hover, flotando alrededor del centro de la entidad. *true* por defecto. * `priority`: Resuelve conflictos cuando varias entidades están en proximidad. Los valores más altos tienen prioridad. Si varias entidades tienen el mismo valor de prioridad, se elige la más cercana. ## Eliminar callbacks Para eliminar un callback de proximidad, usa la función remove correspondiente: ```ts pointerEventsSystem.removeOnProximityDown(myEntity) pointerEventsSystem.removeOnProximityUp(myEntity) pointerEventsSystem.removeOnProximityEnter(myEntity) pointerEventsSystem.removeOnProximityLeave(myEntity) ``` Una vez eliminado, la entidad deja de reaccionar 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 entidad, y `pointerEventsSystem.onProximityLeave` cuando sale. Esto puede usarse para mostrar al jugador pistas de feedback adicionales, por ejemplo un sonido o una animación cuando un objeto puede interactuarse. ```ts pointerEventsSystem.onProximityEnter( { entity: myEntity, opts: { button: InputAction.IA_POINTER, hoverText: 'Cerca', maxPlayerDistance: 5, }, }, function () { console.log('Player entered proximity') } ) pointerEventsSystem.onProximityLeave( { entity: myEntity, opts: { button: InputAction.IA_POINTER, hoverText: 'Cerca', maxPlayerDistance: 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', 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-es/scenes-sdk7/interactividad/eventos-de-boton/proximity-events.md?ask=&goal= ``` `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.