@rpgjs/server 5.0.0-alpha.15 → 5.0.0-alpha.17

package/dist/index.js

@@ -11349,10 +11349,10 @@ __decorateClass$3([
   sync()
 ], RpgCommonPlayer.prototype, "type");
 __decorateClass$3([
-  persist()
+  sync()
 ], RpgCommonPlayer.prototype, "x");
 __decorateClass$3([
-  persist()
+  sync()
 ], RpgCommonPlayer.prototype, "y");
 __decorateClass$3([
   sync()
@@ -12545,6 +12545,48 @@ class Entity {
     this.force.set(0, 0);
     this.torque = 0;
   }
+  /**
+   * Stops all movement immediately
+   * 
+   * Completely stops the entity's movement by:
+   * - Setting velocity to zero
+   * - Setting angular velocity to zero
+   * - Clearing accumulated forces and torques
+   * - Waking up the entity if it was sleeping
+   * - Notifying movement state change
+   * 
+   * Unlike `freeze()`, this method keeps the entity dynamic and does not
+   * change its state. It's useful for stopping movement when changing maps,
+   * teleporting, or when you need to halt an entity without making it static.
+   * 
+   * @returns This entity for chaining
+   * 
+   * @example
+   * ```ts
+   * // Stop movement when changing maps
+   * if (mapChanged) {
+   *   entity.stopMovement();
+   * }
+   * 
+   * // Stop movement after teleporting
+   * entity.position.set(100, 200);
+   * entity.stopMovement();
+   * 
+   * // Stop movement when player dies
+   * if (player.isDead()) {
+   *   playerEntity.stopMovement();
+   * }
+   * ```
+   */
+  stopMovement() {
+    this.velocity.set(0, 0);
+    this.angularVelocity = 0;
+    this.clearForces();
+    this.wakeUp();
+    this.notifyMovementChange();
+    this.notifyDirectionChange();
+    return this;
+  }
   /**
    * Clamps velocities to maximum values
    */
@@ -14232,6 +14274,11 @@ class CollisionResolver {
   /**
    * Separates two entities by moving them apart
    * 
+   * This method applies position corrections to resolve penetration between
+   * colliding entities. After applying corrections, it notifies position change
+   * handlers to ensure proper synchronization with game logic (e.g., updating
+   * owner.x/y signals for network sync).
+   * 
    * @param entityA - First entity
    * @param entityB - Second entity
    * @param normal - Separation normal (from A to B)
@@ -14250,9 +14297,11 @@ class CollisionResolver {
     const correctionB = normal.mul(correction * (entityB.invMass / totalInvMass));
     if (!entityA.isStatic()) {
       entityA.position.addInPlace(correctionA);
+      entityA.notifyPositionChange();
     }
     if (!entityB.isStatic()) {
       entityB.position.addInPlace(correctionB);
+      entityB.notifyPositionChange();
     }
   }
   /**
@@ -15404,6 +15453,47 @@ let MovementManager$1 = class MovementManager {
     const body = this.resolveTarget(target);
     this.entries.delete(body.id);
   }
+  /**
+   * Stops all movement for an entity immediately
+   * 
+   * This method completely stops an entity's movement by:
+   * - Removing all active movement strategies (dash, linear moves, etc.)
+   * - Stopping the entity's velocity and angular velocity
+   * - Clearing accumulated forces
+   * - Waking up the entity if it was sleeping
+   * 
+   * This is useful when changing maps, teleporting, or when you need
+   * to halt an entity's movement completely without making it static.
+   * 
+   * @param target - Entity, MovementBody, or identifier
+   * 
+   * @example
+   * ```ts
+   * // Stop movement when changing maps
+   * if (mapChanged) {
+   *   movement.stopMovement(playerEntity);
+   * }
+   * 
+   * // Stop movement after teleporting
+   * entity.position.set(100, 200);
+   * movement.stopMovement(entity);
+   * 
+   * // Stop movement when player dies
+   * if (player.isDead()) {
+   *   movement.stopMovement(playerEntity);
+   * }
+   * ```
+   */
+  stopMovement(target) {
+    const body = this.resolveTarget(target);
+    this.clear(target);
+    if ("getEntity" in body && typeof body.getEntity === "function") {
+      const entity = body.getEntity();
+      if (entity && typeof entity.stopMovement === "function") {
+        entity.stopMovement();
+      }
+    }
+  }
   /**
    * Checks if an entity has active strategies.
    *
@@ -17004,6 +17094,9 @@ class MovementManager {
   clear(id) {
     this.core.clear(id);
   }
+  stopMovement(id) {
+    this.core.stopMovement(id);
+  }
   hasActiveStrategies(id) {
     return this.core.hasActiveStrategies(id);
   }
@@ -17037,12 +17130,33 @@ class RpgCommonMap {
      * It's shared using the share() operator, meaning that all subscribers will receive
      * events from a single interval rather than creating multiple intervals.
      * 
+     * ## Physics Loop Architecture
+     * 
+     * The physics simulation is centralized in this game loop:
+     * 
+     * 1. **Input Processing** (`processInput`): Only updates entity velocities, does NOT step physics
+     * 2. **Game Loop** (`tick$` -> `runFixedTicks`): Executes physics simulation with fixed timestep
+     * 3. **Fixed Timestep Pattern**: Accumulator-based approach ensures deterministic physics
+     * 
+     * ```
+     * Input Events ─────────────────────────────────────────────────────────────►
+     *     │                                                                       
+     *     ▼ (update velocity only)                                               
+     * ┌─────────────────────────────────────────────────────────────────────────┐
+     * │                        Game Loop (tick$)                                │
+     * │  ┌─────────────────┐   ┌─────────────────┐   ┌─────────────────┐       │
+     * │  │ updateMovements │ → │  stepOneTick    │ → │ postTickUpdates │       │
+     * │  │ (apply velocity)│   │ (physics step)  │   │ (zones, sync)   │       │
+     * │  └─────────────────┘   └─────────────────┘   └─────────────────┘       │
+     * └─────────────────────────────────────────────────────────────────────────┘
+     * ```
+     * 
      * @example
      * ```ts
-     * // Subscribe to the game tick to update entity positions
-     * map.tick$.subscribe(timestamp => {
-     *   // Update game entities based on elapsed time
-     *   this.updateEntities(timestamp);
+     * // Subscribe to the game tick for custom updates
+     * map.tick$.subscribe(({ delta, timestamp }) => {
+     *   // Custom game logic runs alongside physics
+     *   this.updateCustomEntities(delta);
      * });
      * ```
      */
@@ -17192,6 +17306,7 @@ class RpgCommonMap {
     if (typeof player.autoChangeMap === "function") {
       const mapChanged = await player.autoChangeMap({ x: nextX, y: nextY }, direction);
       if (mapChanged) {
+        this.stopMovement(player);
         return;
       }
     }
@@ -17217,6 +17332,43 @@ class RpgCommonMap {
   getObjectById(id) {
     return this.players()[id] ?? this.events()[id];
   }
+  /**
+   * Execute physics simulation with fixed timestep
+   * 
+   * This method runs the physics engine using a fixed timestep accumulator pattern.
+   * It ensures deterministic physics regardless of frame rate by:
+   * 1. Accumulating delta time
+   * 2. Running fixed-size physics steps until the accumulator is depleted
+   * 3. Calling `updateMovements()` before each step to apply velocity changes
+   * 4. Running post-tick updates (zones, callbacks) after each step
+   * 
+   * ## Architecture
+   * 
+   * The physics loop is centralized here and called from `tick$` subscription.
+   * Input processing (`processInput`) only updates entity velocities - it does NOT
+   * step the physics. This ensures:
+   * - Consistent physics timing (60fps fixed timestep)
+   * - No double-stepping when inputs are processed
+   * - Proper accumulator-based interpolation support
+   * 
+   * @param deltaMs - Time elapsed since last call in milliseconds
+   * @param hooks - Optional callbacks for before/after each physics step
+   * @returns Number of physics ticks executed
+   * 
+   * @example
+   * ```ts
+   * // Called automatically by tick$ subscription
+   * this.tickSubscription = this.tick$.subscribe(({ delta }) => {
+   *   this.runFixedTicks(delta);
+   * });
+   * 
+   * // Or manually with hooks for debugging
+   * this.runFixedTicks(16, {
+   *   beforeStep: () => console.log('Before physics step'),
+   *   afterStep: (tick) => console.log(`Physics tick ${tick} completed`)
+   * });
+   * ```
+   */
   runFixedTicks(deltaMs, hooks) {
     if (!Number.isFinite(deltaMs) || deltaMs <= 0) {
       return 0;
@@ -17227,12 +17379,46 @@ class RpgCommonMap {
     while (this.physicsAccumulatorMs >= fixedStepMs) {
       this.physicsAccumulatorMs -= fixedStepMs;
       hooks?.beforeStep?.();
+      this.physic.updateMovements();
       const tick = this.physic.stepOneTick();
       executed += 1;
+      this.runPostTickUpdates();
       hooks?.afterStep?.(tick);
     }
     return executed;
   }
+  /**
+   * Force a single physics tick outside of the normal game loop
+   * 
+   * This method is primarily used for **client-side prediction** where the client
+   * needs to immediately simulate physics in response to local input, rather than
+   * waiting for the next game loop tick.
+   * 
+   * ## Use Cases
+   * 
+   * - **Client-side prediction**: Immediately simulate player movement for responsive feel
+   * - **Testing**: Force a physics step in unit tests
+   * - **Special effects**: Immediate physics response for specific game events
+   * 
+   * ## Important
+   * 
+   * This method should NOT be used on the server for normal input processing.
+   * Server-side physics is handled by `runFixedTicks` in the main game loop to ensure
+   * deterministic simulation.
+   * 
+   * @param hooks - Optional callbacks for before/after the physics step
+   * @returns The physics tick number
+   * 
+   * @example
+   * ```ts
+   * // Client-side: immediately simulate predicted movement
+   * class RpgClientMap extends RpgCommonMap {
+   *   stepPredictionTick(): void {
+   *     this.forceSingleTick();
+   *   }
+   * }
+   * ```
+   */
   forceSingleTick(hooks) {
     hooks?.beforeStep?.();
     this.physic.updateMovements();
@@ -17560,22 +17746,60 @@ class RpgCommonMap {
    * Add a character to the physics world
    * @private
    */
+  /**
+   * Add a character entity to the physics world
+   * 
+   * Creates a physics entity for a character (player or NPC) with proper position handling.
+   * The owner's x/y signals represent **top-left** coordinates, while the physics entity
+   * uses **center** coordinates internally.
+   * 
+   * ## Position System
+   * 
+   * - `owner.x()` / `owner.y()` → **top-left** corner of the character's hitbox
+   * - `entity.position` → **center** of the physics collider
+   * - Conversion: `center = topLeft + (size / 2)`
+   * 
+   * @param options - Character configuration
+   * @returns The character's unique ID
+   * 
+   * @example
+   * ```ts
+   * // Player at top-left position (100, 100) with 32x32 hitbox
+   * // Physics entity will be at center (116, 116)
+   * this.addCharacter({
+   *   owner: player,
+   *   x: 116,  // center X (ignored, uses owner.x())
+   *   y: 116,  // center Y (ignored, uses owner.y())
+   *   kind: "hero"
+   * });
+   * ```
+   * 
+   * @private
+   */
   addCharacter(options) {
     if (!options || typeof options.owner?.id !== "string") {
       throw new Error("Character requires an owner object with a string id");
     }
-    const id = options.owner.id;
-    const radius = options.radius ?? 25;
-    const diameter = radius * 2;
-    const topLeftX = options.x - radius;
-    const topLeftY = options.y - radius;
-    const centerX = topLeftX + diameter / 2;
-    const centerY = topLeftY + diameter / 2;
+    const owner = options.owner;
+    const id = owner.id;
+    const hitbox = typeof owner.hitbox === "function" ? owner.hitbox() : owner.hitbox;
+    const width = hitbox?.w ?? 32;
+    const height = hitbox?.h ?? 32;
+    const radius = Math.max(width, height) / 2;
+    const topLeftX = owner.x();
+    const topLeftY = owner.y();
+    const centerX = topLeftX + width / 2;
+    const centerY = topLeftY + height / 2;
     const isStatic = !!options.isStatic;
     const entity = this.physic.createEntity({
       uuid: id,
       position: { x: centerX, y: centerY },
+      // Use radius for circular collision detection
       radius: Math.max(radius, 1),
+      // Also store explicit width/height for consistent position conversions
+      // This ensures getBodyPosition/setBodyPosition use the same dimensions
+      width,
+      height,
       mass: options.mass ?? (isStatic ? Infinity : 1),
       friction: options.friction ?? 0.4,
       linearDamping: isStatic ? 1 : 0.2,
@@ -17587,17 +17811,15 @@ class RpgCommonMap {
     } else {
       entity.unfreeze();
     }
-    entity.owner = options.owner;
+    entity.owner = owner;
     entity.onDirectionChange(({ cardinalDirection }) => {
       if (!("$send" in this)) return;
-      const owner = entity.owner;
-      if (!owner) return;
+      const owner2 = entity.owner;
+      if (!owner2) return;
       if (cardinalDirection === "idle") return;
-      owner.changeDirection(cardinalDirection);
+      owner2.changeDirection(cardinalDirection);
     });
     entity.onMovementChange(({ isMoving, intensity }) => {
-      const owner = entity.owner;
-      if (!owner) return;
       const LOW_INTENSITY_THRESHOLD = 10;
       if (isMoving && intensity > LOW_INTENSITY_THRESHOLD) {
         owner.animationName.set("walk");
@@ -17605,19 +17827,21 @@ class RpgCommonMap {
         owner.animationName.set("stand");
       }
     });
+    const entityWidth = width;
+    const entityHeight = height;
     entity.onPositionChange(({ x, y }) => {
-      const owner = entity.owner;
-      if (!owner) return;
-      const width = entity.width || (entity.radius ? entity.radius * 2 : 32);
-      const height = entity.height || (entity.radius ? entity.radius * 2 : 32);
-      const topLeftX2 = x - width / 2;
-      const topLeftY2 = y - height / 2;
+      const topLeftX2 = x - entityWidth / 2;
+      const topLeftY2 = y - entityHeight / 2;
+      let changed = false;
       if (typeof owner.x === "function" && typeof owner.x.set === "function") {
         owner.x.set(Math.round(topLeftX2));
-        owner.applyFrames?.();
+        changed = true;
       }
       if (typeof owner.y === "function" && typeof owner.y.set === "function") {
         owner.y.set(Math.round(topLeftY2));
+        changed = true;
+      }
+      if (changed) {
         owner.applyFrames?.();
       }
     });
@@ -17700,15 +17924,40 @@ class RpgCommonMap {
   }
   /**
    * Stop movement for a player
+   * 
+   * Completely stops all movement for a player, including:
+   * - Clearing all active movement strategies (dash, linear moves, etc.)
+   * - Setting velocity to zero
+   * - Resetting intended direction
+   * 
+   * This method is particularly useful when changing maps to ensure
+   * the player doesn't carry over movement from the previous map.
+   * 
+   * @param player - The player to stop
+   * @returns True if the player was found and movement was stopped
+   * 
+   * @example
+   * ```ts
+   * // Stop player movement when changing maps
+   * if (mapChanged) {
+   *   map.stopMovement(player);
+   * }
+   * 
+   * // Stop movement when player dies
+   * if (player.isDead()) {
+   *   map.stopMovement(player);
+   * }
+   * ```
    * @protected
    */
   stopMovement(player) {
     const entity = this.physic.getEntityByUUID(player.id);
     if (!entity) return false;
+    this.moveManager.stopMovement(player.id);
     if (typeof player.setIntendedDirection === "function") {
       player.setIntendedDirection(null);
     }
-    entity.setVelocity({ x: 0, y: 0 });
+    player.pendingInputs = [];
     return true;
   }
   /**
@@ -17808,11 +18057,11 @@ class RpgCommonMap {
   setBodyPosition(id, x, y, mode = "center") {
     const entity = this.physic.getEntityByUUID(id);
     if (!entity) return;
+    const width = entity.width || (entity.radius ? entity.radius * 2 : 32);
+    const height = entity.height || (entity.radius ? entity.radius * 2 : 32);
     let centerX = x;
     let centerY = y;
     if (mode === "top-left") {
-      const width = entity.width || (entity.radius ? entity.radius * 2 : 32);
-      const height = entity.height || (entity.radius ? entity.radius * 2 : 32);
       centerX = x + width / 2;
       centerY = y + height / 2;
     }
@@ -19064,7 +19313,7 @@ function WithMoveManager(Base) {
       staticTarget.freeze();
       map.moveManager.add(
         this.id,
-        new SeekAvoid(engine, () => staticTarget, 3, 50, 5)
+        new SeekAvoid(engine, () => staticTarget, 80, 140, 80, 48)
       );
     }
     /**
@@ -22376,7 +22625,10 @@ const _RpgPlayer = class _RpgPlayer extends BasicPlayerMixins(RpgCommonPlayer) {
   async teleport(positions) {
     if (!this.map) return false;
     if (this.map.physic) {
-      this.map.physic.updateHitbox(this.id, positions.x, positions.y, void 0, void 0, true);
+      const entity = this.map.physic.getEntityByUUID(this.id);
+      if (entity) {
+        this.map.physic.teleport(entity, { x: positions.x, y: positions.y });
+      }
     } else {
       this.x.set(positions.x);
       this.y.set(positions.y);
@@ -25957,7 +26209,6 @@ let RpgMap = class extends RpgCommonMap {
     player._onInit();
     this.dataIsReady$.pipe(
       finalize$1(() => {
-        player.applyFrames();
         this.hooks.callHooks("server-player-onJoinMap", player, this).subscribe();
       })
     ).subscribe();
@@ -26077,8 +26328,16 @@ let RpgMap = class extends RpgCommonMap {
    * This method processes all pending inputs for a player while performing
    * anti-cheat validation to prevent time manipulation and frame skipping.
    * It validates the time deltas between inputs and ensures they are within
-   * acceptable ranges. After processing, it saves the last frame position
-   * for use in packet interception.
+   * acceptable ranges.
+   * 
+   * ## Architecture
+   * 
+   * **Important**: This method only updates entity velocities - it does NOT step
+   * the physics engine. Physics simulation is handled centrally by the game loop
+   * (`tick$` -> `runFixedTicks`). This ensures:
+   * - Consistent physics timing (60fps fixed timestep)
+   * - No double-stepping when multiple inputs are processed
+   * - Deterministic physics regardless of input frequency
    * 
    * @param playerId - The ID of the player to process inputs for
    * @param controls - Optional anti-cheat configuration
@@ -26160,7 +26419,6 @@ let RpgMap = class extends RpgCommonMap {
       lastProcessedFrame = input.frame;
     }
     if (hasProcessedInputs) {
-      this.forceSingleTick();
       player.lastProcessedInputTs = lastProcessedTime;
     } else {
       const idleTimeout = Math.max(config.minTimeBetweenInputs * 4, 50);
@@ -26170,7 +26428,6 @@ let RpgMap = class extends RpgCommonMap {
         player.lastProcessedInputTs = 0;
       }
     }
-    player.applyFrames();
     return {
       player,
       inputs: processedInputs
@@ -26307,7 +26564,6 @@ let RpgMap = class extends RpgCommonMap {
     eventInstance.context = context$1;
     eventInstance.x.set(x);
     eventInstance.y.set(y);
-    eventInstance.applyFrames();
     if (event.name) eventInstance.name.set(event.name);
     this.events()[id] = eventInstance;
     await eventInstance.execMethod("onInit");