@dcl/ecs 7.21.1-23203004012.commit-7c64ac2 → 7.21.1-23252789519.commit-9f806e1

package/dist/components/manual/Transform.d.ts

@@ -1,5 +1,6 @@
 import { LastWriteWinElementSetComponentDefinition, IEngine } from '../../engine';
 import { Entity } from '../../engine/entity';
+import type { Vector3Type } from '../../schemas/custom/Vector3';
 /**
  * @public
  */
@@ -10,6 +11,18 @@ export type TransformComponent = LastWriteWinElementSetComponentDefinition<Trans
 export interface TransformComponentExtended extends TransformComponent {
     create(entity: Entity, val?: TransformTypeWithOptionals): TransformType;
     createOrReplace(entity: Entity, val?: TransformTypeWithOptionals): TransformType;
+    /**
+     * Transforms a direction vector from an entity's local coordinate space
+     * to world space, accounting for the full parent hierarchy.
+     *
+     * This applies only rotation (not translation or scale) — suitable for
+     * direction vectors like force/impulse directions.
+     *
+     * @param entity - The source entity whose local space defines the direction
+     * @param localDirection - Direction vector in the entity's local coordinates
+     * @returns The direction vector in world coordinates
+     */
+    localToWorldDirection(entity: Entity, localDirection: Vector3Type): Vector3Type;
 }
 /**
  * @public

package/dist/components/manual/Transform.js

@@ -1,3 +1,7 @@
+// Use import * to safely handle circular dependency (tree.ts → components → Transform.ts → tree.ts).
+// With import *, the namespace object's properties are resolved at access time (live bindings in ESM,
+// getters via __importStar in CJS), so by the time methods are called all exports are available.
+import * as treeHelpers from '../../runtime/helpers/tree';
 /**
  * @internal
  */
@@ -101,6 +105,10 @@ export function defineTransformComponent(engine) {
         },
         createOrReplace(entity, val) {
             return transformDef.createOrReplace(entity, TransformSchema.extend(val));
+        },
+        localToWorldDirection(entity, localDirection) {
+            const worldRotation = treeHelpers.getWorldRotation(engine, entity);
+            return treeHelpers.rotateVectorByQuaternion(localDirection, worldRotation);
         }
     };
 }

package/dist/index.d.ts

@@ -12,6 +12,7 @@ export * from './systems/assetLoad';
 export * from './systems/async-task';
 export * from './systems/tween';
 export * from './systems/triggerArea';
+export * from './systems/physics';
 export * from './engine/entity';
 export * from './components/types';
 import { MaterialComponentDefinitionExtended, MeshColliderComponentDefinitionExtended, MeshRendererComponentDefinitionExtended, TransformComponentExtended, AnimatorComponentDefinitionExtended, AudioSourceComponentDefinitionExtended, AudioStreamComponentDefinitionExtended, ISyncComponents, TweenComponentDefinitionExtended, INetowrkEntity, INetowrkParent, VirtualCameraComponentDefinitionExtended, InputModifierComponentDefinitionExtended, LightSourceComponentDefinitionExtended, TriggerAreaComponentDefinitionExtended } from './components/types';

package/dist/index.js

@@ -13,6 +13,7 @@ export * from './systems/assetLoad';
 export * from './systems/async-task';
 export * from './systems/tween';
 export * from './systems/triggerArea';
+export * from './systems/physics';
 export * from './engine/entity';
 export * from './components/types';
 // @internal

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

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

package/dist/runtime/helpers/index.js

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

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

@@ -2,6 +2,12 @@ import { Entity } from '../../engine/entity';
 import { ComponentDefinition, IEngine } from '../../engine';
 import { Vector3Type } from '../../schemas/custom/Vector3';
 import { QuaternionType } from '../../schemas/custom/Quaternion';
+/**
+ * @public
+ * Rotate a vector by a quaternion
+ * Uses the formula: v' = q * v * q^(-1), optimized version
+ */
+export declare function rotateVectorByQuaternion(v: Vector3Type, q: QuaternionType): Vector3Type;
 /**
  * Get an iterator of entities that follow a tree structure for a component
  * @public

package/dist/runtime/helpers/tree.js

@@ -35,11 +35,11 @@ function multiplyQuaternions(q1, q2) {
     };
 }
 /**
- * @internal
+ * @public
  * Rotate a vector by a quaternion
  * Uses the formula: v' = q * v * q^(-1), optimized version
  */
