@dcl/ecs 7.18.2-21450088960.commit-3c16004 → 7.18.2-21453292414.commit-1da934f

package/dist/components/types.d.ts

@@ -3,7 +3,7 @@ export type { AudioSourceComponentDefinitionExtended } from './extended/AudioSou
 export type { AudioStreamComponentDefinitionExtended } from './extended/AudioStream';
 export type { MeshRendererComponentDefinitionExtended } from './extended/MeshRenderer';
 export type { MeshColliderComponentDefinitionExtended } from './extended/MeshCollider';
-export type { TextureHelper, MaterialComponentDefinitionExtended } from './extended/Material';
+export type { TextureHelper, MaterialComponentDefinitionExtended, FlatTexture, ReadonlyFlatMaterial, ReadonlyFlatTexture, FlatMaterial } from './extended/Material';
 export type { TweenHelper, TweenComponentDefinitionExtended } from './extended/Tween';
 export type { CameraTransitionHelper, VirtualCameraComponentDefinitionExtended } from './extended/VirtualCamera';
 export type { TransformComponentExtended, TransformTypeWithOptionals } from './manual/Transform';

package/dist/runtime/helpers/index.d.ts

@@ -1,2 +1,3 @@
 export * from './coordinates';
 export * from './tree';
+export { createTimers, Timers, TimerId, TimerCallback } from './timers';

package/dist/runtime/helpers/index.js

@@ -1,2 +1,3 @@
 export * from './coordinates';
 export * from './tree';
+export { createTimers } from './timers';

package/dist/runtime/helpers/timers.d.ts

@@ -0,0 +1,85 @@
+import { IEngine } from '../../engine/types';
+export type TimerId = number;
+export type TimerCallback = () => void;
+export type Timers = {
+    /**
+     * Delays the execution of a function by a given amount of milliseconds.
+     *
+     * @param callback - The function to execute after the delay
+     * @param ms - The delay in milliseconds
+     * @returns A TimerId that can be used to cancel the timeout
+     *
+     * @example
+     * ```ts
+     * const timeoutId = timers.setTimeout(() => {
+     *   console.log('1 second passed')
+     * }, 1000)
+     * ```
+     */
+    setTimeout(callback: TimerCallback, ms: number): TimerId;
+    /**
+     * Cancels a timeout previously established by setTimeout.
+     *
+     * @param timerId - The TimerId returned by setTimeout
+     *
+     * @example
+     * ```ts
+     * const timeoutId = timers.setTimeout(() => {
+     *   console.log('This will not run')
+     * }, 1000)
+     *
+     * timers.clearTimeout(timeoutId)
+     * ```
+     */
+    clearTimeout(timerId: TimerId): void;
+    /**
+     * Repeatedly executes a function at specified intervals.
+     *
+     * @param callback - The function to execute at each interval
+     * @param ms - The interval in milliseconds
+     * @returns A TimerId that can be used to cancel the interval
+     *
+     * @example
+     * ```ts
+     * const intervalId = timers.setInterval(() => {
+     *   console.log('Printing this every 1 second')
+     * }, 1000)
+     * ```
+     */
+    setInterval(callback: TimerCallback, ms: number): TimerId;
+    /**
+     * Cancels an interval previously established by setInterval.
+     *
+     * @param timerId - The TimerId returned by setInterval
+     *
+     * @example
+     * ```ts
+     * const intervalId = timers.setInterval(() => {
+     *   console.log('This will stop')
+     * }, 1000)
+     *
+     * timers.clearInterval(intervalId)
+     * ```
+     */
+    clearInterval(timerId: TimerId): void;
+};
+/**
+ * Creates a timer system bound to a specific engine instance.
+ *
+ * @param targetEngine - The engine instance to bind timers to
+ * @returns A Timers object with setTimeout, clearTimeout, setInterval, and clearInterval methods
+ *
+ * @example
+ * ```ts
+ * import { Engine } from '@dcl/sdk/ecs'
+ * import { createTimers } from '@dcl/sdk/ecs'
+ *
+ * const engine = Engine()
+ * const timers = createTimers(engine)
+ *
+ * timers.setTimeout(() => console.log('done'), 1000)
+ * ```
+ *
+ * @public
+ */
+export declare function createTimers(targetEngine: IEngine): Timers;

package/dist/runtime/helpers/timers.js

