> 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/system-based-events.md).

# 基于系统的事件

了解如何处理场景中的用户点击。

如果场景中有多个相似实体，且它们都通过相同逻辑激活，你可以编写一个系统来遍历所有实体，只需描述一次这种行为。这也是性能最高且更偏向 [面向数据的](https://docs.decentraland.org/creator/content-creator-zh/chang-jing-sdk7/jia-gou/data-oriented-programming.md) 方法。

你也可以使用系统来检测 [全局输入事件](#global-input-events)，这样无论玩家光标瞄准何处，按下按键时场景都会作出响应。

如果你只想通过点击或按下单个实体上的按钮来激活它，最简单的方法是使用 [注册回调](https://docs.decentraland.org/creator/content-creator-zh/chang-jing-sdk7/jiao-hu-xing/an-niu-shi-jian/register-callback.md) 方法。

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

实体要能够交互，必须具有 [碰撞体](https://docs.decentraland.org/creator/content-creator-zh/chang-jing-sdk7/3d-nei-rong-ji-chu/colliders.md)。详情请参阅 [障碍物](https://docs.decentraland.org/creator/content-creator-zh/chang-jing-sdk7/jiao-hu-xing/an-niu-shi-jian/click-events.md#obstacles) 。这同样适用于近距离点击事件。

## 使用系统

在每个刻帧中，运行输入 `inputSystem` 命名空间中的一个辅助函数，检查按钮事件。 [系统](https://docs.decentraland.org/creator/content-creator-zh/chang-jing-sdk7/jia-gou/systems.md).

例如，以下系统使用 `inputSystem.isTriggered()` 函数检查是否点击了指针。每个刻帧都会检查按钮是否按下。如果 `inputSystem.isTriggered()` 返回 *true*，系统就会运行一些自定义逻辑作为响应。

```ts
engine.addSystem(() => {
	if (inputSystem.isTriggered(InputAction.IA_POINTER, PointerEventType.PET_DOWN)) {
		// 对按钮按下事件的响应逻辑
	}
})
```

以下辅助函数可在 `inputSystem` 命名空间中使用，并且可以像这样在每个刻帧中调用：

* `inputSystem.isTriggered`：如果自上一个刻帧以来发生了输入操作，则返回 true。
* `inputSystem.isPressed`：如果当前正按住某个输入，则返回 true。按钮松开之前，每个刻帧都会返回 true。
* `inputSystem.getInputCommand`：返回一个包含输入操作数据的对象。

详情请参阅下文各部分的说明。

处理实体上的按钮事件时，务必向玩家提供反馈，让玩家知道该实体可以交互。如果向实体添加 `PointerEvents` 组件，玩家将光标悬停在该实体上时会看到提示。请参阅 [显示反馈](#show-feedback) ，了解如何为可交互实体添加悬停提示。

### 全局输入事件

使用 `inputSystem.isTriggered` 检测 SDK 所跟踪的任意输入上的按下和松开事件。

```ts
engine.addSystem(() => {
	if (
		inputSystem.isTriggered(InputAction.IA_POINTER, PointerEventType.PET_DOWN)
	) {
		// 对按钮按下事件的响应逻辑
	}
})
```

上面的示例会检查按钮是否被按下，而不管指针位于何处，也不管指针路径上是否有实体。

`inputSystem.isTriggered()` 会返回 *true* 仅当指定的按钮在游戏循环的当前帧中被按下时。如果按钮未被按下，或者在上一帧中已经处于按下状态，则会返回 *false*.

{% hint style="warning" %}
**📔 注意**：玩家必须位于场景边界内，才能检测到指针事件。玩家的光标也必须处于锁定状态；光标未锁定时按下的按钮不会被检测到。

你想要与之交互的每个实体都必须同时具有 [`PointerEvents` 组件](#show-feedback) 和一个 [碰撞体](https://docs.decentraland.org/creator/content-creator-zh/chang-jing-sdk7/3d-nei-rong-ji-chu/colliders.md).
{% endhint %}

该 `inputSystem.isTriggered` 函数需要以下参数：

* `InputAction`：要监听的输入，取值为 `InputAction` 枚举中的值。请参阅 [指针按钮](https://docs.decentraland.org/creator/content-creator-zh/chang-jing-sdk7/jiao-hu-xing/an-niu-shi-jian/click-events.md#pointer-buttons) 以查看支持的选项。
* `PointerEventType`：要监听的事件类型，取自 `PointerEventType` 枚举。请参阅 [指针事件类型](https://docs.decentraland.org/creator/content-creator-zh/chang-jing-sdk7/jiao-hu-xing/an-niu-shi-jian/click-events.md#types-of-pointer-events) 以查看支持的选项。

### 激活实体

若要检测指向特定实体时的按钮事件，请向 `inputSystem.isTriggered` 传入第三个可选参数，以指定要检查的实体。

```ts
// 为实体添加 PointerEvents 组件
PointerEvents.create(myEntity, {
	pointerEvents: [
		{
			eventType: PointerEventType.PET_DOWN,
			eventInfo: {
				button: InputAction.IA_PRIMARY,
				showFeedback: false,
			},
		},
	],
})

// 创建系统
engine.addSystem(() => {
	if (
		inputSystem.isTriggered(
			InputAction.IA_POINTER,
			PointerEventType.PET_DOWN,
			myEntity
		)
	) {
		// 响应 myEntity 上按钮按下的逻辑
	}
})
```

上面的示例会在每个 tick 检查是否用指针按键（鼠标左键）按下了一个硬编码的实体。

此 `inputSystem.isTriggered` 函数接受以下参数：

* `InputAction`：要监听的输入，取值为 `InputAction` 枚举中的值。请参阅 [指针按钮](https://docs.decentraland.org/creator/content-creator-zh/chang-jing-sdk7/jiao-hu-xing/an-niu-shi-jian/click-events.md#pointer-buttons) 以查看支持的选项。
* `PointerEventType`：要监听的事件类型，取自 `PointerEventType` 枚举。请参阅 [指针事件类型](https://docs.decentraland.org/creator/content-creator-zh/chang-jing-sdk7/jiao-hu-xing/an-niu-shi-jian/click-events.md#types-of-pointer-events) 以查看支持的选项。
* `Entity` *（可选）*：要在其上检查这些事件的实体。如果未提供值，则会检查按钮是否在全局范围内被按下，而不管玩家的光标指向何处。

请注意，在此示例中，我们还向要交互的实体添加了一个 `PointerEvents` 组件。此步骤是必需的；如果没有此组件，该实体将无法被任何函数检测到 `inputSystem`。有关 [显示反馈](#show-feedback) 组件的更多详细信息，请参阅 `PointerEvents` 。

{% hint style="warning" %}
**📔 注意**：以及一个 [碰撞体](https://docs.decentraland.org/creator/content-creator-zh/chang-jing-sdk7/3d-nei-rong-ji-chu/colliders.md)。有关详细信息，请参阅 [障碍物](https://docs.decentraland.org/creator/content-creator-zh/chang-jing-sdk7/jiao-hu-xing/an-niu-shi-jian/click-events.md#obstacles) 。
{% endhint %}

如果玩家可以用相同的方式与多个实体交互，可以考虑使用 `inputSystem.getInputCommand`。此命令会返回有关全局点击命令的信息，包括实体 ID。你可以利用这些信息执行一个能够处理所有实体的函数。

```ts
engine.addSystem(() => {
	const result = inputSystem.getInputCommand(
		InputAction.IA_POINTER,
		PointerEventType.PET_DOWN
	)
	if (result) {
		if (result.hit?.entityId === myEntity) {
			// 处理点击
		}
	}
})
```

{% hint style="warning" %}
**📔 注意**：每个要与之交互的实体都必须同时具有 [`PointerEvents` 组件](#show-feedback) 和一个 [碰撞体](https://docs.decentraland.org/creator/content-creator-zh/chang-jing-sdk7/3d-nei-rong-ji-chu/colliders.md).
{% endhint %}

请参阅 [输入操作的数据](#data-from-input-action) 了解更多信息。此方法还会提供有关指针事件命中情况的更详细数据。

### 按钮抬起

你也可以用类似的方法检查指针抬起事件，方法是使用 `PointerEventType.PET_UP`.

```ts
engine.addSystem(() => {
	if (
		inputSystem.isTriggered(
			InputAction.IA_POINTER,
			PointerEventType.PET_UP,
			myEntity
		)
	) {
		// 指针指向 myEntity 时按钮抬起的响应逻辑
	}
})
```

{% hint style="warning" %}
**📔 注意**：针对特定实体检查指针抬起事件时，不会考虑按下按钮时光标指向的位置，只会考虑抬起按钮时光标指向的位置。

还请注意，实体必须同时具有 [`PointerEvents` 组件](#show-feedback) 和一个 [碰撞体](https://docs.decentraland.org/creator/content-creator-zh/chang-jing-sdk7/3d-nei-rong-ji-chu/colliders.md).
{% endhint %}

### 检查按钮是否按下

在系统中使用 `inputSystem.isPressed()` ，检查按钮当前是否处于按下状态。

```ts
engine.addSystem(() => {
	if (inputSystem.isPressed(InputAction.IA_POINTER)) {
		// 按钮按住时的响应逻辑
	}
})
```

`inputSystem.isPressed()` 会在按钮当前处于按住状态时返回 *true* ，无论按钮何时按下，也无论玩家的光标指向何处。否则会返回 *false*.

该 `inputSystem.isPressed` 函数接受一个参数：

* `InputAction`：要监听的输入，取值为 `InputAction` 枚举中的值。请参阅 [指针按钮](https://docs.decentraland.org/creator/content-creator-zh/chang-jing-sdk7/jiao-hu-xing/an-niu-shi-jian/click-events.md#pointer-buttons) 以查看支持的选项。

### 处理多个实体

如果场景中有多个实体会以相同方式响应指针事件，那么编写一个遍历所有这些实体的系统会很合适。

```ts
engine.addSystem(() => {
	const activatedEntites = engine.getEntitiesWith(PointerEvents)
	for (const [entity] of activatedEntites) {
		if (
			inputSystem.isTriggered(
				InputAction.IA_POINTER,
				PointerEventType.PET_DOWN,
				entity
			)
		) {
			// 与实体交互时执行的逻辑
		}
	}
})
```

此示例使用 [组件查询](https://docs.decentraland.org/creator/content-creator-zh/chang-jing-sdk7/jia-gou/querying-components.md) 遍历所有带有 `PointerEvents` 组件的实体。然后，它使用 `inputSystem.isTriggered`逐个检查这些实体。如果在任一实体上检测到输入操作，就会执行自定义逻辑。

与其在一个系统中遍历 *所有* 带有 `PointerEvents` 组件的实体，不如编写不同的系统来处理行为各异的实体。建议使用特定的 [自定义组件](https://docs.decentraland.org/creator/content-creator-zh/chang-jing-sdk7/jia-gou/custom-components.md)标记不同类型的实体，并在单独的系统中遍历它们。

```ts
engine.addSystem(() => {
	const activatedDoors = engine.getEntitiesWith(IsDoor, PointerEvents)
	for (const [entity] of activatedDoors) {
		if (
			inputSystem.isTriggered(
				InputAction.IA_POINTER,
				PointerEventType.PET_DOWN,
				entity
			)
		) {
			openDoor(entity)
		}
	}
})

engine.addSystem(() => {
	const pickedUpGems = engine.getEntitiesWith(IsGem, PointerEvents)
	for (const [entity] of pickedUpGems) {
		if (
			inputSystem.isTriggered(
				InputAction.IA_POINTER,
				PointerEventType.PET_DOWN,
				entity
			)
		) {
			pickUp(entity)
		}
	}
})
```

此示例中，一个系统会遍历所有带有名为 `IsDoor` 的自定义组件的实体，另一个系统则会遍历所有带有名为 `isGem`的自定义组件的实体。两个系统都会检查每个匹配的实体，判断它们是否被指针按钮触发。

这种组织场景代码的方式非常 [面向数据](https://docs.decentraland.org/creator/content-creator-zh/chang-jing-sdk7/jia-gou/data-oriented-programming.md) ，应该能非常高效地利用内存资源。

\## 实体上的多个按钮

使用 `pointerEventsSystem.onPointerDown`这类辅助函数时，每个实体只能有一种事件类型，无法注册两个不同的按钮事件。使用基于系统的事件则没有这一限制。例如，下面的实体既可以通过按 E 键交互，也可以通过按 F 键交互，且两者会触发不同的功能。

```ts
    engine.addSystem(() => {
        if (inputSystem.isTriggered(InputAction.IA_PRIMARY, PointerEventType.PET_DOWN, myEntity)) {
            // 对 E 键作出响应
        }
        if (inputSystem.isTriggered(InputAction.IA_SECONDARY, PointerEventType.PET_DOWN, myEntity)) {
            // 对 F 键作出响应
        }
    })
```

## 显示反馈

若要在指针指向某个实体时显示 UI 提示，请使用该实体的 `PointerEvents` 组件中的属性。

```ts
// 创建实体
const myEntity = engine.addEntity()

// 为实体添加 PointerEvents 组件
PointerEvents.create(myEntity, {
	pointerEvents: [
		{
			eventType: PointerEventType.PET_DOWN,
			eventInfo: {
				button: InputAction.IA_POINTER,
			},
		},
	],
})
```

每当玩家的光标指向此实体中的碰撞体时，UI 都会显示悬停提示，表明该实体可以交互。有关可配置项的详细信息，请参阅以下章节。

{% hint style="warning" %}
**📔 注意**： `PointerEvents` 组件仅负责显示悬停反馈。如需通过自定义逻辑处理按钮事件本身，请参阅 [Using-a-system](#using-a-system).
{% endhint %}

该 `PointerEvents` 组件至少需要一个指针事件定义。每个指针事件定义可配置以下内容：

* `eventType`：要监听的事件类型，其值来自 `PointerEventType` 枚举。请参阅 [指针事件类型](https://docs.decentraland.org/creator/content-creator-zh/chang-jing-sdk7/jiao-hu-xing/an-niu-shi-jian/click-events.md#types-of-pointer-events) 了解支持的选项。
* `eventInfo`：一个可包含以下字段的对象：
  * `button` (*必需*）：要监听的输入，取值为以下 `InputAction` 枚举中的值。请参阅 [指针按钮](https://docs.decentraland.org/creator/content-creator-zh/chang-jing-sdk7/jiao-hu-xing/an-niu-shi-jian/click-events.md#pointer-buttons) 了解支持的选项。
  * `hoverText` *（可选）*：悬停反馈提示中显示的字符串。默认为“交互”。
  * `showFeedback` *（可选）*：如果为 false，则会隐藏此实体的悬停提示和边缘高亮。 *true* （默认值）。
  * `showHighlight` *（可选）*：如果为 true，玩家将鼠标悬停在实体上时，会看到边缘高亮。 *true* （默认值）。只有在 `showFeedback` 为 *true*.
  * `maxDistance` *（可选）*：玩家的 **头像** 与实体的距离上限，超过此距离便无法与其交互，单位为米。默认值为 *10 米*。请参阅 [最大距离](#max-distance).
  * `maxCameraDistance` *（可选）*： **活动摄像机** 与实体之间的最大交互距离（以米为单位）。默认未设置。请参阅 [最大距离](#max-distance).
  * `priority` *（可选）*：多个实体重叠时，决定哪个实体优先。数值越大，优先级越高。 *0* 默认值。

单个 `PointerEvents` 组件可以包含多个指针事件定义，用于检测不同按钮触发的不同事件。每个实体只能有 *一个* `PointerEvents` 组件，但此组件的 `pointerEvents` 数组中可以包含多个对象，每个对象对应一个要响应的事件。

```ts
PointerEvents.create(NPCEntity, {
	pointerEvents: [
		{
			eventType: PointerEventType.PET_DOWN,
			eventInfo: {
				button: InputAction.IA_POINTER,
				hoverText: 'Greet',
			},
		},
		{
			eventType: PointerEventType.PET_DOWN,
			eventInfo: {
				button: InputAction.IA_PRIMARY,
				hoverText: 'Choke',
			},
		},
		{
			eventType: PointerEventType.PET_UP,
			eventInfo: {
				button: InputAction.IA_PRIMARY,
				hoverText: 'Stop Choke',
			},
		},
		{
			eventType: PointerEventType.PET_DOWN,
			eventInfo: {
				button: InputAction.IA_SECONDARY,
				hoverText: 'Give gem',
			},
		},
	],
})
```

玩家会看到多个标签，每个指针事件对应一个，围绕光标呈放射状显示。

下面的示例将使用 `PointerEvents` 显示悬停提示，并结合一个系统，通过自定义逻辑处理玩家的实际操作。

```ts
// 创建实体
const myEntity = engine.addEntity()

// 为实体提供悬停反馈
PointerEvents.create(myEntity, {
	pointerEvents: [
		{
			eventType: PointerEventType.PET_DOWN,
			eventInfo: {
				button: InputAction.IA_POINTER,
				hoverText: 'Open',
			},
		},
	],
})

// 处理对实体的点击事件
engine.addSystem(() => {
	if (
		inputSystem.isTriggered(
			InputAction.IA_POINTER,
			PointerEventType.PET_DOWN,
			myEntity
		)
	) {
		// 响应输入操作的自定义逻辑
	}
})
```

### 悬停反馈

玩家将光标悬停在带有 `PointerEvents` 组件的物品上时，会看到：

* 实体边缘高亮显示
* 光标附近会显示悬停提示，其中包含需要按下的按钮图标，以及显示“交互”的文字。

这些元素可以切换和自定义。

界面上的悬停反馈会根据你在 `button` 字段中选择的输入显示不同的图标。在 PC 上， `E` 对应 `InputAction.IA_PRIMARY`， `F` 对应 `对应 InputAction.IA_SECONDARY`，鼠标图标对应 `InputAction.IA_POINTER`.

更改 `hoverText` 值即可更改显示的文字。请保持文字简短，以便快速阅读，同时避免过多遮挡屏幕。

```ts
// 创建实体
const chest = engine.addEntity()

// 为实体添加 PointerEvents 组件
PointerEvents.create(chest, {
	pointerEvents: [
		{
			eventType: PointerEventType.PET_DOWN,
			eventInfo: {
				button: InputAction.IA_POINTER,
				hoverText: 'Open',
			},
		},
	],
})
```

在上面的示例中，指针事件包含一个 `hoverText`值。此字段定义玩家指向实体时在 UI 中显示的字符串。默认情况下，该字符串为 *互动*.

{% hint style="info" %}
**💡 提示**： `hoverText` 字符串应描述交互时发生的操作。例如 `打开`, `激活`, `抓取`, `选择`。这些字符串应尽可能简短，以免过多分散玩家的注意力。
{% endhint %}

如果一个实体上有多个指针事件，这些事件各自的悬停提示会以光标为中心呈放射状显示。

该 `hoverText` 的 `.UP` 只有当玩家已经按住对应的按键并指向该实体时，才会显示指针事件。

如果某个实体同时具有 `DOWN` 指针事件和 `UP` 指针事件，则在未按下按钮时会显示 `DOWN` 操作的提示。只有在按下按钮并保持按下状态时，提示才会切换为来自 `UP` 事件的提示。

```ts
// 创建实体
const entity = engine.addEntity()

// 为实体添加 PointerEvents 组件
PointerEvents.create(entity, {
	pointerEvents: [
		{
			eventType: PointerEventType.PET_DOWN,
			eventInfo: {
				button: InputAction.IA_POINTER,
				hoverText: 'Drag',
			},
		},
		{
			eventType: PointerEventType.PET_UP,
			eventInfo: {
				button: InputAction.IA_POINTER,
				hoverText: 'Drop',
			},
		},
	],
})
```

若要隐藏悬停提示但保留边缘高亮，请将 `hoverText` 的值设为 ""。

```ts
// 创建实体
const chest = engine.addEntity()

// 为实体添加 PointerEvents 组件
PointerEvents.create(chest, {
	pointerEvents: [
		{
			eventType: PointerEventType.PET_DOWN,
			eventInfo: {
				button: InputAction.IA_POINTER,
				hoverText: '',
			},
		},
	],
})
```

若要隐藏边缘高亮但保留悬停提示，请将 `showHighlight` 设为 *false*.

```ts
// 创建实体
const chest = engine.addEntity()

// 为实体添加 PointerEvents 组件
PointerEvents.create(chest, {
	pointerEvents: [
		{
			eventType: PointerEventType.PET_DOWN,
			eventInfo: {
				button: InputAction.IA_POINTER,
				hoverText: 'Open door',
				showHighlight: false,
			},
		},
	],
})
```

若要同时隐藏悬停提示和边缘高亮，请将 `showFeedback` 设置为 *false*。这样设置后，光标不会显示任何图标或文字，也不会显示任何边缘高亮。你也可以直接从实体中移除 `PointerEvents` 组件。

```ts
// 创建实体
const chest = engine.addEntity()

// 为实体添加 PointerEvents 组件
PointerEvents.create(chest, {
	pointerEvents: [
		{
			eventType: PointerEventType.PET_DOWN,
			eventInfo: {
				button: InputAction.IA_POINTER,
				showFeedback: false,
			},
		},
	],
})
```

### 最大距离

某些实体可能被有意设置为仅在近距离内可交互。如果玩家离实体太远，光标旁边就不会显示悬停提示。

默认情况下，只有当玩家的 **化身** 距离实体不超过 *10 米* 时，才能点击该实体。你可以通过设置指针事件的 `maxDistance` 属性来更改此距离。

```ts
// 创建实体
const myEntity = engine.addEntity()

// 为实体添加 PointerEvents 组件
PointerEvents.create(myEntity, {
	pointerEvents: [
		{
			eventType: PointerEventType.PET_DOWN,
			eventInfo: {
				button: InputAction.IA_POINTER,
				maxDistance: 6,
			},
		},
	],
})

// implement a system to handle the pointer event
engine.addSystem(() => {
	// fetch data about the pointer event
	const cmd = inputSystem.getInputCommand(
		InputAction.IA_POINTER,
		PointerEventType.PET_DOWN,
		myEntity
	)

	// 检查点击是否足够接近
	if (cmd && cmd.hit && cmd.hit.length < 6) {
		// 执行某些操作
	}
})
```

上面的示例将悬停提示的最大距离设为 *6 米*。请确保处理输入操作的逻辑也遵循相同规则。有关如何获取输入操作的距离，请参阅 [输入操作中的数据](#data-from-input-action) 。

`maxDistance` 是从玩家的 **化身**，因此它在第一人称和第三人称视角下的行为相同。

若要改为根据 **当前摄像机** 的距离限制交互，请使用 `maxCameraDistance`。同时设置两者意味着任一检查通过即可。完整规则请参阅 [距离限制](https://docs.decentraland.org/creator/content-creator-zh/chang-jing-sdk7/jiao-hu-xing/an-niu-shi-jian/register-callback.md#distance-limits) 。

{% hint style="warning" %}
**📔 注意**: `maxPlayerDistance` 是一个已弃用的别名，对应 `maxDistance`。两者都测量与虚拟形象之间的距离，因此请使用 `maxDistance` 来构建新场景。
{% endhint %}

## 高级自定义提示

通过 `PointerEvents` 组件，可以轻松地在玩家的光标开始悬停在实体上时显示 UI 提示。通常，让提示的行为与玩家在其他 Decentraland 场景中习惯看到的保持一致是个好做法。不过，在某些情况下，你可能希望以自定义方式提示某个对象可以交互。例如，当玩家开始将光标悬停在实体上时，可以播放一段轻柔的声音。也可以在悬停期间在实体周围显示发光的高亮效果，并在不再悬停时将其隐藏。还可以将其用于特定的游戏机制。

使用 `inputSystem.isTriggered()` 函数与 `PointerEventType.PET_HOVER_ENTER` 和 `PointerEventType.PET_HOVER_LEAVE` 事件结合使用，以便在玩家的光标开始指向实体的碰撞体，以及光标不再指向该碰撞体时，执行自定义行为。

下面的示例会在光标开始指向实体的碰撞体时，将实体放大到 *1.5* ，并在光标移开时将实体恢复到大小为 *1* 。

```ts
engine.addSystem(() => {
	const meshEntities = engine.getEntitiesWith(MeshRenderer)
	for (const [entity] of meshEntities) {
		if (
			inputSystem.isTriggered(
				InputAction.IA_POINTER,
				PointerEventType.PET_HOVER_ENTER,
				entity
			)
		) {
			Transform.getMutable(entity).scale = Vector3.create(1.5, 1.5, 1.5)
		}

		if (
			inputSystem.isTriggered(
				InputAction.IA_POINTER,
				PointerEventType.PET_HOVER_LEAVE,
				entity
			)
		) {
			Transform.getMutable(entity).scale = Vector3.create(1, 1, 1)
		}
	}
})
```

{% hint style="warning" %}
**📔 注意**：每个要与之交互的实体都必须同时具有 [`PointerEvents` 组件](#show-feedback) 和一个 [碰撞体](https://docs.decentraland.org/creator/content-creator-zh/chang-jing-sdk7/3d-nei-rong-ji-chu/colliders.md).
{% endhint %}

## 接近事件

无论光标指向何处，都可以使用 `PET_DOWN` 在使用 `InteractionType.PROXIMITY`的实体上检查接近按钮按下事件。将指针事件定义中 `interactionType` 字段（位于 `eventInfo`旁边）设置为接近类型，以标记该事件。

详细信息请参阅 [**接近事件**](https://docs.decentraland.org/creator/content-creator-zh/chang-jing-sdk7/jiao-hu-xing/an-niu-shi-jian/proximity-events.md) ，其中还介绍了可用的辅助函数。

```ts
PointerEvents.create(myEntity, {
	pointerEvents: [
		{
			eventType: PointerEventType.PET_DOWN,
			eventInfo: {
				button: InputAction.IA_PRIMARY,
				hoverText: 'Press E',
				maxDistance: 5
			},
			interactionType: InteractionType.PROXIMITY,
		},
	],
})

engine.addSystem(() => {
	if (inputSystem.isTriggered(InputAction.IA_PRIMARY, PointerEventType.PET_DOWN, myEntity)) {
		console.log('Player pressed button near entity')
	}
})
```

借助 `pointerEventsSystem.onProximityDown`等辅助函数，一个实体可以同时拥有一个光标处理程序和一个接近处理程序，并且两个回调都会运行。但它无法为同一处理程序注册两个不同的按钮。基于系统的事件则没有这些限制：每种行为都可以定义一个条目。例如，下面的实体既可以通过将光标指向它并按 E 进行交互，也可以在不将光标指向它的情况下走近并按 E 进行交互。

```ts
	PointerEvents.create(myEntity, {
        pointerEvents: [
            {
                eventType: PointerEventType.PET_DOWN,
                eventInfo: {
                    button: InputAction.IA_POINTER,
                    hoverText: 'Click',
                    maxDistance: 15,
                },
                interactionType: InteractionType.CURSOR,
            },
            {
                eventType: PointerEventType.PET_DOWN,
                eventInfo: {
                    button: InputAction.IA_PRIMARY,
                    hoverText: 'Press E',
                    maxDistance: 15,
                },
                interactionType: InteractionType.PROXIMITY,
            },
        ],
    })
    
    engine.addSystem(() => {
        if (inputSystem.isTriggered(InputAction.IA_POINTER, PointerEventType.PET_DOWN, myEntity)) {
            console.log('Player clicked at entity')
        }
        if (inputSystem.isTriggered(InputAction.IA_PRIMARY, PointerEventType.PET_DOWN, myEntity)) {
            console.log('Player pressed button near entity')
        }
    })
```

你也可以将 `inputSystem.isTriggered()` 与 `PET_PROXIMITY_ENTER` 和 `PET_PROXIMITY_LEAVE` 事件类型配合使用，以便在玩家进入或离开实体的接近范围时作出响应。这对于为通过接近触发的实体提供额外反馈很有用，例如播放声音或动画。

要使其正常工作，实体必须具有一个 `PointerEvents` 组件，并定义相应的接近事件类型。

```ts
PointerEvents.create(myEntity, {
	pointerEvents: [
		{
			eventType: PointerEventType.PET_PROXIMITY_ENTER,
			eventInfo: {
				button: InputAction.IA_POINTER,
				maxDistance: 5,
			},
		},
		{
			eventType: PointerEventType.PET_PROXIMITY_LEAVE,
			eventInfo: {
				button: InputAction.IA_POINTER,
				maxDistance: 5,
				showFeedback: false,
			},
		},
	],
})

engine.addSystem(() => {
	if (inputSystem.isTriggered(InputAction.IA_POINTER, PointerEventType.PET_PROXIMITY_ENTER, myEntity)) {
		console.log('Player entered proximity')
	}
	if (inputSystem.isTriggered(InputAction.IA_POINTER, PointerEventType.PET_PROXIMITY_LEAVE, myEntity)) {
		console.log('Player left proximity')
	}
})
```

## 输入操作数据

获取输入操作的数据，例如按下的按钮、命中的实体、射线的方向和长度等。请参阅（[查看文档](https://github.com/decentraland/docs/tree/main/README.md)），了解所有可用数据的说明。

要获取此数据，请使用 `inputSystem.getInputCommand`。此函数会返回完整的数据结构，其中包含有关输入事件的数据。

```ts
engine.addSystem(() => {
	const cmd = inputSystem.getInputCommand(
		InputAction.IA_POINTER,
		PointerEventType.PET_DOWN,
		myEntity
	)
	if (cmd) {
		console.log(cmd.hit?.entityId)
	}
})
```

如果没有与查询匹配的输入操作， `inputSystem.getInputCommand` 会返回 *null*。请确保在逻辑中处理这种情况。

### 最大点击距离

要限制最大距离，让实体只能在近距离内被点击，请获取事件数据中的 `hit.length` 属性。

```ts
// implement a system to handle the pointer event
engine.addSystem(() => {
	// fetch data about the pointer event
	const cmd = inputSystem.getInputCommand(
		InputAction.IA_POINTER,
		PointerEventType.PET_DOWN,
		myEntity
	)

	// 检查点击是否足够接近
	if (cmd && cmd.hit && cmd.hit.length < 6) {
		// 执行某些操作
	}
})
```

{% hint style="warning" %}
**📔 注意**：如果要忽略距离较远的事件，请确保在 `PointerEvents` 组件上设置 `maxDistance` 参数，以保持行为一致。
{% endhint %}

### 模型中的不同网格

通常， *.glTF* 3D 模型由多个网格组成，每个网格都有各自的内部名称。所有按钮事件都会包含被点击的具体网格的信息，因此你可以根据此信息触发不同的点击行为。

要查看模型中网格的名称，你必须使用编辑工具打开 3D 模型，例如 [Blender](https://www.blender.org/) 。

![](https://2460066822-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoPnXBby9S6MrsW83Y9qZ%2Fuploads%2Fgit-blob-e2fc19b4253833aec3e79f338177b0c6657fb696%2Fmesh-names.webp?alt=media)

{% hint style="info" %}
**💡 提示**：你也可以通过记录被点击网格的名称并在控制台中查看来了解它的名称。
{% endhint %}

你可以通过点击事件返回的 `hit` 对象访问 `meshName` 属性。

在下面的示例中，我们有一个房屋模型，其中包含一个名为 `firePlace`的网格。我们希望仅在点击对应的网格时才点燃壁炉。

```ts
engine.addSystem(() => {
	const cmd = inputSystem.getInputCommand(
		InputAction.IA_POINTER,
		PointerEventType.PET_DOWN,
		myEntity
	)
	if (cmd && cmd.hit?.meshName === 'firePlace') {
		// 点燃壁炉
	}
})
```

{% hint style="warning" %}
**📔 注意**：这仅适用于基于指针的事件，不适用于基于距离的事件，因为在这种情况下，模型的所有网格都可能同时处于玩家的邻近范围内。
{% endhint %}


---

# 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/system-based-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.