-function rotateVectorByQuaternion(v, q) {
+export 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

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

@@ -0,0 +1 @@
+export {};

package/dist/runtime/helpers/vectors.js

@@ -0,0 +1,36 @@
+/**
+ * Lightweight Vector3 math utilities for internal use.
+ * Mirrors the subset of @dcl/ecs-math Vector3 API used by the physics helpers.
+ *
+ * TEMPORARY WORKAROUND: @dcl/ecs-math ships ESM-only, which breaks the dist-cjs build.
+ * The proper fix is to add a CJS build to @dcl/ecs-math upstream, then replace this
+ * file with `import { Vector3 } from '@dcl/ecs-math'`.
+ *
+ * @internal
+ */
+export const Vector3 = {
+    add(a, b) {
+        return { x: a.x + b.x, y: a.y + b.y, z: a.z + b.z };
+    },
+    subtract(a, b) {
+        return { x: a.x - b.x, y: a.y - b.y, z: a.z - b.z };
+    },
+    scale(v, s) {
+        return { x: v.x * s, y: v.y * s, z: v.z * s };
+    },
+    length(v) {
+        return Math.sqrt(v.x * v.x + v.y * v.y + v.z * v.z);
+    },
+    normalize(v) {
+        const len = Vector3.length(v);
+        if (len === 0)
+            return { x: 0, y: 0, z: 0 };
+        return { x: v.x / len, y: v.y / len, z: v.z / len };
+    },
+    equals(a, b) {
+        return a.x === b.x && a.y === b.y && a.z === b.z;
+    },
+    equalsToFloats(v, x, y, z) {
+        return v.x === x && v.y === y && v.z === z;
+    }
+};

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

@@ -12,6 +12,7 @@ import { AssetLoadLoadingStateSystem } from '../../systems/assetLoad';
 import { TweenSystem } from '../../systems/tween';
 import { TriggerAreaEventsSystem } from '../../systems/triggerArea';
 import { createTimers, Timers } from '../helpers/timers';
+import { PhysicsSystem } from '../../systems/physics';
 /**
  * @public
  * The engine is the part of the scene that sits in the middle and manages all of the other parts.
@@ -77,6 +78,12 @@ export { TriggerAreaEventsSystem };
  */
 export declare const timers: Timers;
 export { Timers, createTimers };
+/**
+ * @public
+ * Physics helpers for applying impulses and forces to the player.
+ */
+export declare const Physics: PhysicsSystem;
+export { PhysicsSystem };
 /**
  * @public
  * Runs an async function

package/dist/runtime/initialization/index.js

@@ -14,6 +14,7 @@ import { pointerEventColliderChecker } from '../../systems/pointer-event-collide
 import { createTriggerAreaEventsSystem } from '../../systems/triggerArea';
 import { createTimers } from '../helpers/timers';
 import { setGlobalPolyfill } from '../globals';
+import { createPhysicsSystem } from '../../systems/physics';
 /**
  * @public
  * The engine is the part of the scene that sits in the middle and manages all of the other parts.
@@ -77,6 +78,11 @@ setGlobalPolyfill('setTimeout', timers.setTimeout);
 setGlobalPolyfill('clearTimeout', timers.clearTimeout);
 setGlobalPolyfill('setInterval', timers.setInterval);
 setGlobalPolyfill('clearInterval', timers.clearInterval);
+/**
+ * @public
+ * Physics helpers for applying impulses and forces to the player.
+ */
+export const Physics = /* @__PURE__ */ createPhysicsSystem(engine);
 /**
  * Adds pointer event collider system only in DEV env
  */

package/dist/systems/physics-force.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/systems/physics-force.js

@@ -0,0 +1,140 @@
+import * as components from '../components';
+import { Vector3, createTimers } from '../runtime/helpers';
+import { KnockbackFalloff } from './physics-impulse';
+/** @internal */
+export function createPhysicsForceHelper(engine) {
+    const PhysicsCombinedForce = components.PhysicsCombinedForce(engine);
+    const Transform = components.Transform(engine);
+    const timers = createTimers(engine);
+    const durationTimers = new Map();
+    // Key = source entity producing the force (not the target); all forces target PlayerEntity.
+    const forceSources = new Map();
+    const repulsionSources = new Map();
+    let lastWrittenForceVector = null;
+    function recalcForce() {
+        if (forceSources.size === 0) {
+            if (PhysicsCombinedForce.has(engine.PlayerEntity)) {
+                PhysicsCombinedForce.deleteFrom(engine.PlayerEntity);
+            }
+            lastWrittenForceVector = null;
+            return;
+        }
+        const current = PhysicsCombinedForce.getOrNull(engine.PlayerEntity);
+        if (current && lastWrittenForceVector && current.vector) {
+            if (!Vector3.equals(current.vector, lastWrittenForceVector)) {
+                console.error('PBPhysicsCombinedForce was modified externally.', 'Expected:', lastWrittenForceVector, 'Found:', current.vector, '-- overwriting with local state.');
+            }
+        }
+        let sum = { x: 0, y: 0, z: 0 };
+        for (const v of forceSources.values()) {
+            sum = Vector3.add(sum, v);
+        }
+        PhysicsCombinedForce.createOrReplace(engine.PlayerEntity, { vector: sum });
+        lastWrittenForceVector = sum;
+    }
+    function applyForceToPlayer(source, vector, magnitude) {
+        let finalVector;
+        if (Vector3.equalsToFloats(vector, 0, 0, 0))
+            return;
+        if (typeof magnitude === 'number') {
+            finalVector = Vector3.scale(Vector3.normalize(vector), magnitude);
+        }
+        else {
+            finalVector = vector;
+        }
+        forceSources.set(source, finalVector);
+        recalcForce();
+    }
+    function removeForceFromPlayer(source) {
+        repulsionSources.delete(source);
+        const timerId = durationTimers.get(source);
+        if (timerId !== undefined) {
+            timers.clearTimeout(timerId);
+            durationTimers.delete(source);
+        }
+        if (!forceSources.has(source))
+            return;
+        forceSources.delete(source);
+        recalcForce();
+    }
+    function scheduleForceDuration(source, seconds) {
+        const existing = durationTimers.get(source);
+        if (existing !== undefined) {
+            timers.clearTimeout(existing);
+        }
+        const timerId = timers.setTimeout(() => {
+            durationTimers.delete(source);
+            removeForceFromPlayer(source);
+        }, seconds * 1000);
+        durationTimers.set(source, timerId);
+    }
+    function applyForceToPlayerForDuration(source, duration, vector, magnitude) {
+        applyForceToPlayer(source, vector, magnitude);
+        scheduleForceDuration(source, duration);
+    }
+    function computeRepulsionVector(fromPosition, magnitude, radius, falloff) {
+        const diff = Vector3.subtract(Transform.get(engine.PlayerEntity).position, fromPosition);
+        if (Vector3.equalsToFloats(diff, 0, 0, 0))
+            return { x: 0, y: magnitude, z: 0 };
+        // Fast path: default params — no need to compute distance
+        if (radius === Infinity && falloff === KnockbackFalloff.CONSTANT) {
+            return Vector3.scale(Vector3.normalize(diff), magnitude);
+        }
+        const distance = Vector3.length(diff);
+        if (distance > radius)
+            return null;
+        let effectiveMagnitude;
+        switch (falloff) {
+            case KnockbackFalloff.LINEAR:
+                effectiveMagnitude = magnitude * (1 - distance / radius);
+                break;
+            case KnockbackFalloff.INVERSE_SQUARE:
+                effectiveMagnitude = magnitude / (distance * distance + 1);
+                break;
+            case KnockbackFalloff.CONSTANT:
+            default:
+                effectiveMagnitude = magnitude;
+                break;
+        }
+        if (effectiveMagnitude === 0)
+            return null;
+        // normalize(diff) * effectiveMagnitude in one step
+        return Vector3.scale(diff, effectiveMagnitude / distance);
+    }
+    function applyRepulsionForceToPlayer(source, fromPosition, magnitude, radius = Infinity, falloff = KnockbackFalloff.CONSTANT) {
+        repulsionSources.set(source, { fromPosition, magnitude, radius, falloff });
+        const vector = computeRepulsionVector(fromPosition, magnitude, radius, falloff);
+        if (vector) {
+            forceSources.set(source, vector);
+        }
+        else {
+            forceSources.delete(source);
+        }
+        recalcForce();
+    }
+    // Background system: recalculate repulsion vectors and clean up stale forces every tick.
+    // Stale forces can appear when CRDT sync from another client writes PhysicsCombinedForce
+    // externally (entity-1 ambiguity: each client interprets entity 1 as its own player).
+    engine.addSystem(() => {
+        // Repulsion forces need per-tick direction recalculation as the player moves
+        if (repulsionSources.size > 0) {
+            for (const [source, { fromPosition, magnitude, radius, falloff }] of repulsionSources) {
+                const vector = computeRepulsionVector(fromPosition, magnitude, radius, falloff);
+                if (vector) {
+                    forceSources.set(source, vector);
+                }
+                else {
+                    forceSources.delete(source);
+                }
+            }
+            recalcForce();
+            return;
+        }
+        // No local sources — clean up any externally-created component (e.g. from CRDT sync)
+        if (forceSources.size === 0 && PhysicsCombinedForce.has(engine.PlayerEntity)) {
+            PhysicsCombinedForce.deleteFrom(engine.PlayerEntity);
+            lastWrittenForceVector = null;
+        }
+    });
+    return { applyForceToPlayer, removeForceFromPlayer, applyForceToPlayerForDuration, applyRepulsionForceToPlayer };
+}

package/dist/systems/physics-impulse.d.ts

@@ -0,0 +1,12 @@
+/**
+ * @public
+ * Falloff mode for knockback force over distance.
+ */
+export declare enum KnockbackFalloff {
+    /** Same force at any distance within radius */
+    CONSTANT = 0,
+    /** Smooth linear decrease to 0 at radius edge: F = magnitude * (1 - distance / radius) */
+    LINEAR = 1,
+    /** Sharp drop-off, physically realistic: F = magnitude / (distance^2 + 1) */
+    INVERSE_SQUARE = 2
+}

package/dist/systems/physics-impulse.js

@@ -0,0 +1,85 @@
+import * as components from '../components';
+import { Vector3 } from '../runtime/helpers';
+/**
+ * @public
+ * Falloff mode for knockback force over distance.
+ */
+export var KnockbackFalloff;
+(function (KnockbackFalloff) {
+    /** Same force at any distance within radius */
+    KnockbackFalloff[KnockbackFalloff["CONSTANT"] = 0] = "CONSTANT";
+    /** Smooth linear decrease to 0 at radius edge: F = magnitude * (1 - distance / radius) */
+    KnockbackFalloff[KnockbackFalloff["LINEAR"] = 1] = "LINEAR";
+    /** Sharp drop-off, physically realistic: F = magnitude / (distance^2 + 1) */
+    KnockbackFalloff[KnockbackFalloff["INVERSE_SQUARE"] = 2] = "INVERSE_SQUARE";
+})(KnockbackFalloff || (KnockbackFalloff = {}));
+/** @internal */
+export function createPhysicsImpulseHelper(engine) {
+    const PhysicsCombinedImpulse = components.PhysicsCombinedImpulse(engine);
+    const Transform = components.Transform(engine);
+    const EngineInfo = components.EngineInfo(engine);
+    let impulseEventId = 0;
+    let lastWrittenEventId = 0;
+    let lastWrittenTick = -1;
+    function applyImpulseToPlayer(vector, magnitude) {
+        let finalVector;
+        if (typeof magnitude === 'number') {
+            if (Vector3.equalsToFloats(vector, 0, 0, 0))
+                return;
+            finalVector = Vector3.scale(Vector3.normalize(vector), magnitude);
+        }
+        else {
+            if (Vector3.equalsToFloats(vector, 0, 0, 0))
+                return;
+            finalVector = vector;
+        }
+        const currentTick = EngineInfo.getOrNull(engine.RootEntity)?.tickNumber ?? 0;
+        const existing = PhysicsCombinedImpulse.getOrNull(engine.PlayerEntity);
+        if (existing && existing.eventId !== lastWrittenEventId && lastWrittenEventId !== 0) {
+            throw new Error('PBPhysicsCombinedImpulse was modified outside Physics helper. ' +
+                'Do not mix direct component access with Physics.applyImpulseToPlayer().');
+        }
+        if (lastWrittenTick === currentTick && existing) {
+            finalVector = Vector3.add(existing.vector ?? { x: 0, y: 0, z: 0 }, finalVector);
+        }
+        else {
+            lastWrittenEventId = ++impulseEventId;
+        }
+        lastWrittenTick = currentTick;
+        PhysicsCombinedImpulse.createOrReplace(engine.PlayerEntity, {
+            vector: finalVector,
+            eventId: lastWrittenEventId
+        });
+    }
+    function applyKnockbackToPlayer(fromPosition, magnitude, radius = Infinity, falloff = KnockbackFalloff.CONSTANT) {
+        const diff = Vector3.subtract(Transform.get(engine.PlayerEntity).position, fromPosition);
+        if (Vector3.equalsToFloats(diff, 0, 0, 0)) {
+            applyImpulseToPlayer({ x: 0, y: magnitude, z: 0 });
+            return;
+        }
+        // Fast path: default params — no need to compute distance
+        if (radius === Infinity && falloff === KnockbackFalloff.CONSTANT) {
+            applyImpulseToPlayer(Vector3.scale(Vector3.normalize(diff), magnitude));
+            return;
+        }
+        const distance = Vector3.length(diff);
+        if (distance > radius)
+            return;
+        let effectiveMagnitude;
+        switch (falloff) {
+            case KnockbackFalloff.LINEAR:
+                effectiveMagnitude = magnitude * (1 - distance / radius);
+                break;
+            case KnockbackFalloff.INVERSE_SQUARE:
+                effectiveMagnitude = magnitude / (distance * distance + 1);
+                break;
+            case KnockbackFalloff.CONSTANT:
+            default:
+                effectiveMagnitude = magnitude;
+                break;
+        }
+        // normalize(diff) * effectiveMagnitude in one step
+        applyImpulseToPlayer(Vector3.scale(diff, effectiveMagnitude / distance));
+    }
+    return { applyImpulseToPlayer, applyKnockbackToPlayer };
+}

package/dist/systems/physics.d.ts

@@ -0,0 +1,77 @@
+import { Entity } from '../engine';
+import { Vector3Type } from '../schemas';
+import { KnockbackFalloff } from './physics-impulse';
+export { KnockbackFalloff } from './physics-impulse';
+/**
+ * @public
+ */
+export interface PhysicsSystem {
+    /**
+     * Apply a one-shot impulse to the player entity.
+     * Multiple calls within the same frame are accumulated (summed).
+     *
+     * @param vector - a single `vector` whose length encodes the strength.
+     * or use overload for `direction` with a separate `magnitude` — the direction will be normalized before scaling.
+     */
+    applyImpulseToPlayer(vector: Vector3Type): void;
+    applyImpulseToPlayer(direction: Vector3Type, magnitude: number): void;
+    /**
+     * Apply a continuous force to the player from a given source entity.
+     * Multiple sources are accumulated: the registry sums all active forces
+     * and writes a single PBPhysicsCombinedForce component.
+     * Calling again with the same source replaces its previous force.
+     *
+     * @param source - Entity key identifying this force source
+     * @param vector - single `vector` whose length encodes the strength
+     * or use overload for `direction` with a separate `magnitude` — the direction will be normalized before scaling.
+     */
+    applyForceToPlayer(source: Entity, vector: Vector3Type): void;
+    applyForceToPlayer(source: Entity, direction: Vector3Type, magnitude: number): void;
+    /**
+     * Remove a continuous force from the player. Remaining sources are
+     * re-summed; if none remain the force is cleared. No-op if the source
+     * is not registered.
+     *
+     * @param source - Entity key identifying the force source to remove
+     */
+    removeForceFromPlayer(source: Entity): void;
+    /**
+     * Push the player away from a point. Computes direction from
+     * `fromPosition` to the player, applies falloff, and delegates
+     * to applyImpulseToPlayer.
+     *
+     * If the player is exactly at `fromPosition`, pushes upward.
+     *
+     * @param fromPosition - world-space origin of the knockback (explosion center, enemy position, etc.)
+     * @param magnitude - base impulse strength
+     * @param radius - max distance of effect (default: Infinity)
+     * @param falloff - how force decreases with distance (default: CONSTANT)
+     */
+    applyKnockbackToPlayer(fromPosition: Vector3Type, magnitude: number, radius?: number, falloff?: KnockbackFalloff): void;
+    /**
+     * Apply a continuous force to the player for a limited duration.
+     * After `duration` seconds the force is automatically removed.
+     * Calling again with the same source resets the timer.
+     *
+     * @param source - Entity key identifying this force source
+     * @param duration - how long the force lasts, in seconds
+     * @param vector - single `vector` whose length encodes the strength
+     * or use overload for `direction` with a separate `magnitude` — the direction will be normalized before scaling.
+     */
+    applyForceToPlayerForDuration(source: Entity, duration: number, vector: Vector3Type): void;
+    applyForceToPlayerForDuration(source: Entity, duration: number, direction: Vector3Type, magnitude: number): void;
+    /**
+     * Apply a continuous repulsion force that pushes the player away from a point,
+     * recalculating direction every tick as the player moves.
+     * Remove with `removeForceFromPlayer(source)`.
+     *
+     * Negative magnitude = attraction (pulls toward the source).
+     *
+     * @param source - Entity key identifying this force source
+     * @param fromPosition - world-space origin of repulsion
+     * @param magnitude - base force strength
+     * @param radius - max distance of effect (default: Infinity)
+     * @param falloff - how force decreases with distance (default: CONSTANT)
+     */
+    applyRepulsionForceToPlayer(source: Entity, fromPosition: Vector3Type, magnitude: number, radius?: number, falloff?: KnockbackFalloff): void;
+}

package/dist/systems/physics.js

@@ -0,0 +1,18 @@
+import { createPhysicsImpulseHelper } from './physics-impulse';
+import { createPhysicsForceHelper } from './physics-force';
+export { KnockbackFalloff } from './physics-impulse';
+/**
+ * @internal
+ */
+export function createPhysicsSystem(engine) {
+    const impulse = createPhysicsImpulseHelper(engine);
+    const force = createPhysicsForceHelper(engine);
+    return {
+        applyImpulseToPlayer: impulse.applyImpulseToPlayer,
+        applyForceToPlayer: force.applyForceToPlayer,
+        removeForceFromPlayer: force.removeForceFromPlayer,
+        applyKnockbackToPlayer: impulse.applyKnockbackToPlayer,
+        applyForceToPlayerForDuration: force.applyForceToPlayerForDuration,
+        applyRepulsionForceToPlayer: force.applyRepulsionForceToPlayer
+    };
+}

package/dist-cjs/components/manual/Transform.d.ts

@@ -1,5 +1,6 @@
 import { LastWriteWinElementSetComponentDefinition, IEngine } from '../../engine';
 import { Entity } from '../../engine/entity';
+import type { Vector3Type } from '../../schemas/custom/Vector3';
 /**
  * @public
  */
@@ -10,6 +11,18 @@ export type TransformComponent = LastWriteWinElementSetComponentDefinition<Trans
 export interface TransformComponentExtended extends TransformComponent {
     create(entity: Entity, val?: TransformTypeWithOptionals): TransformType;
     createOrReplace(entity: Entity, val?: TransformTypeWithOptionals): TransformType;
+    /**
+     * Transforms a direction vector from an entity's local coordinate space
+     * to world space, accounting for the full parent hierarchy.
+     *
+     * This applies only rotation (not translation or scale) — suitable for
+     * direction vectors like force/impulse directions.
+     *
+     * @param entity - The source entity whose local space defines the direction
+     * @param localDirection - Direction vector in the entity's local coordinates
+     * @returns The direction vector in world coordinates
+     */
+    localToWorldDirection(entity: Entity, localDirection: Vector3Type): Vector3Type;
 }
 /**
  * @public

package/dist-cjs/components/manual/Transform.js

@@ -1,6 +1,33 @@
 "use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || function (mod) {
+    if (mod && mod.__esModule) return mod;
+    var result = {};
+    if (mod != null) for (var k in mod) if (k !== "default" && Object.prototype.hasOwnProperty.call(mod, k)) __createBinding(result, mod, k);
+    __setModuleDefault(result, mod);
+    return result;
+};
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.defineTransformComponent = exports.TransformSchema = exports.TRANSFORM_LENGTH = exports.COMPONENT_ID = void 0;
+// Use import * to safely handle circular dependency (tree.ts → components → Transform.ts → tree.ts).
+// With import *, the namespace object's properties are resolved at access time (live bindings in ESM,
+// getters via __importStar in CJS), so by the time methods are called all exports are available.
+const treeHelpers = __importStar(require("../../runtime/helpers/tree"));
 /**
  * @internal
  */
@@ -104,6 +131,10 @@ function defineTransformComponent(engine) {
         },
         createOrReplace(entity, val) {
             return transformDef.createOrReplace(entity, exports.TransformSchema.extend(val));
+        },
+        localToWorldDirection(entity, localDirection) {
+            const worldRotation = treeHelpers.getWorldRotation(engine, entity);
+            return treeHelpers.rotateVectorByQuaternion(localDirection, worldRotation);
         }
     };
 }

