@dcl/ecs 7.22.6-25007982108.commit-83012ab → 7.22.6-25321038582.commit-63ddb3f

package/dist-cjs/systems/events.js

@@ -45,15 +45,14 @@ function createPointerEventsSystem(engine, inputSystem) {
         EventType[EventType["Up"] = 2] = "Up";
         EventType[EventType["HoverEnter"] = 3] = "HoverEnter";
         EventType[EventType["HoverLeave"] = 4] = "HoverLeave";
-        EventType[EventType["Drag"] = 5] = "Drag";
-        EventType[EventType["DragLocked"] = 6] = "DragLocked";
-        EventType[EventType["DragEnd"] = 7] = "DragEnd";
+        EventType[EventType["ProximityEnter"] = 5] = "ProximityEnter";
+        EventType[EventType["ProximityLeave"] = 6] = "ProximityLeave";
     })(EventType || (EventType = {}));
     const eventsMap = new Map();
     function getEvent(entity) {
         return eventsMap.get(entity) || eventsMap.set(entity, new Map()).get(entity);
     }
-    function setPointerEvent(entity, type, opts) {
+    function setPointerEvent(entity, type, opts, interactionType = 0 /* InteractionType.CURSOR */) {
         const pointerEvent = PointerEvents.getMutableOrNull(entity) || PointerEvents.create(entity);
         pointerEvent.pointerEvents.push({
             eventType: type,
@@ -63,15 +62,19 @@ function createPointerEventsSystem(engine, inputSystem) {
                 showHighlight: opts.showHighlight,
                 hoverText: opts.hoverText,
                 maxDistance: opts.maxDistance,
-                maxPlayerDistance: opts.maxPlayerDistance
-            }
+                maxPlayerDistance: opts.maxPlayerDistance,
+                priority: opts.priority
+            },
+            interactionType: interactionType ?? 0 /* InteractionType.CURSOR */
         });
     }
