@rpgjs/client 5.0.0-alpha.9 → 5.0.0-beta.10

package/dist/Game/Object.js

@@ -0,0 +1,255 @@
+import { inject } from "../core/inject.js";
+import { RpgClientEngine } from "../RpgClientEngine.js";
+import { signal, trigger } from "canvasengine";
+import { ModulesToken, RpgCommonPlayer } from "@rpgjs/common";
+import { from, map, of, switchMap } from "rxjs";
+//#region src/Game/Object.ts
+var RpgClientObject = class extends RpgCommonPlayer {
+	constructor() {
+		super();
+		this.emitParticleTrigger = trigger();
+		this.particleName = signal("");
+		this.animationCurrentIndex = signal(0);
+		this.animationIsPlaying = signal(false);
+		this._param = signal({});
+		this.frames = [];
+		this.graphicsSignals = signal([]);
+		this.flashTrigger = trigger();
+		this.hooks.callHooks("client-sprite-onInit", this).subscribe();
+		this._frames.observable.subscribe(({ items }) => {
+			if (!this.id) return;
+			const nextFrames = items.flatMap((item) => Array.isArray(item) ? item : [item]);
+			this.frames = [...this.frames, ...nextFrames];
+		});
+		this.graphics.observable.pipe(map(({ items }) => items), switchMap((graphics) => {
+			if (graphics.length === 0) return of([]);
+			return from(Promise.all(graphics.map((graphic) => this.engine.getSpriteSheet(graphic))));
+		})).subscribe((sheets) => {
+			this.graphicsSignals.set(sheets);
+		});
+		this.engine.tick.pipe().subscribe(() => {
+			const frame = this.frames.shift();
+			if (frame) {
+				if (typeof frame.x !== "number" || typeof frame.y !== "number") return;
+				this.engine.scene.setBodyPosition(this.id, frame.x, frame.y, "top-left");
+			}
+		});
+	}
+	/**
+	* Access the shared client hook registry.
+	*
+	* @returns The hook service used to register and trigger client-side hooks.
+	*/
+	get hooks() {
+		return inject(ModulesToken);
+	}
+	/**
+	* Access the current client engine instance.
+	*
+	* @returns The active {@link RpgClientEngine} instance.
+	*/
+	get engine() {
+		return inject(RpgClientEngine);
+	}
+	clearAnimationControls() {
+		if (this.animationSubscription) {
+			this.animationSubscription.unsubscribe();
+			this.animationSubscription = void 0;
+		}
+		if (this.animationResetTimeout) {
+			clearTimeout(this.animationResetTimeout);
+			this.animationResetTimeout = void 0;
+		}
+	}
+	resolveAnimationWait() {
+		const resolve = this.animationWaitResolve;
+		this.animationWaitResolve = void 0;
+		resolve?.();
+	}
+	finishTemporaryAnimation() {
+		const restoreState = this.animationRestoreState;
+		this.clearAnimationControls();
+		this.animationCurrentIndex.set(0);
+		if (restoreState) {
+			this.animationName.set(restoreState.animationName);
+			this.graphics.set([...restoreState.graphics]);
+		}
+		this.animationRestoreState = void 0;
+		this.animationIsPlaying.set(false);
+		this.resolveAnimationWait();
+	}
+	/**
+	* Trigger a flash animation on this sprite
+	* 
+	* This method triggers a flash effect using CanvasEngine's flash directive.
+	* The flash can be configured with various options including type (alpha, tint, or both),
+	* duration, cycles, and color.
+	* 
+	* ## Design
+	* 
+	* The flash uses a trigger system that is connected to the flash directive in the
+	* character component. This allows for flexible configuration and can be triggered
+	* from both server events and client-side code.
+	* 
+	* @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
+	* player.flash({ type: 'tint', tint: 0xff0000 });
+	* 
+	* // Flash with both alpha and tint
+	* player.flash({ 
+	*   type: 'both', 
+	*   alpha: 0.5, 
+	*   tint: 0xff0000,
+	*   duration: 200,
+	*   cycles: 2
+	* });
+	* 
+	* // Quick damage flash
+	* player.flash({ 
+	*   type: 'tint', 
+	*   tint: 0xff0000, 
+	*   duration: 150,
+	*   cycles: 1
+	* });
+	* ```
+	*/
+	flash(options) {
+		const flashOptions = {
+			type: options?.type || "alpha",
+			duration: options?.duration ?? 300,
+			cycles: options?.cycles ?? 1,
+			alpha: options?.alpha ?? .3,
+			tint: options?.tint ?? 16777215
+		};
+		let tintValue = flashOptions.tint;
+		if (typeof tintValue === "string") tintValue = {
+			"white": 16777215,
+			"red": 16711680,
+			"green": 65280,
+			"blue": 255,
+			"yellow": 16776960,
+			"cyan": 65535,
+			"magenta": 16711935,
+			"black": 0
+		}[tintValue.toLowerCase()] ?? 16777215;
+		this.flashTrigger.start({
+			...flashOptions,
+			tint: tintValue
+		});
+	}
+	/**
+	* Reset animation state when animation changes externally
+	*
+	* This method should be called when the animation changes due to movement
+	* or other external factors to ensure the animation system doesn't get stuck
+	*
+	* @example
+	* ```ts
+	* // Reset when player starts moving
+	* player.resetAnimationState();
+	* ```
+	*/
+	resetAnimationState() {
+		if (this.animationRestoreState) {
+			this.finishTemporaryAnimation();
+			return;
+		}
+		this.animationIsPlaying.set(false);
+		this.animationCurrentIndex.set(0);
+		this.clearAnimationControls();
+		this.resolveAnimationWait();
+	}
+	setAnimation(animationName, graphicOrNbTimes, nbTimesOrOptions, options) {
+		let graphic;
+		let finalNbTimes = Infinity;
+		let restoreOptions = options;
+		if (typeof graphicOrNbTimes === "number") {
+			finalNbTimes = graphicOrNbTimes;
+			restoreOptions = typeof nbTimesOrOptions === "object" ? nbTimesOrOptions : options;
+		} else if (graphicOrNbTimes !== void 0) {
+			graphic = graphicOrNbTimes;
+			if (typeof nbTimesOrOptions === "number") finalNbTimes = nbTimesOrOptions;
+			else {
+				finalNbTimes = Infinity;
+				restoreOptions = nbTimesOrOptions ?? options;
+			}
+		} else finalNbTimes = Infinity;
+		if (this.animationIsPlaying()) this.finishTemporaryAnimation();
+		const waitPromise = finalNbTimes === Infinity ? Promise.resolve() : new Promise((resolve) => {
+			this.animationWaitResolve = resolve;
+		});
+		this.animationIsPlaying.set(true);
+		const previousAnimationName = restoreOptions?.restoreAnimationName ?? this.animationName();
+		const previousGraphics = restoreOptions?.restoreGraphics ? [...restoreOptions.restoreGraphics] : [...this.graphics()];
+		this.animationRestoreState = {
+			animationName: previousAnimationName,
+			graphics: previousGraphics
+		};
+		this.animationCurrentIndex.set(0);
+		if (graphic !== void 0) if (Array.isArray(graphic)) this.graphics.set(graphic);
+		else this.graphics.set([graphic]);
+		this.clearAnimationControls();
+		this.animationSubscription = this.animationCurrentIndex.observable.subscribe((index) => {
+			if (index >= finalNbTimes) this.finishTemporaryAnimation();
+		});
+		if (finalNbTimes !== Infinity) this.animationResetTimeout = setTimeout(() => {
+			if (this.animationIsPlaying()) this.finishTemporaryAnimation();
+		}, restoreOptions?.timeoutMs ?? Math.max(1e3, finalNbTimes * 1e3));
+		this.animationName.set(animationName);
+		return waitPromise;
+	}
+	/**
+	* Display a registered component animation effect on this object.
+	*
+	* @param id - Identifier of the component animation to play.
+	* @param params - Parameters forwarded to the animation effect.
+	* @returns A promise resolved when the animation component calls `onFinish`.
+	*/
+	showComponentAnimation(id, params) {
+		return inject(RpgClientEngine).getComponentAnimation(id).displayEffect(params, this);
+	}
+	/**
+	* Display a registered spritesheet animation effect on this object.
+	*
+	* @param graphic - Identifier of the spritesheet to use.
+	* @param animationName - Name of the animation inside the spritesheet.
+	* @returns A promise resolved when the animation component calls `onFinish`.
+	*/
+	showAnimation(graphic, animationName = "default") {
+		return this.showComponentAnimation("animation", {
+			graphic,
+			animationName
+		});
+	}
+	/**
+	* Check whether this client object represents an event.
+	*
+	* @returns `true` if the object type is `event`, otherwise `false`.
+	*/
+	isEvent() {
+		return this._type === "event";
+	}
+	/**
+	* Check whether this client object represents a player.
+	*
+	* @returns `true` if the object type is `player`, otherwise `false`.
+	*/
+	isPlayer() {
+		return this._type === "player";
+	}
+};
+//#endregion
+export { RpgClientObject };
+
+//# sourceMappingURL=Object.js.map

