trigger areas

content/ADR-258-trigger-areas.md

@@ -0,0 +1,201 @@
+---
+layout: adr
+adr: 258
+title: Trigger Areas
+date: 2025-02-19
+status: Draft
+type: RFC
+spdx-license: CC0-1.0
+authors:
+  - nearnshaw
+---
+
+## Abstract
+
+This document describes an approach for implementing native trigger areas in creator scenes. Triggers are a fundamental feature of game development that should be available as a core engine capability rather than requiring external dependencies. Currently, creators must rely heavily on the Utils library for this essential functionality, which presents several significant limitations:
+
+- **Performance degradation**: The library implementation results in bad performance and slower SDK ticks due to its non-native approach
+- **Shape constraints**: Triggers are restricted to box colliders only, limiting creative possibilities  
+- **Developer experience**: The current approach is not easy on the creator and requires additional library dependencies
+- **Architectural limitations**: As a library solution, it cannot leverage engine-level optimizations or native collision detection
+
+The native engine implementation addresses these issues by providing:
+- Better performance through engine-level integration with the existing collision system
+- Support for any arbitrary shape from 3D models using mesh colliders, not just primitive shapes
+- Seamless integration with existing components like MeshCollider and ColliderLayer
+- A friendlier developer experience through helper functions similar to our pointerEvents system
+- Native support for multiple trigger layers and collision detection
+
+This new approach enables creators to define trigger areas using any collider shape - from simple primitives to complex meshes from GLTF models - and react to enter, exit, and stay events when entities on specific collision layers overlap with them.
+
+## Trigger areas
+
+Trigger areas are a region in the scene that trigger an action whenever something overlaps with them (usually the player, but not necessarily). We can also trigger actions continuously while something keeps overlapping (on each frame), or when it stops overlapping.
+
+The shape of a trigger area is given by a collider. It can use a simple primitive shape, or it can even take any arbitrary shape from a 3D model.
+
+We will create a new component for this, called `TriggerArea`. It will have the following fields:
+
+- `mesh`: An enum, that allows to define the shape of the trigger area. `TAMT_BOX` (default) or `TAMT_SPHERE`
+- `collisionMask`: The collision layer mask that triggers the trigger
+
+
+### Collision layers
+
+Trigger areas can only be triggered by entities on certain _collision layers_. We should reuse the `ColliderLayer` enum for this.
+
+Most of the time you want to check for just the position of the player, so we should have a collision layer dedicated to this, and it should be the default of any Trigger component. This new layer should be added to the `ColliderLayer` enum.
+
+The `ColliderLayer` enum should have the following values:
+
+- `CL_NONE`: No layer, the trigger area will not trigger any events
+- `CL_POINTER`: The default layer for any pointer events
+- `CL_PHYSICS`: The default layer for all entities with a physics collider
+- `CL_CUSTOM1`: A custom layer for any other object that can move around the scene
+- `CL_CUSTOM2`: A custom layer for any other object that can move around the scene
+- `CL_CUSTOM3`: A custom layer for any other object that can move around the scene
+- `CL_CUSTOM4`: A custom layer for any other object that can move around the scene
+- `CL_CUSTOM5`: A custom layer for any other object that can move around the scene
+- `CL_CUSTOM6`: A custom layer for any other object that can move around the scene
+- `CL_CUSTOM7`: A custom layer for any other object that can move around the scene
+- `CL_CUSTOM8`: A custom layer for any other object that can move around the scene
+- `CL_PLAYER`: The default layer for the player
+
+A single trigger area can have multiple trigger layers at once, similarly to how collision layers work on colliders.
+
+When using the `POINTER` layer, the trigger area will trigger events when the pointer is hovered over it, in the same way that ON_HOVER events from the PointerEvents component work.
+
+When using the `PHYSICS` layer, the trigger area will trigger events when any entity with a physics collider overlaps with it.
+
+Note: If a collider with the same shape blocks a player from entering a trigger area, then we won't consider a trigger event being sent. There must be an overlap with the area, not just contact. For example, if a same entity has both a MeshCollider component set to the layer `CL_PHYSICS` and a Trigger component set to the layer `CL_PLAYER`, and both meshes have the same shape, then the player will never be able to activate a trigger event from this entity. In the future we'll likely want to do _Collision Events_ as a separate feature.
+
+### Trigger events
+
+Trigger areas can trigger events when the player (or any other entity on the trigger layer) enters, exits or stays in the area.
+
+Trigger events are shared from the engine to the SDK via a component, following a similar approach as we do with pointer events and raycasts. We define a `TriggerAreaResult` component for this purpose. Creators are not expected to read values or make use of this component directly, unless they really want to fine tune their scene’s behavior — the `triggerAreaEventsSystem` helpers (see _Code helpers_ below) are the supported entry point.
+
+The `TriggerAreaResult` component is grow-only (GOVS): every event is appended as a discrete entry rather than overwriting the previous one. Each entry has the following fields:
+
+- `triggeredEntity`: The entity that was triggered (this is the entity that owns the trigger area)
+- `triggeredEntityPosition`: The position of the triggered entity at the time of the trigger.
+- `triggeredEntityRotation`: The rotation of the triggered entity at the time of the trigger.
+- `eventType`: The state of the trigger event (`TAET_ENTER`, `TAET_EXIT`, `TAET_STAY`)
+- `timestamp`: The timestamp of the trigger event
+- `trigger`: An object with the following fields:
+  - `entity`: The entity that triggered the trigger
+  - `layers`: The collision layermask of the entity that triggered the Trigger Area
+  - `position`: The position of the entity that triggered the trigger
+  - `rotation`: The rotation of the entity that triggered the trigger
+  - `scale`: The scale of the entity that triggered the trigger
+
+#### Emission contract: ENTER/EXIT on the wire, STAY synthesized by the SDK
+
+The three event types are split across two layers:
+
+- **`TAET_ENTER` and `TAET_EXIT`** are emitted by the engine (Explorer) as discrete state transitions: one entry per (trigger area, triggerer) pair when the triggerer crosses into the area, and one when it crosses out. These are the only event types that travel over the CRDT wire. Explorer implementations **MUST NOT** emit `TAET_STAY` entries — emitting them every frame floods the CRDT channel and overflows the GOVS buffer, which is capped at a small number of entries.
+
+- **`TAET_STAY`** is the responsibility of the SDK runtime. The SDK's `triggerAreaEventsSystem` maintains a per-trigger-area set of "currently inside" triggerers, driven entirely by the wire `TAET_ENTER` and `TAET_EXIT` events: on `TAET_ENTER` the triggerer is added to the set, on `TAET_EXIT` it is removed. On every tick, for each triggerer still in the set, the SDK synthesizes a `PBTriggerAreaResult` with `eventType = TAET_STAY` and dispatches it to any `onTriggerStay` callback registered for the trigger area. Synthesized payloads refresh `position`, `rotation` and `scale` from the live `Transform` component of the trigger area and triggerer entities when those are scene-owned; for triggerers without a scene-side `Transform` (e.g. the reserved player-avatar entity) the synthesized payload falls back to the cached values from the most recent `TAET_ENTER`.
+
+This split means scene developers see no behavioral difference: an `onTriggerStay` callback continues to fire every frame while a triggerer remains inside, with `result.eventType === TriggerAreaEventType.TAET_STAY` on every call. Only the wire footprint changes: at 60 fps with N triggerers inside, traffic drops from O(60·N) `TriggerAreaResult` appends per second to O(1) — exactly one append on enter and one on exit per (trigger area, triggerer) session.
+
+For backward compatibility, SDK runtimes **MUST** silently ignore any `TAET_STAY` entries that arrive on the wire from legacy Explorer implementations that have not yet adopted this contract. The synthesized per-tick dispatch is the single source of truth; wire `TAET_STAY` events must not be forwarded to `onTriggerStay` callbacks, to avoid double-firing.
+
+### Ensure detection
+
+There's a possible scenario where an entity may be moving so fast that it crosses through a trigger area without spending a frame within the trigger area. We should detect when this is the case and activate a trigger event in this scenario too.
+
+We can make reasonable asssumptions to cover this scenario only if the moving object is moving via a Tween. If the moving object is being moved by a system in the scene frame by frame, we can't easily infer from the engine that a smooth movement is taking place. For those cases, the engine only knows of distinct positions on each frame, and we should evaluate triggers frame by frame.
+
+### Code helpers
+
+Even though at a low-level data travels in an ECS way, we should offer a friendlier way to deal with this for creators. This is the same approach we already use with pointer events and raycasts.
+
+We’ll create a system and helper functions for reacting to a trigger events from a trigger area, similar to our [pointerEvents](https://docs.decentraland.org/creator/development-guide/sdk7/click-events/) system
+
+- `onTriggerEnter`
+- `onTriggerExit`
+- `onTriggerStay`
+
+It will look something like this:
+
+```ts
+TriggerArea.setBox(myTrigger)
+Transform.create(myTrigger, {
+  position: Vector3.create(8, 0, 8),
+  scale: Vector3.create(1, 1, 1),
+})
+triggerAreaEventsSystem.onTriggerEnter(myTrigger, function(result) {
+  // Do whatever I want
+})
+
+## Triggers embedded in 3D models
+
+
+It should also be possible to create trigger areas embedded into 3D models. If a mesh in a 3D model has a name that contains the string `_trigger`, it will be considered a trigger area.
+
+
+
+## Serialization
+
+```yaml
+
+```
+
+```protobuf
+
+```
+
+## Semantics
+
+### Example
+
+Low level:
+
+```ts
+function TriggerReadingSystem() {
+  const triggeredEntities = engine.getEntitiesWith(TriggerCollisionResult)
+  for (const [entity] of triggeredEntities) {
+
+    const result = TriggerCollisionResult.getOrNull(entity)
+    if(result){
+      console.log("TRIGGER EVENT DATA:", result.commands)
+    }
+  }
+}
+
+engine.addSystem(TriggerReadingSystem)
+```
+
+High level:
+
+_Option 1: Using the TriggerArea component_
+```ts
+const myTrigger = engine.addEntity()
+
+MeshCollider.setBox(myTrigger, {collisionMask: ColliderLayer.CL_PHYSICS})
+
+TriggerArea.setBox(myTrigger, {layer:TriggerLayer.TL_PLAYER })
+
+Tramsform.create(myTrigger)
+```
+
+_Option 2: Using the triggerEventsSystem_
+```ts
+const myTrigger = engine.addEntity()
+
+MeshCollider.setBox(myTrigger, {collisionMask: ColliderLayer.CL_PHYSICS})
+
+Tramsform.create(myTrigger)
+triggerEventsSystem.OnTriggerEnter(
+    {
+      entity: myTrigger,
+      opts: {
+        layer: Player
+      }
+    },
+    function (otherEntity) {
+      // Do whatever I want
+    }
+  )
+```