-    function removePointerEvent(entity, type, button) {
+    function removePointerEvent(entity, type, button, interactionType = 0 /* InteractionType.CURSOR */) {
         const pointerEvent = PointerEvents.getMutableOrNull(entity);
         if (!pointerEvent)
             return;
-        pointerEvent.pointerEvents = pointerEvent.pointerEvents.filter((pointer) => !(pointer.eventInfo?.button === button && pointer.eventType === type));
+        pointerEvent.pointerEvents = pointerEvent.pointerEvents.filter((pointer) => !(pointer.eventInfo?.button === button &&
+            pointer.eventType === type &&
+            pointer.interactionType === interactionType));
     }
     function getPointerEvent(eventType) {
         if (eventType === EventType.Up) {
@@ -83,148 +86,117 @@ function createPointerEventsSystem(engine, inputSystem) {
         else if (eventType === EventType.HoverEnter) {
             return 2 /* PointerEventType.PET_HOVER_ENTER */;
         }
-        else if (eventType === EventType.Drag) {
-            return 7 /* PointerEventType.PET_DRAG */;
-        }
-        else if (eventType === EventType.DragLocked) {
-            return 6 /* PointerEventType.PET_DRAG_LOCKED */;
+        else if (eventType === EventType.ProximityEnter) {
+            return 4 /* PointerEventType.PET_PROXIMITY_ENTER */;
         }
-        else if (eventType === EventType.DragEnd) {
-            return 8 /* PointerEventType.PET_DRAG_END */;
+        else if (eventType === EventType.ProximityLeave) {
+            return 5 /* PointerEventType.PET_PROXIMITY_LEAVE */;
         }
         return 1 /* PointerEventType.PET_DOWN */;
     }
-    function getEventType(pet) {
-        if (pet === 0 /* PointerEventType.PET_UP */) {
-            return EventType.Up;
-        }
-        else if (pet === 2 /* PointerEventType.PET_HOVER_ENTER */) {
-            return EventType.HoverEnter;
-        }
-        else if (pet === 3 /* PointerEventType.PET_HOVER_LEAVE */) {
-            return EventType.HoverLeave;
-        }
-        else if (pet === 7 /* PointerEventType.PET_DRAG */) {
-            return EventType.Drag;
-        }
-        else if (pet === 6 /* PointerEventType.PET_DRAG_LOCKED */) {
-            return EventType.DragLocked;
-        }
-        else if (pet === 8 /* PointerEventType.PET_DRAG_END */) {
-            return EventType.DragEnd;
-        }
-        else {
-            return EventType.Down;
-        }
-    }
-    function removeEvent(entity, type) {
+    function removeEvent(entity, type, interactionType = 0 /* InteractionType.CURSOR */) {
         const event = getEvent(entity);
-        const pointerEventList = event.get(type);
-        if (pointerEventList === undefined) {
-            return;
-        }
-        for (const button of pointerEventList.keys()) {
-            removePointerEvent(entity, getPointerEvent(type), button);
+        const pointerEvent = event.get(type);
+        if (pointerEvent?.opts.hoverText) {
+            removePointerEvent(entity, getPointerEvent(type), pointerEvent.opts.button);
         }
         event.delete(type);
     }
     engine.addSystem(function EventSystem() {
-        if (eventsMap.size === 0) {
-            return;
-        }
-        for (const entity of eventsMap.keys()) {
+        for (const [entity, event] of eventsMap) {
             if (engine.getEntityState(entity) === entity_1.EntityState.Removed) {
                 eventsMap.delete(entity);
-            }
-        }
-        for (const command of inputSystem.getInputCommands()) {
-            const entity = command.hit?.entityId;
-            if (entity === undefined) {
-                continue;
-            }
-            const entityMap = eventsMap.get(entity);
-            if (entityMap === undefined) {
                 continue;
             }
-            const typeMap = entityMap.get(getEventType(command.state));
-            if (typeMap) {
-                const data = typeMap.get(command.button);
-                if (data) {
-                    (0, invariant_1.checkNotThenable)(data.cb(command), 'Event handler returned a thenable. Only synchronous functions are allowed');
+            for (const [eventType, { cb, opts }] of event) {
+                if (eventType === EventType.Click) {
+                    const command = inputSystem.getClick(opts.button, entity);
+                    if (command)
+                        (0, invariant_1.checkNotThenable)(cb(command.up), 'Click event returned a thenable. Only synchronous functions are allowed');
                 }
-                const anyData = typeMap.get(3 /* InputAction.IA_ANY */);
-                if (anyData) {
-                    (0, invariant_1.checkNotThenable)(anyData.cb(command), 'Event handler returned a thenable. Only synchronous functions are allowed');
-                }
-            }
-            // check clicks separately
-            if (command.state === 0 /* PointerEventType.PET_UP */) {
-                const clickMap = entityMap.get(EventType.Click);
-                if (clickMap) {
-                    const data = clickMap.get(command.button);
-                    if (data && inputSystem.getClick(command.button, entity)) {
-                        (0, invariant_1.checkNotThenable)(data.cb(command), 'Click event returned a thenable. Only synchronous functions are allowed');
-                    }
-                    const anyData = clickMap.get(3 /* InputAction.IA_ANY */);
-                    if (anyData && inputSystem.getClick(command.button, entity)) {
-                        (0, invariant_1.checkNotThenable)(anyData.cb(command), 'Event handler returned a thenable. Only synchronous functions are allowed');
+                if (eventType === EventType.Down ||
+                    eventType === EventType.Up ||
+                    eventType === EventType.HoverEnter ||
+                    eventType === EventType.HoverLeave ||
+                    eventType === EventType.ProximityEnter ||
+                    eventType === EventType.ProximityLeave) {
+                    const command = inputSystem.getInputCommand(opts.button, getPointerEvent(eventType), entity);
+                    if (command) {
+                        (0, invariant_1.checkNotThenable)(cb(command), 'Event handler returned a thenable. Only synchronous functions are allowed');
                     }
                 }
             }
         }
     });
-    // return a function with the correct event type.
-    // we use onPointerDown as the "archetype" for the returned function, but it fits with
-    // all the onPointer* declarations
-    const onPointerFunction = (ty) => {
-        return (arg0, arg1, arg2) => {
-            let entity;
-            let optsList;
-            if (typeof arg0 === 'number') {
-                // called as onPointerDown(entity: Entity, cb: EventSystemCallback, opts?: Partial<EventSystemOptions>): void
-                entity = arg0;
-                const cb = arg1;
-                const opts = arg2;
-                optsList = [{ cb, ...(0, exports.getDefaultOpts)(opts) }];
-            }
-            else if (typeof arg1 === 'function') {
-                // called as onPointerDown(pointerData: { entity: Entity; opts?: Partial<EventSystemOptions> }, cb: EventSystemCallback): void
-                const { entity: e, opts } = arg0;
-                const cb = arg1;
-                entity = e;
-                optsList = [{ cb, ...(0, exports.getDefaultOpts)(opts) }];
-            }
-            else {
-                // called as onPointerDown(pointerData: { entity: Entity; optsList: EventSystemOptionsCallback[] }): void
-                const { entity: e, optsList: o } = arg0;
-                entity = e;
-                optsList = o;
-            }
-            const previous = getEvent(entity).get(ty) ?? new Map();
-            const callbacks = new Map();
-            for (const opts of optsList) {
-                const prevOpts = previous.get(opts.button);
-                if (prevOpts !== undefined) {
-                    if (prevOpts.hoverText !== opts.hoverText ||
-                        prevOpts.maxDistance !== opts.maxDistance ||
-                        prevOpts.showFeedback !== opts.showFeedback ||
-                        prevOpts.showHighlight !== opts.showHighlight) {
-                        removePointerEvent(entity, getPointerEvent(ty), opts.button);
-                        setPointerEvent(entity, getPointerEvent(ty), opts);
-                    }
-                }
-                else {
-                    setPointerEvent(entity, getPointerEvent(ty), opts);
-                }
-                callbacks.set(opts.button, opts);
-            }
-            for (const button of previous.keys()) {
-                if (!callbacks.has(button)) {
-                    removePointerEvent(entity, getPointerEvent(ty), button);
-                }
-            }
-            getEvent(entity).set(ty, callbacks);
-        };
+    const onPointerDown = (...args) => {
+        const [data, cb, maybeOpts] = args;
+        if (typeof data === 'number') {
+            return onPointerDown({ entity: data, opts: maybeOpts ?? {} }, cb);
+        }
+        const { entity, opts } = data;
+        const options = (0, exports.getDefaultOpts)(opts);
+        removeEvent(entity, EventType.Down);
+        getEvent(entity).set(EventType.Down, { cb, opts: options });
+        setPointerEvent(entity, 1 /* PointerEventType.PET_DOWN */, options);
+    };
+    const onPointerUp = (...args) => {
+        const [data, cb, maybeOpts] = args;
+        if (typeof data === 'number') {
+            return onPointerUp({ entity: data, opts: maybeOpts ?? {} }, cb);
+        }
+        const { entity, opts } = data;
+        const options = (0, exports.getDefaultOpts)(opts);
+        removeEvent(entity, EventType.Up);
+        getEvent(entity).set(EventType.Up, { cb, opts: options });
+        setPointerEvent(entity, 0 /* PointerEventType.PET_UP */, options);
+    };
+    const onPointerHoverEnter = (...args) => {
+        const [data, cb] = args;
+        const { entity, opts } = data;
+        const options = (0, exports.getDefaultOpts)(opts);
+        removeEvent(entity, EventType.HoverEnter);
+        getEvent(entity).set(EventType.HoverEnter, { cb, opts: options });
+        setPointerEvent(entity, 2 /* PointerEventType.PET_HOVER_ENTER */, options);
+    };
+    const onPointerHoverLeave = (...args) => {
+        const [data, cb] = args;
+        const { entity, opts } = data;
+        const options = (0, exports.getDefaultOpts)(opts);
+        removeEvent(entity, EventType.HoverLeave);
+        getEvent(entity).set(EventType.HoverLeave, { cb, opts: options });
+        setPointerEvent(entity, 3 /* PointerEventType.PET_HOVER_LEAVE */, options);
+    };
+    const onProximityDown = (...args) => {
+        const [data, cb] = args;
+        const { entity, opts } = data;
+        const options = (0, exports.getDefaultOpts)(opts);
+        removeEvent(entity, EventType.Down, 1 /* InteractionType.PROXIMITY */);
+        getEvent(entity).set(EventType.Down, { cb, opts: options });
+        setPointerEvent(entity, 1 /* PointerEventType.PET_DOWN */, options, 1 /* InteractionType.PROXIMITY */);
+    };
+    const onProximityUp = (...args) => {
+        const [data, cb] = args;
+        const { entity, opts } = data;
+        const options = (0, exports.getDefaultOpts)(opts);
+        removeEvent(entity, EventType.Up, 1 /* InteractionType.PROXIMITY */);
+        getEvent(entity).set(EventType.Up, { cb, opts: options });
+        setPointerEvent(entity, 0 /* PointerEventType.PET_UP */, options, 1 /* InteractionType.PROXIMITY */);
+    };
+    const onProximityEnter = (...args) => {
+        const [data, cb] = args;
+        const { entity, opts } = data;
+        const options = (0, exports.getDefaultOpts)(opts);
+        removeEvent(entity, EventType.ProximityEnter, 1 /* InteractionType.PROXIMITY */);
+        getEvent(entity).set(EventType.ProximityEnter, { cb, opts: options });
+        setPointerEvent(entity, 4 /* PointerEventType.PET_PROXIMITY_ENTER */, options, 1 /* InteractionType.PROXIMITY */);
+    };
+    const onProximityLeave = (...args) => {
+        const [data, cb] = args;
+        const { entity, opts } = data;
+        const options = (0, exports.getDefaultOpts)(opts);
+        removeEvent(entity, EventType.ProximityLeave, 1 /* InteractionType.PROXIMITY */);
+        getEvent(entity).set(EventType.ProximityLeave, { cb, opts: options });
+        setPointerEvent(entity, 5 /* PointerEventType.PET_PROXIMITY_LEAVE */, options, 1 /* InteractionType.PROXIMITY */);
     };
     return {
         removeOnClick(entity) {
@@ -242,23 +214,35 @@ function createPointerEventsSystem(engine, inputSystem) {
         removeOnPointerHoverLeave(entity) {
             removeEvent(entity, EventType.HoverLeave);
         },
-        removeOnPointerDrag(entity) {
-            removeEvent(entity, EventType.Drag);
+        removeOnProximityDown(entity) {
+            removeEvent(entity, EventType.Down, 1 /* InteractionType.PROXIMITY */);
+        },
+        removeOnProximityUp(entity) {
+            removeEvent(entity, EventType.Up, 1 /* InteractionType.PROXIMITY */);
         },
-        removeOnPointerDragLocked(entity) {
-            removeEvent(entity, EventType.DragLocked);
+        removeOnProximityEnter(entity) {
+            removeEvent(entity, EventType.ProximityEnter, 1 /* InteractionType.PROXIMITY */);
         },
-        removeOnPointerDragEnd(entity) {
-            removeEvent(entity, EventType.DragEnd);
+        removeOnProximityLeave(entity) {
+            removeEvent(entity, EventType.ProximityLeave, 1 /* InteractionType.PROXIMITY */);
+        },
+        onClick(value, cb) {
+            const { entity } = value;
+            const options = (0, exports.getDefaultOpts)(value.opts);
+            // Clear previous event with over feedback included
+            removeEvent(entity, EventType.Click);
+            // Set new event
+            getEvent(entity).set(EventType.Click, { cb, opts: options });
+            setPointerEvent(entity, 1 /* PointerEventType.PET_DOWN */, options);
         },
-        onClick: onPointerFunction(EventType.Click),
-        onPointerDown: onPointerFunction(EventType.Down),
-        onPointerUp: onPointerFunction(EventType.Up),
-        onPointerHoverEnter: onPointerFunction(EventType.HoverEnter),
-        onPointerHoverLeave: onPointerFunction(EventType.HoverLeave),
-        onPointerDrag: onPointerFunction(EventType.Drag),
-        onPointerDragLocked: onPointerFunction(EventType.DragLocked),
-        onPointerDragEnd: onPointerFunction(EventType.DragEnd)
+        onPointerDown,
+        onPointerUp,
+        onPointerHoverEnter,
+        onPointerHoverLeave,
+        onProximityDown,
+        onProximityUp,
+        onProximityEnter,
+        onProximityLeave
     };
 }
 exports.createPointerEventsSystem = createPointerEventsSystem;

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;