package/dist/Game/Object.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Object.js","names":[],"sources":["../../src/Game/Object.ts"],"sourcesContent":["import { Hooks, ModulesToken, RpgCommonPlayer } from \"@rpgjs/common\";\nimport { trigger, signal, type Trigger } from \"canvasengine\";\nimport { from, map, of, Subscription, switchMap } from \"rxjs\";\nimport { inject } from \"../core/inject\";\nimport { RpgClientEngine } from \"../RpgClientEngine\";\ntype Frame = { x: number; y: number; ts: number };\n\ntype AnimationRestoreOptions = {\n  restoreAnimationName?: string;\n  restoreGraphics?: any[];\n  timeoutMs?: number;\n};\n\ntype FlashType = 'alpha' | 'tint' | 'both';\n\ntype FlashOptions = {\n  type?: FlashType;\n  duration?: number;\n  cycles?: number;\n  alpha?: number;\n  tint?: number | string;\n};\n\ntype FlashTriggerOptions = Omit<FlashOptions, \"tint\"> & {\n  tint: number;\n};\n\ntype ConfigurableTrigger<T> = Omit<Trigger<T>, \"start\"> & {\n  start(config?: T): Promise<void>;\n};\n\nexport abstract class RpgClientObject extends RpgCommonPlayer {\n  abstract _type: string;\n  emitParticleTrigger = trigger();\n  particleName = signal(\"\");\n  animationCurrentIndex = signal(0);\n  animationIsPlaying = signal(false);\n  _param = signal({});\n  frames: Frame[] = [];\n  graphicsSignals = signal<any[]>([]);\n  flashTrigger: ConfigurableTrigger<FlashTriggerOptions> = trigger<FlashTriggerOptions>();\n  private animationRestoreState?: {\n    animationName: string;\n    graphics: any[];\n  };\n\n  constructor() {\n    super();\n    this.hooks.callHooks(\"client-sprite-onInit\", this).subscribe();\n\n    this._frames.observable.subscribe(({ items }) => {\n      if (!this.id) return;\n      //if (this.id == this.engine.playerIdSignal()!) return;\n      const nextFrames = items.flatMap((item): Frame[] =>\n        Array.isArray(item) ? item : [item]\n      );\n      this.frames = [...this.frames, ...nextFrames];\n    });\n\n    this.graphics.observable\n    .pipe(\n      map(({ items }) => items),\n      switchMap(graphics => {\n        if (graphics.length === 0) return of([]);\n        return from(Promise.all(graphics.map(graphic => this.engine.getSpriteSheet(graphic))));\n      })\n    )\n    .subscribe((sheets) => {  \n      this.graphicsSignals.set(sheets);\n    });\n\n    this.engine.tick\n      .pipe\n      //throttleTime(10)\n      ()\n      .subscribe(() => {\n        const frame = this.frames.shift();\n        if (frame) {\n          if (typeof frame.x !== \"number\" || typeof frame.y !== \"number\") return;\n          this.engine.scene.setBodyPosition(\n            this.id,\n            frame.x,\n            frame.y,\n            \"top-left\"\n          );\n        }\n      });\n  }\n\n  /**\n   * Access the shared client hook registry.\n   *\n   * @returns The hook service used to register and trigger client-side hooks.\n   */\n  get hooks() {\n    return inject<Hooks>(ModulesToken);\n  }\n\n  /**\n   * Access the current client engine instance.\n   *\n   * @returns The active {@link RpgClientEngine} instance.\n   */\n  get engine() {\n    return inject(RpgClientEngine);\n  }\n\n  private animationSubscription?: Subscription;\n  private animationResetTimeout?: ReturnType<typeof setTimeout>;\n  private animationWaitResolve?: () => void;\n\n  private clearAnimationControls() {\n    if (this.animationSubscription) {\n      this.animationSubscription.unsubscribe();\n      this.animationSubscription = undefined;\n    }\n    if (this.animationResetTimeout) {\n      clearTimeout(this.animationResetTimeout);\n      this.animationResetTimeout = undefined;\n    }\n  }\n\n  private resolveAnimationWait() {\n    const resolve = this.animationWaitResolve;\n    this.animationWaitResolve = undefined;\n    resolve?.();\n  }\n\n  private finishTemporaryAnimation() {\n    const restoreState = this.animationRestoreState;\n    this.clearAnimationControls();\n    this.animationCurrentIndex.set(0);\n    if (restoreState) {\n      this.animationName.set(restoreState.animationName);\n      this.graphics.set([...restoreState.graphics]);\n    }\n    this.animationRestoreState = undefined;\n    this.animationIsPlaying.set(false);\n    this.resolveAnimationWait();\n  }\n\n  /**\n   * Trigger a flash animation on this sprite\n   * \n   * This method triggers a flash effect using CanvasEngine's flash directive.\n   * The flash can be configured with various options including type (alpha, tint, or both),\n   * duration, cycles, and color.\n   * \n   * ## Design\n   * \n   * The flash uses a trigger system that is connected to the flash directive in the\n   * character component. This allows for flexible configuration and can be triggered\n   * from both server events and client-side code.\n   * \n   * @param options - Flash configuration options\n   * @param options.type - Type of flash effect: 'alpha' (opacity), 'tint' (color), or 'both' (default: 'alpha')\n   * @param options.duration - Duration of the flash animation in milliseconds (default: 300)\n   * @param options.cycles - Number of flash cycles (flash on/off) (default: 1)\n   * @param options.alpha - Alpha value when flashing, from 0 to 1 (default: 0.3)\n   * @param options.tint - Tint color when flashing as hex value or color name (default: 0xffffff - white)\n   * \n   * @example\n   * ```ts\n   * // Simple flash with default settings (alpha flash)\n   * player.flash();\n   * \n   * // Flash with red tint\n   * player.flash({ type: 'tint', tint: 0xff0000 });\n   * \n   * // Flash with both alpha and tint\n   * player.flash({ \n   *   type: 'both', \n   *   alpha: 0.5, \n   *   tint: 0xff0000,\n   *   duration: 200,\n   *   cycles: 2\n   * });\n   * \n   * // Quick damage flash\n   * player.flash({ \n   *   type: 'tint', \n   *   tint: 0xff0000, \n   *   duration: 150,\n   *   cycles: 1\n   * });\n   * ```\n   */\n  flash(options?: FlashOptions): void {\n    const flashOptions = {\n      type: options?.type || 'alpha',\n      duration: options?.duration ?? 300,\n      cycles: options?.cycles ?? 1,\n      alpha: options?.alpha ?? 0.3,\n      tint: options?.tint ?? 0xffffff,\n    };\n    \n    // Convert color name to hex if needed\n    let tintValue = flashOptions.tint;\n    if (typeof tintValue === 'string') {\n      // Common color name to hex mapping\n      const colorMap: Record<string, number> = {\n        'white': 0xffffff,\n        'red': 0xff0000,\n        'green': 0x00ff00,\n        'blue': 0x0000ff,\n        'yellow': 0xffff00,\n        'cyan': 0x00ffff,\n        'magenta': 0xff00ff,\n        'black': 0x000000,\n      };\n      tintValue = colorMap[tintValue.toLowerCase()] ?? 0xffffff;\n    }\n    \n    this.flashTrigger.start({\n      ...flashOptions,\n      tint: tintValue,\n    });\n  }\n\n  /**\n   * Reset animation state when animation changes externally\n   *\n   * This method should be called when the animation changes due to movement\n   * or other external factors to ensure the animation system doesn't get stuck\n   *\n   * @example\n   * ```ts\n   * // Reset when player starts moving\n   * player.resetAnimationState();\n   * ```\n   */\n  resetAnimationState() {\n    if (this.animationRestoreState) {\n      this.finishTemporaryAnimation();\n      return;\n    }\n    this.animationIsPlaying.set(false);\n    this.animationCurrentIndex.set(0);\n    this.clearAnimationControls();\n    this.resolveAnimationWait();\n  }\n\n  /**\n   * Set a custom animation for a specific number of times\n   *\n   * Plays a custom animation for the specified number of repetitions.\n   * The animation system prevents overlapping animations and automatically\n   * returns to the previous animation when complete.\n   *\n   * @param animationName - Name of the animation to play\n   * @param nbTimes - Number of times to repeat the animation (default: Infinity for continuous)\n   * @param options - Restore and timeout options\n   * @returns A promise resolved when a finite animation finishes, is interrupted, or times out\n   *\n   * @example\n   * ```ts\n   * // Play attack animation 3 times\n   * await player.setAnimation('attack', 3);\n   *\n   * // Play continuous spell animation\n   * player.setAnimation('spell');\n   * ```\n   */\n  setAnimation(animationName: string, nbTimes?: number, options?: AnimationRestoreOptions): Promise<void>;\n  /**\n   * Set a custom animation with temporary graphic change\n   *\n   * Plays a custom animation for the specified number of repetitions and temporarily\n   * changes the player's graphic (sprite sheet) during the animation. The graphic\n   * is automatically reset when the animation finishes.\n   *\n   * @param animationName - Name of the animation to play\n   * @param graphic - The graphic(s) to temporarily use during the animation\n   * @param nbTimes - Number of times to repeat the animation (default: Infinity for continuous)\n   * @param options - Restore and timeout options\n   * @returns A promise resolved when a finite animation finishes, is interrupted, or times out\n   *\n   * @example\n   * ```ts\n   * // Play attack animation with temporary graphic change\n   * await player.setAnimation('attack', 'hero_attack', 3);\n   * ```\n   */\n  setAnimation(animationName: string, graphic?: string | string[], nbTimes?: number, options?: AnimationRestoreOptions): Promise<void>;\n  setAnimation(\n    animationName: string,\n    graphicOrNbTimes?: string | string[] | number,\n    nbTimesOrOptions?: number | AnimationRestoreOptions,\n    options?: AnimationRestoreOptions\n  ): Promise<void> {\n    let graphic: string | string[] | undefined;\n    let finalNbTimes: number = Infinity;\n    let restoreOptions: AnimationRestoreOptions | undefined = options;\n\n    // Handle overloads\n    if (typeof graphicOrNbTimes === 'number') {\n      // setAnimation(animationName, nbTimes)\n      finalNbTimes = graphicOrNbTimes;\n      restoreOptions = typeof nbTimesOrOptions === 'object' ? nbTimesOrOptions : options;\n    } else if (graphicOrNbTimes !== undefined) {\n      // setAnimation(animationName, graphic, nbTimes)\n      graphic = graphicOrNbTimes;\n      if (typeof nbTimesOrOptions === 'number') {\n        finalNbTimes = nbTimesOrOptions;\n      } else {\n        finalNbTimes = Infinity;\n        restoreOptions = nbTimesOrOptions ?? options;\n      }\n    } else {\n      // setAnimation(animationName) - nbTimes remains Infinity\n      finalNbTimes = Infinity;\n    }\n\n    if (this.animationIsPlaying()) {\n      this.finishTemporaryAnimation();\n    }\n\n    const waitPromise =\n      finalNbTimes === Infinity\n        ? Promise.resolve()\n        : new Promise<void>((resolve) => {\n            this.animationWaitResolve = resolve;\n          });\n\n    this.animationIsPlaying.set(true);\n    const previousAnimationName =\n      restoreOptions?.restoreAnimationName ?? this.animationName();\n    const previousGraphics = restoreOptions?.restoreGraphics\n      ? [...restoreOptions.restoreGraphics]\n      : [...this.graphics()];\n    this.animationRestoreState = {\n      animationName: previousAnimationName,\n      graphics: previousGraphics,\n    };\n    this.animationCurrentIndex.set(0);\n\n    // Temporarily change graphic if provided\n    if (graphic !== undefined) {\n      if (Array.isArray(graphic)) {\n        this.graphics.set(graphic);\n      } else {\n        this.graphics.set([graphic]);\n      }\n    }\n\n    this.clearAnimationControls();\n\n    this.animationSubscription =\n      this.animationCurrentIndex.observable.subscribe((index) => {\n        if (index >= finalNbTimes) {\n          this.finishTemporaryAnimation();\n        }\n      });\n\n    if (finalNbTimes !== Infinity) {\n      this.animationResetTimeout = setTimeout(() => {\n        if (this.animationIsPlaying()) {\n          this.finishTemporaryAnimation();\n        }\n      }, restoreOptions?.timeoutMs ?? Math.max(1000, finalNbTimes * 1000));\n    }\n\n    this.animationName.set(animationName);\n\n    return waitPromise;\n  }\n\n  /**\n   * Display a registered component animation effect on this object.\n   *\n   * @param id - Identifier of the component animation to play.\n   * @param params - Parameters forwarded to the animation effect.\n   * @returns A promise resolved when the animation component calls `onFinish`.\n   */\n  showComponentAnimation(id: string, params: any): Promise<void> {\n    const engine = inject(RpgClientEngine);\n    return engine.getComponentAnimation(id).displayEffect(params, this);\n  }\n\n  /**\n   * Display a registered spritesheet animation effect on this object.\n   *\n   * @param graphic - Identifier of the spritesheet to use.\n   * @param animationName - Name of the animation inside the spritesheet.\n   * @returns A promise resolved when the animation component calls `onFinish`.\n   */\n  showAnimation(graphic: string, animationName: string = 'default'): Promise<void> {\n    return this.showComponentAnimation('animation', {\n      graphic,\n      animationName,\n    });\n  }\n  \n  /**\n   * Check whether this client object represents an event.\n   *\n   * @returns `true` if the object type is `event`, otherwise `false`.\n   */\n  isEvent(): boolean {\n    return this._type === 'event';\n  }\n\n  /**\n   * Check whether this client object represents a player.\n   *\n   * @returns `true` if the object type is `player`, otherwise `false`.\n   */\n  isPlayer(): boolean {\n    return this._type === 'player';\n  }\n}\n"],"mappings":"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"}

