@rpgjs/server 5.0.0-alpha.18 → 5.0.0-alpha.19

package/dist/Player/ItemManager.d.ts

@@ -1,4 +1,144 @@
 import { PlayerCtor } from '@rpgjs/common';
+import { RpgPlayer } from './Player';
+/**
+ * Interface defining the hooks that can be implemented on item classes or objects
+ *
+ * These hooks are called at specific moments during the item lifecycle:
+ * - `onAdd`: When the item is added to the player's inventory
+ * - `onUse`: When the item is successfully used
+ * - `onUseFailed`: When the item usage fails (e.g., chance roll failed)
+ * - `onRemove`: When the item is removed from the inventory
+ * - `onEquip`: When the item is equipped or unequipped
+ *
+ * @example
+ * ```ts
+ * const itemHooks: ItemHooks = {
+ *   onAdd(player) {
+ *     console.log('Item added to inventory');
+ *   },
+ *   onUse(player) {
+ *     player.hp += 100;
+ *   }
+ * };
+ * ```
+ */
+export interface ItemHooks {
+    /**
+     * Called when the item is added to the player's inventory
+     *
+     * @param player - The player receiving the item
+     */
+    onAdd?: (player: RpgPlayer) => void | Promise<void>;
+    /**
+     * Called when the item is successfully used
+     *
+     * @param player - The player using the item
+     */
+    onUse?: (player: RpgPlayer) => void | Promise<void>;
+    /**
+     * Called when the item usage fails (e.g., chance roll failed)
+     *
+     * @param player - The player attempting to use the item
+     */
+    onUseFailed?: (player: RpgPlayer) => void | Promise<void>;
+    /**
+     * Called when the item is removed from the inventory
+     *
+     * @param player - The player losing the item
+     */
+    onRemove?: (player: RpgPlayer) => void | Promise<void>;
+    /**
+     * Called when the item is equipped or unequipped
+     *
+     * @param player - The player equipping/unequipping the item
+     * @param equip - true if equipping, false if unequipping
+     */
+    onEquip?: (player: RpgPlayer, equip: boolean) => void | Promise<void>;
+}
+/**
+ * Base properties that can be included in an item object
+ *
+ * This interface defines the common properties that items can have.
+ * Use this as a base and extend it with specific item types.
+ *
+ * @template T - Additional properties specific to the item type
+ *
+ * @example
+ * ```ts
+ * interface PotionData extends ItemData {
+ *   hpValue: number;
+ *   mpValue: number;
+ * }
+ *
+ * const potion: ItemObject<PotionData> = {
+ *   name: 'Health Potion',
+ *   description: 'Restores 100 HP',
+ *   price: 200,
+ *   hpValue: 100,
+ *   mpValue: 0,
+ *   onUse(player) {
+ *     player.hp += this.hpValue;
+ *   }
+ * };
+ * ```
+ */
+export interface ItemData {
+    /** Item name */
+    name?: string;
+    /** Item description */
+    description?: string;
+    /** Item price */
+    price?: number;
+    /** HP value restored when used */
+    hpValue?: number;
+    /** MP/SP value restored when used */
+    mpValue?: number;
+    /** Chance to successfully use the item (0-1) */
+    hitRate?: number;
+    /** Whether the item is consumable */
+    consumable?: boolean;
+    /** States to add when used */
+    addStates?: any[];
+    /** States to remove when used */
+    removeStates?: any[];
+    /** Elemental properties */
+    elements?: any[];
+    /** Parameter modifiers */
+    paramsModifier?: Record<string, any>;
+    /** Item type (for equipment validation) */
+    _type?: 'item' | 'weapon' | 'armor';
+}
+/**
+ * Item object type that combines data properties with hooks
+ *
+ * This type allows you to create item objects directly without needing a class.
+ * The object can contain both item data properties and lifecycle hooks.
+ *
+ * @template T - Additional properties specific to the item type (extends ItemData)
+ *
+ * @example
+ * ```ts
+ * const potion: ItemObject = {
+ *   name: 'Health Potion',
+ *   description: 'Restores 100 HP',
+ *   price: 200,
+ *   hpValue: 100,
+ *   consumable: true,
+ *   onAdd(player) {
+ *     console.log('Potion added!');
+ *   },
+ *   onUse(player) {
+ *     player.hp += 100;
+ *   }
+ * };
+ *
+ * player.addItem(potion);
+ * ```
+ */
+export type ItemObject<T extends ItemData = ItemData> = T & ItemHooks & {
+    /** Item identifier (required if not using class or string) */
+    id?: string;
+};
 /**
  * Item Manager Mixin
  *

package/dist/decorators/event.d.ts

@@ -0,0 +1,46 @@
+export declare enum EventMode {
+    Shared = "shared",
+    Scenario = "scenario"
+}
+export interface EventOptions {
+    /**
+     * The mode of the event, shared evening or scenario
+     *
+     * The scenario mode allows you to have events specific to the player. Thus, the graphics, the positions of the event will be different for each player. Beware of performance! The event is duplicated by each player.
+     *
+     * `shared` mode by default
+     *
+     * ```ts
+     * import { RpgEvent, EventData, RpgPlayer, EventMode } from '@rpgjs/server'
+     * @EventData({
+     *      name: 'EV-1',
+     *      mode: EventMode.Scenario // or EventMode.Shared
+     * })
+     * export class CharaEvent extends RpgEvent { }
+     * ```
+     *
+     * @prop {string} [mode] Either "shared" or "scenario".
+     * @memberof EventData
+     * */
+    mode?: EventMode;
+    width?: number;
+    height?: number;
+    /**
+     * The hitbox of the event. By default, this is the size of the tile of the map
+     *
+     * @prop { { width: number, height: number }} [hitbox]
+     * @memberof EventData
+     * */
+    hitbox?: {
+        width?: number;
+        height?: number;
+    };
+    /**
+     * Name of the event. This is its identifier. it allows you to retrieve an event and place it on the map
+     *
+     * @prop {string} name
+     * @memberof EventData
+     * */
+    name: string;
+}
+export declare function EventData(options: EventOptions): (target: any) => void;