package/dist-cjs/index.d.ts

@@ -12,6 +12,7 @@ export * from './systems/assetLoad';
 export * from './systems/async-task';
 export * from './systems/tween';
 export * from './systems/triggerArea';
+export * from './systems/physics';
 export * from './engine/entity';
 export * from './components/types';
 import { MaterialComponentDefinitionExtended, MeshColliderComponentDefinitionExtended, MeshRendererComponentDefinitionExtended, TransformComponentExtended, AnimatorComponentDefinitionExtended, AudioSourceComponentDefinitionExtended, AudioStreamComponentDefinitionExtended, ISyncComponents, TweenComponentDefinitionExtended, INetowrkEntity, INetowrkParent, VirtualCameraComponentDefinitionExtended, InputModifierComponentDefinitionExtended, LightSourceComponentDefinitionExtended, TriggerAreaComponentDefinitionExtended } from './components/types';

package/dist-cjs/index.js

@@ -43,6 +43,7 @@ __exportStar(require("./systems/assetLoad"), exports);
 __exportStar(require("./systems/async-task"), exports);
 __exportStar(require("./systems/tween"), exports);
 __exportStar(require("./systems/triggerArea"), exports);
+__exportStar(require("./systems/physics"), exports);
 __exportStar(require("./engine/entity"), exports);
 __exportStar(require("./components/types"), exports);
 // @internal

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

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