package/dist/Game/Player.d.ts

@@ -1,4 +1,4 @@
 import { RpgClientObject } from './Object';
 export declare class RpgClientPlayer extends RpgClientObject {
-    type: string;
+    _type: string;
 }

package/dist/Game/Player.js

@@ -0,0 +1,12 @@
+import { RpgClientObject } from "./Object.js";
+//#region src/Game/Player.ts
+var RpgClientPlayer = class extends RpgClientObject {
+	constructor(..._args) {
+		super(..._args);
+		this._type = "player";
+	}
+};
+//#endregion
+export { RpgClientPlayer };
+
+//# sourceMappingURL=Player.js.map

package/dist/Game/Player.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Player.js","names":[],"sources":["../../src/Game/Player.ts"],"sourcesContent":["import { RpgClientObject } from \"./Object\";\n\nexport class RpgClientPlayer extends RpgClientObject {\n    _type = 'player'\n}   "],"mappings":";;AAEA,IAAa,kBAAb,cAAqC,gBAAgB;;;eACzC;;AACZ"}

package/dist/Gui/Gui.d.ts

@@ -1,23 +1,208 @@
 import { Context } from '@signe/di';
+import { Signal, WritableSignal } from 'canvasengine';
+import { Subscription } from 'rxjs';
 interface GuiOptions {
-    name: string;
-    component: any;
+    name?: string;
+    id?: string;
+    component?: any;
     display?: boolean;
     data?: any;
+    /**
+     * Auto display the GUI when added to the system
+     * @default false
+     */
+    autoDisplay?: boolean;
+    /**
+     * Function that returns an array of Signal dependencies
+     * The GUI will only display when all dependencies are resolved (!= undefined)
+     * @returns Array of Signal dependencies
+     */
+    dependencies?: () => Signal[];
+    /**
+     * Attach the GUI to sprites instead of displaying globally
+     * When true, the GUI will be rendered in character.ce for each sprite
+     * @default false
+     */
+    attachToSprite?: boolean;
+    /**
+     * Vue v4 compatibility flag. Prefer attachToSprite in v5 projects.
+     */
+    rpgAttachToSprite?: boolean;
+}
+export interface GuiInstance {
+    name: string;
+    component: any;
+    display: WritableSignal<boolean>;
+    data: WritableSignal<any>;
+    autoDisplay: boolean;
+    dependencies?: Signal[];
+    subscription?: Subscription;
+    attachToSprite?: boolean;
+}
+interface GuiAction {
+    guiId: string;
+    name: string;
+    data: any;
+    clientActionId: string;
 }
