@rpgjs/server 5.0.0-alpha.16 → 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()
@@ -14274,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)
@@ -14292,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();
     }
   }
   /**
@@ -17123,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);
      * });
      * ```
      */
@@ -17304,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;
@@ -17314,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();
@@ -17647,23 +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 owner = options.owner;
     const id = owner.id;
-    const radius = owner.hitbox?.w ?? options.radius ?? 25;
-    const diameter = radius * 2;
-    const topLeftX = owner.x() - radius;
-    const topLeftY = owner.y() - radius;
-    const centerX = topLeftX + diameter / 2;
-    const centerY = topLeftY + diameter / 2;
+    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,
@@ -17691,17 +17827,21 @@ class RpgCommonMap {
         owner.animationName.set("stand");
       }
     });
+    const entityWidth = width;
+    const entityHeight = height;
     entity.onPositionChange(({ x, y }) => {
-      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?.();
       }
     });
@@ -17917,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;
     }
@@ -19173,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)
       );
     }
     /**
@@ -26069,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();
@@ -26189,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
@@ -26272,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);
@@ -26282,7 +26428,6 @@ let RpgMap = class extends RpgCommonMap {
         player.lastProcessedInputTs = 0;
       }
     }
-    player.applyFrames();
     return {
       player,
       inputs: processedInputs
@@ -26419,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");