> 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: '松开 E',
            maxDistance: 5,
        },
    },
    function () {
        console.log('玩家在实体附近松开了按钮')
    }
)
```

{% 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)。该方法还支持使用 `作用在使用` 字段中。

## 优先级

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

如果玩家既处于带有近距离交互的实体范围内，同时光标又指向一个具有指针交互的实体，那么带有指针交互的实体始终优先。再次强调，只会激活一个实体。

```ts
pointerEventsSystem.onProximityDown(
    {
        entity: doorEntity,
        opts: {
            button: InputAction.IA_PRIMARY,
            hoverText: '打开门',
            maxDistance: 5,
            priority: 2,
        },
    },
    function () {
        console.log('门已激活')
    }
)

pointerEventsSystem.onProximityDown(
    {
        entity: floorEntity,
        opts: {
            button: InputAction.IA_PRIMARY,
            hoverText: '踩这里',
            maxDistance: 5,
            priority: 1,
        },
    },
    function () {
        console.log('地板已激活')
    }
)
```

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

该 `优先级` 字段也可以设置在 `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，当玩家在范围内时，会在实体上显示边缘高亮。 *真* 。
* `showFeedback`：如果为 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: '附近',
            maxDistance: 5,
        },
    },
    function () {
        console.log('玩家进入接近范围')
    }
)

pointerEventsSystem.onProximityLeave(
    {
        entity: myEntity,
        opts: {
            button: InputAction.IA_POINTER,
            hoverText: '附近',
            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: '打开 / 关闭',
            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 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-zh/chang-jing-sdk7/jiao-hu-xing/an-niu-shi-jian/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.