package/dist-cjs/runtime/helpers/index.js

@@ -17,5 +17,6 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.createTimers = void 0;
 __exportStar(require("./coordinates"), exports);
 __exportStar(require("./tree"), exports);
+__exportStar(require("./vectors"), exports);
 var timers_1 = require("./timers");
 Object.defineProperty(exports, "createTimers", { enumerable: true, get: function () { return timers_1.createTimers; } });

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

@@ -2,6 +2,12 @@ import { Entity } from '../../engine/entity';
 import { ComponentDefinition, IEngine } from '../../engine';
 import { Vector3Type } from '../../schemas/custom/Vector3';
 import { QuaternionType } from '../../schemas/custom/Quaternion';
+/**
+ * @public
+ * Rotate a vector by a quaternion
+ * Uses the formula: v' = q * v * q^(-1), optimized version
+ */
+export declare function rotateVectorByQuaternion(v: Vector3Type, q: QuaternionType): Vector3Type;
 /**
  * Get an iterator of entities that follow a tree structure for a component
  * @public

package/dist-cjs/runtime/helpers/tree.js

@@ -23,7 +23,7 @@ var __importStar = (this && this.__importStar) || function (mod) {
     return result;
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.getWorldRotation = exports.getWorldPosition = exports.getEntitiesWithParent = exports.removeEntityWithChildren = exports.getComponentEntityTree = void 0;
+exports.getWorldRotation = exports.getWorldPosition = exports.getEntitiesWithParent = exports.removeEntityWithChildren = exports.getComponentEntityTree = exports.rotateVectorByQuaternion = void 0;
 const components = __importStar(require("../../components"));
 /**
  * @internal
@@ -61,7 +61,7 @@ function multiplyQuaternions(q1, q2) {
     };
 }
 /**
- * @internal
+ * @public
  * Rotate a vector by a quaternion
  * Uses the formula: v' = q * v * q^(-1), optimized version
  */
