> 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/3d-nei-rong-ji-chu/trigger-areas.md).

# 触发区域

了解如何在场景中使用触发区域

触发区域允许你响应玩家或任何其他实体进入或离开某个区域的事件。这是创建交互场景的基础工具。你可以用它实现玩家靠近时开门，或球进入球门时得分等效果。

## 使用触发区域

要使用触发区域，你需要向实体添加 `TriggerArea` 组件，然后使用 `triggerAreaEventsSystem` 来响应这些事件。

```ts
import { engine, Transform, TriggerArea, triggerAreaEventsSystem } from '@dcl/sdk/ecs'

// 创建实体
const triggerEntity = engine.addEntity()

// 设置 Transform
Transform.create(triggerEntity, {
  position: Vector3.create(8, 0, 8)
  })

// 触发区域
TriggerArea.setBox(triggerEntity)

// 触发区域激活时的事件
triggerAreaEventsSystem.onTriggerEnter(triggerEntity, function(result) {
  if (result.trigger?.entity !== engine.PlayerEntity) return;
  console.log('玩家进入了触发区域！')
})
```

默认情况下， `TriggerArea` 组件会响应 *任意* 玩家走入区域的事件。上面的代码添加了 `if (result.trigger?.entity !== engine.PlayerEntity) return` 来检查触发事件的实体是否为当前玩家，而不是其他人的化身

## 触发区域形状

触发区域可以是立方体或球体。

```ts
import { engine, Transform, TriggerArea } from '@dcl/sdk/ecs'

// 立方体
TriggerArea.setBox(triggerEntity)

// 球体
TriggerArea.setSphere(triggerEntity)
```

{% hint style="info" %}
**💡 提示**：球体是引擎最容易计算的形状，因为只需检查与球心的距离即可。如果不确定该选哪种形状，请使用球体。
{% endhint %}

要调整触发区域的大小，可以使用实体上 `scale` 属性，该实体包含 `Transform` 组件和 `TriggerArea`.

```ts
import { engine, Transform, TriggerArea } from '@dcl/sdk/ecs'

const triggerEntity = engine.addEntity()

TriggerArea.setBox(triggerEntity)

Transform.create(triggerEntity, {
  scale: Vector3.create(4, 2, 4),
})
```

### 调试

要调试场景并查看触发区域覆盖的范围，可以向带有触发区域的实体添加 `MeshRenderer` 组件，并将形状设为你想要调试的形状。默认网格的尺寸会与触发区域的尺寸相匹配。

```ts
import { engine, Transform, TriggerArea } from '@dcl/sdk/ecs'

const triggerEntity = engine.addEntity()

TriggerArea.setBox(triggerEntity)

MeshRenderer.setBox(triggerEntity)

Transform.create(triggerEntity, {
  position: Vector3.create(8, 0, 8),
})
```

## 触发区域事件

你可以使用 `triggerAreaEventsSystem` 来响应触发区域的不同事件：

* `onTriggerEnter`：当实体进入触发区域时触发。
* `onTriggerExit`：当实体离开触发区域时触发。
* `onTriggerStay`：实体处于触发区域内时，每帧都会触发。

```ts
import { engine, Transform, TriggerArea, triggerAreaEventsSystem } from '@dcl/sdk/ecs'

const triggerEntity = engine.addEntity()

TriggerArea.setBox(triggerEntity)

// 进入时
triggerAreaEventsSystem.onTriggerEnter(triggerEntity, function(result) {
  console.log('玩家进入了触发区域！')
})

// 离开时
triggerAreaEventsSystem.onTriggerExit(triggerEntity, function(result) {
  console.log('Player exited trigger area!')
})

// 停留时
triggerAreaEventsSystem.onTriggerStay(triggerEntity, function(result) {
  console.log('Player is in trigger area!')
})
```

## 触发事件的响应

触发区域事件触发时，可以使用 `result` 参数获取有关被触发实体以及触发该事件的实体的信息。

result `参数中提供以下属性：` ：