@@ -0,0 +1,69 @@
+/**
+ * Creates a timer system bound to a specific engine instance.
+ *
+ * @param targetEngine - The engine instance to bind timers to
+ * @returns A Timers object with setTimeout, clearTimeout, setInterval, and clearInterval methods
+ *
+ * @example
+ * ```ts
+ * import { Engine } from '@dcl/sdk/ecs'
+ * import { createTimers } from '@dcl/sdk/ecs'
+ *
+ * const engine = Engine()
+ * const timers = createTimers(engine)
+ *
+ * timers.setTimeout(() => console.log('done'), 1000)
+ * ```
+ *
+ * @public
+ */
+export function createTimers(targetEngine) {
+    const timers = new Map();
+    let timerIdCounter = 0;
+    function system(dt) {
+        for (const [timerId, timerData] of timers) {
+            timerData.accumulatedTime += 1000 * dt;
+            if (timerData.accumulatedTime < timerData.interval) {
+                continue;
+            }
+            if (timerData.recurrent) {
+                // For intervals, subtract full interval periods to handle accumulated time
+                const fullIntervals = Math.floor(timerData.accumulatedTime / timerData.interval);
+                timerData.accumulatedTime -= fullIntervals * timerData.interval;
+            }
+            else {
+                timers.delete(timerId);
+            }
+            timerData.callback();
+        }
+    }
+    targetEngine.addSystem(system, Number.MAX_SAFE_INTEGER, '@dcl/ecs/timers');
+    return {
+        setTimeout(callback, ms) {
+            const timerId = timerIdCounter++;
+            timers.set(timerId, {
+                callback,
+                interval: ms,
+                recurrent: false,
+                accumulatedTime: 0
+            });
+            return timerId;
+        },
+        clearTimeout(timerId) {
+            timers.delete(timerId);
+        },
+        setInterval(callback, ms) {
+            const timerId = timerIdCounter++;
+            timers.set(timerId, {
+                callback,
+                interval: ms,
+                recurrent: true,
+                accumulatedTime: 0
+            });
+            return timerId;
+        },
+        clearInterval(timerId) {
+            timers.delete(timerId);
+        }
+    };
+}

package/dist/runtime/helpers/tree.d.ts

@@ -1,5 +1,7 @@
 import { Entity } from '../../engine/entity';
 import { ComponentDefinition, IEngine } from '../../engine';
+import { Vector3Type } from '../../schemas/custom/Vector3';
+import { QuaternionType } from '../../schemas/custom/Quaternion';
 /**
  * Get an iterator of entities that follow a tree structure for a component
  * @public
@@ -30,3 +32,62 @@ export declare function getComponentEntityTree<T>(engine: Pick<IEngine, 'getEnti
  * @public
  */
 export declare function removeEntityWithChildren(engine: Pick<IEngine, 'getEntitiesWith' | 'defineComponentFromSchema' | 'removeEntity' | 'defineComponent'>, entity: Entity): void;
+/**
+ * Get all entities that have the given entity as their parent
+ * @public
+ * @param engine - the engine running the entities
+ * @param parent - the parent entity to find children for
+ * @returns An array of entities that have the given parent
+ *
+ * Example:
+ * ```ts
+ * const children = getEntitiesWithParent(engine, myEntity)
+ * for (const child of children) {
+ *   // process each child entity
+ * }
+ * ```
+ */
+export declare function getEntitiesWithParent(engine: Pick<IEngine, 'getEntitiesWith' | 'defineComponentFromSchema'>, parent: Entity): Entity[];
+/** @public Engine type for world transform functions */
+export type WorldTransformEngine = Pick<IEngine, 'getEntitiesWith' | 'defineComponentFromSchema' | 'PlayerEntity'>;
+/**
+ * Get the world position of an entity, taking into account the full parent hierarchy.
+ * This computes the world-space position by accumulating all parent transforms
+ * (position, rotation, and scale).
+ *
+ * When the entity has AvatarAttach and Transform, the renderer updates the Transform
+ * with avatar-relative values (including the exact anchor point offset for hand, head, etc.).
+ * This function combines the player's transform with those values to compute the world position.
+ *
+ * @public
+ * @param engine - the engine running the entities
+ * @param entity - the entity to get the world position for
+ * @returns The entity's position in world space. Returns `{x: 0, y: 0, z: 0}` if the entity has no Transform.
+ *
+ * Example:
+ * ```ts
+ * const worldPos = getWorldPosition(engine, childEntity)
+ * console.log(`World position: ${worldPos.x}, ${worldPos.y}, ${worldPos.z}`)
+ * ```
+ */
+export declare function getWorldPosition(engine: WorldTransformEngine, entity: Entity): Vector3Type;
+/**
+ * Get the world rotation of an entity, taking into account the full parent hierarchy.
+ * This computes the world-space rotation by combining all parent rotations.
+ *
+ * When the entity has AvatarAttach and Transform, the renderer updates the Transform
+ * with avatar-relative values (including the exact anchor point rotation for hand, head, etc.).
+ * This function combines the player's rotation with those values to compute the world rotation.
+ *
+ * @public
+ * @param engine - the engine running the entities
+ * @param entity - the entity to get the world rotation for
+ * @returns The entity's rotation in world space as a quaternion. Returns identity quaternion `{x: 0, y: 0, z: 0, w: 1}` if the entity has no Transform.
+ *
+ * Example:
+ * ```ts
+ * const worldRot = getWorldRotation(engine, childEntity)
+ * console.log(`World rotation: ${worldRot.x}, ${worldRot.y}, ${worldRot.z}, ${worldRot.w}`)
+ * ```
+ */
+export declare function getWorldRotation(engine: WorldTransformEngine, entity: Entity): QuaternionType;