@@ -80,6 +80,7 @@ function rotateVectorByQuaternion(v, q) {
         z: iz * qw + iw * -qz + ix * -qy - iy * -qx
     };
 }
+exports.rotateVectorByQuaternion = rotateVectorByQuaternion;
 /** @internal Identity transform values */
 const IDENTITY_POSITION = { x: 0, y: 0, z: 0 };
 const IDENTITY_ROTATION = { x: 0, y: 0, z: 0, w: 1 };

package/dist-cjs/runtime/helpers/vectors.d.ts

@@ -0,0 +1 @@
+export {};

package/dist-cjs/runtime/helpers/vectors.js

@@ -0,0 +1,39 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Vector3 = void 0;
+/**
+ * Lightweight Vector3 math utilities for internal use.
+ * Mirrors the subset of @dcl/ecs-math Vector3 API used by the physics helpers.
+ *
+ * TEMPORARY WORKAROUND: @dcl/ecs-math ships ESM-only, which breaks the dist-cjs build.
+ * The proper fix is to add a CJS build to @dcl/ecs-math upstream, then replace this
+ * file with `import { Vector3 } from '@dcl/ecs-math'`.
+ *
+ * @internal
+ */
+exports.Vector3 = {
+    add(a, b) {
+        return { x: a.x + b.x, y: a.y + b.y, z: a.z + b.z };
+    },
+    subtract(a, b) {
+        return { x: a.x - b.x, y: a.y - b.y, z: a.z - b.z };
+    },
+    scale(v, s) {
+        return { x: v.x * s, y: v.y * s, z: v.z * s };
+    },
+    length(v) {
+        return Math.sqrt(v.x * v.x + v.y * v.y + v.z * v.z);
+    },
+    normalize(v) {
+        const len = exports.Vector3.length(v);
+        if (len === 0)
+            return { x: 0, y: 0, z: 0 };
+        return { x: v.x / len, y: v.y / len, z: v.z / len };
+    },
+    equals(a, b) {
+        return a.x === b.x && a.y === b.y && a.z === b.z;
+    },
+    equalsToFloats(v, x, y, z) {
+        return v.x === x && v.y === y && v.z === z;
+    }
+};

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

@@ -12,6 +12,7 @@ import { AssetLoadLoadingStateSystem } from '../../systems/assetLoad';
 import { TweenSystem } from '../../systems/tween';
 import { TriggerAreaEventsSystem } from '../../systems/triggerArea';
 import { createTimers, Timers } from '../helpers/timers';
+import { PhysicsSystem } from '../../systems/physics';
 /**
  * @public
  * The engine is the part of the scene that sits in the middle and manages all of the other parts.
@@ -77,6 +78,12 @@ export { TriggerAreaEventsSystem };
  */
 export declare const timers: Timers;
 export { Timers, createTimers };
