@rpgjs/common 5.0.0-alpha.4 → 5.0.0-alpha.41

package/src/rooms/Map.ts

@@ -1,18 +1,170 @@
 import { generateShortUUID, users } from "@signe/sync";
 import { effect, Signal, signal } from "@signe/reactive";
 import { Direction, RpgCommonPlayer } from "../Player";
-import { RpgCommonPhysic } from "../Physic";
-import { Observable, share, Subject } from "rxjs";
-import { Knockback, LinearMove, MovementManager } from "../movement";
+import {
+  PhysicsEngine,
+  Vector2,
+  Entity,
+  EntityState,
+  assignPolygonCollider,
+  AABB,
+  createCollider,
+} from "@rpgjs/physic";
+import { combineLatest, Observable, share, Subject, Subscription } from "rxjs";
+import { MovementManager } from "../movement";
+import { WorldMapsManager, type RpgWorldMaps } from "./WorldMaps";
+
+export type PhysicsEntityKind = "hero" | "npc" | "generic";
+
+export interface MapPhysicsInitContext {
+  mapData: any;
+}
+
+export interface MapPhysicsEntityContext {
+  owner: any;
+  entity: Entity;
+  kind: PhysicsEntityKind;
+}
+
+interface ZoneOptions {
+  x?: number;
+  y?: number;
+  radius: number;
+  angle?: number;
+  direction?: "up" | "down" | "left" | "right";
+  linkedTo?: string;
+  limitedByWalls?: boolean;
+}
 
 export abstract class RpgCommonMap<T extends RpgCommonPlayer> {
   abstract players: Signal<Record<string, T>>;
   abstract events: Signal<Record<string, any>>;
-  
+
   data = signal<any | null>(null);
-  physic = new RpgCommonPhysic();
-  moveManager = new MovementManager()
+  physic = new PhysicsEngine({
+    timeStep: 1 / 60,
+    gravity: new Vector2(0, 0),
+    enableSleep: false,
+  });
+  moveManager = new MovementManager(() => this.physic);
+
+  private speedScalar = 50; // Default speed scalar for movement
+
+  // World Maps properties
+  tileWidth: number = 32;
+  tileHeight: number = 32;
+  worldMapsManager?: WorldMapsManager;
+
+  // Synchronization throttling properties
+  throttleSync?: number;
+  throttleStorage?: number;
+  sessionExpiryTime?: number;
+
+  tickSubscription?: Subscription | null;
+  playersSubscription?: Subscription | null;
+  eventsSubscription?: Subscription | null;
+  private physicsAccumulatorMs = 0;
+  private physicsSyncDepth = 0;
+
+  /**
+   * Whether to automatically subscribe to tick$ for physics updates
+   * Set to false in test environments for manual control with nextTick()
+   */
+  protected autoTickEnabled: boolean = true;
+
+  get isStandalone() {
+    return typeof window !== 'undefined'
+  }
+  
+
+  /**
+   * Get the width of the map in pixels
+   * 
+   * @returns The width of the map in pixels, or 0 if not loaded
+   * 
+   * @example
+   * ```ts
+   * const width = map.widthPx;
+   * console.log(`Map width: ${width}px`);
+   * ```
+   */
+  get widthPx(): number {
+    return this.data()?.width ?? 0
+  }
+
+  /**
+   * Get the height of the map in pixels
+   * 
+   * @returns The height of the map in pixels, or 0 if not loaded
+   * 
+   * @example
+   * ```ts
+   * const height = map.heightPx;
+   * console.log(`Map height: ${height}px`);
+   * ```
+   */
+  get heightPx(): number {
+    return this.data()?.height ?? 0
+  }
+
+  /**
+   * Get the unique identifier of the map
+   * 
+   * @returns The map ID, or empty string if not loaded
+   * 
+   * @example
+   * ```ts
+   * const mapId = map.id;
+   * console.log(`Current map: ${mapId}`);
+   * ```
+   */
+  get id(): string {
+    return this.data()?.id ?? ''
+  }
 
+    /**
+   * Get the X position of this map in the world coordinate system
+   * 
+   * This is used when maps are part of a larger world map. The world position
+   * indicates where this map is located relative to other maps.
+   * 
+   * @returns The X position in world coordinates, or 0 if not in a world
+   * 
+   * @example
+   * ```ts
+   * const worldX = map.worldX;
+   * console.log(`Map is at world position (${worldX}, ${map.worldY})`);
+   * ```
+   */
+    get worldX(): number {
+      const worldMaps = this.getWorldMapsManager?.();
+      if (!worldMaps) return 0;
+      // Extract real map ID (remove "map-" prefix if present)
+      const mapId = this.id.startsWith('map-') ? this.id.slice(4) : this.id;
+      return worldMaps.getMapInfo(mapId)?.worldX ?? 0
+    }
+    
+    /**
+     * Get the Y position of this map in the world coordinate system
+     * 
+     * This is used when maps are part of a larger world map. The world position
+     * indicates where this map is located relative to other maps.
+     * 
+     * @returns The Y position in world coordinates, or 0 if not in a world
+     * 
+     * @example
+     * ```ts
+     * const worldY = map.worldY;
+     * console.log(`Map is at world position (${map.worldX}, ${worldY})`);
+     * ```
+     */
+    get worldY(): number {
+      const worldMaps = this.getWorldMapsManager?.();
+      if (!worldMaps) return 0;
+      // Extract real map ID (remove "map-" prefix if present)
+      const mapId = this.id.startsWith('map-') ? this.id.slice(4) : this.id;
+      return worldMaps.getMapInfo(mapId)?.worldY ?? 0
+    }
 
   /**
    * Observable representing the game loop tick
@@ -21,12 +173,33 @@ export abstract class RpgCommonMap<T extends RpgCommonPlayer> {
    * 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);
    * });
    * ```
    */
@@ -42,76 +215,243 @@ export abstract class RpgCommonMap<T extends RpgCommonPlayer> {
     share()
   );
 
+  /**
+   * Clear all physics content and reset to initial state
+   * 
+   * This method completely clears the physics system by:
+   * - Removing all hitboxes (static and movable)
+   * - Removing all zones
+   * - Clearing all collision data and events
+   * - Clearing all movement events and sliding data
+   * - Unsubscribing from the tick subscription
+   * - Resetting the physics engine to a clean state
+   * 
+   * Use this method when you need to completely reset the map's physics
+   * system, such as when changing maps or restarting a level.
+   * 
+   * @example
+   * ```ts
+   * // Clear all physics when changing maps
+   * map.clearPhysic();
+   * 
+   * // Then reload physics for the new map
+   * map.loadPhysic();
+   * ```
+   */
+  clearPhysic() {
+    // Unsubscribe from tick to stop physics updates
+    if (this.tickSubscription) {
+      this.tickSubscription.unsubscribe();
+      this.tickSubscription = null;
+    }
+
+    if (this.playersSubscription) {
+      this.playersSubscription.unsubscribe();
+      this.playersSubscription = null;
+    }
+
+    if (this.eventsSubscription) {
+      this.eventsSubscription.unsubscribe();
+      this.eventsSubscription = null;
+    }
+
+    // Clear all hitboxes and zones from physics system
+    this.clearAll();
+
+    // Reset movement manager
+    this.moveManager.clearAll();
+    this.emitPhysicsReset();
+
+    this.physicsAccumulatorMs = 0;
+  }
+
+  /**
+   * Clear all physics entities and internal state
+   * @private
+   */
+  private clearAll(): void {
+    // Remove all entities from physics engine
+    const entities = this.physic.getEntities();
+    for (const entity of entities) {
+      const owner = (entity as any).owner;
+      if (owner) {
+        this.emitPhysicsEntityRemove({
+          owner,
+          entity,
+          kind: this.resolvePhysicsEntityKind(owner, entity.uuid),
+        });
+      }
+      this.physic.removeEntity(entity);
+    }
+
+    // Clear movement manager and zone manager
+    this.physic.getMovementManager().clearAll();
+    this.physic.getZoneManager().clear();
+  }
+
   loadPhysic() {
-    const hitboxes = this.data().hitboxes ?? [];
+    this.clearPhysic();
+
+    const mapData = this.data?.();
+    const mapWidth = typeof mapData?.width === "number" ? mapData.width : 0;
+    const mapHeight = typeof mapData?.height === "number" ? mapData.height : 0;
+    const hitboxes: Array<
+      | { id?: string; x: number; y: number; width: number; height: number }
+      | { id?: string; points: number[][] }
+    > = Array.isArray(mapData?.hitboxes) ? mapData.hitboxes : [];
 
-    const gap = 100;
-    this.physic.addStaticHitbox('map-width-left', -gap, 0, gap, this.data().height);
-    this.physic.addStaticHitbox('map-width-right', this.data().width, 0, gap, this.data().height);
-    this.physic.addStaticHitbox('map-height-top', 0, -gap, this.data().width, gap);
-    this.physic.addStaticHitbox('map-height-bottom', 0, this.data().height, this.data().width, gap);
+    if (mapWidth > 0 && mapHeight > 0) {
+      const gap = 100;
+      this.addStaticHitbox('map-width-left', -gap, 0, gap, mapHeight);
+      this.addStaticHitbox('map-width-right', mapWidth, 0, gap, mapHeight);
+      this.addStaticHitbox('map-height-top', 0, -gap, mapWidth, gap);
+      this.addStaticHitbox('map-height-bottom', 0, mapHeight, mapWidth, gap);
+    }
 
     for (let staticHitbox of hitboxes) {
-      this.physic.addStaticHitbox(staticHitbox.id ?? generateShortUUID(), staticHitbox.x, staticHitbox.y, staticHitbox.width, staticHitbox.height);
+      if ('x' in staticHitbox) {
+        this.addStaticHitbox(staticHitbox.id ?? generateShortUUID(), staticHitbox.x, staticHitbox.y, staticHitbox.width, staticHitbox.height);
+      }
+      else if ('points' in staticHitbox) {
+        this.addStaticHitbox(staticHitbox.id ?? generateShortUUID(), staticHitbox.points);
+      }
     }
 
-    this.events.observable.subscribe(({ value: event, type }) => {
-      if (type == 'add') {
-        this.physic.addMovableHitbox(event, event.x(), event.y(), event.hitbox().w, event.hitbox().h, {
-          isSensor: true
+    this.emitPhysicsInit({ mapData });
+
+    this.playersSubscription = (this.players as any).observable.subscribe(
+      ({ value: player, type, key }: any) => {
+        if (type === "remove") {
+          this.removeHitbox(key, player, "hero");
+          return;
+        }
+
+        if (type == 'reset') {
+          if (!player) return;
+          for (let id in player) {
+            const _player = player[id]
+            _player.id = _player.id ?? id;
+            this.createCharacterHitbox(_player, "hero");
+          }
+          return;
+        }
+
+        if (!player) return;
+        if (type === "add") {
+          player.id = key;
+          this.createCharacterHitbox(player, "hero");
+        } else if (type === "update") {
+          player.id = player.id ?? key;
+          if (!this.getBody(key)) {
+            this.createCharacterHitbox(player, "hero");
+            return;
+          }
+          if (this.isPhysicsSyncingSignals) {
+            return;
+          }
+          this.updateCharacterHitbox(player);
+        }
+      },
+    );
+
+    this.eventsSubscription = this.events.observable.subscribe(({ value: event, type, key }) => {
+      if (type === "add") {
+        event.id = key;
+        this.createCharacterHitbox(event, "npc", {
+          mass: 100,
         });
-        this.physic.registerMovementEvents(event.id, () => {
-          event.animationName.set('walk')
-        }, () => {
-          event.animationName.set('stand')
-        })
-      }
-      else if (type == 'remove') {
-        this.physic.removeHitbox(event.id);
+      } else if (type === "remove") {
+        // Clean up movement event subscriptions
+        const eventObj = this.getObjectById(key);
+        if (eventObj && typeof (eventObj as any)._movementUnsubscribe === 'function') {
+          (eventObj as any)._movementUnsubscribe();
+        }
+        this.removeHitbox(key, event, "npc");
+      } else if (type === "update") {
+        event.id = event.id ?? key;
+        if (!this.getBody(key)) {
+          this.createCharacterHitbox(event, "npc", {
+            mass: 100,
+          });
+          return;
+        }
+        this.updateCharacterHitbox(event);
+      } else if (type === "reset") {
+        for (const id in event) {
+          const _event = event[id];
+          if (!_event) continue;
+          _event.id = _event.id ?? id;
+          this.createCharacterHitbox(_event, "npc", {
+            mass: 100,
+          });
+        }
       }
     });
 
-    this.tick$.subscribe(({ delta }) => {
-      this.physic.update(delta);
-      this.moveManager.update(delta, this.physic);
-    });
-  }
+    // Hydrate physics world with already-loaded scene objects.
+    // This covers cases where sync state is present before subscriptions are attached.
+    const players = this.players();
+    for (const id in players) {
+      const player = players[id];
+      if (!player) continue;
+      player.id = player.id ?? id;
+      this.createCharacterHitbox(player, "hero");
+    }
 
-  movePlayer(player: T, direction: Direction) {
-    this.physic.moveBody(player, direction);
+    const events = this.events();
+    for (const id in events) {
+      const event = events[id];
+      if (!event) continue;
+      event.id = event.id ?? id;
+      this.createCharacterHitbox(event, "npc", {
+        mass: 100,
+      });
+    }
+
+    // S'abonner au ticker automatique seulement si autoTickEnabled est true
+    if (this.autoTickEnabled) {
+      this.tickSubscription = this.tick$.subscribe(({ delta }) => {
+        this.runFixedTicks(delta);
+      });
+    }
   }
 
-  /**
-   * Register movement events for a player or event
-   * 
-   * Attaches event listeners to detect when an entity starts or stops moving
-   * 
-   * @param id - ID of the entity (player or event)
-   * @param onStartMoving - Callback when entity starts moving
-   * @param onStopMoving - Callback when entity stops moving
-   * @returns Boolean indicating success
-   * 
-   * @example
-   * ```ts
-   * // Register movement events for the player
-   * map.registerMovementEvents('player1', 
-   *   () => console.log('Player started moving'),
-   *   () => console.log('Player stopped moving')
-   * );
-   * ```
-   */
-  registerMovementEvents(
-    id: string,
-    onStartMoving?: () => void,
-    onStopMoving?: () => void
-  ): boolean {
-    // Check if the object with this ID exists
-    const object = this.getObjectById(id);
-    if (!object) return false;
+  async movePlayer(player: T, direction: Direction) {
+    // Calculate next position before movement
+    const currentX = player.x();
+    const currentY = player.y();
+    const speed = player.speed();
+
+    let nextX = currentX;
+    let nextY = currentY;
     
-    // Register with physics system
-    this.physic.registerMovementEvents(id, onStartMoving, onStopMoving);
-    return true;
+    switch (direction) {
+      case Direction.Left:
+        nextX = currentX - speed;
+        break;
+      case Direction.Right:
+        nextX = currentX + speed;
+        break;
+      case Direction.Up:
+        nextY = currentY - speed;
+        break;
+      case Direction.Down:
+        nextY = currentY + speed;
+        break;
+    }
+
+    player.changeDirection(direction);
+
+     // Check for automatic map change if the method exists
+    if (typeof (player as any).autoChangeMap === 'function' && !player.isEvent()) {
+      const mapChanged = await (player as any).autoChangeMap({ x: nextX, y: nextY }, direction);
+      if (mapChanged) {
+       this.stopMovement(player);
+       return
+      }
+    }
+    
+    this.moveBody(player, direction);
   }
 
   /**
@@ -129,7 +469,7 @@ export abstract class RpgCommonMap<T extends RpgCommonPlayer> {
    * ```
    */
   isMoving(id: string): boolean {
-    return this.physic.isMoving(id);
+    return this.isEntityMoving(id);
   }
 
   getObjectById(id: string) {
@@ -137,121 +477,483 @@ export abstract class RpgCommonMap<T extends RpgCommonPlayer> {
   }
 
   /**
-   * Create a temporary and moving hitbox on the map
+   * Execute physics simulation with fixed timestep
    * 
-   * Allows to create a temporary hitbox that moves through multiple positions sequentially.
-   * For example, you can use it to explode a bomb and find all the affected players, 
-   * or during a sword strike, you can create a moving hitbox and find the affected players.
+   * 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
    * 
-   * The method creates a zone sensor that moves through the specified hitbox positions
-   * at the given speed, detecting collisions with players and events at each step.
+   * ## Architecture
    * 
-   * @param hitboxes - Array of hitbox positions to move through sequentially
-   * @param options - Configuration options for the movement
-   * @returns Observable that emits arrays of hit entities and completes when movement is finished
+   * 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
-   * // Create a sword slash effect that moves through two positions
-   * map.createMovingHitbox([
-   *   { x: 100, y: 100, width: 50, height: 50 },
-   *   { x: 120, y: 100, width: 50, height: 50 }
-   * ], { speed: 2 }).subscribe({
-   *   next(hits) {
-   *     // hits contains RpgPlayer or RpgEvent objects that were hit
-   *     console.log('Hit entities:', hits);
-   *   },
-   *   complete() {
-   *     console.log('Movement finished');
-   *   }
+   * // 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`)
    * });
    * ```
    */
-  createMovingHitbox(
-    hitboxes: Array<{ x: number; y: number; width: number; height: number }>,
-    options: { speed?: number } = {}
-  ): Observable<(T | any)[]> {
-    const { speed = 1 } = options;
-    const zoneId = `moving_hitbox_${generateShortUUID()}`;
-    
-    return new Observable(observer => {
-      if (hitboxes.length === 0) {
-        observer.complete();
-        return;
-      }
+  protected runFixedTicks(
+    deltaMs: number,
+    hooks?: {
+      beforeStep?: () => void;
+      afterStep?: (tick: number) => void;
+    },
+  ): number {
+    if (!Number.isFinite(deltaMs) || deltaMs <= 0) {
+      return 0;
+    }
 
-      let currentIndex = 0;
-      let frameCounter = 0;
-      const hitEntities = new Set<string>();
+    const fixedStepMs = this.physic.getWorld().getTimeStep() * 1000;
+    this.physicsAccumulatorMs += deltaMs;
+    let executed = 0;
 
-      // Create initial zone at first hitbox position
-      const firstHitbox = hitboxes[0];
-      const radius = Math.max(firstHitbox.width, firstHitbox.height) / 2;
+    while (this.physicsAccumulatorMs >= fixedStepMs) {
+      this.physicsAccumulatorMs -= fixedStepMs;
+      hooks?.beforeStep?.();
       
-      this.physic.addZone(zoneId, {
-        x: firstHitbox.x + firstHitbox.width / 2,
-        y: firstHitbox.y + firstHitbox.height / 2,
-        radius: radius
+      // Update movements before physics step (applies velocity changes from inputs)
+      this.physic.updateMovements();
+      
+      const tick = this.physic.stepOneTick();
+      executed += 1;
+      
+      // Run post-tick updates (zones, position sync callbacks)
+      this.runPostTickUpdates();
+      
+      hooks?.afterStep?.(tick);
+    }
+
+    return executed;
+  }
+
+  /**
+   * Manually trigger a single game tick
+   * 
+   * This method allows you to manually advance the game by one tick (16ms at 60fps).
+   * It's primarily useful for testing where you need precise control over when
+   * physics updates occur, rather than relying on the automatic tick$ subscription.
+   * 
+   * ## Use Cases
+   * 
+   * - **Testing**: Control exactly when physics steps occur in unit tests
+   * - **Manual control**: Step through game state manually for debugging
+   * - **Deterministic testing**: Ensure consistent timing in test scenarios
+   * 
+   * ## Important
+   * 
+   * This method should NOT be used in production code alongside the automatic `tick$`
+   * subscription, as it will cause double-stepping. Use either:
+   * - Automatic ticks (via `loadPhysic()` which subscribes to `tick$`)
+   * - Manual ticks (via `nextTick()` without `loadPhysic()` subscription)
+   * 
+   * @param deltaMs - Optional delta time in milliseconds (default: 16ms for 60fps)
+   * @returns Number of physics ticks executed
+   * 
+   * @example
+   * ```ts
+   * // In tests: manually advance game by one tick
+   * map.nextTick(); // Advances by 16ms (one frame at 60fps)
+   * 
+   * // With custom delta
+   * map.nextTick(32); // Advances by 32ms (two frames at 60fps)
+   * 
+   * // In a test loop
+   * for (let i = 0; i < 60; i++) {
+   *   map.nextTick(); // Simulate 1 second of game time
+   * }
+   * ```
+   */
+  nextTick(deltaMs: number = 16): number {
+    return this.runFixedTicks(deltaMs);
+  }
+
+  /**
+   * 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();
+   *   }
+   * }
+   * ```
+   */
+  protected forceSingleTick(hooks?: { beforeStep?: () => void; afterStep?: (tick: number) => void }): number {
+    hooks?.beforeStep?.();
+    this.physic.updateMovements();
+    const tick = this.physic.stepOneTick();
+    this.runPostTickUpdates();
+    hooks?.afterStep?.(tick);
+    const fixedMs = this.physic.getWorld().getTimeStep() * 1000;
+    this.physicsAccumulatorMs = Math.max(0, this.physicsAccumulatorMs - fixedMs);
+    return tick;
+  }
+
+  private createCharacterHitbox(
+    owner: any,
+    kind: PhysicsEntityKind,
+    options?: { isStatic?: boolean; mass?: number },
+  ): void {
+    if (!owner?.id) {
+      return;
+    }
+    const existingEntity = this.physic.getEntityByUUID(owner.id);
+    if (existingEntity) {
+      // Rebind owner when the player instance is restored/replaced (e.g. map transfer).
+      // Position sync callbacks read entity.owner at runtime.
+      (existingEntity as any).owner = owner;
+      this.updateCharacterHitbox(owner);
+      return;
+    }
+
+    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;
+    this.addCharacter({
+      owner,
+      radius,
+      kind,
+      maxSpeed: owner.speed(),
+      collidesWithCharacters: !this.shouldDisableCharacterCollisions(owner),
+      isStatic: options?.isStatic,
+      mass: options?.mass,
+    });
+    const entity = this.getBody(owner.id);
+    if (entity) {
+      this.emitPhysicsEntityAdd({
+        owner,
+        entity,
+        kind,
       });
+    }
+  }
 
-      // Register zone events to detect hits
-      this.physic.registerZoneEvents(
-        zoneId,
-        (hitIds: string[]) => {
-          // Convert hit IDs to actual objects and emit
-          const hitObjects = hitIds
-            .map(id => this.getObjectById(id))
-            .filter(obj => obj !== undefined);
-          
-          if (hitObjects.length > 0) {
-            // Track hit entities to avoid duplicates
-            hitIds.forEach(id => hitEntities.add(id));
-            observer.next(hitObjects);
-          }
+  private updateCharacterHitbox(owner: any): void {
+    if (!owner?.id) return;
+    const entity = this.physic.getEntityByUUID(owner.id);
+    if (!entity) return;
+
+    // Rebind owner on every update to keep physics callbacks attached to the
+    // current player instance after room/session transfers.
+    (entity as any).owner = owner;
+
+    const hitbox = typeof owner.hitbox === "function" ? owner.hitbox() : owner.hitbox;
+    const width = hitbox?.w ?? 32;
+    const height = hitbox?.h ?? 32;
+    const topLeftX = this.resolveNumeric(owner.x);
+    const topLeftY = this.resolveNumeric(owner.y);
+    this.updateHitbox(owner.id, topLeftX, topLeftY, width, height);
+    this.setCharacterCollisionEnabled(owner.id, !this.shouldDisableCharacterCollisions(owner));
+  }
+
+  private resolveNumeric(source: any, fallback = 0): number {
+    if (typeof source === "function") {
+      try {
+        return Number(source()) ?? fallback;
+      } catch {
+        return fallback;
+      }
+    }
+    if (typeof source === "number") {
+      return source;
+    }
+    return fallback;
+  }
+
+  private shouldDisableCharacterCollisions(owner: any): boolean {
+    if (typeof owner._through === "function") {
+      try {
+        return !!owner._through();
+      } catch {
+        return false;
+      }
+    }
+    if (typeof owner.through === "boolean") {
+      return owner.through;
+    }
+    return false;
+  }
+
+  private resolvePhysicsEntityKind(owner: any, id?: string): PhysicsEntityKind {
+    if (typeof owner?.isEvent === "function") {
+      try {
+        if (owner.isEvent()) {
+          return "npc";
         }
-      );
+      } catch {
+        // Ignore owner inspection errors and fallback below
+      }
+    }
+
+    const ownerId = typeof owner?.id === "string" ? owner.id : id;
+    if (ownerId && this.players()?.[ownerId]) {
+      return "hero";
+    }
+    if (ownerId && this.events()?.[ownerId]) {
+      return "npc";
+    }
+    return "generic";
+  }
+
+  protected emitPhysicsInit(_context: MapPhysicsInitContext): void {}
+
+  protected emitPhysicsEntityAdd(_context: MapPhysicsEntityContext): void {}
+
+  protected emitPhysicsEntityRemove(_context: MapPhysicsEntityContext): void {}
+
+  protected emitPhysicsReset(): void {}
+
+  protected withPhysicsSync<T>(run: () => T): T {
+    this.physicsSyncDepth += 1;
+    try {
+      return run();
+    } finally {
+      this.physicsSyncDepth -= 1;
+    }
+  }
+
+  protected get isPhysicsSyncingSignals(): boolean {
+    return this.physicsSyncDepth > 0;
+  }
+
+  /**
+   * Get the world maps manager
+   * 
+   * @returns WorldMapsManager instance or null if not configured
+   * 
+   * @example
+   * ```ts
+   * const worldMaps = map.getWorldMapsManager();
+   * if (worldMaps) {
+   *   const adjacentMaps = worldMaps.getAdjacentMaps(currentMap, coordinates);
+   * }
+   * ```
+   */
+  getWorldMapsManager(): WorldMapsManager | null {
+    return this.worldMapsManager ?? null;
+  }
+
+  /**
+   * Get attached World
+   * 
+   * Recover the world attached to this map (undefined if no world attached)
+   * 
+   * @since 3.0.0-beta.8
+   * @returns {RpgWorldMaps | undefined} The world maps manager instance if attached, otherwise undefined
+   * 
+   * @example
+   * ```ts
+   * const world = map.getInWorldMaps();
+   * if (world) {
+   *   console.log(world.getAllMaps());
+   * }
+   * ```
+   */
+  getInWorldMaps(): RpgWorldMaps | undefined {
+    return this.worldMapsManager ?? undefined;
+  }
+
+  /**
+   * Remove this map from the world
+   * 
+   * Remove this map from the world
+   * 
+   * @since 3.0.0-beta.8
+   * @returns {boolean | undefined} True if removed, false if not found, undefined if no world attached
+   * 
+   * @example
+   * ```ts
+   * const removed = map.removeFromWorldMaps();
+   * ```
+   */
+  removeFromWorldMaps(): boolean | undefined {
+    if (!this.worldMapsManager) return undefined;
+    const id = (this as any).id as string | undefined;
+    if (!id) return false;
+    return this.worldMapsManager.removeMap(id);
+  }
+
+  /**
+   * Assign the map to a world
+   * 
+   * Assign the map to a world
+   * 
+   * @since 3.0.0-beta.8
+   * @param {RpgWorldMaps} worldMap world maps
+   * @returns {void}
+   * 
+   * @example
+   * ```ts
+   * const world = new WorldMapsManager();
+   * world.configure([{ id: 'm1', worldX: 0, worldY: 0, width: 1024, height: 1024 }]);
+   * map.setInWorldMaps(world);
+   * ```
+   */
+  setInWorldMaps(worldMap: RpgWorldMaps): void {
+    this.worldMapsManager = worldMap;
+  }
+
+  
+
+  /**
+   * Create a temporary and moving hitbox on the map
+   * 
+   * Allows to create a temporary hitbox that moves through multiple positions sequentially.
+   * For example, you can use it to explode a bomb and find all the affected players, 
+   * or during a sword strike, you can create a moving hitbox and find the affected players.
+   * 
+   * The method creates a zone sensor that moves through the specified hitbox positions
+   * at the given speed, detecting collisions with players and events at each step.
+   * 
+   * @param hitboxes - Array of hitbox positions to move through sequentially
+   * @param options - Configuration options for the movement
+   * @returns Observable that emits arrays of hit entities and completes when movement is finished
+   * 
+   * @example
+   * ```ts
+   * // Create a sword slash effect that moves through two positions
+   * map.createMovingHitbox([
+   *   { x: 100, y: 100, width: 50, height: 50 },
+   *   { x: 120, y: 100, width: 50, height: 50 }
+   * ], { speed: 2 }).subscribe({
+   *   next(hits) {
+   *     // hits contains RpgPlayer or RpgEvent objects that were hit
+   *     console.log('Hit entities:', hits);
+   *   },
+   *   complete() {
+   *     console.log('Movement finished');
+   *   }
+   * });
+   * ```
+   */
+  createMovingHitbox(
+    hitboxes: Array<{ x: number; y: number; width: number; height: number }>,
+    options: { speed?: number } = {}
+  ): Observable<(T | any)[]> {
+    const { speed = 1 } = options;
+    const zoneId = `moving_hitbox_${generateShortUUID()}`;
+
+    return new Observable(observer => {
+      if (hitboxes.length === 0) {
+        observer.complete();
+        return;
+      }
+
+      let currentIndex = 0;
+      let frameCounter = 0;
+      const hitEntities = new Set<string>();
+
+      // Create initial zone at first hitbox position
+      const firstHitbox = hitboxes[0];
+      const radius = Math.max(firstHitbox.width, firstHitbox.height) / 2;
+
+      this.addZone(zoneId, {
+        x: firstHitbox.x + firstHitbox.width / 2,
+        y: firstHitbox.y + firstHitbox.height / 2,
+        radius: radius
+      });
+
+      // Register zone events to detect hits
+      this.registerZoneEvents(
+        zoneId,
+        (hitIds: string[]) => {
+          // Convert hit IDs to actual objects and emit
+          const hitObjects = hitIds
+            .map(id => this.getObjectById(id))
+            .filter(obj => obj !== undefined);
+
+          if (hitObjects.length > 0) {
+            // Track hit entities to avoid duplicates
+            hitIds.forEach(id => hitEntities.add(id));
+            observer.next(hitObjects);
+          }
+        }
+      );
 
       // Subscribe to tick to handle movement
       const tickSubscription = this.tick$.subscribe(() => {
         frameCounter++;
-        
+
         // Move to next position based on speed
         if (frameCounter >= speed) {
           frameCounter = 0;
           currentIndex++;
-          
+
           // Check if we've reached the end
           if (currentIndex >= hitboxes.length) {
             // Clean up and complete
-            this.physic.removeZone(zoneId);
+            this.removeZone(zoneId);
             tickSubscription.unsubscribe();
             observer.complete();
             return;
           }
-          
+
           // Move zone to next position
           const nextHitbox = hitboxes[currentIndex];
-          const zone = this.physic.getZone(zoneId);
-          
+          const zone = this.getZone(zoneId);
+
           if (zone) {
             // Remove current zone and create new one at next position
-            this.physic.removeZone(zoneId);
-            
+            this.removeZone(zoneId);
+
             const newRadius = Math.max(nextHitbox.width, nextHitbox.height) / 2;
-            this.physic.addZone(zoneId, {
+            this.addZone(zoneId, {
               x: nextHitbox.x + nextHitbox.width / 2,
               y: nextHitbox.y + nextHitbox.height / 2,
               radius: newRadius
             });
-            
+
             // Re-register zone events for the new zone
-            this.physic.registerZoneEvents(
+            this.registerZoneEvents(
               zoneId,
               (hitIds: string[]) => {
                 const hitObjects = hitIds
                   .map(id => this.getObjectById(id))
                   .filter(obj => obj !== undefined);
-                
+
                 if (hitObjects.length > 0) {
                   hitIds.forEach(id => hitEntities.add(id));
                   observer.next(hitObjects);
@@ -265,8 +967,792 @@ export abstract class RpgCommonMap<T extends RpgCommonPlayer> {
       // Cleanup function
       return () => {
         tickSubscription.unsubscribe();
-        this.physic.removeZone(zoneId);
+        this.removeZone(zoneId);
       };
     });
   }
+
+  /**
+   * Add a static hitbox to the physics world
+   * @private
+   */
+  private addStaticHitbox(
+    id: string,
+    xOrPoints: number | number[][],
+    y?: number,
+    width?: number,
+    height?: number,
+  ): string {
+    // Check if entity already exists
+    if (this.physic.getEntityByUUID(id)) {
+      throw new Error(`Hitbox with id ${id} already exists`);
+    }
+
+    let entity: Entity;
+    let boxWidth: number;
+    let boxHeight: number;
+
+    if (Array.isArray(xOrPoints)) {
+      const points = xOrPoints;
+      if (points.length < 3) {
+        throw new Error(`Polygon must have at least 3 points, got ${points.length}`);
+      }
+
+      let minX = Number.POSITIVE_INFINITY;
+      let minY = Number.POSITIVE_INFINITY;
+      let maxX = Number.NEGATIVE_INFINITY;
+      let maxY = Number.NEGATIVE_INFINITY;
+
+      for (const point of points) {
+        if (!Array.isArray(point) || point.length !== 2 || typeof point[0] !== "number" || typeof point[1] !== "number") {
+          throw new Error(`Invalid point ${JSON.stringify(point)}. Expected [x, y].`);
+        }
+        minX = Math.min(minX, point[0]);
+        maxX = Math.max(maxX, point[0]);
+        minY = Math.min(minY, point[1]);
+        maxY = Math.max(maxY, point[1]);
+      }
+
+      const centerX = (minX + maxX) / 2;
+      const centerY = (minY + maxY) / 2;
+      boxWidth = Math.max(maxX - minX, 1);
+      boxHeight = Math.max(maxY - minY, 1);
+
+      entity = this.physic.createEntity({
+        uuid: id,
+        position: { x: centerX, y: centerY },
+        width: boxWidth,
+        height: boxHeight,
+        mass: Infinity,
+        state: EntityState.Static,
+        restitution: 0
+      });
+      entity.freeze();
+
+      const localVertices = points.map((point) => {
+        const [px, py] = point as [number, number];
+        return new Vector2(px - centerX, py - centerY);
+      });
+      assignPolygonCollider(entity, { vertices: localVertices });
+    } else {
+      if (typeof y !== "number" || typeof width !== "number" || typeof height !== "number") {
+        throw new Error("Rectangle hitbox requires x, y, width and height parameters");
+      }
+
+      const centerX = xOrPoints + width / 2;
+      const centerY = y + height / 2;
+      boxWidth = Math.max(width, 1);
+      boxHeight = Math.max(height, 1);
+
+      entity = this.physic.createEntity({
+        uuid: id,
+        position: { x: centerX, y: centerY },
+        width: boxWidth,
+        height: boxHeight,
+        mass: Infinity,
+        state: EntityState.Static,
+        restitution: 0
+      });
+      entity.freeze();
+    }
+
+    return id;
+  }
+
+  /**
+   * 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
+   */
+  private addCharacter(options: {
+    owner: any;
+    radius?: number;
+    kind?: PhysicsEntityKind;
+    collidesWithCharacters?: boolean;
+    maxSpeed?: number;
+    isStatic?: boolean;
+    friction?: number;
+    mass?: number;
+  }): string {
+    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;
+
+    // Get hitbox dimensions - hitbox.w/h are the FULL dimensions, not radius
+    const hitbox = typeof owner.hitbox === "function" ? owner.hitbox() : owner.hitbox;
+    const width = hitbox?.w ?? 32;
+    const height = hitbox?.h ?? 32;
+
+    // Calculate radius from dimensions (use the larger dimension for circular collider)
+    const radius = Math.max(width, height) / 2;
+
+    // owner.x() and owner.y() are TOP-LEFT positions
+    const topLeftX = owner.x();
+    const topLeftY = owner.y();
+
+    // Convert to CENTER for physics engine
+    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: width,
+      height: height,
+      mass: options.mass ?? (isStatic ? Infinity : 1),
+      friction: options.friction ?? 0.4,
+      linearDamping: isStatic ? 1 : 0.2,
+      maxLinearVelocity: options.maxSpeed ? options.maxSpeed * this.speedScalar : 200,
+      restitution: 0
+    });
+
+    if (isStatic) {
+      entity.freeze();
+    } else {
+      entity.unfreeze();
+    }
+
+    // Store owner reference directly on entity for syncing positions
+    (entity as any).owner = owner;
+
+    entity.onDirectionChange(({ cardinalDirection }) => {
+      // hack to prevent direction in client side
+      if (!('$send' in this)) return;
+      const owner = (entity as any).owner;
+      if (!owner) return;
+      if (cardinalDirection === 'idle') return;
+      // Don't change direction if it's locked
+      if (owner.directionFixed) return;
+      owner.changeDirection(cardinalDirection as Direction);
+    });
+
+    entity.onMovementChange(({ isMoving, intensity }) => {
+      // Prevent animation changes on client side (same as onDirectionChange)
+      if (!('$send' in this)) return;
+      
+      // Get owner from entity (same pattern as onDirectionChange)
+      const owner = (entity as any).owner;
+      if (!owner) return;
+      
+      // Don't change animation if it's locked
+      if (owner.animationFixed) return;
+      
+      // Only change animation if intensity is low (avoid animation flicker on micro-movements)
+      // Intensity threshold: 10 pixels/second (adjust based on your game's needs)
+      const LOW_INTENSITY_THRESHOLD = 10;
+      
+      // Try to use setAnimation method if available (preferred method)
+      // Otherwise, try to access animationName signal directly
+      const hasSetAnimation = typeof owner.setAnimation === 'function';
+      const animationNameSignal = owner.animationName;
+      const ownerHasAnimationName = animationNameSignal && typeof animationNameSignal === 'object' && typeof animationNameSignal.set === 'function';
+      
+      if (isMoving && intensity > LOW_INTENSITY_THRESHOLD) {
+        if (hasSetAnimation) {
+          owner.setGraphicAnimation("walk");
+        } else if (ownerHasAnimationName) {
+          animationNameSignal.set("walk");
+        }
+      } else if (!isMoving) {
+        if (hasSetAnimation) {
+          owner.setGraphicAnimation("stand");
+        } else if (ownerHasAnimationName) {
+          animationNameSignal.set("stand");
+        }
+      }
+      // If moving with high intensity, keep current animation (e.g., already running)
+    });
+
+    // Register position sync handler to update owner.x and owner.y.
+    // Read owner dynamically from entity to avoid stale references after map transfer.
+    
+    entity.onPositionChange(({ x, y }) => {
+      const currentOwner = (entity as any).owner;
+      if (!currentOwner) {
+        return;
+      }
+
+      const entityWidth = entity.width || width;
+      const entityHeight = entity.height || height;
+      // Calculate top-left from center using the original hitbox dimensions
+      // This ensures consistency: center = topLeft + (size / 2)
+      // Therefore: topLeft = center - (size / 2)
+      const topLeftX = x - entityWidth / 2;
+      const topLeftY = y - entityHeight / 2;
+      let changed = false;
+
+      if (typeof currentOwner.x === "function" && typeof currentOwner.x.set === "function") {
+        currentOwner.x.set(Math.round(topLeftX));
+        changed = true;
+      }
+      if (typeof currentOwner.y === "function" && typeof currentOwner.y.set === "function") {
+        currentOwner.y.set(Math.round(topLeftY));
+        changed = true;
+      }
+      if (changed) {
+        currentOwner.applyFrames?.();
+      }
+    });
+
+    // Add resolution filter for through/throughOtherPlayer/throughEvent
+    // This filter determines if collisions should be RESOLVED (blocking) or just DETECTED.
+    // When returning false, entities pass through each other but collision events still fire.
+    entity.addResolutionFilter((self, other) => {
+      const selfOwner = (self as any).owner;
+      const otherOwner = (other as any).owner;
+
+      // If either entity has no owner, resolve collision (e.g., walls, obstacles must block)
+      if (!selfOwner || !otherOwner) {
+        return true;
+      }
+
+    
+      if (selfOwner.z() !== otherOwner.z()) {
+        return false; // Don't resolve collision
+      }
+
+      // Check if selfOwner has _through property (passes through everything)
+      // This applies to both players and events
+      if (typeof selfOwner._through === "function") {
+        try {
+          if (selfOwner._through() === true) {
+            return false; // Pass through but events still fire
+          }
+        } catch {
+          // Ignore errors
+        }
+      } else if (selfOwner.through === true) {
+        return false;
+      }
+
+      // Determine the type of both entities via lookup in players/events
+      const playersMap = this.players();
+      const eventsMap = this.events();
+      const isSelfPlayer = !!playersMap[self.uuid];
+      const isOtherPlayer = !!playersMap[other.uuid];
+      const isSelfEvent = !!eventsMap[self.uuid];
+      const isOtherEvent = !!eventsMap[other.uuid];
+      const readScenarioOwnerId = (owner: any): string | undefined => {
+        const scenarioOwnerId = owner?._scenarioOwnerId ?? owner?.scenarioOwnerId;
+        return typeof scenarioOwnerId === "string" && scenarioOwnerId.length > 0
+          ? scenarioOwnerId
+          : undefined;
+      };
+      const selfScenarioOwnerId = readScenarioOwnerId(selfOwner);
+      const otherScenarioOwnerId = readScenarioOwnerId(otherOwner);
+
+      // Scenario events are isolated per player:
+      // they only collide with their owner and scenario events of the same owner.
+      if (selfScenarioOwnerId) {
+        if (isOtherPlayer && other.uuid !== selfScenarioOwnerId) {
+          return false;
+        }
+        if (isOtherEvent && otherScenarioOwnerId !== selfScenarioOwnerId) {
+          return false;
+        }
+      }
+      if (otherScenarioOwnerId) {
+        if (isSelfPlayer && self.uuid !== otherScenarioOwnerId) {
+          return false;
+        }
+        if (isSelfEvent && selfScenarioOwnerId !== otherScenarioOwnerId) {
+          return false;
+        }
+      }
+
+      // throughOtherPlayer only applies when SELF is a player and OTHER is also a player
+      // (players passing through other players)
+      if (isSelfPlayer && isOtherPlayer) {
+        if (typeof selfOwner._throughOtherPlayer === "function") {
+          try {
+            if (selfOwner._throughOtherPlayer() === true) {
+              return false; // Pass through players but events still fire
+            }
+          } catch {
+            // Ignore errors
+          }
+        } else if (selfOwner.throughOtherPlayer === true) {
+          return false;
+        }
+      }
+
+      // throughEvent only applies when SELF is a player and OTHER is an event
+      // (players passing through events)
+      if (isSelfPlayer && isOtherEvent) {
+        if (typeof selfOwner._throughEvent === "function") {
+          try {
+            if (selfOwner._throughEvent() === true) {
+              return false; // Pass through events but events still fire
+            }
+          } catch {
+            // Ignore errors
+          }
+        } else if (selfOwner.throughEvent === true) {
+          return false;
+        }
+      }
+
+      return true; // Resolve collision (block movement)
+    });
+
+    return id;
+  }
+
+  /**
+   * Update hitbox position and size
+   * 
+   * @param id - Entity ID
+   * @param x - Top-left X coordinate
+   * @param y - Top-left Y coordinate
+   * @param width - Optional width
+   * @param height - Optional height
+   * @returns True if hitbox was updated successfully
+   */
+  updateHitbox(id: string, x: number, y: number, width?: number, height?: number): boolean {
+    const entity = this.physic.getEntityByUUID(id);
+    if (!entity) return false;
+
+    if (typeof width === "number" && typeof height === "number") {
+      entity.width = Math.max(width, 1);
+      entity.height = Math.max(height, 1);
+    }
+
+    // Calculate center from top-left
+    const entityWidth = entity.width || entity.radius * 2 || 32;
+    const entityHeight = entity.height || entity.radius * 2 || 32;
+    const centerX = x + entityWidth / 2;
+    const centerY = y + entityHeight / 2;
+    entity.position.set(centerX, centerY);
+
+    return true;
+  }
+
+  /**
+   * Remove a hitbox from the physics world
+   * @private
+   */
+  private removeHitbox(id: string, owner?: any, kind?: PhysicsEntityKind): boolean {
+    const entity = this.physic.getEntityByUUID(id);
+    if (!entity) {
+      return false;
+    }
+    const resolvedOwner = owner ?? (entity as any).owner;
+    if (resolvedOwner) {
+      this.emitPhysicsEntityRemove({
+        owner: resolvedOwner,
+        entity,
+        kind: kind ?? this.resolvePhysicsEntityKind(resolvedOwner, id),
+      });
+    }
+    this.physic.removeEntity(entity);
+    return true;
+  }
+
+  /**
+   * Check if an entity is moving
+   * @private
+   */
+  private isEntityMoving(id: string): boolean {
+    const entity = this.physic.getEntityByUUID(id);
+    if (!entity) return false;
+    // Check if entity has velocity
+    return entity.velocity.length() > 0.1;
+  }
+
+  /**
+   * Move a body in a direction
+   * @private
+   */
+  private moveBody(player: any, direction: Direction): boolean {
+    const entity = this.physic.getEntityByUUID(player.id);
+    if (!entity) return false;
+
+    const speedValue = player.speed()
+
+    let vx = 0, vy = 0;
+    switch (direction) {
+      case Direction.Left:
+        vx = -speedValue * this.speedScalar;
+        break;
+      case Direction.Right:
+        vx = speedValue * this.speedScalar;
+        break;
+      case Direction.Up:
+        vy = -speedValue * this.speedScalar;
+        break;
+      case Direction.Down:
+        vy = speedValue * this.speedScalar;
+        break;
+    }
+
+    // Input sets the base velocity. Movement strategies (dash/knockback/AI, etc.)
+    // are responsible for adding or overriding velocity when needed.
+    entity.setVelocity({ x: vx, y: vy });
+    entity.wakeUp();
+    return true;
+  }
+
+  /**
+   * 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
+   */
+  protected stopMovement(player: any): boolean {
+    const entity = this.physic.getEntityByUUID(player.id);
+    if (!entity) return false;
+
+    // Stop all movement using the MovementManager (clears strategies and stops entity movement)
+    this.moveManager.stopMovement(player.id);
+
+    player.pendingInputs = [];
+    
+    return true;
+  }
+
+  /**
+   * Set character collision enabled
+   * @private
+   */
+  private setCharacterCollisionEnabled(id: string, collides: boolean): boolean {
+    const entity = this.physic.getEntityByUUID(id);
+    if (!entity) {
+      return false;
+    }
+    // Collision filtering is handled by PhysicsEngine's collision system
+    // This method is kept for API compatibility but doesn't need to do anything
+    // as PhysicsEngine handles collisions automatically
+    return true;
+  }
+
+  /**
+   * Get collisions for an entity
+   * 
+   * Returns all entities that are colliding with the specified entity.
+   * Uses the entity's actual AABB bounds to detect collisions in all directions.
+   * 
+   * @param id - Entity UUID to check collisions for
+   * @returns Array of entity UUIDs that are colliding with the specified entity
+   * 
+   * @example
+   * ```ts
+   * // Get all entities colliding with player
+   * const collisions = map.getCollisions('player1');
+   * collisions.forEach(id => {
+   *   console.log(`Entity ${id} is colliding with player`);
+   * });
+   * ```
+   */
+  protected getCollisions(id: string): string[] {
+    const entity = this.physic.getEntityByUUID(id);
+    if (!entity) return [];
+
+    // Get the entity's actual collider and AABB bounds
+    const collider = createCollider(entity);
+    if (!collider) return [];
+
+    const entityAABB = collider.getBounds();
+    
+    // Expand AABB slightly to ensure we catch nearby entities
+    // This helps with edge cases where entities are just touching
+    const expandedAABB = entityAABB.expand(1);
+
+    // Query nearby entities using the expanded AABB
+    const nearby = this.physic.queryAABB(expandedAABB);
+    const collisions: string[] = [];
+
+    // Check actual AABB intersections for each nearby entity
+    for (const other of nearby) {
+      if (other.uuid === id) continue;
+
+      const otherCollider = createCollider(other);
+      if (!otherCollider) continue;
+
+      const otherAABB = otherCollider.getBounds();
+      
+      // Check if AABBs actually intersect
+      if (entityAABB.intersects(otherAABB)) {
+        collisions.push(other.uuid);
+      }
+    }
+
+    return collisions;
+  }
+
+  /**
+   * Get physics body (entity) for an id
+   * @protected
+   */
+  public getBody(id: string): Entity | undefined {
+    return this.physic.getEntityByUUID(id);
+  }
+
+  /**
+   * Get the current physics tick
+   * @returns Current tick number
+   */
+  getTick(): number {
+    return this.physic.getTick();
+  }
+
+  /**
+   * Get body position in different modes
+   * 
+   * @param id - Entity ID
+   * @param mode - Position mode: "center" or "top-left"
+   * @returns Position coordinates or undefined if entity not found
+   */
+  getBodyPosition(
+    id: string,
+    mode: "center" | "top-left" = "center",
+  ): { x: number; y: number } | undefined {
+    const entity = this.physic.getEntityByUUID(id);
+    if (!entity) return undefined;
+
+    const centerX = entity.position.x;
+    const centerY = entity.position.y;
+    if (mode === "center") {
+      return { x: centerX, y: centerY };
+    }
+
+    // Calculate top-left from center
+    const width = entity.width || (entity.radius ? entity.radius * 2 : 32);
+    const height = entity.height || (entity.radius ? entity.radius * 2 : 32);
+    return {
+      x: centerX - width / 2,
+      y: centerY - height / 2,
+    };
+  }
+
+  /**
+   * Set body position
+   * 
+   * @param id - Entity ID
+   * @param x - X coordinate
+   * @param y - Y coordinate
+   * @param mode - Position mode: "center" or "top-left"
+   * @returns True if position was set successfully
+   */
+  setBodyPosition(
+    id: string,
+    x: number,
+    y: number,
+    mode: "center" | "top-left" = "center",
+  ): Entity | undefined {
+    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") {
+      centerX = x + width / 2;
+      centerY = y + height / 2;
+    }
+
+    entity.position.set(centerX, centerY);
+    entity.notifyPositionChange();
+    
+    return entity;
+  }
+
+  /**
+   * Handle collision enter
+   * @private
+   */
+  // Collision handling is now done directly via entity hooks in addCharacter
+  // These methods are no longer needed as PhysicsEngine handles collisions internally
+
+  /**
+   * Add a zone
+   * @private
+   */
+  private addZone(id: string, options: ZoneOptions): string {
+    // Check if zone or entity already exists
+    const zoneManager = this.physic.getZoneManager();
+    if (this.physic.getEntityByUUID(id)) {
+      throw new Error(`Zone with id ${id} already exists as entity`);
+    }
+
+    const radius = options.radius;
+    if (typeof radius !== "number" || radius <= 0) {
+      throw new Error("Zone radius must be a positive number");
+    }
+
+    // If linkedTo is specified, get the entity
+    let attachedEntity: Entity | undefined;
+    if (options.linkedTo) {
+      attachedEntity = this.physic.getEntityByUUID(options.linkedTo);
+      if (!attachedEntity) {
+        throw new Error(`Cannot link zone to unknown entity ${options.linkedTo}`);
+      }
+    }
+
+    const callbacks: { onEnter?: (entities: Entity[]) => void; onExit?: (entities: Entity[]) => void } = {};
+
+    // Store callbacks for later updates
+    (callbacks as any)._onEnterString = undefined;
+    (callbacks as any)._onExitString = undefined;
+
+    const zoneId = attachedEntity
+      ? zoneManager.createAttachedZone(attachedEntity, {
+        radius,
+        angle: options.angle ?? 360,
+        direction: options.direction ?? 'down',
+        limitedByWalls: options.limitedByWalls ?? false,
+      }, callbacks)
+      : zoneManager.createZone({
+        position: { x: options.x ?? 0, y: options.y ?? 0 },
+        radius,
+        angle: options.angle ?? 360,
+        direction: options.direction ?? 'down',
+        limitedByWalls: options.limitedByWalls ?? false,
+      }, callbacks);
+
+    // Store zone ID mapping
+    (this as any)._zoneIdMap = (this as any)._zoneIdMap || new Map();
+    (this as any)._zoneIdMap.set(id, zoneId);
+
+    return id;
+  }
+
+  /**
+   * Remove a zone
+   * @private
+   */
+  private removeZone(id: string): boolean {
+    const zoneIdMap = (this as any)._zoneIdMap;
+    if (!zoneIdMap) return false;
+
+    const zoneId = zoneIdMap.get(id);
+    if (!zoneId) return false;
+
+    const zoneManager = this.physic.getZoneManager();
+    zoneManager.removeZone(zoneId);
+    zoneIdMap.delete(id);
+    return true;
+  }
+
+  /**
+   * Get a zone
+   * @private
+   */
+  private getZone(id: string): any {
+    const zoneIdMap = (this as any)._zoneIdMap;
+    if (!zoneIdMap) return undefined;
+
+    const zoneId = zoneIdMap.get(id);
+    if (!zoneId) return undefined;
+
+    const zoneManager = this.physic.getZoneManager();
+    return zoneManager.getZone(zoneId);
+  }
+
+  /**
+   * Register zone events
+   * @private
+   */
+  private registerZoneEvents(
+    id: string,
+    onEnter?: (hitIds: string[]) => void,
+    onExit?: (hitIds: string[]) => void,
+  ): boolean {
+    const zoneIdMap = (this as any)._zoneIdMap;
+    if (!zoneIdMap) return false;
+
+    const zoneId = zoneIdMap.get(id);
+    if (!zoneId) return false;
+
+    const zoneManager = this.physic.getZoneManager();
+
+    // Use registerCallbacks to update callbacks
+    const callbacks: { onEnter?: (entities: Entity[]) => void; onExit?: (entities: Entity[]) => void } = {};
+    if (onEnter) {
+      callbacks.onEnter = (entities: Entity[]) => {
+        onEnter(entities.map(e => e.uuid));
+      };
+    }
+    if (onExit) {
+      callbacks.onExit = (entities: Entity[]) => {
+        onExit(entities.map(e => e.uuid));
+      };
+    }
+
+    return zoneManager.registerCallbacks(zoneId, callbacks);
+  }
+
+  /**
+   * Run post-tick updates (update zones)
+   * @private
+   */
+  private runPostTickUpdates(): void {
+    // Position sync is now handled automatically by entity.onPositionChange hooks
+    // Movement callbacks are also handled in the onPositionChange handler
+
+    // Update zones
+    const zoneManager = this.physic.getZoneManager();
+    zoneManager.update();
+  }
 }