feat: trigger area components (#1210)

* TriggerArea and TriggerAreaResult components
* triggerAreaEventsSystem helper
* TriggerArea extension helper

Author: pravusjif

Makefile

@@ -62,6 +62,9 @@ test-cli:
 	@mkdir -p tmp/scene
 	cd tmp/scene; $(PWD)/packages/@dcl/sdk-commands/dist/index.js init
 
+test-file:
+	node_modules/.bin/jest --detectOpenHandles --colors --runTestsByPath $(FILE)
+
 init-test-scene:
 	git clone https://github.com/decentraland/sdk7-scene-template test-scene
 	cd test-scene && npm i ./../packages/@dcl/sdk  && npm i ./../packages/@dcl/sdk-commands  && npm i ./../packages/@dcl/js-runtime

package-lock.json

@@ -6,7 +6,7 @@
   "bugs": "https://github.com/decentraland/js-sdk-toolchain/issues",
   "dependencies": {
     "@actions/core": "^1.10.0",
-    "@dcl/protocol": "1.0.0-16800835851.commit-2ec49fe",
+    "@dcl/protocol": "1.0.0-18103449748.commit-258fabc",
     "@dcl/quickjs-emscripten": "^0.21.0-3680274614.commit-1808aa1",
     "@dcl/ts-proto": "1.153.0",
     "@types/fs-extra": "^9.0.12",

package.json

@@ -0,0 +1,54 @@
+import { Entity, IEngine, LastWriteWinElementSetComponentDefinition } from '../../engine'
+import { ColliderLayer, PBTriggerArea, TriggerArea, TriggerAreaMeshType } from '../generated/index.gen'
+
+/**
+ * @public
+ */
+export interface TriggerAreaComponentDefinitionExtended
+  extends LastWriteWinElementSetComponentDefinition<PBTriggerArea> {
+  /**
+   * @public
+   * Set a box in the MeshCollider component
+   * @param entity - entity to create or replace the TriggerArea component
+   * @param collisionMask - the collision layers mask for the trigger to react, default: Player
+   */
+  setBox(entity: Entity, collisionMask?: ColliderLayer | ColliderLayer[]): void
+
+  /**
+   * @public
+   * Set a sphere in the MeshCollider component
+   * @param entity - entity to create or replace the TriggerArea component
+   * @param collisionMask - the collision layers mask for the trigger to react, default: Player
+   */
+  setSphere(entity: Entity, collisionMask?: ColliderLayer | ColliderLayer[]): void
+}
+
+export function defineTriggerAreaComponent(
+  engine: Pick<IEngine, 'defineComponentFromSchema'>
+): TriggerAreaComponentDefinitionExtended {
+  const theComponent = TriggerArea(engine)
+
+  function getCollisionMask(layers?: ColliderLayer | ColliderLayer[]) {
+    if (Array.isArray(layers)) {
+      return layers.map((item) => item as number).reduce((prev, item) => prev | item, 0)
+    } else if (layers) {
+      return layers
+    }
+  }
+
+  return {
+    ...theComponent,
+    setBox(entity: Entity, collisionMask?: ColliderLayer | ColliderLayer[]): void {
+      theComponent.createOrReplace(entity, {
+        mesh: TriggerAreaMeshType.TAMT_BOX,
+        collisionMask: getCollisionMask(collisionMask)
+      })
+    },
+    setSphere(entity: Entity, collisionMask?: ColliderLayer | ColliderLayer[]): void {
+      theComponent.createOrReplace(entity, {
+        mesh: TriggerAreaMeshType.TAMT_SPHERE,
+        collisionMask: getCollisionMask(collisionMask)
+      })
+    }
+  }
+}

packages/@dcl/ecs/src/components/extended/TriggerArea.ts

@@ -17,6 +17,7 @@ import { MediaState } from './generated/pb/decentraland/sdk/components/common/me
 import { defineVirtualCameraComponent, VirtualCameraComponentDefinitionExtended } from './extended/VirtualCamera'
 import { defineInputModifierComponent, InputModifierComponentDefinitionExtended } from './extended/InputModifier'
 import { defineLightSourceComponent, LightSourceComponentDefinitionExtended } from './extended/LightSource'
+import { defineTriggerAreaComponent, TriggerAreaComponentDefinitionExtended } from './extended/TriggerArea'
 import defineTagsComponent, { TagsComponentDefinitionExtended } from './manual/Tags'
 
 export * from './generated/index.gen'
@@ -71,6 +72,10 @@ export const InputModifier: LwwComponentGetter<InputModifierComponentDefinitionE
 export const LightSource: LwwComponentGetter<LightSourceComponentDefinitionExtended> = (engine) =>
   defineLightSourceComponent(engine)
 
+/* @__PURE__ */
+export const TriggerArea: LwwComponentGetter<TriggerAreaComponentDefinitionExtended> = (engine) =>
+  defineTriggerAreaComponent(engine)
+
 /**
  * @alpha
  */

packages/@dcl/ecs/src/components/index.ts

@@ -14,3 +14,4 @@ export type { INetowrkEntity, INetowrkEntityType } from './manual/NetworkEntity'
 export type { INetowrkParent, INetowrkParentType } from './manual/NetworkParent'
 export type { InputModifierHelper, InputModifierComponentDefinitionExtended } from './extended/InputModifier'
 export type { LightSourceHelper, LightSourceComponentDefinitionExtended } from './extended/LightSource'
+export type { TriggerAreaComponentDefinitionExtended } from './extended/TriggerArea'

packages/@dcl/ecs/src/components/types.ts

@@ -11,6 +11,7 @@ export * from './systems/raycast'
 export * from './systems/videoEvents'
 export * from './systems/async-task'
 export * from './systems/tween'
+export * from './systems/triggerArea'
 export * from './engine/entity'
 export * from './components/types'
 
@@ -34,7 +35,8 @@ import {
   INetowrkParent,
   VirtualCameraComponentDefinitionExtended,
   InputModifierComponentDefinitionExtended,
-  LightSourceComponentDefinitionExtended
+  LightSourceComponentDefinitionExtended,
+  TriggerAreaComponentDefinitionExtended
 } from './components/types'
 import { NameComponent } from './components/manual/Name'
 import { TagsComponentDefinitionExtended } from './components/manual/Tags'
@@ -53,6 +55,7 @@ export const Tween: TweenComponentDefinitionExtended = /* @__PURE__*/ components
 export const VirtualCamera: VirtualCameraComponentDefinitionExtended = /* @__PURE__*/ components.VirtualCamera(engine)
 export const InputModifier: InputModifierComponentDefinitionExtended = /* @__PURE__*/ components.InputModifier(engine)
 export const LightSource: LightSourceComponentDefinitionExtended = /* @__PURE__*/ components.LightSource(engine)
+export const TriggerArea: TriggerAreaComponentDefinitionExtended = /* @__PURE__*/ components.TriggerArea(engine)
 
 /**
  * @alpha

packages/@dcl/ecs/src/index.ts

@@ -11,6 +11,7 @@ import { createRaycastSystem, RaycastSystem } from '../../systems/raycast'
 import { createVideoEventsSystem, VideoEventsSystem } from '../../systems/videoEvents'
 import { TweenSystem, createTweenSystem } from '../../systems/tween'
 import { pointerEventColliderChecker } from '../../systems/pointer-event-collider-checker'
+import { createTriggerAreaEventsSystem, TriggerAreaEventsSystem } from '../../systems/triggerArea'
 
 /**
  * @public
@@ -65,6 +66,13 @@ export { VideoEventsSystem }
 export const tweenSystem: TweenSystem = createTweenSystem(engine)
 export { TweenSystem }
 
+/**
+ * @public
+ * Register callback functions for trigger area results.
+ */
+export const triggerAreaEventsSystem: TriggerAreaEventsSystem = /* @__PURE__ */ createTriggerAreaEventsSystem(engine)
+export { TriggerAreaEventsSystem }
+
 /**
  * Adds pointer event collider system only in DEV env
  */

packages/@dcl/ecs/src/runtime/initialization/index.ts

@@ -0,0 +1,192 @@
+import * as components from '../components'
+import { DeepReadonlyObject, Entity, IEngine } from '../engine'
+import { EntityState } from '../engine/entity'
+import { PBTriggerAreaResult, TriggerAreaEventType } from '../components'
+
+/**
+ * @public
+ */
+export type TriggerAreaEventSystemCallback = (result: DeepReadonlyObject<PBTriggerAreaResult>) => void
+
+/**
+ * @public
+ */
+export interface TriggerAreaEventsSystem {
+  /**
+   * @public
+   * Execute callback when an entity enters the Trigger Area
+   * @param entity - The entity that already has the TriggerArea component
+   * @param cb - Function to execute the 'Enter' type of result is detected
+   */
+  onTriggerEnter(entity: Entity, cb: TriggerAreaEventSystemCallback): void
+
+  /**
+   * @public
+   * Remove the callback for Trigger Area 'Enter' type of result
+   * @param entity - Entity where the Trigger Area was attached
+   */
+  removeOnTriggerEnter(entity: Entity): void
+
+  /**
+   * @public
+   * Execute callback when an entity stays in the Trigger Area
+   * @param entity - The entity that already has the TriggerArea component
+   * @param cb - Function to execute the 'Stay' type of result is detected
+   */
+  onTriggerStay(entity: Entity, cb: TriggerAreaEventSystemCallback): void
+
+  /**
+   * @public
+   * Remove the callback for Trigger Area 'Stay' type of result
+   * @param entity - Entity where the Trigger Area was attached
+   */
+  removeOnTriggerStay(entity: Entity): void
+
+  /**
+   * @public
+   * Execute callback when an entity exits the Trigger Area
+   * @param entity - The entity that already has the TriggerArea component
+   * @param cb - Function to execute the 'Exit' type of result is detected
+   */
+  onTriggerExit(entity: Entity, cb: TriggerAreaEventSystemCallback): void
+
+  /**
+   * @public
+   * Remove the callback for Trigger Area 'Exit' type of result
+   * @param entity - Entity where the Trigger Area was attached
+   */
+  removeOnTriggerExit(entity: Entity): void
+}
+
+/**
+ * @internal
+ */
+export function createTriggerAreaEventsSystem(engine: IEngine): TriggerAreaEventsSystem {
+  const triggerAreaResultComponent = components.TriggerAreaResult(engine)
+  const entitiesMap = new Map<
+    Entity,
+    {
+      triggerCallbackMap: Map<TriggerAreaEventType, TriggerAreaEventSystemCallback>
+      lastConsumedTimestamp: number
+    }
+  >()
+
+  function hasCallbacksMap(entity: Entity): boolean {
+    return entitiesMap.has(entity) && entitiesMap.get(entity) !== undefined
+  }
+
+  function addEntityCallback(
+    entity: Entity,
+    triggerType: TriggerAreaEventType,
+    callback: TriggerAreaEventSystemCallback
+  ) {
+    if (hasCallbacksMap(entity)) {
+      entitiesMap.get(entity)!.triggerCallbackMap.set(triggerType, callback)
+    } else {
+      entitiesMap.set(entity, {
+        triggerCallbackMap: new Map<TriggerAreaEventType, TriggerAreaEventSystemCallback>([[triggerType, callback]]),
+        lastConsumedTimestamp: -1
+      })
+    }
+  }
+
+  function removeEntityCallback(entity: Entity, triggerType: TriggerAreaEventType) {
+    if (!entitiesMap.has(entity) || !entitiesMap.get(entity)!.triggerCallbackMap.has(triggerType)) return
+    const triggerCallbackMap = entitiesMap.get(entity)!.triggerCallbackMap
+    triggerCallbackMap.delete(triggerType)
+
+    // Remove entity if no more trigger callbacks are registered
+    if (triggerCallbackMap.size === 0) entitiesMap.delete(entity)
+  }
+
+  function onTriggerEnter(entity: Entity, cb: TriggerAreaEventSystemCallback) {
+    addEntityCallback(entity, TriggerAreaEventType.TAET_ENTER, cb)
+  }
+  function removeOnTriggerEnter(entity: Entity) {
+    removeEntityCallback(entity, TriggerAreaEventType.TAET_ENTER)
+  }
+
+  function onTriggerStay(entity: Entity, cb: TriggerAreaEventSystemCallback) {
+    addEntityCallback(entity, TriggerAreaEventType.TAET_STAY, cb)
+  }
+  function removeOnTriggerStay(entity: Entity) {
+    removeEntityCallback(entity, TriggerAreaEventType.TAET_STAY)
+  }
+
+  function onTriggerExit(entity: Entity, cb: TriggerAreaEventSystemCallback) {
+    addEntityCallback(entity, TriggerAreaEventType.TAET_EXIT, cb)
+  }
+  function removeOnTriggerExit(entity: Entity) {
+    removeEntityCallback(entity, TriggerAreaEventType.TAET_EXIT)
+  }
+
+  engine.addSystem(function TriggerAreaResultSystem() {
+    const garbageEntries = []
+    for (const [entity, data] of entitiesMap) {
+      if (engine.getEntityState(entity) === EntityState.Removed) {
+        garbageEntries.push(entity)
+        continue
+      }
+
+      const result = triggerAreaResultComponent.get(entity)
+
+      // The Explorer may be taking time before the result component is put
+      if (result.size === 0) continue
+
+      const values = Array.from(result.values())
+
+      // determine starting index for new values (more than one could be added between System updates)
+      // search backwards to find the anchor at lastConsumedTimestamp
+      let startIndex = 0
+      if (data.lastConsumedTimestamp >= 0) {
+        const newestTimestamp = values[values.length - 1].timestamp
+
+        // if nothing new, skip processing
+        if (newestTimestamp <= data.lastConsumedTimestamp) {
+          continue
+        }
+
+        // Find index of value with the lastConsumedTimestamp
+        let i = values.length - 2
+        while (i >= 0 && values[i].timestamp > data.lastConsumedTimestamp) i--
+
+        // Mark the following value index as the starting point to trigger all the new value callbacks
+        startIndex = i + 1
+      }
+
+      if (startIndex >= values.length) continue
+
+      // Trigger callbacks for all the new values
+      for (let i = startIndex; i < values.length; i++) {
+        switch (values[i].eventType) {
+          case TriggerAreaEventType.TAET_ENTER:
+            if (!data.triggerCallbackMap.has(TriggerAreaEventType.TAET_ENTER)) continue
+            data.triggerCallbackMap.get(TriggerAreaEventType.TAET_ENTER)!(values[i])
+            break
+          case TriggerAreaEventType.TAET_STAY:
+            if (!data.triggerCallbackMap.has(TriggerAreaEventType.TAET_STAY)) continue
+            data.triggerCallbackMap.get(TriggerAreaEventType.TAET_STAY)!(values[i])
+            break
+          case TriggerAreaEventType.TAET_EXIT:
+            if (!data.triggerCallbackMap.has(TriggerAreaEventType.TAET_EXIT)) continue
+            data.triggerCallbackMap.get(TriggerAreaEventType.TAET_EXIT)!(values[i])
+            break
+        }
+      }
+
+      data.lastConsumedTimestamp = values[values.length - 1].timestamp
+    }
+
+    // Clean up garbage entries
+    garbageEntries.forEach((garbageEntity) => entitiesMap.delete(garbageEntity))
+  })
+
+  return {
+    onTriggerEnter,
+    removeOnTriggerEnter,
+    onTriggerStay,
+    removeOnTriggerStay,
+    onTriggerExit,
+    removeOnTriggerExit
+  }
+}