+/**
+ * @public
+ * Physics helpers for applying impulses and forces to the player.
+ */
+export declare const Physics: PhysicsSystem;
+export { PhysicsSystem };
 /**
  * @public
  * Runs an async function

package/dist-cjs/runtime/initialization/index.js

@@ -4,7 +4,7 @@
  * init and it'll be changing.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.executeTask = exports.createTimers = exports.timers = exports.triggerAreaEventsSystem = exports.tweenSystem = exports.assetLoadLoadingStateSystem = exports.videoEventsSystem = exports.raycastSystem = exports.pointerEventsSystem = exports.inputSystem = exports.engine = void 0;
+exports.executeTask = exports.Physics = exports.createTimers = exports.timers = exports.triggerAreaEventsSystem = exports.tweenSystem = exports.assetLoadLoadingStateSystem = exports.videoEventsSystem = exports.raycastSystem = exports.pointerEventsSystem = exports.inputSystem = exports.engine = void 0;
 const engine_1 = require("../../engine");
 const async_task_1 = require("../../systems/async-task");
 const events_1 = require("../../systems/events");
@@ -18,6 +18,7 @@ const triggerArea_1 = require("../../systems/triggerArea");
 const timers_1 = require("../helpers/timers");
 Object.defineProperty(exports, "createTimers", { enumerable: true, get: function () { return timers_1.createTimers; } });
 const globals_1 = require("../globals");
+const physics_1 = require("../../systems/physics");
 /**
  * @public
  * The engine is the part of the scene that sits in the middle and manages all of the other parts.
@@ -80,6 +81,11 @@ exports.timers = (0, timers_1.createTimers)(exports.engine);
 (0, globals_1.setGlobalPolyfill)('clearTimeout', exports.timers.clearTimeout);
 (0, globals_1.setGlobalPolyfill)('setInterval', exports.timers.setInterval);
 (0, globals_1.setGlobalPolyfill)('clearInterval', exports.timers.clearInterval);
+/**
+ * @public
+ * Physics helpers for applying impulses and forces to the player.
+ */
+exports.Physics = (0, physics_1.createPhysicsSystem)(exports.engine);
 /**
  * Adds pointer event collider system only in DEV env
  */

package/dist-cjs/systems/physics-force.d.ts

@@ -0,0 +1 @@
+export {};

package/dist-cjs/systems/physics-force.js