package/dist/runtime/helpers/tree.js

@@ -1,4 +1,161 @@
 import * as components from '../../components';
+/**
+ * @internal
+ * Add two Vector3 values
+ */
+function addVectors(v1, v2) {
+    return {
+        x: v1.x + v2.x,
+        y: v1.y + v2.y,
+        z: v1.z + v2.z
+    };
+}
+/**
+ * @internal
+ * Multiply two Vector3 values element-wise (used for scaling)
+ */
+function multiplyVectors(v1, v2) {
+    return {
+        x: v1.x * v2.x,
+        y: v1.y * v2.y,
+        z: v1.z * v2.z
+    };
+}
+/**
+ * @internal
+ * Multiply two quaternions (combines rotations)
+ * Result represents applying q1 first, then q2
+ */
+function multiplyQuaternions(q1, q2) {
+    return {
+        x: q1.w * q2.x + q1.x * q2.w + q1.y * q2.z - q1.z * q2.y,
+        y: q1.w * q2.y - q1.x * q2.z + q1.y * q2.w + q1.z * q2.x,
+        z: q1.w * q2.z + q1.x * q2.y - q1.y * q2.x + q1.z * q2.w,
+        w: q1.w * q2.w - q1.x * q2.x - q1.y * q2.y - q1.z * q2.z
+    };
+}
+/**
+ * @internal
+ * Rotate a vector by a quaternion
+ * Uses the formula: v' = q * v * q^(-1), optimized version
+ */
+function rotateVectorByQuaternion(v, q) {
+    // Extract quaternion components
+    const qx = q.x, qy = q.y, qz = q.z, qw = q.w;
+    // Calculate cross product terms (q.xyz × v) * 2
+    const ix = qw * v.x + qy * v.z - qz * v.y;
+    const iy = qw * v.y + qz * v.x - qx * v.z;
+    const iz = qw * v.z + qx * v.y - qy * v.x;
+    const iw = -qx * v.x - qy * v.y - qz * v.z;
+    // Calculate final rotated vector
+    return {
+        x: ix * qw + iw * -qx + iy * -qz - iz * -qy,
+        y: iy * qw + iw * -qy + iz * -qx - ix * -qz,
+        z: iz * qw + iw * -qz + ix * -qy - iy * -qx
+    };
+}
+/** @internal Identity transform values */
+const IDENTITY_POSITION = { x: 0, y: 0, z: 0 };
+const IDENTITY_ROTATION = { x: 0, y: 0, z: 0, w: 1 };
+const IDENTITY_SCALE = { x: 1, y: 1, z: 1 };
+/**
+ * @internal
+ * Computes the world transform for an entity with AvatarAttach.
+ * If the entity has a Transform, the avatar-relative values (set by the renderer)
+ * are combined with the player's transform. Otherwise, returns the player's transform
+ * with identity scale.
+ */
+function computeAvatarAttachedWorldTransform(playerTransform, entityTransform) {
+    if (!entityTransform) {
+        return {
+            position: { ...playerTransform.position },
+            rotation: { ...playerTransform.rotation },
+            scale: { ...IDENTITY_SCALE }
+        };
+    }
+    const rotatedPosition = rotateVectorByQuaternion(entityTransform.position, playerTransform.rotation);
+    return {
+        position: addVectors(playerTransform.position, rotatedPosition),
+        rotation: multiplyQuaternions(playerTransform.rotation, entityTransform.rotation),
+        scale: entityTransform.scale
+    };
+}
+/**
+ * @internal
+ * Finds the transform of a player by their avatar ID.
+ * Returns the local player's transform if avatarId is undefined,
+ * or searches for a remote player by matching their address.
+ */
+function findPlayerTransform(Transform, PlayerIdentityData, localPlayerEntity, avatarId) {
+    // Local player (avatarId undefined)
+    if (avatarId === undefined) {
+        return Transform.getOrNull(localPlayerEntity);
+    }
+    // Remote player - find their entity by matching address
+    if (!PlayerIdentityData) {
+        return null;
+    }
+    for (const [playerEntity, identityData] of PlayerIdentityData.iterator()) {
+        if (identityData.address === avatarId) {
+            return Transform.getOrNull(playerEntity);
+        }
+    }
+    return null;
+}
+/**
+ * @internal
+ * Computes world position, rotation, and scale in a single hierarchy traversal.
+ * This is O(n) where n is the depth of the hierarchy.
+ *
+ * When an entity has AvatarAttach and Transform, the renderer updates the Transform
+ * with avatar-relative values (including the exact anchor point offset). This function
+ * combines the player's transform with the entity's avatar-relative transform to
+ * compute the world-space position.
+ *
+ * @throws Error if a circular dependency is detected in the entity hierarchy
+ */
+function getWorldTransformInternal(Transform, AvatarAttach, PlayerIdentityData, PlayerEntity, entity, visited = new Set()) {
+    const transform = Transform.getOrNull(entity);
+    const avatarAttach = AvatarAttach?.getOrNull(entity);
+    // Handle AvatarAttach: combine player's transform with the entity's avatar-relative transform
+    // (which the renderer updates with the exact anchor point offset for hand, head, etc.)
+    if (avatarAttach) {
+        const playerTransform = findPlayerTransform(Transform, PlayerIdentityData, PlayerEntity, avatarAttach.avatarId);
+        if (playerTransform) {
+            return computeAvatarAttachedWorldTransform(playerTransform, transform);
+        }
+        // Player's Transform not available, fall through to normal Transform handling
+    }
+    if (!transform) {
+        return {
+            position: { ...IDENTITY_POSITION },
+            rotation: { ...IDENTITY_ROTATION },
+            scale: { ...IDENTITY_SCALE }
+        };
+    }
+    if (!transform.parent) {
+        return {
+            position: { ...transform.position },
+            rotation: { ...transform.rotation },
+            scale: { ...transform.scale }
+        };
+    }
+    visited.add(entity);
+    if (visited.has(transform.parent)) {
+        throw new Error(`Circular dependency detected in entity hierarchy: entity ${entity} has ancestor ${transform.parent} which creates a cycle`);
+    }
+    const parentWorld = getWorldTransformInternal(Transform, AvatarAttach, PlayerIdentityData, PlayerEntity, transform.parent, visited);
+    const worldScale = multiplyVectors(parentWorld.scale, transform.scale);
+    const worldRotation = multiplyQuaternions(parentWorld.rotation, transform.rotation);
+    const scaledPosition = multiplyVectors(transform.position, parentWorld.scale);
+    const rotatedPosition = rotateVectorByQuaternion(scaledPosition, parentWorld.rotation);
+    const worldPosition = addVectors(parentWorld.position, rotatedPosition);
+    return {
+        position: worldPosition,
+        rotation: worldRotation,
+        scale: worldScale
+    };
+}
 function* genEntityTree(entity, entities) {
     // This avoid infinite loop when there is a cyclic parenting
     if (!entities.has(entity))
@@ -70,3 +227,84 @@ export function removeEntityWithChildren(engine, entity) {
         engine.removeEntity(ent);
     }
 }
