@rpgjs/server 5.0.0-alpha.3 → 5.0.0-alpha.31

package/src/Player/Player.ts

@@ -5,33 +5,47 @@ import {
   RpgCommonPlayer,
   ShowAnimationParams,
   Constructor,
-  ZoneOptions,
+  Direction,
+  AttachShapeOptions,
+  RpgShape,
+  ShapePositioning,
 } from "@rpgjs/common";
-import { WithComponentManager, IComponentManager } from "./ComponentManager";
+import { Entity, Vector2 } from "@rpgjs/physic";
+import { IComponentManager, WithComponentManager } from "./ComponentManager";
 import { RpgMap } from "../rooms/map";
 import { Context, inject } from "@signe/di";
 import { IGuiManager, WithGuiManager } from "./GuiManager";
 import { MockConnection } from "@signe/room";
 import { IMoveManager, WithMoveManager } from "./MoveManager";
 import { IGoldManager, WithGoldManager } from "./GoldManager";
-import { IWithVariableManager, WithVariableManager } from "./VariableManager";
-import { sync } from "@signe/sync";
-import { signal } from "@signe/reactive";
+import { WithVariableManager, type IVariableManager } from "./VariableManager";
+import { createStatesSnapshotDeep, load, sync, type } from "@signe/sync";
+import { computed, signal } from "@signe/reactive";
 import {
-  IWithParameterManager,
+  IParameterManager,
   WithParameterManager,
 } from "./ParameterManager";
 import { WithItemFixture } from "./ItemFixture";
-import { WithStateManager } from "./StateManager";
-import { WithItemManager } from "./ItemManager";
-import { lastValueFrom } from "rxjs";
-import { WithBattleManager } from "./BattleManager";
-import { WithEffectManager } from "./EffectManager";
-import { WithSkillManager, IWithSkillManager } from "./SkillManager";
-import { AGI, AGI_CURVE, DEX, DEX_CURVE, INT, INT_CURVE, MAXHP, MAXHP_CURVE, MAXSP, MAXSP_CURVE, STR, STR_CURVE } from "../presets";
-import { WithClassManager } from "./ClassManager";
-import { WithElementManager } from "./ElementManager";
-
+import { IItemManager, WithItemManager } from "./ItemManager";
+import { bufferTime, combineLatest, debounceTime, distinctUntilChanged, filter, lastValueFrom, map, Observable, pairwise, sample, throttleTime } from "rxjs";
+import { IEffectManager, WithEffectManager } from "./EffectManager";
+import { AGI, DEX, INT, MAXHP, MAXSP, STR } from "@rpgjs/common";
+import { AGI_CURVE, DEX_CURVE, INT_CURVE, MAXHP_CURVE, MAXSP_CURVE, STR_CURVE } from "../presets";
+import { IElementManager, WithElementManager } from "./ElementManager";
+import { ISkillManager, WithSkillManager } from "./SkillManager";
+import { IBattleManager, WithBattleManager } from "./BattleManager";
+import { IClassManager, WithClassManager } from "./ClassManager";
+import { IStateManager, WithStateManager } from "./StateManager";
+import {
+  buildSaveSlotMeta,
+  resolveAutoSaveStrategy,
+  resolveSaveSlot,
+  resolveSaveStorageStrategy,
+  shouldAutoSave,
+  type SaveRequestContext,
+  type SaveSlotIndex,
+  type SaveSlotMeta,
+} from "../services/save";
 
 /**
  * Combines multiple RpgCommonPlayer mixins into one
@@ -46,59 +60,214 @@ function combinePlayerMixins<T extends Constructor<RpgCommonPlayer>>(
     mixins.reduce((ExtendedClass, mixin) => mixin(ExtendedClass), Base);
 }
 
-const PlayerMixins = combinePlayerMixins([
+// Start with basic mixins that work
+const BasicPlayerMixins = combinePlayerMixins([
   WithComponentManager,
   WithEffectManager,
   WithGuiManager,
   WithMoveManager,
   WithGoldManager,
-  WithVariableManager,
   WithParameterManager,
   WithItemFixture,
-  WithStateManager,
   WithItemManager,
-  WithSkillManager,
+  WithElementManager,
+  WithVariableManager,
+  WithStateManager,
   WithClassManager,
+  WithSkillManager,
   WithBattleManager,
-  WithElementManager,
 ]);
 
 /**
  * RPG Player class with component management capabilities
+ * 
+ * Combines all player mixins to provide a complete player implementation
+ * with graphics, movement, inventory, skills, and battle capabilities.
+ * 
+ * @example
+ * ```ts
+ * // Create a new player
+ * const player = new RpgPlayer();
+ * 
+ * // Set player graphics
+ * player.setGraphic("hero");
+ * 
+ * // Add parameters and items
+ * player.addParameter("strength", { start: 10, end: 100 });
+ * player.addItem(sword);
+ * ```
  */
