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

package/dist/systems/events.js

@@ -18,15 +18,14 @@ export 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,
@@ -36,15 +35,19 @@ export 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) {
@@ -56,148 +59,117 @@ export 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) === 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) {
-                    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)
+                        checkNotThenable(cb(command.up), 'Click event returned a thenable. Only synchronous functions are allowed');
                 }
-                const anyData = typeMap.get(3 /* InputAction.IA_ANY */);
-                if (anyData) {
-                    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)) {
-                        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)) {
-                        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) {
+                        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, ...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, ...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 = 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 = 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 = 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 = 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 = 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 = 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 = 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 = 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) {
@@ -215,22 +187,34 @@ export 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 = 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
     };
 }

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;
+}