@@ -0,0 +1,167 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || function (mod) {
+    if (mod && mod.__esModule) return mod;
+    var result = {};
+    if (mod != null) for (var k in mod) if (k !== "default" && Object.prototype.hasOwnProperty.call(mod, k)) __createBinding(result, mod, k);
+    __setModuleDefault(result, mod);
+    return result;
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createPhysicsForceHelper = void 0;
+const components = __importStar(require("../components"));
+const helpers_1 = require("../runtime/helpers");
+const physics_impulse_1 = require("./physics-impulse");
+/** @internal */
+function createPhysicsForceHelper(engine) {
+    const PhysicsCombinedForce = components.PhysicsCombinedForce(engine);
+    const Transform = components.Transform(engine);
+    const timers = (0, helpers_1.createTimers)(engine);
+    const durationTimers = new Map();
+    // Key = source entity producing the force (not the target); all forces target PlayerEntity.
+    const forceSources = new Map();
+    const repulsionSources = new Map();
+    let lastWrittenForceVector = null;
+    function recalcForce() {
+        if (forceSources.size === 0) {
+            if (PhysicsCombinedForce.has(engine.PlayerEntity)) {
+                PhysicsCombinedForce.deleteFrom(engine.PlayerEntity);
+            }
+            lastWrittenForceVector = null;
+            return;
+        }
+        const current = PhysicsCombinedForce.getOrNull(engine.PlayerEntity);
+        if (current && lastWrittenForceVector && current.vector) {
+            if (!helpers_1.Vector3.equals(current.vector, lastWrittenForceVector)) {
+                console.error('PBPhysicsCombinedForce was modified externally.', 'Expected:', lastWrittenForceVector, 'Found:', current.vector, '-- overwriting with local state.');
+            }
+        }
+        let sum = { x: 0, y: 0, z: 0 };
+        for (const v of forceSources.values()) {
+            sum = helpers_1.Vector3.add(sum, v);
+        }
+        PhysicsCombinedForce.createOrReplace(engine.PlayerEntity, { vector: sum });
+        lastWrittenForceVector = sum;
+    }
+    function applyForceToPlayer(source, vector, magnitude) {
+        let finalVector;
+        if (helpers_1.Vector3.equalsToFloats(vector, 0, 0, 0))
+            return;
+        if (typeof magnitude === 'number') {
+            finalVector = helpers_1.Vector3.scale(helpers_1.Vector3.normalize(vector), magnitude);
+        }
+        else {
+            finalVector = vector;
+        }
+        forceSources.set(source, finalVector);
+        recalcForce();
+    }
+    function removeForceFromPlayer(source) {
+        repulsionSources.delete(source);
+        const timerId = durationTimers.get(source);
+        if (timerId !== undefined) {
+            timers.clearTimeout(timerId);
+            durationTimers.delete(source);
+        }
+        if (!forceSources.has(source))
+            return;
+        forceSources.delete(source);
+        recalcForce();
+    }
+    function scheduleForceDuration(source, seconds) {
+        const existing = durationTimers.get(source);
+        if (existing !== undefined) {
+            timers.clearTimeout(existing);
+        }
+        const timerId = timers.setTimeout(() => {
+            durationTimers.delete(source);
+            removeForceFromPlayer(source);
+        }, seconds * 1000);
+        durationTimers.set(source, timerId);
+    }
+    function applyForceToPlayerForDuration(source, duration, vector, magnitude) {
+        applyForceToPlayer(source, vector, magnitude);
+        scheduleForceDuration(source, duration);
+    }
+    function computeRepulsionVector(fromPosition, magnitude, radius, falloff) {
+        const diff = helpers_1.Vector3.subtract(Transform.get(engine.PlayerEntity).position, fromPosition);
+        if (helpers_1.Vector3.equalsToFloats(diff, 0, 0, 0))
+            return { x: 0, y: magnitude, z: 0 };
+        // Fast path: default params — no need to compute distance
+        if (radius === Infinity && falloff === physics_impulse_1.KnockbackFalloff.CONSTANT) {
+            return helpers_1.Vector3.scale(helpers_1.Vector3.normalize(diff), magnitude);
+        }
+        const distance = helpers_1.Vector3.length(diff);
+        if (distance > radius)
+            return null;
+        let effectiveMagnitude;
+        switch (falloff) {
+            case physics_impulse_1.KnockbackFalloff.LINEAR:
+                effectiveMagnitude = magnitude * (1 - distance / radius);
+                break;
+            case physics_impulse_1.KnockbackFalloff.INVERSE_SQUARE:
+                effectiveMagnitude = magnitude / (distance * distance + 1);
+                break;
+            case physics_impulse_1.KnockbackFalloff.CONSTANT:
+            default:
+                effectiveMagnitude = magnitude;
+                break;
+        }
+        if (effectiveMagnitude === 0)
+            return null;
+        // normalize(diff) * effectiveMagnitude in one step
+        return helpers_1.Vector3.scale(diff, effectiveMagnitude / distance);
+    }
+    function applyRepulsionForceToPlayer(source, fromPosition, magnitude, radius = Infinity, falloff = physics_impulse_1.KnockbackFalloff.CONSTANT) {
+        repulsionSources.set(source, { fromPosition, magnitude, radius, falloff });
+        const vector = computeRepulsionVector(fromPosition, magnitude, radius, falloff);
+        if (vector) {
+            forceSources.set(source, vector);
+        }
+        else {
+            forceSources.delete(source);
+        }
+        recalcForce();
+    }
+    // Background system: recalculate repulsion vectors and clean up stale forces every tick.
+    // Stale forces can appear when CRDT sync from another client writes PhysicsCombinedForce
+    // externally (entity-1 ambiguity: each client interprets entity 1 as its own player).
+    engine.addSystem(() => {
+        // Repulsion forces need per-tick direction recalculation as the player moves
+        if (repulsionSources.size > 0) {
+            for (const [source, { fromPosition, magnitude, radius, falloff }] of repulsionSources) {
+                const vector = computeRepulsionVector(fromPosition, magnitude, radius, falloff);
+                if (vector) {
+                    forceSources.set(source, vector);
+                }
+                else {
+                    forceSources.delete(source);
+                }
+            }
+            recalcForce();
+            return;
+        }
+        // No local sources — clean up any externally-created component (e.g. from CRDT sync)
+        if (forceSources.size === 0 && PhysicsCombinedForce.has(engine.PlayerEntity)) {
+            PhysicsCombinedForce.deleteFrom(engine.PlayerEntity);
+            lastWrittenForceVector = null;
+        }
+    });
+    return { applyForceToPlayer, removeForceFromPlayer, applyForceToPlayerForDuration, applyRepulsionForceToPlayer };
+}
+exports.createPhysicsForceHelper = createPhysicsForceHelper;

package/dist-cjs/systems/physics-impulse.d.ts

@@ -0,0 +1,12 @@
+/**
+ * @public
+ * Falloff mode for knockback force over distance.
+ */
+export declare enum KnockbackFalloff {
+    /** Same force at any distance within radius */
+    CONSTANT = 0,
+    /** Smooth linear decrease to 0 at radius edge: F = magnitude * (1 - distance / radius) */
+    LINEAR = 1,
+    /** Sharp drop-off, physically realistic: F = magnitude / (distance^2 + 1) */
+    INVERSE_SQUARE = 2
+}

package/dist-cjs/systems/physics-impulse.js

@@ -0,0 +1,112 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || function (mod) {
+    if (mod && mod.__esModule) return mod;
+    var result = {};
+    if (mod != null) for (var k in mod) if (k !== "default" && Object.prototype.hasOwnProperty.call(mod, k)) __createBinding(result, mod, k);
+    __setModuleDefault(result, mod);
+    return result;
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createPhysicsImpulseHelper = exports.KnockbackFalloff = void 0;
+const components = __importStar(require("../components"));
+const helpers_1 = require("../runtime/helpers");
+/**
+ * @public
+ * Falloff mode for knockback force over distance.
+ */
+var KnockbackFalloff;
+(function (KnockbackFalloff) {
+    /** Same force at any distance within radius */
+    KnockbackFalloff[KnockbackFalloff["CONSTANT"] = 0] = "CONSTANT";
+    /** Smooth linear decrease to 0 at radius edge: F = magnitude * (1 - distance / radius) */
+    KnockbackFalloff[KnockbackFalloff["LINEAR"] = 1] = "LINEAR";
+    /** Sharp drop-off, physically realistic: F = magnitude / (distance^2 + 1) */
+    KnockbackFalloff[KnockbackFalloff["INVERSE_SQUARE"] = 2] = "INVERSE_SQUARE";
+})(KnockbackFalloff = exports.KnockbackFalloff || (exports.KnockbackFalloff = {}));
+/** @internal */
+function createPhysicsImpulseHelper(engine) {
+    const PhysicsCombinedImpulse = components.PhysicsCombinedImpulse(engine);
+    const Transform = components.Transform(engine);
+    const EngineInfo = components.EngineInfo(engine);
+    let impulseEventId = 0;
+    let lastWrittenEventId = 0;
+    let lastWrittenTick = -1;
+    function applyImpulseToPlayer(vector, magnitude) {
+        let finalVector;
+        if (typeof magnitude === 'number') {
+            if (helpers_1.Vector3.equalsToFloats(vector, 0, 0, 0))
+                return;
+            finalVector = helpers_1.Vector3.scale(helpers_1.Vector3.normalize(vector), magnitude);
+        }
+        else {
+            if (helpers_1.Vector3.equalsToFloats(vector, 0, 0, 0))
+                return;
+            finalVector = vector;
+        }
+        const currentTick = EngineInfo.getOrNull(engine.RootEntity)?.tickNumber ?? 0;
+        const existing = PhysicsCombinedImpulse.getOrNull(engine.PlayerEntity);
+        if (existing && existing.eventId !== lastWrittenEventId && lastWrittenEventId !== 0) {
+            throw new Error('PBPhysicsCombinedImpulse was modified outside Physics helper. ' +
+                'Do not mix direct component access with Physics.applyImpulseToPlayer().');
+        }
+        if (lastWrittenTick === currentTick && existing) {
+            finalVector = helpers_1.Vector3.add(existing.vector ?? { x: 0, y: 0, z: 0 }, finalVector);
+        }
+        else {
+            lastWrittenEventId = ++impulseEventId;
+        }
+        lastWrittenTick = currentTick;
+        PhysicsCombinedImpulse.createOrReplace(engine.PlayerEntity, {
+            vector: finalVector,
+            eventId: lastWrittenEventId
+        });
+    }
+    function applyKnockbackToPlayer(fromPosition, magnitude, radius = Infinity, falloff = KnockbackFalloff.CONSTANT) {
+        const diff = helpers_1.Vector3.subtract(Transform.get(engine.PlayerEntity).position, fromPosition);
+        if (helpers_1.Vector3.equalsToFloats(diff, 0, 0, 0)) {
+            applyImpulseToPlayer({ x: 0, y: magnitude, z: 0 });
+            return;
+        }
+        // Fast path: default params — no need to compute distance
+        if (radius === Infinity && falloff === KnockbackFalloff.CONSTANT) {
+            applyImpulseToPlayer(helpers_1.Vector3.scale(helpers_1.Vector3.normalize(diff), magnitude));
+            return;
+        }
+        const distance = helpers_1.Vector3.length(diff);
+        if (distance > radius)
+            return;
+        let effectiveMagnitude;
+        switch (falloff) {
+            case KnockbackFalloff.LINEAR:
+                effectiveMagnitude = magnitude * (1 - distance / radius);
+                break;
+            case KnockbackFalloff.INVERSE_SQUARE:
+                effectiveMagnitude = magnitude / (distance * distance + 1);
+                break;
+            case KnockbackFalloff.CONSTANT:
+            default:
+                effectiveMagnitude = magnitude;
+                break;
+        }
+        // normalize(diff) * effectiveMagnitude in one step
+        applyImpulseToPlayer(helpers_1.Vector3.scale(diff, effectiveMagnitude / distance));
+    }
+    return { applyImpulseToPlayer, applyKnockbackToPlayer };
+}
+exports.createPhysicsImpulseHelper = createPhysicsImpulseHelper;

package/dist-cjs/systems/physics.d.ts

@@ -0,0 +1,77 @@
+import { Entity } from '../engine';
+import { Vector3Type } from '../schemas';
+import { KnockbackFalloff } from './physics-impulse';
+export { KnockbackFalloff } from './physics-impulse';
+/**
+ * @public
+ */
+export interface PhysicsSystem {
+    /**
+     * Apply a one-shot impulse to the player entity.
+     * Multiple calls within the same frame are accumulated (summed).
+     *
+     * @param vector - a single `vector` whose length encodes the strength.
+     * or use overload for `direction` with a separate `magnitude` — the direction will be normalized before scaling.
+     */
+    applyImpulseToPlayer(vector: Vector3Type): void;
+    applyImpulseToPlayer(direction: Vector3Type, magnitude: number): void;
+    /**
+     * Apply a continuous force to the player from a given source entity.
+     * Multiple sources are accumulated: the registry sums all active forces
+     * and writes a single PBPhysicsCombinedForce component.
+     * Calling again with the same source replaces its previous force.
+     *
+     * @param source - Entity key identifying this force source
+     * @param vector - single `vector` whose length encodes the strength
+     * or use overload for `direction` with a separate `magnitude` — the direction will be normalized before scaling.
+     */
+    applyForceToPlayer(source: Entity, vector: Vector3Type): void;
+    applyForceToPlayer(source: Entity, direction: Vector3Type, magnitude: number): void;
+    /**
+     * Remove a continuous force from the player. Remaining sources are
+     * re-summed; if none remain the force is cleared. No-op if the source
+     * is not registered.
+     *
+     * @param source - Entity key identifying the force source to remove
+     */
+    removeForceFromPlayer(source: Entity): void;
+    /**
+     * Push the player away from a point. Computes direction from
+     * `fromPosition` to the player, applies falloff, and delegates
+     * to applyImpulseToPlayer.
+     *
+     * If the player is exactly at `fromPosition`, pushes upward.
+     *
+     * @param fromPosition - world-space origin of the knockback (explosion center, enemy position, etc.)
+     * @param magnitude - base impulse strength
+     * @param radius - max distance of effect (default: Infinity)
+     * @param falloff - how force decreases with distance (default: CONSTANT)
+     */
+    applyKnockbackToPlayer(fromPosition: Vector3Type, magnitude: number, radius?: number, falloff?: KnockbackFalloff): void;
+    /**
+     * Apply a continuous force to the player for a limited duration.
+     * After `duration` seconds the force is automatically removed.
+     * Calling again with the same source resets the timer.
+     *
+     * @param source - Entity key identifying this force source
+     * @param duration - how long the force lasts, in seconds
+     * @param vector - single `vector` whose length encodes the strength
+     * or use overload for `direction` with a separate `magnitude` — the direction will be normalized before scaling.
+     */
+    applyForceToPlayerForDuration(source: Entity, duration: number, vector: Vector3Type): void;
+    applyForceToPlayerForDuration(source: Entity, duration: number, direction: Vector3Type, magnitude: number): void;
+    /**
+     * Apply a continuous repulsion force that pushes the player away from a point,
+     * recalculating direction every tick as the player moves.
+     * Remove with `removeForceFromPlayer(source)`.
+     *
+     * Negative magnitude = attraction (pulls toward the source).
+     *
+     * @param source - Entity key identifying this force source
+     * @param fromPosition - world-space origin of repulsion
+     * @param magnitude - base force strength
+     * @param radius - max distance of effect (default: Infinity)
+     * @param falloff - how force decreases with distance (default: CONSTANT)
+     */
+    applyRepulsionForceToPlayer(source: Entity, fromPosition: Vector3Type, magnitude: number, radius?: number, falloff?: KnockbackFalloff): void;
+}

package/dist-cjs/systems/physics.js

@@ -0,0 +1,23 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createPhysicsSystem = exports.KnockbackFalloff = void 0;
+const physics_impulse_1 = require("./physics-impulse");
+const physics_force_1 = require("./physics-force");
+var physics_impulse_2 = require("./physics-impulse");
+Object.defineProperty(exports, "KnockbackFalloff", { enumerable: true, get: function () { return physics_impulse_2.KnockbackFalloff; } });
+/**
+ * @internal
+ */
+function createPhysicsSystem(engine) {
+    const impulse = (0, physics_impulse_1.createPhysicsImpulseHelper)(engine);
+    const force = (0, physics_force_1.createPhysicsForceHelper)(engine);
+    return {
+        applyImpulseToPlayer: impulse.applyImpulseToPlayer,
+        applyForceToPlayer: force.applyForceToPlayer,
+        removeForceFromPlayer: force.removeForceFromPlayer,
+        applyKnockbackToPlayer: impulse.applyKnockbackToPlayer,
+        applyForceToPlayerForDuration: force.applyForceToPlayerForDuration,
+        applyRepulsionForceToPlayer: force.applyRepulsionForceToPlayer
+    };
+}
+exports.createPhysicsSystem = createPhysicsSystem;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@dcl/ecs",
   "description": "Decentraland ECS",
-  "version": "7.21.1-23203004012.commit-7c64ac2",
+  "version": "7.21.1-23252789519.commit-9f806e1",
   "author": "DCL",
   "bugs": "https://github.com/decentraland/ecs/issues",
   "files": [
@@ -31,7 +31,8 @@
     "displayName": "ECS",
     "tsconfig": "./tsconfig.json"
   },
+  "dependencies": {},
   "types": "./dist/index.d.ts",
   "typings": "./dist/index.d.ts",
-  "commit": "7c64ac29ee3f34e79019b4435854537a261721ab"
+  "commit": "9f806e11cc45f8449a651c31e78123680a8488d8"
 }