* `triggeredEntity`：被触发实体的 ID（即拥有触发区域的实体）
* `triggeredEntityPosition`：被触发实体的位置
* `triggeredEntityRotation`：被触发实体的旋转
* `eventType`：触发事件的类型（ENTER、EXIT、STAY）
* `timestamp`：触发事件的时间戳
* `trigger`：包含以下字段的对象：
  * `entity`：触发触发器的实体 ID（即进入触发区域的实体）
  * `layers`：触发触发器的实体的碰撞层
  * `position`：触发触发器的实体的位置
  * `rotation`：触发触发器的实体的旋转
  * `scale`：触发触发器的实体的缩放

{% hint style="warning" %}
**常见误解**：尽管名称如此， `result.triggeredEntity` 并 **不** 指触发该事件的实体。这两个字段很容易混淆：

* `result.trigger?.entity`：进入触发区域的实体。通常你需要检查的就是它，例如用于识别进入区域的是哪个玩家或物体。
* `result.triggeredEntity`：拥有 `TriggerArea` 组件的实体（即触发区域本身，而不是进入该区域的实体）。

如果需要识别进入区域的实体，请使用 `result.trigger?.entity` 。
{% endhint %}

```ts
import { engine, Transform, TriggerArea, triggerAreaEventsSystem } from '@dcl/sdk/ecs'

// 拥有触发区域的实体
const triggerEntity = engine.addEntity()

TriggerArea.setBox(triggerEntity)

Transform.create(triggerEntity, {
  position: Vector3.create(8, 0, 8),
})

// 进入时
triggerAreaEventsSystem.onTriggerEnter(triggerEntity, function(result) {
  console.log('An entity entered trigger area!', result.triggeredEntity)
  console.log('Triggered entity position: ', result.triggeredEntityPosition)
  console.log('Triggered entity rotation: ', result.triggeredEntityRotation)
  console.log('Event type: ', result.eventType)
  console.log('Timestamp: ', result.timestamp)
  console.log('Trigger entity: ', result.trigger.entity)
  console.log('Trigger layers: ', result.trigger.layers)
  console.log('Trigger position: ', result.trigger.position)
  console.log('Trigger rotation: ', result.trigger.rotation)
  console.log('Trigger scale: ', result.trigger.scale)
})
```

## 检测玩家进入区域

触发区域最常见的用途，是对玩家进入或离开区域作出反应。两个碰撞层可用于检测头像，具体使用哪个取决于场景应对谁作出反应：

* `ColliderLayer.CL_MAIN_PLAYER`：仅检测 **正在使用本地设备的玩家**。如果响应只针对该玩家，例如将其传送、为其播放声音，或跟踪其任务进度，请使用此层。从性能角度来看，这也是开销最低的选项。
* `ColliderLayer.CL_PLAYER`：检测 **所有头像**，包括本地玩家和场景中渲染的其他玩家。如果任何人进入都很重要，例如有人靠近时打开的门，或统计房间内有多少人，请使用此层。如果未指定图层，默认使用此层。

以下示例仅对本地玩家作出反应：

```ts
import { engine, Transform, TriggerArea, ColliderLayer, triggerAreaEventsSystem } from '@dcl/sdk/ecs'

// 创建实体
const triggerEntity = engine.addEntity()

// 设置 Transform
Transform.create(triggerEntity, {
  position: Vector3.create(8, 0, 8),
})

// 仅检测本地玩家的触发区域
TriggerArea.setBox(triggerEntity, ColliderLayer.CL_MAIN_PLAYER)

// 触发区域激活时的事件
triggerAreaEventsSystem.onTriggerEnter(triggerEntity, function (result) {
  console.log('You entered the trigger area!')
})
```

使用 `CL_PLAYER`时，所有头像都会触发该区域。若要判断触发区域的头像是否为本地玩家，请将结果中的实体与 `engine.PlayerEntity`:

```ts
import { engine, Transform, TriggerArea, triggerAreaEventsSystem } from '@dcl/sdk/ecs'

// 创建实体
const triggerEntity = engine.addEntity()

// 设置 Transform
Transform.create(triggerEntity, {
  position: Vector3.create(8, 0, 8),
})

// 使用默认 CL_PLAYER 图层的触发区域
TriggerArea.setBox(triggerEntity)

// 触发区域激活时的事件
triggerAreaEventsSystem.onTriggerEnter(triggerEntity, function (result) {
  if (result.trigger?.entity === engine.PlayerEntity) {
    console.log('You entered the trigger area!')
  } else {
    console.log('Another player entered the trigger area!')
  }
})
```

