From bfbd24607b89d86fb995e9ce98eac7a7dbd277dd Mon Sep 17 00:00:00 2001
From: Muna <44584806+decentraland-bot@users.noreply.github.com>
Date: Fri, 22 May 2026 15:39:53 -0300
Subject: [PATCH] docs: clarify trigger?.entity vs triggeredEntity fields in
 TriggerArea

---
 creator/sdk7/3d-essentials/trigger-areas.md | 11 +++++++++++
 1 file changed, 11 insertions(+)

diff --git a/creator/sdk7/3d-essentials/trigger-areas.md b/creator/sdk7/3d-essentials/trigger-areas.md
index 6e243e2b..a4769b5b 100644
--- a/creator/sdk7/3d-essentials/trigger-areas.md
+++ b/creator/sdk7/3d-essentials/trigger-areas.md
@@ -133,6 +133,17 @@ The following properties are available in the `result` parameter:
   * `rotation`: The rotation of the entity that triggered the trigger
   * `scale`: The scale of the entity that triggered the trigger
 
+{% hint style="warning" %}
+**⚠️ Common confusion — `triggeredEntity` vs `result.trigger?.entity`**
+
+These two fields are easily mixed up:
+
+* **`result.trigger?.entity`** — the entity that **walked into** the trigger area (Entity B — this is usually what you want to check, e.g. to identify which player or object entered).
+* **`result.triggeredEntity`** — the entity that **owns the TriggerArea component** (Entity A — the static trigger zone itself, not the entity that entered it).
+
+Despite the name, `triggeredEntity` does **not** refer to the entity that triggered the event. It refers to the entity whose trigger area was activated. Use `result.trigger?.entity` when you need to identify the entering entity.
+{% endhint %}
+
 ```ts
 import { engine, Transform, TriggerArea, triggerAreaEventsSystem } from '@dcl/sdk/ecs'