@rpgjs/server 5.0.0-alpha.21 → 5.0.0-alpha.23

package/src/Player/Player.ts

@@ -172,6 +172,11 @@ export class RpgPlayer extends BasicPlayerMixins(RpgCommonPlayer) {
     return inject<Hooks>(this.context as any, ModulesToken);
   }
 
+  // compatibility with v4
+  get server() {
+    return this.map
+  }
+
   applyFrames() {
     this._frames.set(this.frames)
     this.frames = []
@@ -862,6 +867,218 @@ export class RpgPlayer extends BasicPlayerMixins(RpgCommonPlayer) {
     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

package/src/Player/SkillManager.ts

@@ -61,50 +61,11 @@ export function WithSkillManager<TBase extends PlayerCtor>(Base: TBase) {
       });
     }
 
-    /**
-     * Retrieves a learned skill. Returns null, if not found
-     * ```ts
-     * import Fire from 'your-database/skills/fire'
-     *
-     * player.getSkill(Fire)
-     *  ```
-     *
-     * @title Get Skill
-     * @method player.getSkill(skillClass)
-     * @param {SkillClass | string} skillClass or data id
-     * @returns {instance of SkillClass | null}
-     * @memberof SkillManager
-     */
     getSkill(skillClass: any | string) {
       const index = this._getSkillIndex(skillClass);
       return this.skills()[index] ?? null;
     }
 