-export class RpgPlayer extends PlayerMixins(RpgCommonPlayer) {
+export class RpgPlayer extends BasicPlayerMixins(RpgCommonPlayer) {
   map: RpgMap | null = null;
   context?: Context;
   conn: MockConnection | null = null;
+  touchSide: boolean = false; // Protection against map change loops
+
+  /**
+   * Computed signal for world X position
+   * 
+   * Calculates the absolute world X position from the map's world position
+   * plus the player's local X position. Returns 0 if no map is assigned.
+   * 
+   * @example
+   * ```ts
+   * const worldX = player.worldX();
+   * console.log(`Player is at world X: ${worldX}`);
+   * ```
+   */
+  get worldPositionX() {
+    return this._getComputedWorldPosition('x');
+  }
+
+  /**
+   * Computed signal for world Y position
+   * 
+   * Calculates the absolute world Y position from the map's world position
+   * plus the player's local Y position. Returns 0 if no map is assigned.
+   * 
+   * @example
+   * ```ts
+   * const worldY = player.worldY();
+   * console.log(`Player is at world Y: ${worldY}`);
+   * ```
+   */
+  get worldPositionY() {
+    return this._getComputedWorldPosition('y');
+  }
+
+  private _worldPositionSignals = new WeakMap<any, any>();
+
+  private _getComputedWorldPosition(axis: 'x' | 'y') {
+    // We use a WeakMap to cache the computed signal per instance
+    // This ensures that if the player object is copied (e.g. in tests),
+    // the new instance gets its own signal bound to itself.
+    if (!this._worldPositionSignals) {
+      this._worldPositionSignals = new WeakMap();
+    }
+
+    const key = axis;
+    let signals = this._worldPositionSignals.get(this);
+    if (!signals) {
+      signals = {};
+      this._worldPositionSignals.set(this, signals);
+    }
+
+    if (!signals[key]) {
+      signals[key] = computed(() => {
+        const map = this.map as RpgMap | null;
+        const mapWorldPos = map ? (map[axis === 'x' ? 'worldX' : 'worldY'] ?? 0) : 0;
+        return mapWorldPos + (this[axis] as any)();
+      });
+    }
+    return signals[key];
+  }
+
+  /** Internal: Shapes attached to this player */
+  private _attachedShapes: Map<string, RpgShape> = new Map();
+
+  /** Internal: Shapes where this player is currently located */
+  private _inShapes: Set<RpgShape> = new Set();
+  /** Last processed client input timestamp for reconciliation */
+  lastProcessedInputTs: number = 0;
+  /** Last processed client input frame for reconciliation with server tick */
+  _lastFramePositions: {
+    frame: number;
+    position: {
+      x: number;
+      y: number;
+      direction: Direction;
+    };
+    serverTick?: number; // Server tick at which this position was computed
+  } | null = null;
+
+  frames: { x: number; y: number; ts: number }[] = [];
 
   @sync(RpgPlayer) events = signal<RpgEvent[]>([]);
 
   constructor() {
     super();
-    this.expCurve = {
-        basis: 30,
-        extra: 20,
-        accelerationA: 30,
-        accelerationB: 30
-    }
 
-    this.addParameter(MAXHP, MAXHP_CURVE)
-    this.addParameter(MAXSP, MAXSP_CURVE)
-    this.addParameter(STR, STR_CURVE)
-    this.addParameter(INT, INT_CURVE)
-    this.addParameter(DEX, DEX_CURVE)
-    this.addParameter(AGI, AGI_CURVE)
-    this.allRecovery()
+    let lastEmitted: { x: number; y: number } | null = null;
+    let pendingUpdate: { x: number; y: number } | null = null;
+    let updateScheduled = false;
+
+    combineLatest([this.x.observable, this.y.observable])
+      .subscribe(([x, y]) => {
+        pendingUpdate = { x, y };
+
+        // Schedule a synchronous update using queueMicrotask
+        // This groups multiple rapid changes (x and y in the same tick) into a single frame
+        if (!updateScheduled) {
+          updateScheduled = true;
+          queueMicrotask(() => {
+            if (pendingUpdate) {
+              const { x, y } = pendingUpdate;
+              // Only emit if the values are different from the last emitted frame
+              if (!lastEmitted || lastEmitted.x !== x || lastEmitted.y !== y) {
+                this.frames = [...this.frames, {
+                  x: x,
+                  y: y,
+                  ts: Date.now(),
+                }];
+                lastEmitted = { x, y };
+              }
+              pendingUpdate = null;
+            }
+            updateScheduled = false;
+          });
+        }
+      })
+  }
+
+  _onInit() {
+    this.hooks.callHooks("server-playerProps-load", this).subscribe();
+  }
+
+  onGameStart() {
+    // Use type assertion to access mixin properties
+    (this as any).expCurve = {
+      basis: 30,
+      extra: 20,
+      accelerationA: 30,
+      accelerationB: 30
+    };
+
+    ;(this as any).addParameter(MAXHP, MAXHP_CURVE);
+    (this as any).addParameter(MAXSP, MAXSP_CURVE);
+    (this as any).addParameter(STR, STR_CURVE);
+    (this as any).addParameter(INT, INT_CURVE);
+    (this as any).addParameter(DEX, DEX_CURVE);
+    (this as any).addParameter(AGI, AGI_CURVE);
+    (this as any).allRecovery();
+  }
+
+  get hooks() {
+    return inject<Hooks>(this.context as any, ModulesToken);
+  }
+
+  // compatibility with v4
+  get server() {
+    return this.map
+  }
+
+  setMap(map: RpgMap) {
+    this.map = map;
+  }
+
+  applyFrames() {
+    this._frames.set(this.frames)
+    this.frames = []
   }
 
   async execMethod(method: string, methodData: any[] = [], target?: any) {
     let ret: any;
     if (target) {
-      ret = await target[method](...methodData);
+      if (typeof target[method] === 'function') {
+        ret = await target[method](...methodData);
+      }
     }
     else {
-      const hooks = inject<Hooks>(this.context as any, ModulesToken);
-      ret = await lastValueFrom(hooks
+      ret = await lastValueFrom(this.hooks
         .callHooks(`server-player-${method}`, target ?? this, ...methodData));
     }
     this.syncChanges()
@@ -125,17 +294,114 @@ export class RpgPlayer extends PlayerMixins(RpgCommonPlayer) {
     mapId: string,
     positions?: { x: number; y: number; z?: number } | string
   ): Promise<any | null | boolean> {
+    const realMapId = 'map-' + mapId;
+    const room = this.getCurrentMap();
+
+    const canChange: boolean[] = await lastValueFrom(this.hooks.callHooks("server-player-canChangeMap", this, {
+      id: mapId,
+    }));
+    if (canChange.some(v => v === false)) return false;
+
+    if (positions && typeof positions === 'object') {
+      this.teleport(positions)
+    }
+    await room?.$sessionTransfer(this.conn, realMapId);
     this.emit("changeMap", {
-      mapId: 'map-' + mapId,
+      mapId: realMapId,
       positions,
     });
     return true;
   }
 
+  async autoChangeMap(nextPosition: Vector2): Promise<boolean> {
+    const map = this.getCurrentMap()
+    const worldMaps = map?.getInWorldMaps()
+    let ret: boolean = false
+    if (worldMaps && map) {
+        const direction = this.getDirection()
+        const marginLeftRight = map.tileWidth / 2
+        const marginTopDown = map.tileHeight / 2
+
+        const changeMap = async (adjacent, to) => {
+            if (this.touchSide) {
+                return false
+            }
+            this.touchSide = true
+            const [nextMap] = worldMaps.getAdjacentMaps(map, adjacent)
+            if (!nextMap) return false
+            const id = nextMap.id as string
+            const nextMapInfo = worldMaps.getMapInfo(id)
+            return !!(await this.changeMap(id, to(nextMapInfo)))
+        }
+
+        if (nextPosition.x < marginLeftRight && direction == Direction.Left) {
+            ret = await changeMap({
+                x: map.worldX - 1,
+                y: this.worldPositionY() + 1
+            }, nextMapInfo => ({
+                x: (nextMapInfo.width) - this.hitbox().w - marginLeftRight,
+                y: map.worldY - nextMapInfo.y + nextPosition.y
+            }))
+        }
+        else if (nextPosition.x > map.widthPx - this.hitbox().w - marginLeftRight && direction == Direction.Right) {
+            ret = await changeMap({
+                x: map.worldX + map.widthPx + 1,
+                y: this.worldPositionY() + 1
+            }, nextMapInfo => ({
+                x: marginLeftRight,
+                y: map.worldY - nextMapInfo.y + nextPosition.y
+            }))
+        }
+        else if (nextPosition.y < marginTopDown && direction == Direction.Up) {
+            ret = await changeMap({
+                x: this.worldPositionX() + 1,
+                y: map.worldY - 1
+            }, nextMapInfo => ({
+                x: map.worldX - nextMapInfo.x + nextPosition.x,
+                y: (nextMapInfo.height) - this.hitbox().h - marginTopDown,
+            }))
+        }
+        else if (nextPosition.y > map.heightPx - this.hitbox().h - marginTopDown && direction == Direction.Down) {
+            ret = await changeMap({
+                x: this.worldPositionX() + 1,
+                y: map.worldY + map.heightPx + 1
+            }, nextMapInfo => ({
+                x: map.worldX - nextMapInfo.x + nextPosition.x,
+                y: marginTopDown,
+            }))
+        }
+        else {
+            this.touchSide = false
+        }
+    }
+    return ret
+}
+
   async teleport(positions: { x: number; y: number }) {
     if (!this.map) return false;
-    // For movable objects like players, the position represents the center
-    this.map.physic.updateHitbox(this.id, positions.x, positions.y);
+    if (this.map && this.map.physic) {
+      // Skip collision check for teleportation (allow teleporting through walls)
+      const entity = this.map.physic.getEntityByUUID(this.id);
+      if (entity) {
+        const hitbox = typeof this.hitbox === "function" ? this.hitbox() : this.hitbox;
+        const width = hitbox?.w ?? 32;
+        const height = hitbox?.h ?? 32;
+        
+        // Convert top-left position to center position for physics engine
+        // positions.x/y are TOP-LEFT coordinates, but physic.teleport expects CENTER coordinates
+        const centerX = positions.x + width / 2;
+        const centerY = positions.y + height / 2;
+        
+        this.map.physic.teleport(entity, { x: centerX, y: centerY });
+      }
+    }
+    this.x.set(positions.x)
+    this.y.set(positions.y)
+    // Wait for the frame to be added before applying frames
+    // This ensures the frame is added before applyFrames() is called
+    queueMicrotask(() => {
+      this.applyFrames()
+    })
   }
 
   getCurrentMap<T extends RpgMap = RpgMap>(): T | null {
@@ -151,7 +417,191 @@ export class RpgPlayer extends PlayerMixins(RpgCommonPlayer) {
     });
   }
 
-  showAnimation(params: ShowAnimationParams) {}
+  snapshot() {
+    const snapshot = createStatesSnapshotDeep(this);
+    const expCurve = (this as any).expCurve;
+    if (expCurve) {
+      snapshot.expCurve = { ...expCurve };
+    }
+    return snapshot;
+  }
+
+  async applySnapshot(snapshot: string | object) {
+    const data = typeof snapshot === "string" ? JSON.parse(snapshot) : snapshot;
+    const withItems = (this as any).resolveItemsSnapshot?.(data) ?? data;
+    const withSkills = (this as any).resolveSkillsSnapshot?.(withItems) ?? withItems;
+    const withStates = (this as any).resolveStatesSnapshot?.(withSkills) ?? withSkills;
+    const withClass = (this as any).resolveClassSnapshot?.(withStates) ?? withStates;
+    const resolvedSnapshot = (this as any).resolveEquipmentsSnapshot?.(withClass) ?? withClass;
+    load(this, resolvedSnapshot);
+    if (resolvedSnapshot.expCurve) {
+      (this as any).expCurve = resolvedSnapshot.expCurve;
+    }
+    if (Array.isArray(resolvedSnapshot.items)) {
+      this.items.set(resolvedSnapshot.items);
+    }
+    if (Array.isArray(resolvedSnapshot.skills)) {
+      this.skills.set(resolvedSnapshot.skills);
+    }
+    if (Array.isArray(resolvedSnapshot.states)) {
+      this.states.set(resolvedSnapshot.states);
+    }
+    if (resolvedSnapshot._class != null && this._class?.set) {
+      this._class.set(resolvedSnapshot._class);
+    }
+    if (Array.isArray(resolvedSnapshot.equipments)) {
+      this.equipments.set(resolvedSnapshot.equipments);
+    }
+    await lastValueFrom(this.hooks.callHooks("server-player-onLoad", this, resolvedSnapshot));
+    return resolvedSnapshot;
+  }
+
+  async save(slot: SaveSlotIndex = "auto", meta: SaveSlotMeta = {}, context: SaveRequestContext = {}) {
+    const policy = resolveAutoSaveStrategy();
+    if (policy.canSave && !policy.canSave(this, context)) {
+      return null;
+    }
+    const resolvedSlot = resolveSaveSlot(slot, policy, this, context);
+    if (resolvedSlot === null) {
+      return null;
+    }
+    const snapshot = this.snapshot();
+    await lastValueFrom(this.hooks.callHooks("server-player-onSave", this, snapshot));
+    const storage = resolveSaveStorageStrategy();
+    const finalMeta = buildSaveSlotMeta(this, meta);
+    await storage.save(this, resolvedSlot, JSON.stringify(snapshot), finalMeta);
+    return { index: resolvedSlot, meta: finalMeta };
+  }
+
+  async load(
+    slot: SaveSlotIndex = "auto",
+    context: SaveRequestContext = {},
+    options: { changeMap?: boolean } = {}
+  ) {
+    const policy = resolveAutoSaveStrategy();
+    if (policy.canLoad && !policy.canLoad(this, context)) {
+      return { ok: false };
+    }
+    const resolvedSlot = resolveSaveSlot(slot, policy, this, context);
+    if (resolvedSlot === null) {
+      return { ok: false };
+    }
+    const storage = resolveSaveStorageStrategy();
+    const slotData = await storage.get(this, resolvedSlot);
+    if (!slotData?.snapshot) {
+      return { ok: false };
+    }
+    await this.applySnapshot(slotData.snapshot);
+    const { snapshot, ...meta } = slotData;
+    if (options.changeMap !== false && meta.map) {
+      await this.changeMap(meta.map);
+    }
+    return { ok: true, slot: meta, index: resolvedSlot };
+  }
+
+ 
+  /**
+   * @deprecated Use setGraphicAnimation instead.
+   * @param animationName - The name of the animation to play (e.g., 'attack', 'skill', 'walk')
+   * @param nbTimes - Number of times to repeat the animation (default: Infinity for continuous)
+   */
+  setAnimation(animationName: string, nbTimes: number = Infinity) {
+    console.warn('setAnimation is deprecated. Use setGraphicAnimation instead.');
+    this.setGraphicAnimation(animationName, nbTimes);
+  }
+
+  /**
+   * @deprecated Use setGraphicAnimation instead.
+   * @param graphic - The graphic to use for the animation (e.g., 'attack', 'skill', 'walk')
+   * @param animationName - The name of the animation to play (e.g., 'attack', 'skill', 'walk')
+   * @param replaceGraphic - Whether to replace the player's graphic (default: false)
+   */
+  showAnimation(graphic: string, animationName: string, replaceGraphic: boolean = false) {
+    if (replaceGraphic) {
+      console.warn('showAnimation is deprecated. Use player.setGraphicAnimation instead.');
+      this.setGraphicAnimation(animationName, graphic);
+    }
+    else {
+      console.warn('showAnimation is deprecated. Use map.showAnimation instead.');
+      const map = this.getCurrentMap();
+      map?.showAnimation({ x: this.x(), y: this.y() }, graphic, animationName);
+    }
+  }
+
+   /**
+   * Set the current animation of the player's sprite
+   *
+   * This method changes the animation state of the player's current sprite.
+   * It's used to trigger character animations like attack, skill, or custom movements.
+   * When `nbTimes` is set to a finite number, the animation will play that many times
+   * before returning to the previous animation state.
+   *
+   * If `animationFixed` is true, this method will not change the animation.
+   *
+   * @param animationName - The name of the animation to play (e.g., 'attack', 'skill', 'walk')
+   * @param nbTimes - Number of times to repeat the animation (default: Infinity for continuous)
+   */
+  setGraphicAnimation(animationName: string, nbTimes: number): void;
+  /**
+   * Set the current animation of the player's sprite with a temporary graphic change
+   *
+   * This method changes the animation state of the player's current sprite and temporarily
+   * changes the player's graphic (sprite sheet) during the animation. The graphic is
+   * automatically reset when the animation finishes.
+   *
+   * When `nbTimes` is set to a finite number, the animation will play that many times
+   * before returning to the previous animation state and graphic.
+   *
+   * If `animationFixed` is true, this method will not change the animation.
+   *
+   * @param animationName - The name of the animation to play (e.g., 'attack', 'skill', 'walk')
+   * @param graphic - The graphic(s) to temporarily use during the animation
+   * @param nbTimes - Number of times to repeat the animation (default: Infinity for continuous)
+   */
+  setGraphicAnimation(animationName: string, graphic: string | string[], nbTimes: number): void;
+  setGraphicAnimation(animationName: string, graphic: string | string[]): void;
+  setGraphicAnimation(animationName: string, graphicOrNbTimes?: string | string[] | number, nbTimes: number = 1): void {
+    // Don't change animation if it's locked
+    if (this.animationFixed) {
+      return;
+    }
+
+    let graphic: string | string[] | undefined;
+    let finalNbTimes: number = Infinity;
+
+    // Handle overloads
+    if (typeof graphicOrNbTimes === 'number') {
+      // setGraphicAnimation(animationName, nbTimes)
+      finalNbTimes = graphicOrNbTimes;
+    } else if (graphicOrNbTimes !== undefined) {
+      // setGraphicAnimation(animationName, graphic, nbTimes)
+      graphic = graphicOrNbTimes;
+      finalNbTimes = nbTimes ?? Infinity;
+    } else {
+      // setGraphicAnimation(animationName) - nbTimes remains Infinity
+      finalNbTimes = Infinity;
+    }
+
+    const map = this.getCurrentMap();
+    if (!map) return;
+
+    if (finalNbTimes === Infinity) {
+      if (graphic) this.setGraphic(graphic);
+      this.animationName.set(animationName);
+    }
+    else {
+      map.$broadcast({
+        type: "setAnimation",
+        value: {
+          animationName,
+          graphic,
+          nbTimes: finalNbTimes,
+          object: this.id,
+        },
+      });
+    }
+  }
+
 
   /**
    * Run the change detection cycle. Normally, as soon as a hook is called in a class, the cycle is started. But you can start it manually
@@ -164,11 +614,15 @@ export class RpgPlayer extends PlayerMixins(RpgCommonPlayer) {
   */
   syncChanges() {
     this._eventChanges();
+    if (shouldAutoSave(this, { reason: "auto", source: "syncChanges" })) {
+      void this.save("auto", {}, { reason: "auto", source: "syncChanges" });
+    }
   }
 
   databaseById(id: string) {
-    const map = this.getCurrentMap();
-    if (!map) return;
+    // Use this.map directly to support both RpgMap and LobbyRoom
+    const map = this.map as any;
+    if (!map || !map.database) return;
     const data = map.database()[id];
     if (!data)
       throw new Error(
@@ -183,56 +637,310 @@ export class RpgPlayer extends PlayerMixins(RpgCommonPlayer) {
     const { events } = map;
     const arrayEvents: any[] = [
       ...Object.values(this.events()),
-      ...Object.values(events()),
+      ...Object.values(events?.() ?? {}),
     ];
     for (let event of arrayEvents) {
       if (event.onChanges) event.onChanges(this);
     }
   }
 
-  attachShape(id: string, options: ZoneOptions) {
+  /**
+   * Attach a zone shape to this player using the physic zone system
+   * 
+   * This method creates a zone attached to the player's entity in the physics engine.
+   * The zone can be circular or cone-shaped and will detect other entities (players/events)
+   * entering or exiting the zone.
+   * 
+   * @param id - Optional zone identifier. If not provided, a unique ID will be generated
+   * @param options - Zone configuration options
+   * 
+   * @example
+   * ```ts
+   * // Create a circular detection zone
+   * player.attachShape("vision", {
+   *   radius: 150,
+   *   angle: 360,
+   * });
+   * 
+   * // Create a cone-shaped vision zone
+   * player.attachShape("vision", {
+   *   radius: 200,
+   *   angle: 120,
+   *   direction: Direction.Right,
+   *   limitedByWalls: true,
+   * });
+   * 
+   * // Create a zone with width/height (radius calculated automatically)
+   * player.attachShape({
+   *   width: 100,
+   *   height: 100,
+   *   positioning: "center",
+   * });
+   * ```
+   */
+  attachShape(idOrOptions: string | AttachShapeOptions, options?: AttachShapeOptions): RpgShape | undefined {
     const map = this.getCurrentMap();
-    if (!map) return;
+    if (!map) return undefined;
 
-    const physic = map.physic;
+    // Handle overloaded signature: attachShape(options) or attachShape(id, options)
+    let zoneId: string;
+    let shapeOptions: AttachShapeOptions;
 
-    const zoneId = physic.addZone(id, {
-      linkedTo: this.id,
-      ...options,
-    });
+    if (typeof idOrOptions === 'string') {
+      zoneId = idOrOptions;
+      if (!options) {
+        console.warn('attachShape: options must be provided when id is specified');
+        return undefined;
+      }
+      shapeOptions = options;
+    } else {
+      zoneId = `zone-${this.id}-${Date.now()}`;
+      shapeOptions = idOrOptions;
+    }
+
+    // Get player entity from physic engine
+    const playerEntity = map.physic.getEntityByUUID(this.id);
+    if (!playerEntity) {
+      console.warn(`Player entity not found in physic engine for player ${this.id}`);
+      return undefined;
+    }
+
+    // Calculate radius from width/height if not provided
+    let radius: number;
+    if (shapeOptions.radius !== undefined) {
+      radius = shapeOptions.radius;
+    } else if (shapeOptions.width && shapeOptions.height) {
+      // Use the larger dimension as radius, or calculate from area
+      radius = Math.max(shapeOptions.width, shapeOptions.height) / 2;
+    } else {
+      console.warn('attachShape: radius or width/height must be provided');
+      return undefined;
+    }
+
+    // Calculate offset based on positioning
+    let offset: Vector2 = new Vector2(0, 0);
+    const positioning: ShapePositioning = shapeOptions.positioning || "default";
+    if (shapeOptions.positioning) {
+      const playerWidth = playerEntity.width || playerEntity.radius * 2 || 32;
+      const playerHeight = playerEntity.height || playerEntity.radius * 2 || 32;
+
+      switch (shapeOptions.positioning) {
+        case 'top':
+          offset = new Vector2(0, -playerHeight / 2);
+          break;
+        case 'bottom':
+          offset = new Vector2(0, playerHeight / 2);
+          break;
+        case 'left':
+          offset = new Vector2(-playerWidth / 2, 0);
+          break;
+        case 'right':
+          offset = new Vector2(playerWidth / 2, 0);
+          break;
+        case 'center':
+        default:
+          offset = new Vector2(0, 0);
+          break;
+      }
+    }
 
-    physic.registerZoneEvents(
-      id,
-      (hitIds) => {
-        hitIds.forEach((id) => {
-          const event = map.getEvent<RpgEvent>(id);
-          const player = map.getPlayer(id);
-          const zone = physic.getZone(zoneId);
-          if (event) {
-            event.execMethod("onInShape", [zone, this]);
-          }
-          if (player) this.execMethod("onDetectInShape", [player, zone]);
-        });
+    // Get zone manager and create attached zone
+    const zoneManager = map.physic.getZoneManager();
+
+    // Convert direction from Direction enum to string if needed
+    // Direction enum values are already strings ("up", "down", "left", "right")
+    let direction: 'up' | 'down' | 'left' | 'right' = 'down';
+    if (shapeOptions.direction !== undefined) {
+      if (typeof shapeOptions.direction === 'string') {
+        direction = shapeOptions.direction as 'up' | 'down' | 'left' | 'right';
+      } else {
+        // Direction enum value is already a string, just cast it
+        direction = String(shapeOptions.direction) as 'up' | 'down' | 'left' | 'right';
+      }
+    }
+
+    // Create zone with metadata for name and properties
+    const metadata: Record<string, any> = {};
+    if (shapeOptions.name) {
+      metadata.name = shapeOptions.name;
+    }
+    if (shapeOptions.properties) {
+      metadata.properties = shapeOptions.properties;
+    }
+
+    // Get initial position
+    const initialX = playerEntity.position.x + offset.x;
+    const initialY = playerEntity.position.y + offset.y;
+
+    const physicZoneId = zoneManager.createAttachedZone(
+      playerEntity,
+      {
+        radius,
+        angle: shapeOptions.angle ?? 360,
+        direction,
+        limitedByWalls: shapeOptions.limitedByWalls ?? false,
+        offset,
+        metadata: Object.keys(metadata).length > 0 ? metadata : undefined,
       },
-      (hitIds) => {
-        hitIds.forEach((id) => {
-          const event = map.getEvent<RpgEvent>(id);
-          const zone = physic.getZone(zoneId);
-          const player = map.getPlayer(id);
-          if (event) {
-            event.execMethod("onOutShape", [zone, this]);
-          }
-          if (player) this.execMethod("onDetectOutShape", [player, zone]);
-        });
+      {
+        onEnter: (entities: Entity[]) => {
+          entities.forEach((entity) => {
+            const event = map.getEvent<RpgEvent>(entity.uuid);
+            const player = map.getPlayer(entity.uuid);
+
+            if (event) {
+              event.execMethod("onInShape", [shape, this]);
+              // Track that this event is in the shape
+              if ((event as any)._inShapes) {
+                (event as any)._inShapes.add(shape);
+              }
+            }
+            if (player) {
+              this.execMethod("onDetectInShape", [player, shape]);
+              // Track that this player is in the shape
+              if (player._inShapes) {
+                player._inShapes.add(shape);
+              }
+            }
+          });
+        },
+        onExit: (entities: Entity[]) => {
+          entities.forEach((entity) => {
+            const event = map.getEvent<RpgEvent>(entity.uuid);
+            const player = map.getPlayer(entity.uuid);
+
+            if (event) {
+              event.execMethod("onOutShape", [shape, this]);
+              // Remove from tracking
+              if ((event as any)._inShapes) {
+                (event as any)._inShapes.delete(shape);
+              }
+            }
+            if (player) {
+              this.execMethod("onDetectOutShape", [player, shape]);
+              // Remove from tracking
+              if (player._inShapes) {
+                player._inShapes.delete(shape);
+              }
+            }
+          });
+        },
       }
     );
+
+    // Create RpgShape instance
+    const shape = new RpgShape({
+      name: shapeOptions.name || zoneId,
+      positioning,
+      width: shapeOptions.width || radius * 2,
+      height: shapeOptions.height || radius * 2,
+      x: initialX,
+      y: initialY,
+      properties: shapeOptions.properties || {},
+      playerOwner: this,
+      physicZoneId: physicZoneId,
+      map: map,
+    });
+
+    // Store mapping from zoneId to physicZoneId for future reference
+    (this as any)._zoneIdMap = (this as any)._zoneIdMap || new Map();
+    (this as any)._zoneIdMap.set(zoneId, physicZoneId);
+
+    // Store the shape
+    this._attachedShapes.set(zoneId, shape);
+
+    // Update shape position when player moves
+    const updateShapePosition = () => {
+      const currentEntity = map.physic.getEntityByUUID(this.id);
+      if (currentEntity) {
+        const zoneInfo = zoneManager.getZone(physicZoneId);
+        if (zoneInfo) {
+          shape._updatePosition(zoneInfo.position.x, zoneInfo.position.y);
+        }
+      }
+    };
+
+    // Listen to position changes to update shape position
+    playerEntity.onPositionChange(() => {
+      updateShapePosition();
+    });
+
+    return shape;
+  }
+
+  /**
+   * Get all shapes attached to this player
+   * 
+   * Returns all shapes that were created using `attachShape()` on this player.
+   * 
+   * @returns Array of RpgShape instances attached to this player
+   * 
+   * @example
+   * ```ts
+   * player.attachShape("vision", { radius: 150 });
+   * player.attachShape("detection", { radius: 100 });
+   * 
+   * const shapes = player.getShapes();
+   * console.log(shapes.length); // 2
+   * ```
+   */
+  getShapes(): RpgShape[] {
+    return Array.from(this._attachedShapes.values());
+  }
+
+  /**
+   * Get all shapes where this player is currently located
+   * 
+   * Returns all shapes (from any player/event) where this player is currently inside.
+   * This is updated automatically when the player enters or exits shapes.
+   * 
+   * @returns Array of RpgShape instances where this player is located
+   * 
+   * @example
+   * ```ts
+   * // Another player has a detection zone
+   * otherPlayer.attachShape("detection", { radius: 200 });
+   * 
+   * // Check if this player is in any shape
+   * const inShapes = player.getInShapes();
+   * if (inShapes.length > 0) {
+   *   console.log("Player is being detected!");
+   * }
+   * ```
+   */
+  getInShapes(): RpgShape[] {
+    return Array.from(this._inShapes);
   }
 
-  broadcastEffect(id: string, params: any) {
+  /**
+   * Show a temporary component animation on this player
+   * 
+   * This method broadcasts a component animation to all clients, allowing
+   * temporary visual effects like hit indicators, spell effects, or status animations
+   * to be displayed on the player.
+   * 
+   * @param id - The ID of the component animation to display
+   * @param params - Parameters to pass to the component animation
+   * 
+   * @example
+   * ```ts
+   * // Show a hit animation with damage text
+   * player.showComponentAnimation("hit", {
+   *   text: "150",
+   *   color: "red"
+   * });
+   * 
+   * // Show a heal animation
+   * player.showComponentAnimation("heal", {
+   *   amount: 50
+   * });
+   * ```
+   */
+  showComponentAnimation(id: string, params: any = {}) {
     const map = this.getCurrentMap();
     if (!map) return;
     map.$broadcast({
-      type: "showEffect",
+      type: "showComponentAnimation",
       value: {
         id,
         params,
@@ -242,17 +950,333 @@ export class RpgPlayer extends PlayerMixins(RpgCommonPlayer) {
   }
 
   showHit(text: string) {
-    this.broadcastEffect("hit", {
+    this.showComponentAnimation("hit", {
       text,
       direction: this.direction(),
     });
   }
+
+  /**
+   * Play a sound on the client side for this player only
+   * 
+   * This method emits an event to play a sound only for this specific player.
+   * The sound must be defined on the client side (in the client module configuration).
+   * 
+   * ## Design
+   * 
+   * The sound is sent only to this player's client connection, making it ideal
+   * for personal feedback sounds like UI interactions, notifications, or personal
+   * achievements. For map-wide sounds that all players should hear, use `map.playSound()` instead.
+   * 
+   * @param soundId - Sound identifier, defined on the client side
+   * @param options - Optional sound configuration
+   * @param options.volume - Volume level (0.0 to 1.0, default: 1.0)
+   * @param options.loop - Whether the sound should loop (default: false)
+   * 
+   * @example
+   * ```ts
+   * // Play a sound for this player only (default behavior)
+   * player.playSound("item-pickup");
+   * 
+   * // Play a sound with volume and loop
+   * player.playSound("background-music", {
+   *   volume: 0.5,
+   *   loop: true
+   * });
+   * 
+   * // Play a notification sound at low volume
+   * player.playSound("notification", { volume: 0.3 });
+   * ```
+   */
+  playSound(soundId: string, options?: { volume?: number; loop?: boolean }): void {
+    const map = this.getCurrentMap();
+    if (!map) return;
+
+    const data: any = {
+      soundId,
+    };
+
+    if (options) {
+      if (options.volume !== undefined) {
+        data.volume = Math.max(0, Math.min(1, options.volume));
+      }
+      if (options.loop !== undefined) {
+        data.loop = options.loop;
+      }
+    }
+
+    // Send only to this player
+    this.emit("playSound", data);
+  }
+
+  /**
+   * Stop a sound that is currently playing for this player
+   * 
+   * This method stops a sound that was previously started with `playSound()`.
+   * The sound must be defined on the client side.
+   * 
+   * @param soundId - Sound identifier to stop
+   * 
+   * @example
+   * ```ts
+   * // Start a looping background music
+   * player.playSound("background-music", { loop: true });
+   * 
+   * // Later, stop it
+   * player.stopSound("background-music");
+   * ```
+   */
+  stopSound(soundId: string): void {
+    const map = this.getCurrentMap();
+    if (!map) return;
+
+    const data = {
+      soundId,
+    };
+
+    // Send stop command only to this player
+    this.emit("stopSound", data);
+  }
+
+  /**
+   * Stop all currently playing sounds for this player
+   * 
+   * This method stops all sounds that are currently playing for the player.
+   * Useful when changing maps to prevent sound overlap.
+   * 
+   * @example
+   * ```ts
+   * // Stop all sounds before changing map
+   * player.stopAllSounds();
+   * await player.changeMap("new-map");
+   * ```
+   */
+  stopAllSounds(): void {
+    const map = this.getCurrentMap();
+    if (!map) return;
+
+    // Send stop all command only to this player
+    this.emit("stopAllSounds", {});
+  }
+
+  /**
+   * Make the camera follow another player or event
+   * 
+   * This method sends an instruction to the client to fix the viewport on another sprite.
+   * The camera will follow the specified player or event, with optional smooth animation.
+   * 
+   * ## Design
+   * 
+   * The camera follow instruction is sent only to this player's client connection.
+   * This allows each player to have their own camera target, useful for cutscenes,
+   * following NPCs, or focusing on specific events.
+   * 
+   * @param otherPlayer - The player or event that the camera should follow
+   * @param options - Camera follow options
+   * @param options.smoothMove - Enable smooth animation. Can be a boolean (default: true) or an object with animation parameters
+   * @param options.smoothMove.time - Time duration for the animation in milliseconds (optional)
+   * @param options.smoothMove.ease - Easing function name. Visit https://easings.net for available functions (optional)
+   * 
+   * @example
+   * ```ts
+   * // Follow another player with default smooth animation
+   * player.cameraFollow(otherPlayer, { smoothMove: true });
+   * 
+   * // Follow an event with custom smooth animation
+   * player.cameraFollow(npcEvent, {
+   *   smoothMove: {
+   *     time: 1000,
+   *     ease: "easeInOutQuad"
+   *   }
+   * });
+   * 
+   * // Follow without animation (instant)
+   * player.cameraFollow(targetPlayer, { smoothMove: false });
+   * ```
+   */
+  cameraFollow(
+    otherPlayer: RpgPlayer | RpgEvent,
+    options?: {
+      smoothMove?: boolean | { time?: number; ease?: string };
+    }
+  ): void {
+    const map = this.getCurrentMap();
+    if (!map) return;
+
+    const data: any = {
+      targetId: otherPlayer.id,
+    };
+
+    // Handle smoothMove option
+    if (options?.smoothMove !== undefined) {
+      if (typeof options.smoothMove === "boolean") {
+        data.smoothMove = options.smoothMove;
+      } else {
+        // smoothMove is an object
+        data.smoothMove = {
+          enabled: true,
+          ...options.smoothMove,
+        };
+      }
+    } else {
+      // Default to true if not specified
+      data.smoothMove = true;
+    }
+
+    // Send camera follow instruction only to this player
+    this.emit("cameraFollow", data);
+  }
+
+
+  /**
+   * Trigger a flash animation on this player
+   * 
+   * This method sends a flash animation event to the client, creating a visual
+   * feedback effect on the player's sprite. The flash can be configured with
+   * various options including type (alpha, tint, or both), duration, cycles, and color.
+   * 
+   * ## Design
+   * 
+   * The flash is sent as a broadcast event to all clients viewing this player.
+   * This is useful for visual feedback when the player takes damage, receives
+   * a buff, or when an important event occurs.
+   * 
+   * @param options - Flash configuration options
+   * @param options.type - Type of flash effect: 'alpha' (opacity), 'tint' (color), or 'both' (default: 'alpha')
+   * @param options.duration - Duration of the flash animation in milliseconds (default: 300)
+   * @param options.cycles - Number of flash cycles (flash on/off) (default: 1)
+   * @param options.alpha - Alpha value when flashing, from 0 to 1 (default: 0.3)
+   * @param options.tint - Tint color when flashing as hex value or color name (default: 0xffffff - white)
+   * 
+   * @example
+   * ```ts
+   * // Simple flash with default settings (alpha flash)
+   * player.flash();
+   * 
+   * // Flash with red tint when taking damage
+   * player.flash({ type: 'tint', tint: 0xff0000 });
+   * 
+   * // Flash with both alpha and tint for dramatic effect
+   * player.flash({ 
+   *   type: 'both', 
+   *   alpha: 0.5, 
+   *   tint: 0xff0000,
+   *   duration: 200,
+   *   cycles: 2
+   * });
+   * 
+   * // Quick damage flash
+   * player.flash({ 
+   *   type: 'tint', 
+   *   tint: 'red', 
+   *   duration: 150,
+   *   cycles: 1
+   * });
+   * ```
+   */
+  flash(options?: {
+    type?: 'alpha' | 'tint' | 'both';
+    duration?: number;
+    cycles?: number;
+    alpha?: number;
+    tint?: number | string;
+  }): void {
+    const map = this.getCurrentMap();
+    if (!map) return;
+
+    const flashOptions = {
+      type: options?.type || 'alpha',
+      duration: options?.duration ?? 300,
+      cycles: options?.cycles ?? 1,
+      alpha: options?.alpha ?? 0.3,
+      tint: options?.tint ?? 0xffffff,
+    };
+
+    map.$broadcast({
+      type: "flash",
+      value: {
+        object: this.id,
+        ...flashOptions,
+      },
+    });
+  }
+
+  /**
+   * Set the hitbox of the player for collision detection
+   * 
+   * This method defines the hitbox used for collision detection in the physics engine.
+   * The hitbox can be smaller or larger than the visual representation of the player,
+   * allowing for precise collision detection.
+   * 
+   * ## Design
+   * 
+   * The hitbox is used by the physics engine to detect collisions with other entities,
+   * static obstacles, and shapes. Changing the hitbox will immediately update the
+   * collision detection without affecting the visual appearance of the player.
+   * 
+   * @param width - Width of the hitbox in pixels
+   * @param height - Height of the hitbox in pixels
+   * 
+   * @example
+   * ```ts
+   * // Set a 20x20 hitbox for precise collision detection
+   * player.setHitbox(20, 20);
+   * 
+   * // Set a larger hitbox for easier collision detection
+   * player.setHitbox(40, 40);
+   * ```
+   */
+  setHitbox(width: number, height: number): void {
+    // Validate inputs
+    if (typeof width !== 'number' || width <= 0) {
+      throw new Error('setHitbox: width must be a positive number');
+    }
+    if (typeof height !== 'number' || height <= 0) {
+      throw new Error('setHitbox: height must be a positive number');
+    }
+
+    // Update hitbox signal
+    this.hitbox.set({
+      w: width,
+      h: height,
+    });
+
+    // Update physics entity if map exists
+    const map = this.getCurrentMap();
+    if (map && map.physic) {
+      const topLeftX = this.x();
+      const topLeftY = this.y();
+      map.updateHitbox(this.id, topLeftX, topLeftY, width, height);
+    }
+  }
+
+  /**
+   * Set the sync schema for the map
+   * @param schema - The schema to set
+   */
+  setSync(schema: any) {
+    for (let key in schema) {
+      this[key] = type(signal(null), key, {
+        syncWithClient: schema[key]?.$syncWithClient,
+        persist: schema[key]?.$permanent,
+      }, this)
+    }
+  }
+
+  isEvent(): boolean {
+    return false;
+  }
 }
 
 export class RpgEvent extends RpgPlayer {
+
+  constructor() {
+    super();
+    this.onGameStart()
+  }
+
   override async execMethod(methodName: string, methodData: any[] = [], instance = this) {
-    const hooks = inject<Hooks>(this.context as any, ModulesToken);
-    await lastValueFrom(hooks
+    await lastValueFrom(this.hooks
       .callHooks(`server-event-${methodName}`, instance, ...methodData));
     if (!instance[methodName]) {
       return;
@@ -261,19 +1285,45 @@ export class RpgEvent extends RpgPlayer {
     return ret;
   }
 
+  /**
+   * Remove this event from the map
+   * 
+   * Stops all movements before removing to prevent "unable to resolve entity" errors
+   * from the MovementManager when the entity is destroyed while moving.
+   */
   remove() {
     const map = this.getCurrentMap();
     if (!map) return;
+    
+    // Stop all movements before removing to prevent MovementManager errors
+    this.stopMoveTo();
+    
     map.removeEvent(this.id);
   }
+
+  override isEvent(): boolean {
+    return true;
+  }
 }
 
-export interface RpgPlayer
-  extends RpgCommonPlayer,
-    IComponentManager,
-    IGuiManager,
-    IMoveManager,
-    IGoldManager,
-    IWithVariableManager,
-    IWithParameterManager,
-    IWithSkillManager {}
+
+/**
+ * Interface extension for RpgPlayer
+ * 
+ * Extends the RpgPlayer class with additional interfaces from mixins.
+ * This provides proper TypeScript support for all mixin methods and properties.
+ */
+export interface RpgPlayer extends
+  IVariableManager,
+  IMoveManager,
+  IGoldManager,
+  IComponentManager,
+  IGuiManager,
+  IItemManager,
+  IEffectManager,
+  IParameterManager,
+  IElementManager,
+  ISkillManager,
+  IBattleManager,
+  IClassManager,
+  IStateManager { }