大多数情况下，与其尝试检测所有玩家，不如只检测当前玩家（通过 `CL_MAIN_PLAYER`），然后在所有玩家之间同步该触发器的效果。例如，滑动门只会为你的头像打开，但门的打开状态随后会同步给所有其他玩家。

{% hint style="info" %}
**💡 提示**：掩码仅包含头像图层（`CL_PLAYER`, `CL_MAIN_PLAYER`、 `CL_MAIN_PLAYER` ，或两者）的触发区域经过了优化：引擎会将它们置于仅供头像使用的物理图层中，因此与头像以外对象的重叠会在到达场景代码之前被物理引擎丢弃。掩码恰好等于
{% endhint %}

的触发区域还会进一步优化：在到达处理程序之前，它会直接跳过与非本地玩家碰撞体的任何重叠，因此仅检测本地玩家几乎没有开销。\
\
触发区域图层
------

使用 `TriggerArea` 组件的可选第二个参数来设置会激活触发区域的图层。默认情况下，只有 `ColliderLayer.CL_PLAYER`图层会激活触发区域，参见 [检测玩家进入区域](#detect-players-entering-an-area).

将其他实体的碰撞图层作为 `TriggerArea` 组件的第二个参数传入，即可更改碰撞图层以检测该实体。

```ts
import { engine, Transform, TriggerArea, MeshCollider, ColliderLayer, triggerAreaEventsSystem } from '@dcl/sdk/ecs'

// 触发区域
const triggerEntity = engine.addEntity()

TriggerArea.setBox(triggerEntity, ColliderLayer.CL_CUSTOM1)

Transform.create(triggerEntity, {
  position: Vector3.create(8, 0, 8),
})

// 会激活触发区域的实体
const movingEntity = engine.addEntity()

Transform.create(movingEntity, {
  position: Vector3.create(8, 0, 8),
})

MeshCollider.setBox(movingEntity, ColliderLayer.CL_CUSTOM1)
```

允许的值与 `MeshCollider` 组件相同。详情请参阅 [碰撞图层](https://docs.decentraland.org/creator/content-creator-zh/chang-jing-sdk7/3d-nei-rong-ji-chu/colliders.md#collision-layers) 。

* `ColliderLayer.CL_PLAYER`：任意头像（本地和远程）
* `ColliderLayer.CL_MAIN_PLAYER`：仅本地玩家
* `ColliderLayer.CL_PHYSICS`
* `ColliderLayer.CL_POINTER`
* `ColliderLayer.CL_CUSTOM1` 至 `CL_CUSTOM8`
* `ColliderLayer.CL_NONE`

{% hint style="info" %}
**💡 提示**：图层 `CL_CUSTOM1` 至 `CL_CUSTOM8` 本身没有任何特殊行为，你可以根据场景需求自由使用。
{% endhint %}

你也可以设置触发区域，使其同时检测多个图层。

```ts
import { engine, Transform, TriggerArea, ColliderLayer, triggerAreaEventsSystem } from '@dcl/sdk/ecs'

const triggerEntity = engine.addEntity()

TriggerArea.setBox(triggerEntity, ColliderLayer.CL_CUSTOM1 | ColliderLayer.CL_CUSTOM2)

Transform.create(triggerEntity, {
  position: Vector3.create(8, 0, 8),
})
```

当具有 `CL_CUSTOM1` 或 `CL_CUSTOM2` 图层的任意实体进入触发区域时，该区域都会被激活。

{% hint style="info" %}
**💡 提示**：如需查看一个完整演示 `TriggerArea` 端到端流程的可运行示例，请参阅 [`75,-9-trigger-areas`](https://github.com/decentraland/sdk7-test-scenes/tree/main/scenes/75,-9-trigger-areas) 测试场景，其中涵盖了 ENTER/EXIT 事件约定，以及 SDK 按 tick 调用的 `onTriggerStay` 合成、旋转区域、自定义碰撞层上的移动触发器，以及附加到下落实体上的区域。要了解碰撞层本身的行为，请参阅 [`5,5-collider-layers`](https://github.com/decentraland/sdk7-test-scenes/tree/main/scenes/5,5-collider-layers).
{% 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/3d-nei-rong-ji-chu/trigger-areas.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.