package/dist/decorators/map.d.ts

@@ -0,0 +1,177 @@
+export interface MapOptions {
+    /**
+     * Map identifier. Allows to go to the map (for example with player.changeMap())
+     *
+     * @prop {string} [id]
+     * @memberof MapData
+     * */
+    id?: string;
+    /**
+    * the path to the .tmx file (Tiled Map Editor)
+    *
+    * Remember to use `require()` function
+    *
+    * ```ts
+    * import { MapData, RpgMap } from '@rpgjs/server'
+    *
+    * @MapData({
+    *      id: 'town',
+    *      file: require('./tmx/town.tmx')
+    * })
+    * class TownMap extends RpgMap { }
+    * ```
+    * @prop {string} file
+    * @memberof MapData
+    * */
+    file: any;
+    /**
+     * The name of the map.
+     * @prop {string} [name]
+     * @memberof MapData
+     * */
+    name?: string;
+    /**
+    * Map events. This is an array containing `RpgEvent` classes.
+    * You can also give an object that will indicate the positions of the event on the map.
+    *
+    * ```ts
+    * import { MapData, RpgMap, EventData, RpgEvent } from '@rpgjs/server'
+    *
+    * @EventData({
+    *      name: 'Ev-1'
+    * })
+    * class NpcEvent extends RpgEvent { }
+    *
+    * @MapData({
+    *      id: 'medieval',
+    *      file: require('./tmx/town.tmx'),
+    *      events: [NpcEvent]
+    * })
+    * class TownMap extends RpgMap {}
+    * ```
+    *
+    * If the positions are not defined, the event will be placed on a Tiled Map Editor shape ([/guide/create-event.html#position-the-event-on-the-map](Guide)). Otherwise, it will be placed at `{x:0, y:0 }`
+    *
+    * You can give positions:
+    *
+    * ```ts
+    * events: [{ event: NpcEvent, x: 10, y: 30 }]
+    * ```
+    *
+    * @prop {Class of RpgEvent[] | { event: Class RpgEvent, x: number, y: number }} [events]
+    * @memberof MapData
+    * */
+    events?: {
+        event: any;
+        x: number;
+        y: number;
+    }[] | any[];
+    /**
+     * The sounds that will be played when the map is open. Sounds must be defined on the client side. Then, put the name of the sound identifier
+     *
+     * So, it is possible to play several sounds (in loop or not) on the card. You can put a background music (BGM) and a background noise (BGS) for example
+     *
+     *  ```ts
+     * sounds: ['my-bgm', 'my-bgs']
+     * ```
+     *
+     * And client side:
+     *
+     * ```ts
+     * import { Sound } from '@rpgjs/client'
+     *
+     * @Sound({
+     *      sounds: {
+     *          'my-bgm': require('./assets/bgm.ogg'),
+     *          'my-bgs': require('./assets/bgs.ogg')
+     *      },
+     *      loop: true
+     * })
+     * export class Sounds {}
+     * ```
+     *
+     * See [https://docs.rpgjs.dev/classes/sound.html#properties](RpgSound Decorator)
+     *
+     * @prop {Array<string>} [sounds]
+     * @memberof MapData
+     * */
+    sounds?: string[];
+    /**
+     * Specify which properties will be synchronized with the client. On the client side, you can retrieve the values synchronized with the valueChanges property on the scene
+     *
+     * You must create the schema:
+     *
+     * ```ts
+     * import { MapData, RpgMap } from '@rpgjs/server'
+     *
+     * @MapData({
+     *      id: 'medieval',
+     *      file: require('./tmx/town.tmx'),
+     *      syncSchema: {
+     *          count: Number
+     *      }
+     * })
+     * export class TownMap extends RpgMap {
+     *      count: number = 0
+     *
+     *      onLoad() {}
+     *
+     *      onJoin() {
+     *          this.count++
+     *      }
+     *
+     *      onLeave(player) {
+     *          super.onLeave(player)
+     *          this.count--
+     *      }
+     * }
+     *
+     * ```
+     *
+     * If you want to change the scheme of players and events, consider overwriting the existing scheme
+     *
+     *  ```ts
+     * import { MapData, RpgMap, RpgPlayer } from '@rpgjs/server'
+     *
+     *
+     * declare module '@rpgjs/server' {
+     *  export interface RpgPlayer {
+     *      customProp: string
+     *  }
+     * }
+     *
+     * @MapData({
+     *      id: 'medieval',
+     *      file: require('./tmx/town.tmx'),
+     *      syncSchema: {
+     *          users: [
+     *              {
+     *                  customProp: String,
+     *                  ...RpgPlayer.schemas
+     *              }
+     *          ]
+     *      }
+     * })
+     * export class TownMap extends RpgMap {}
+     * ```
+     *
+     * The properties are called `users` and `events`. Their scheme is identical and defined in `RpgPlayer.schemas`. To write schematics, refer to the [documentation of the simple-room](https://github.com/RSamaium/simple-room) module
+     *
+     * @prop {object} [syncSchema]
+     * @memberof MapData
+     * */
+    syncSchema?: any;
+    /**
+     * Decreases the RAM of the map. In this case, some instructions will be different.
+     *
+     * `map.getTileByIndex()` will not return all tiles of an index but only the tile of the highest layer
+     *
+     * > You can also use the `low-memory` property in Tiled maps
+     *
+     * @prop {boolean} [lowMemory=false]
+     * @since 3.1.0
+     * @memberof MapData
+     * */
+    lowMemory?: boolean;
+}
+export declare function MapData(options: MapOptions): (target: any) => void;

package/dist/index.d.ts

@@ -10,4 +10,4 @@ export * from './rooms/map';
 export * from './presets';
 export * from '@signe/reactive';
 export * from './Gui';
-export { RpgShape } from '@rpgjs/common';
+export { RpgShape, RpgModule } from '@rpgjs/common';