> 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-zh/chang-jing-sdk7/jiao-hu-xing/an-niu-shi-jian/proximity-events.md).

# 接近事件

检测玩家何时进入或离开某个实体的接近范围。

临近交互可使实体在玩家进入附近并大致朝向它时对按钮事件作出响应，而无需玩家将光标对准该实体。

传统的指针事件使用射线投射：玩家必须先将光标对准实体的碰撞体，然后才能按下按钮触发事件。临近事件则改为检查角色周围给定区域内的实体，而不管玩家的光标指向哪里。

用于临近交互的交互区域是一个宽阔的球面三角切片，从玩家的位置向前投射。与指针事件不同，角色面朝的方向很重要，而与摄像机朝向无关。

。要设置更具体的自定义逻辑，你可能需要直接处理原始数据，并使用 [高级](/creator/content-creator-zh/chang-jing-sdk7/jiao-hu-xing/an-niu-shi-jian/advanced-button-events.md) 的方法。

要使实体可交互，它必须具有 [碰撞体](/creator/content-creator-zh/chang-jing-sdk7/3d-nei-rong-ji-chu/colliders.md)。参见 [障碍物](/creator/content-creator-zh/chang-jing-sdk7/jiao-hu-xing/an-niu-shi-jian/click-events.md#obstacles) 了解更多详情。

## 注册临近回调

该 `pointerEventsSystem` 包含用于临近事件的辅助函数，遵循与 [指针事件回调](/creator/content-creator-zh/chang-jing-sdk7/jiao-hu-xing/an-niu-shi-jian/register-callback.md).

### 临近按钮按下

使用 `pointerEventsSystem.onProximityDown` 用于在玩家处于范围内时检测按钮按下。不同于 `onPointerDown`，这不需要玩家将光标对准该实体。

```ts
pointerEventsSystem.onProximityDown(
    {
        entity: myEntity,
        opts: {
            button: InputAction.IA_PRIMARY,
            hoverText: '按 E',
            maxDistance: 5,
        },
    },
    function () {
        console.log('玩家在实体附近按下按钮')
    }
)
```

使用 `pointerEventsSystem.onProximityUp` 用于检测玩家在范围内松开按钮的时机。

```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" %}
**📔 注意**：每个 `onProximityDown` 和一个 `onProximityUp` 都可以为每个实体注册。添加后，它们会持续监听，直到被移除。不要在系统循环中调用这些，否则会不断重写该行为。
{% endhint %}

## 临近事件类型

已向 `PointerEventType` 枚举中使用：

* `PET_PROXIMITY_ENTER`：当玩家走入实体的临近范围时触发。
* `PET_PROXIMITY_LEAVE`：当玩家移出实体的临近范围时触发。

这些可与一个 `PointerEvents` 组件以及 `inputSystem` 用于 [基于系统的方法](/creator/content-creator-zh/chang-jing-sdk7/jiao-hu-xing/an-niu-shi-jian/system-based-events.md#proximity-events)一起使用。该方法还支持使用临近按钮按下， `InteractionType.PROXIMITY` 字段中，指向你自己的流媒体基础设施。

## 优先级

当多个实体处于范围内且都可以响应同一输入时，默认只会激活离得最近的一个。使用 `优先级` 字段来控制哪个优先。具有 **更高数值** 作为其优先级值的实体会优先响应。

如果玩家既在某个带有临近交互的实体范围内，而玩家的光标又指向一个带有指针交互的实体，则始终优先选择带有指针交互的实体。再次强调，只会激活一个实体。

```ts
pointerEventsSystem.onProximityDown(
    {
        entity: doorEntity,
        opts: {
            button: InputAction.IA_PRIMARY,
            hoverText: '打开门',
            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')
    }
)
```

在上面的示例中，如果两个实体都在范围内，则门实体会响应，因为它的优先级更高。

该 `优先级` 字段也可以在一个 `PointerEvents` 组件。

## 选项

中设置。临近辅助函数接受与其指针对应函数相同的选项：

* `按钮连接您的钱包`：要监听哪个按钮。参见 [指针按钮](/creator/content-creator-zh/chang-jing-sdk7/jiao-hu-xing/an-niu-shi-jian/click-events.md#pointer-buttons) 以查看支持的选项。
* `maxDistance`：从玩家的 **化身** 到实体的最大距离，单位为米。默认 10。
* `hoverText`：当玩家靠近实体时在 UI 中显示的文本。
* `showHighlight`：如果为 true，当玩家在范围内时，在实体上显示边缘高亮。 *true* 。
* `showFeedback`：如果为 true，显示悬停反馈，在实体中心周围悬停。 *true* 。
* `优先级`：当多个实体处于临近范围内时解决冲突。数值越高优先级越高。如果多个实体具有相同的优先级值，则选择最近的一个。

`maxPlayerDistance` 是 `maxDistance`。这两者都是从化身测量距离，因此请使用 `maxDistance` 。

### 什么算作在范围内

临近事件的测量起点是 **玩家胶囊体的中心**，大致在胸部高度，到实体碰撞体上的最近点。这比光标点击的测量起点大约高出一米，因此同一个位置在两种路径下读出的距离可能会略有不同。

仅靠距离还不够。要触发临近事件，玩家还必须：

* 面向 **朝向** 该实体，且位于其正前方大约 120 度的锥形范围内。
* 具有 **清晰的视线** 可直达它，中间没有任何遮挡。

{% hint style="warning" %}
**📔 注意**：临近事件会忽略 `maxCameraDistance`。摄像机位于何处并不影响。只考虑角色的距离、朝向和视线。参见 [距离限制](/creator/content-creator-zh/chang-jing-sdk7/jiao-hu-xing/an-niu-shi-jian/register-callback.md#distance-limits) 了解光标事件中的摄像机限制如何工作。
{% endhint %}

## 移除回调

要移除临近回调，请使用相应的移除函数：

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

一旦移除，该实体将不再对该临近事件作出响应。

## 临近进入和离开

使用 `pointerEventsSystem.onProximityEnter` 用于在玩家走入实体的临近范围时运行回调，以及 `pointerEventsSystem.onProximityLeave` 用于在玩家走出时运行回调。这可用于向玩家显示额外的反馈提示，例如当某个物品可以交互时播放声音或动画。

```ts
pointerEventsSystem.onProximityEnter(
    {
        entity: myEntity,
        opts: {
            button: InputAction.IA_POINTER,
            hoverText: 'Nearby',
            maxDistance: 5,
        },
    },
    function () {
        console.log('玩家进入接近范围')
    }
)

pointerEventsSystem.onProximityLeave(
    {
        entity: myEntity,
        opts: {
            button: InputAction.IA_POINTER,
            hoverText: 'Nearby',
            maxDistance: 5,
        },
    },
    function () {
        console.log('玩家离开接近范围')
    }
)
```

## 示例：临近门

下面的示例会在玩家站在附近并按下按钮时打开或关闭一扇门，而无需将视线对准门。

```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-zh/chang-jing-sdk7/jiao-hu-xing/an-niu-shi-jian/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.