+/**
+ * Get all entities that have the given entity as their parent
+ * @public
+ * @param engine - the engine running the entities
+ * @param parent - the parent entity to find children for
+ * @returns An array of entities that have the given parent
+ *
+ * Example:
+ * ```ts
+ * const children = getEntitiesWithParent(engine, myEntity)
+ * for (const child of children) {
+ *   // process each child entity
+ * }
+ * ```
+ */
+export function getEntitiesWithParent(engine, parent) {
+    const Transform = components.Transform(engine);
+    const entitiesWithParent = [];
+    for (const [entity, transform] of engine.getEntitiesWith(Transform)) {
+        if (transform.parent === parent) {
+            entitiesWithParent.push(entity);
+        }
+    }
+    return entitiesWithParent;
+}
+/**
+ * @internal
+ * Computes the world transform for an entity using the provided engine.
+ * This is a convenience wrapper that initializes the required components.
+ */
+function getWorldTransform(engine, entity) {
+    const Transform = components.Transform(engine);
+    const AvatarAttach = components.AvatarAttach(engine);
+    const PlayerIdentityData = components.PlayerIdentityData(engine);
+    return getWorldTransformInternal(Transform, AvatarAttach, PlayerIdentityData, engine.PlayerEntity, entity);
+}
+/**
+ * Get the world position of an entity, taking into account the full parent hierarchy.
+ * This computes the world-space position by accumulating all parent transforms
+ * (position, rotation, and scale).
+ *
+ * When the entity has AvatarAttach and Transform, the renderer updates the Transform
+ * with avatar-relative values (including the exact anchor point offset for hand, head, etc.).
+ * This function combines the player's transform with those values to compute the world position.
+ *
+ * @public
+ * @param engine - the engine running the entities
+ * @param entity - the entity to get the world position for
+ * @returns The entity's position in world space. Returns `{x: 0, y: 0, z: 0}` if the entity has no Transform.
+ *
+ * Example:
+ * ```ts
+ * const worldPos = getWorldPosition(engine, childEntity)
+ * console.log(`World position: ${worldPos.x}, ${worldPos.y}, ${worldPos.z}`)
+ * ```
+ */
+export function getWorldPosition(engine, entity) {
+    return getWorldTransform(engine, entity).position;
+}
+/**
+ * Get the world rotation of an entity, taking into account the full parent hierarchy.
+ * This computes the world-space rotation by combining all parent rotations.
+ *
+ * When the entity has AvatarAttach and Transform, the renderer updates the Transform
+ * with avatar-relative values (including the exact anchor point rotation for hand, head, etc.).
+ * This function combines the player's rotation with those values to compute the world rotation.
+ *
+ * @public
+ * @param engine - the engine running the entities
+ * @param entity - the entity to get the world rotation for
+ * @returns The entity's rotation in world space as a quaternion. Returns identity quaternion `{x: 0, y: 0, z: 0, w: 1}` if the entity has no Transform.
+ *
+ * Example:
+ * ```ts
+ * const worldRot = getWorldRotation(engine, childEntity)
+ * console.log(`World rotation: ${worldRot.x}, ${worldRot.y}, ${worldRot.z}, ${worldRot.w}`)
+ * ```
+ */
+export function getWorldRotation(engine, entity) {
+    return getWorldTransform(engine, entity).rotation;
+}