+type OptimisticReducer = (data: any, action: GuiAction) => any;
 export declare class RpgGui {
     private context;
     private webSocket;
-    gui: import('canvasengine').WritableArraySignal<any>;
+    gui: import('canvasengine').WritableObjectSignal<Record<string, GuiInstance>>;
+    extraGuis: GuiInstance[];
+    private vueGuiInstance;
+    private optimisticReducers;
+    private pendingActions;
+    /**
+     * Signal tracking which player IDs should display attached GUIs
+     * Key: player ID, Value: boolean (true = show, false = hide)
+     */
+    attachedGuiDisplayState: import('canvasengine').WritableObjectSignal<Record<string, boolean>>;
     constructor(context: Context);
     _initialize(): Promise<void>;
+    /**
+     * Set the VueGui instance reference for Vue component management
+     * This is called by VueGui when it's initialized
+     *
+     * @param vueGuiInstance - The VueGui instance
+     */
+    _setVueGuiInstance(vueGuiInstance: any): void;
+    /**
+     * Notify VueGui about GUI state changes
+     * This synchronizes the Vue component display state
+     *
+     * @param guiId - The GUI component ID
+     * @param display - Display state
+     * @param data - Component data
+     */
+    private _notifyVueGui;
+    /**
+     * Initialize Vue components in the VueGui instance
+     * This should be called after VueGui is mounted
+     */
+    _initializeVueComponents(): void;
     guiInteraction(guiId: string, name: string, data: any): void;
     guiClose(guiId: string, data?: any): void;
-    add(gui: GuiOptions): void;
-    get(id: string | GuiOptions): any;
+    /**
+     * Add a GUI component to the system
+     *
+     * By default, only CanvasEngine components (.ce files) are accepted.
+     * Vue components should be handled by the @rpgjs/vue package.
+     *
+     * @param gui - GUI configuration options
+     * @param gui.name - Name or ID of the GUI component
+     * @param gui.id - Alternative ID if name is not provided
+     * @param gui.component - The component to render (must be a CanvasEngine component)
+     * @param gui.display - Initial display state (default: false)
+     * @param gui.data - Initial data for the component
+     * @param gui.autoDisplay - Auto display when added (default: false)
+     * @param gui.dependencies - Function returning Signal dependencies
+     * @param gui.attachToSprite - Attach GUI to sprites instead of global display (default: false)
+     *
+     * @example
+     * ```ts
+     * gui.add({
+     *   name: 'inventory',
+     *   component: InventoryComponent, // Must be a .ce component
+     *   autoDisplay: true,
+     *   dependencies: () => [playerSignal, inventorySignal]
+     * });
+     *
+     * // Attach to sprites
+     * gui.add({
+     *   name: 'tooltip',
+     *   component: TooltipComponent,
+     *   attachToSprite: true
+     * });
+     * ```
+     */
+    add(gui: GuiOptions | any): void;
+    registerOptimisticReducer(guiId: string, reducer: OptimisticReducer): void;
+    /**
+     * Get all attached GUI components (attachToSprite: true)
+     *
+     * Returns all GUI instances that are configured to be attached to sprites.
+     * These GUIs should be rendered in character.ce instead of canvas.ce.
+     *
+     * @returns Array of GUI instances with attachToSprite: true
+     *
+     * @example
+     * ```ts
+     * const attachedGuis = gui.getAttachedGuis();
+     * // Use in character.ce to render tooltips
+     * ```
+     */
+    getAttachedGuis(): GuiInstance[];
+    getVueGuis(): GuiInstance[];
+    getAttachedVueGuis(): GuiInstance[];
+    /**
+     * Check if a player should display attached GUIs
+     *
+     * @param playerId - The player ID to check
+     * @returns true if attached GUIs should be displayed for this player
+     */
+    shouldDisplayAttachedGui(playerId: string): boolean;
+    get(id: string): GuiInstance | undefined;
     exists(id: string): boolean;
-    getAll(): any;
-    display(id: string, data?: {}): void;
+    getAll(): Record<string, GuiInstance>;
+    /**
+     * Display a GUI component
+     *
+     * Displays the GUI immediately if no dependencies are configured,
+     * or waits for all dependencies to be resolved if dependencies are present.
+     * Automatically manages subscriptions to prevent memory leaks.
+     * Works with both CanvasEngine components and Vue components.
+     *
+     * @param id - The GUI component ID
+     * @param data - Data to pass to the component
+     * @param dependencies - Optional runtime dependencies (overrides config dependencies)
+     *
+     * @example
+     * ```ts
+     * // Display immediately
+     * gui.display('inventory', { items: [] });
+     *
+     * // Display with runtime dependencies
+     * gui.display('shop', { shopId: 1 }, [playerSignal, shopSignal]);
+     * ```
+     */
+    display(id: string, data?: {}, dependencies?: Signal[]): void;
+    isDisplaying(id: string): boolean;
+    /**
+     * Handle Vue component display logic
+     *
+     * @param id - GUI component ID
+     * @param data - Component data
+     * @param dependencies - Runtime dependencies
+     * @param guiInstance - GUI instance
+     */
+    private _handleVueComponentDisplay;
+    /**
+     * Hide a GUI component
+     *
+     * Hides the GUI and cleans up any active subscriptions.
+     * Works with both CanvasEngine components and Vue components.
+     *
+     * @param id - The GUI component ID
+     *
+     * @example
+     * ```ts
+     * gui.hide('inventory');
+     * ```
+     */
     hide(id: string): void;
+    private isVueComponent;
+    private isVueComponentInstance;
+    private removeCanvasGui;
+    private removeVueGui;
+    private resolveComponent;
+    private resolveGuiId;
+    private resolveAttachToSprite;
+    private toGuiState;
+    private clearPendingActions;
+    private applyReducers;
+    private applyOptimisticAction;
+    private applyServerUpdate;
 }
 export {};