-    /**
-         * Learn a skill. Attributes the coefficient 1 to the parameter INT (intelligence) if cd is not present on the class.
-         * 
-         * `onLearn()` method is called on the SkillClass
-         * 
-         * ```ts
-         * import Fire from 'your-database/skills/fire'
-         * 
-         * player.learnSkill(Fire)
-         *  ```
-         * 
-         * @title Learn Skill
-         * @method player.learnSkill(skillClass)
-         * @param {SkillClass | string} skillId or data id
-         * @throws {SkillLog} alreadyLearned
-         *  If the player already knows the skill
-         *  ```
-            {
-                id: SKILL_ALREADY_LEARNED,
-                msg: '...'
-            }
-            ```
-         * @returns {instance of SkillClass}
-         * @memberof SkillManager
-         */
     learnSkill(skillId: any | string) {
       if (this.getSkill(skillId)) {
         throw SkillLog.alreadyLearned(skillId);
@@ -115,36 +76,6 @@ export function WithSkillManager<TBase extends PlayerCtor>(Base: TBase) {
       return instance;
     }
 
-    /**
-     * Forget a skill
-     *
-     * `onForget()` method is called on the SkillClass
-     *
-     * ```ts
-     * import Fire from 'your-database/skills/fire'
-     *
-     * try {
-     *      player.forgetSkill(Fire)
-     * }
-     * catch (err) {
-     *      console.log(err)
-     * }
-     *  ```
-     *
-     * @title Forget Skill
-     * @method player.learnSkill(skillClass)
-     * @param {SkillClass | string} skillId or data id
-     * @throws {SkillLog} notLearned
-     * If trying to forget a skill not learned
-     *  ```
-     * {
-     *      id: SKILL_NOT_LEARNED,
-     *      msg: '...'
-     * }
-     * ```
-     * @returns {instance of SkillClass}
-     * @memberof SkillManager
-     */
     forgetSkill(skillId: any | string) {
       if (isString(skillId)) skillId = (this as any).databaseById(skillId);
       const index = this._getSkillIndex(skillId);
@@ -157,81 +88,6 @@ export function WithSkillManager<TBase extends PlayerCtor>(Base: TBase) {
       return instance;
     }
 
-    /**
-     * Using a skill
-     *
-     * `onUse()` method is called on the SkillClass
-     *
-     * If other players are indicated then damage will be done to these other players. The method `applyDamage()` will be executed
-     *
-     * ```ts
-     * import Fire from 'your-database/skills/fire'
-     *
-     * try {
-     *      player.useSkill(Fire)
-     * }
-     * catch (err) {
-     *      console.log(err)
-     * }
-     *  ```
-     *
-     * or
-     *
-     *
-     * * ```ts
-     * import Fire from 'your-database/skills/fire'
-     *
-     * try {
-     *      player.useSkill(Fire, otherPlayer)
-     * }
-     * catch (err) {
-     *      console.log(err)
-     * }
-     *  ```
-     *
-     * @title Use Skill
-     * @method player.useSkill(skillClass,otherPlayer)
-     * @param {SkillClass | string} skillId or data id
-     * @param {Array<RpgPlayer> | RpgPlayer} [otherPlayer]
-     * @throws {SkillLog} restriction
-     * If the player has the `Effect.CAN_NOT_SKILL` effect
-     *  ```
-     * {
-     *      id: RESTRICTION_SKILL,
-     *      msg: '...'
-     * }
-     * ```
-     * @throws {SkillLog} notLearned
-     * If the player tries to use an unlearned skill
-     *  ```
-     * {
-     *      id: SKILL_NOT_LEARNED,
-     *      msg: '...'
-     * }
-     * ```
-     * @throws {SkillLog} notEnoughSp
-     * If the player does not have enough SP to use the skill
-     *  ```
-     * {
-     *      id: NOT_ENOUGH_SP,
-     *      msg: '...'
-     * }
-     * ```
-     * @throws {SkillLog} chanceToUseFailed
-     * If the chance to use the skill has failed (defined with the `hitRate` property)
-     *  ```
-     * {
-     *      id: USE_CHANCE_SKILL_FAILED,
-     *      msg: '...'
-     * }
-     * ```
-     *
-     * `onUseFailed()` method is called on the SkillClass
-     *
-     * @returns {instance of SkillClass}
-     * @memberof SkillManager
-     * @todo
-     */
     useSkill(skillId: any | string, otherPlayer?: RpgPlayer | RpgPlayer[]) {
       const skill = this.getSkill(skillId);
       if ((this as any).hasEffect(Effect.CAN_NOT_SKILL)) {
@@ -266,7 +122,48 @@ export function WithSkillManager<TBase extends PlayerCtor>(Base: TBase) {
 }
 
 /**
- * Type helper to extract the interface from the WithSkillManager mixin
- * This provides the type without duplicating method signatures
+ * Interface for Skill Manager functionality
+ * 
+ * Provides skill management capabilities including learning, forgetting, and using skills.
+ * This interface defines the public API of the SkillManager mixin.
  */
-export type ISkillManager = InstanceType<ReturnType<typeof WithSkillManager>>;
+export interface ISkillManager {
+  /**
+   * Retrieves a learned skill. Returns null if not found
+   * 
+   * @param skillClass - Skill class or data id
+   * @returns Instance of SkillClass or null
+   */
+  getSkill(skillClass: any | string): any | null;
+
+  /**
+   * Learn a skill
+   * 
+   * @param skillId - Skill class or data id
+   * @returns Instance of SkillClass
+   * @throws SkillLog.alreadyLearned if the player already knows the skill
+   */
+  learnSkill(skillId: any | string): any;
+
+  /**
+   * Forget a skill
+   * 
+   * @param skillId - Skill class or data id
+   * @returns Instance of SkillClass
+   * @throws SkillLog.notLearned if trying to forget a skill not learned
+   */
+  forgetSkill(skillId: any | string): any;
+
+  /**
+   * Using a skill
+   * 
+   * @param skillId - Skill class or data id
+   * @param otherPlayer - Optional target player(s) to apply skill to
+   * @returns Instance of SkillClass
+   * @throws SkillLog.restriction if player has Effect.CAN_NOT_SKILL
+   * @throws SkillLog.notLearned if player tries to use an unlearned skill
+   * @throws SkillLog.notEnoughSp if player does not have enough SP
+   * @throws SkillLog.chanceToUseFailed if the chance to use the skill has failed
+   */
+  useSkill(skillId: any | string, otherPlayer?: RpgPlayer | RpgPlayer[]): any;
+}