package/dist/runtime/initialization/index.d.ts

@@ -10,6 +10,7 @@ import { RaycastSystem } from '../../systems/raycast';
 import { VideoEventsSystem } from '../../systems/videoEvents';
 import { TweenSystem } from '../../systems/tween';
 import { TriggerAreaEventsSystem } from '../../systems/triggerArea';
+import { createTimers, Timers } from '../helpers/timers';
 /**
  * @public
  * The engine is the part of the scene that sits in the middle and manages all of the other parts.
@@ -63,6 +64,12 @@ export { TweenSystem };
  */
 export declare const triggerAreaEventsSystem: TriggerAreaEventsSystem;
 export { TriggerAreaEventsSystem };
+/**
+ * @public
+ * Timer utilities for delayed and repeated execution.
+ */
+export declare const timers: Timers;
+export { Timers, createTimers };
 /**
  * @public
  * Runs an async function

package/dist/runtime/initialization/index.js

@@ -11,6 +11,7 @@ import { createVideoEventsSystem } from '../../systems/videoEvents';
 import { createTweenSystem } from '../../systems/tween';
 import { pointerEventColliderChecker } from '../../systems/pointer-event-collider-checker';
 import { createTriggerAreaEventsSystem } from '../../systems/triggerArea';
+import { createTimers } from '../helpers/timers';
 /**
  * @public
  * The engine is the part of the scene that sits in the middle and manages all of the other parts.
@@ -58,6 +59,16 @@ export const tweenSystem = createTweenSystem(engine);
  * Register callback functions for trigger area results.
  */
 export const triggerAreaEventsSystem = /* @__PURE__ */ createTriggerAreaEventsSystem(engine);
+/**
+ * @public
+ * Timer utilities for delayed and repeated execution.
+ */
+export const timers = /* @__PURE__ */ createTimers(engine);
+export { createTimers };
+globalThis.setTimeout = globalThis.setTimeout ?? timers.setTimeout;
+globalThis.clearTimeout = globalThis.clearTimeout ?? timers.clearTimeout;
+globalThis.setInterval = globalThis.setInterval ?? timers.setInterval;
+globalThis.clearInterval = globalThis.clearInterval ?? timers.clearInterval;
 /**
  * Adds pointer event collider system only in DEV env
  */