@rpgjs/client 5.0.0-beta.2 → 5.0.0-beta.20

package/src/Gui/Gui.ts

@@ -3,12 +3,12 @@ import { signal, Signal, WritableSignal } from "canvasengine";
 import { AbstractWebsocket, WebSocketToken } from "../services/AbstractSocket";
 import { DialogboxComponent, ShopComponent, SaveLoadComponent, MainMenuComponent, NotificationComponent, TitleScreenComponent, GameoverComponent } from "../components/gui";
 import { combineLatest, Subscription } from "rxjs";
-import { delay, PrebuiltGui } from "@rpgjs/common";
+import { PrebuiltGui } from "@rpgjs/common";
 
 interface GuiOptions {
   name?: string;
   id?: string;
-  component: any;
+  component?: any;
   display?: boolean;
   data?: any;
   /**
@@ -28,19 +28,38 @@ interface GuiOptions {
    * @default false
    */
   attachToSprite?: boolean;
+  /**
+   * Vue v4 compatibility flag. Prefer attachToSprite in v5 projects.
+   */
+  rpgAttachToSprite?: boolean;
 }
 
-interface GuiInstance {
+export interface GuiInstance {
   name: string;
   component: any;
   display: WritableSignal<boolean>;
   data: WritableSignal<any>;
+  openId?: string;
   autoDisplay: boolean;
-  dependencies?: () => Signal[];
+  dependencies?: Signal[];
   subscription?: Subscription;
   attachToSprite?: boolean;
 }
 
+type GuiState = {
+  name: string;
+  component: any;
+  display: boolean;
+  data: any;
+  openId?: string;
+  attachToSprite: boolean;
+};
+
+type VueGuiBridge = {
+  updateGuiState?: (state: GuiState) => void;
+  initializeGuiStates?: (states: GuiState[]) => void;
+};
+
 interface GuiAction {
   guiId: string;
   name: string;
@@ -117,7 +136,7 @@ export class RpgGui {
   private webSocket: AbstractWebsocket;
   gui = signal<Record<string, GuiInstance>>({});
   extraGuis: GuiInstance[] = [];
-  private vueGuiInstance: any = null; // Reference to VueGui instance
+  private vueGuiInstance: VueGuiBridge | null = null;
   private optimisticReducers = new Map<string, OptimisticReducer[]>();
   private pendingActions = new Map<string, GuiAction[]>();
   /**
@@ -162,12 +181,18 @@ export class RpgGui {
   }
 
   async _initialize() {
-    this.webSocket.on("gui.open", (data: { guiId: string; data: any }) => {
+    this.webSocket.on("gui.open", (data: { guiId: string; data: any; guiOpenId?: string }) => {
       this.clearPendingActions(data.guiId);
-      this.display(data.guiId, data.data);
+      this.display(data.guiId, data.data, [], data.guiOpenId);
     });
 
-    this.webSocket.on("gui.exit", (guiId: string) => {
+    this.webSocket.on("gui.exit", (payload: string | { guiId: string; guiOpenId?: string }) => {
+      const guiId = typeof payload === "string" ? payload : payload.guiId;
+      const guiOpenId = typeof payload === "string" ? undefined : payload.guiOpenId;
+      const current = this.get(guiId);
+      if (guiOpenId && current?.openId && current.openId !== guiOpenId) {
+        return;
+      }
       this.hide(guiId);
     });
 
@@ -196,6 +221,7 @@ export class RpgGui {
    */
   _setVueGuiInstance(vueGuiInstance: any) {
     this.vueGuiInstance = vueGuiInstance;
+    this._initializeVueComponents();
   }
 
   /**
@@ -207,21 +233,9 @@ export class RpgGui {
    * @param data - Component data
    */
   private _notifyVueGui(guiId: string, display: boolean, data: any = {}) {
-    if (this.vueGuiInstance && this.vueGuiInstance.vm) {
-      // Find the GUI in extraGuis
-      const extraGui = this.extraGuis.find(gui => gui.name === guiId);
-      if (extraGui) {
-        // Update the Vue component's display state and data
-        this.vueGuiInstance.vm.gui[guiId] = {
-          name: guiId,
-          display,
-          data,
-          attachToSprite: extraGui.attachToSprite || false
-        };
-        // Trigger Vue reactivity
-        this.vueGuiInstance.vm.gui = Object.assign({}, this.vueGuiInstance.vm.gui);
-      }
-    }
+    const extraGui = this.extraGuis.find(gui => gui.name === guiId);
+    if (!extraGui) return;
+    this.vueGuiInstance?.updateGuiState?.(this.toGuiState(extraGui, display, data));
   }
 
   /**
@@ -229,20 +243,9 @@ export class RpgGui {
    * This should be called after VueGui is mounted
    */
   _initializeVueComponents() {
-    if (this.vueGuiInstance && this.vueGuiInstance.vm) {
-      // Initialize all extraGuis in the Vue instance
-      this.extraGuis.forEach(gui => {
-        this.vueGuiInstance.vm.gui[gui.name] = {
-          name: gui.name,
-          display: gui.display(),
-          data: gui.data(),
-          attachToSprite: gui.attachToSprite || false
-        };
-      });
-      
-      // Trigger Vue reactivity
-      this.vueGuiInstance.vm.gui = Object.assign({}, this.vueGuiInstance.vm.gui);
-    }
+    this.vueGuiInstance?.initializeGuiStates?.(
+      this.extraGuis.map(gui => this.toGuiState(gui))
+    );
   }
 
   guiInteraction(guiId: string, name: string, data: any) {
@@ -261,9 +264,12 @@ export class RpgGui {
     });
   }
 
-  guiClose(guiId: string, data?: any) {
+  guiClose(guiId: string, data?: any, guiOpenId?: unknown) {
+    const normalizedOpenId =
+      typeof guiOpenId === "string" && guiOpenId.length > 0 ? guiOpenId : undefined;
     this.webSocket.emit("gui.exit", {
       guiId,
+      guiOpenId: normalizedOpenId,
       data,
     });
   }
@@ -301,35 +307,47 @@ export class RpgGui {
    * });
    * ```
    */
-  add(gui: GuiOptions) {
-    const guiId = gui.name || gui.id;
+  add(gui: GuiOptions | any) {
+    const component = this.resolveComponent(gui);
+    const guiId = this.resolveGuiId(gui, component);
     if (!guiId) {
       throw new Error("GUI must have a name or id");
     }
+    const attachToSprite = this.resolveAttachToSprite(gui, component);
     const guiInstance: GuiInstance = {
       name: guiId,
-      component: gui.component,
-      display: signal(gui.display || false),
-      data: signal(gui.data || {}),
+      component,
+      display: signal<boolean>(gui.display || false),
+      data: signal<any>(gui.data || {}),
+      openId: undefined,
       autoDisplay: gui.autoDisplay || false,
       dependencies: gui.dependencies ? gui.dependencies() : [],
-      attachToSprite: gui.attachToSprite || false,
+      attachToSprite,
     };
 
-    // Accept both CanvasEngine components (.ce) and Vue components
-    // Vue components will be handled by VueGui if available
-    if (typeof gui.component !== 'function') {
-      guiInstance.component = gui;
-      this.extraGuis.push(guiInstance);
+    if (this.isVueComponentInstance(guiInstance)) {
+      this.removeCanvasGui(guiId);
+      const existingIndex = this.extraGuis.findIndex(existing => existing.name === guiId);
+      if (existingIndex >= 0) {
+        this.extraGuis[existingIndex].subscription?.unsubscribe();
+        this.extraGuis[existingIndex] = guiInstance;
+      } else {
+        this.extraGuis.push(guiInstance);
+      }
+
+      this._initializeVueComponents();
       
-      // Auto display Vue components if enabled
       if (guiInstance.autoDisplay) {
-        this._notifyVueGui(guiId, true, gui.data || {});
+        this.display(guiId, gui.data);
+      } else {
+        this._notifyVueGui(guiId, guiInstance.display(), guiInstance.data());
       }
       return;
     }
 
+    this.removeVueGui(guiId);
     this.gui()[guiId] = guiInstance;
+    this._initializeVueComponents();
 
     // Auto display if enabled and it's a CanvasEngine component
     if (guiInstance.autoDisplay && typeof gui.component === 'function') {
@@ -357,8 +375,15 @@ export class RpgGui {
    * ```
    */
   getAttachedGuis(): GuiInstance[] {
-    const allGuis = this.getAll();
-    return Object.values(allGuis).filter(gui => gui.attachToSprite === true);
+    return Object.values(this.gui()).filter(gui => gui.attachToSprite === true);
+  }
+
+  getVueGuis(): GuiInstance[] {
+    return [...this.extraGuis];
+  }
+
+  getAttachedVueGuis(): GuiInstance[] {
+    return this.extraGuis.filter(gui => gui.attachToSprite === true);
   }
 
   /**
@@ -418,7 +443,7 @@ export class RpgGui {
    * gui.display('shop', { shopId: 1 }, [playerSignal, shopSignal]);
    * ```
    */
-  display(id: string, data = {}, dependencies: Signal[] = []) {
+  display(id: string, data = {}, dependencies: Signal[] = [], openId?: string) {
     if (!this.exists(id)) {
       throw throwError(id);
     }
@@ -430,8 +455,9 @@ export class RpgGui {
     
     if (isVueComponent) {
       // Handle Vue component display
-      this._handleVueComponentDisplay(id, data, dependencies, guiInstance);
+      this._handleVueComponentDisplay(id, data, dependencies, guiInstance, openId);
     } else {
+      guiInstance.openId = openId;
       guiInstance.data.set(data);
       guiInstance.display.set(true);
     }
@@ -451,7 +477,7 @@ export class RpgGui {
    * @param dependencies - Runtime dependencies
    * @param guiInstance - GUI instance
    */
-  private _handleVueComponentDisplay(id: string, data: any, dependencies: Signal[], guiInstance: GuiInstance) {
+  private _handleVueComponentDisplay(id: string, data: any, dependencies: Signal[], guiInstance: GuiInstance, openId?: string) {
     // Unsubscribe from previous subscription if exists
     if (guiInstance.subscription) {
       guiInstance.subscription.unsubscribe();
@@ -461,7 +487,7 @@ export class RpgGui {
     // Use runtime dependencies or config dependencies
     const deps = dependencies.length > 0 
       ? dependencies 
-      : (guiInstance.dependencies ? guiInstance.dependencies() : []);
+      : (guiInstance.dependencies ?? []);
 
     if (deps.length > 0) {
       // Subscribe to dependencies
@@ -469,6 +495,7 @@ export class RpgGui {
         deps.map(dependency => dependency.observable)
       ).subscribe((values) => {
         if (values.every(value => value !== undefined)) {
+          guiInstance.openId = openId;
           guiInstance.data.set(data);
           guiInstance.display.set(true);
           this._notifyVueGui(id, true, data);
@@ -478,6 +505,7 @@ export class RpgGui {
     }
 
     // No dependencies, display immediately
+    guiInstance.openId = openId;
     guiInstance.data.set(data);
     guiInstance.display.set(true);
     this._notifyVueGui(id, true, data);
@@ -510,6 +538,7 @@ export class RpgGui {
     }
 
     guiInstance.display.set(false)
+    guiInstance.openId = undefined;
     
     // Check if it's a Vue component and notify VueGui
     const isVueComponent = this.extraGuis.some(gui => gui.name === id);
@@ -522,6 +551,49 @@ export class RpgGui {
     return this.extraGuis.some(gui => gui.name === id);
   }
 
+  private isVueComponentInstance(gui: GuiInstance) {
+    return typeof gui.component !== "function";
+  }
+
+  private removeCanvasGui(guiId: string) {
+    const current = this.gui();
+    if (!(guiId in current)) return;
+    const next = { ...current };
+    delete next[guiId];
+    this.gui.set(next);
+  }
+
+  private removeVueGui(guiId: string) {
+    const removed = this.extraGuis.filter(existing => existing.name === guiId);
+    removed.forEach(gui => gui.subscription?.unsubscribe());
+    if (removed.length > 0) {
+      this.extraGuis = this.extraGuis.filter(existing => existing.name !== guiId);
+    }
+  }
+
+  private resolveComponent(gui: GuiOptions | any) {
+    return gui?.component ?? gui;
+  }
+
+  private resolveGuiId(gui: GuiOptions | any, component: any) {
+    return gui?.name || gui?.id || component?.name || component?.__name;
+  }
+
+  private resolveAttachToSprite(gui: GuiOptions | any, component: any) {
+    return !!(gui?.attachToSprite || gui?.rpgAttachToSprite || component?.attachToSprite || component?.rpgAttachToSprite);
+  }
+
+  private toGuiState(gui: GuiInstance, display = gui.display(), data = gui.data()): GuiState {
+    return {
+      name: gui.name,
+      component: gui.component,
+      display,
+      data,
+      openId: gui.openId,
+      attachToSprite: gui.attachToSprite || false,
+    };
+  }
+
   private clearPendingActions(guiId: string) {
     this.pendingActions.delete(guiId);
   }

package/src/Resource.ts

@@ -64,7 +64,7 @@ export class RpgResource {
       // Extract image path from spritesheet
       const imageLink = spritesheet?.image || spritesheet?.imageSource || undefined;
       if (imageLink) {
-        RpgResource._spritesheets.set(id, imageLink);
+        RpgResource._spritesheets.set(String(id), imageLink);
       }
     });
 
@@ -147,4 +147,3 @@ export class RpgResource {
     return RpgResource._sounds;
   }
 }
-

package/src/RpgClient.ts

@@ -2,11 +2,49 @@ import { ComponentFunction, Signal } from 'canvasengine'
 import { RpgClientEngine } from './RpgClientEngine'
 import { Loader, Container } from 'pixi.js'
 import { RpgClientObject } from './Game/Object'
-import { type MapPhysicsEntityContext, type MapPhysicsInitContext } from '@rpgjs/common'
+import type { RpgClientEvent } from './Game/Event'
+import { type I18nMessages, type MapPhysicsEntityContext, type MapPhysicsInitContext, type RpgActionName } from '@rpgjs/common'
+import type {
+    ClientProjectileSpawn,
+    RenderedProjectileProps,
+} from './Game/ProjectileManager'
+import type { ClientVisualMap } from './Game/ClientVisuals'
+import type {
+    RpgInteractionBehavior,
+    RpgInteractionMatcher,
+} from './services/interactions'
 
 type RpgClass<T = any> = new (...args: any[]) => T
 type RpgComponent = RpgClientObject
 type SceneMap = Container
+export type SpriteComponentConfig = ComponentFunction | {
+    component: ComponentFunction
+    props?: Record<string, any> | ((object: RpgClientObject) => Record<string, any>)
+    data?: Record<string, any> | ((object: RpgClientObject) => Record<string, any>)
+    dependencies?: (object: RpgClientObject) => any[]
+}
+
+export type EventComponentSprite = RpgClientEvent & Record<string, any>
+
+export type EventComponentConfig = ComponentFunction | {
+    component: ComponentFunction
+    props?: Record<string, any> | ((event: EventComponentSprite) => Record<string, any>)
+    data?: Record<string, any> | ((event: EventComponentSprite) => Record<string, any>)
+    dependencies?: (event: EventComponentSprite) => any[]
+    renderGraphic?: boolean
+}
+
+export interface RpgSpriteBeforeRemoveContext {
+    reason?: string
+    data?: any
+    transition?: {
+        animation?: string
+        graphic?: string | string[]
+        duration?: number
+        effect?: string
+    }
+    timeoutMs?: number
+}
 
 export interface RpgClientEngineHooks {
     /**
@@ -28,13 +66,14 @@ export interface RpgClientEngineHooks {
     /**
      * Recover keys from the pressed keyboard
      * 
-     * @prop { (engine: RpgClientEngine, obj: { input: string, playerId: number }) => any } [onInput]
+     * @prop { (engine: RpgClientEngine, obj: { input: string | number, action?: string | number, data?: any, playerId: number }) => any } [onInput]
      * @memberof RpgEngineHooks
      */
-    onInput?: (engine: RpgClientEngine, obj: { input: string, playerId: number }) => any
+    onInput?: (engine: RpgClientEngine, obj: { input: RpgActionName, action?: RpgActionName, data?: any, playerId: number }) => any
 
     /**
-     * Called when the user is connected to the server
+     * Called when the user is connected to the server. In MMORPG mode, this
+     * runs after the server sends the RPGJS connection acceptance packet.
      * 
      * @prop { (engine: RpgClientEngine, socket: any) => any } [onConnected]
      * @memberof RpgEngineHooks
@@ -50,7 +89,8 @@ export interface RpgClientEngineHooks {
     onDisconnect?: (engine: RpgClientEngine, reason: any, socket: any) => any
 
     /**
-     * Called when there was a connection error
+     * Called when there was a connection error. In MMORPG mode, this also runs
+     * when server-side auth refuses the connection.
      * 
      * @prop { (engine: RpgClientEngine, err: any, socket: any) => any } [onConnectError]
      * @memberof RpgEngineHooks
@@ -81,7 +121,7 @@ export interface RpgSpriteHooks {
      * }
      * ```
      */
-    componentsBehind?: ComponentFunction[]
+    componentsBehind?: SpriteComponentConfig[]
     
     /**
      * Array of components to render in front of the sprite
@@ -96,7 +136,53 @@ export interface RpgSpriteHooks {
      * }
      * ```
      */
-    componentsInFront?: ComponentFunction[]
+    componentsInFront?: SpriteComponentConfig[]
+
+    /**
+     * Reusable sprite components addressable by server-side component definitions.
+     *
+     * The server sends only the component id and serializable props. The client
+     * registry maps that id to the CanvasEngine component that renders it.
+     *
+     * @prop {Record<string, ComponentFunction>} [components]
+     * @memberof RpgSpriteHooks
+     * @example
+     * ```ts
+     * import GuildBadge from './components/guild-badge.ce'
+     *
+     * const sprite: RpgSpriteHooks = {
+     *   components: {
+     *     guildBadge: GuildBadge
+     *   }
+     * }
+     * ```
+     */
+    components?: Record<string, ComponentFunction>
+
+    /**
+     * Resolve a custom CanvasEngine component for a specific event.
+     *
+     * The component always receives the synced event object as the `sprite` prop.
+     * Custom props are merged in addition to `sprite`, but cannot replace it.
+     * Return `null` or `undefined` to keep the default graphic renderer.
+     *
+     * @prop { (event: EventComponentSprite) => EventComponentConfig | null | undefined } [eventComponent]
+     * @memberof RpgSpriteHooks
+     * @example
+     * ```ts
+     * import ChestEvent from './components/chest-event.ce'
+     *
+     * const sprite: RpgSpriteHooks = {
+     *   eventComponent(sprite) {
+     *     if (sprite.name === 'CHEST') {
+     *       return ChestEvent
+     *     }
+     *     return null
+     *   }
+     * }
+     * ```
+     */
+    eventComponent?: (event: EventComponentSprite) => EventComponentConfig | null | undefined
     
     /**
      * As soon as the sprite is initialized
@@ -114,6 +200,21 @@ export interface RpgSpriteHooks {
      */
     onDestroy?: (sprite: RpgComponent) => any
 
+    /**
+     * Called when a sprite removal is requested, before it disappears from the scene.
+     *
+     * Return a promise to keep the sprite visible while an animation, effect, or
+     * sound transition is running. The server still owns gameplay removal and
+     * uses the timeout carried by the remove request as a safety limit.
+     *
+     * @prop { (sprite: RpgSprite, context: RpgSpriteBeforeRemoveContext) => any } [onBeforeRemove]
+     * @memberof RpgSpriteHooks
+     */
+    onBeforeRemove?: (
+        sprite: RpgComponent,
+        context: RpgSpriteBeforeRemoveContext
+    ) => any
+
     /**
      * As soon as a data is changed on the server side (the name for example), you are able to know the new data but also the old data.
      * 
@@ -191,6 +292,14 @@ export interface RpgSceneHooks<Scene> {
 }
 
 export interface RpgSceneMapHooks extends RpgSceneHooks<SceneMap> {
+    /**
+     * Root CanvasEngine component used to render the RPG scene map.
+     *
+     * Use the exported `SceneMap` component inside your custom component to
+     * keep the default map rendering and compose additional scene children.
+     */
+    component?: ComponentFunction
+
     /**
      * The map and resources are being loaded
      * 
@@ -235,7 +344,37 @@ export interface RpgSceneMapHooks extends RpgSceneHooks<SceneMap> {
     onPhysicsReset?: (scene: SceneMap) => any
 }
 
+export interface RpgProjectileHooks {
+    /**
+     * CanvasEngine components used to render server-authoritative projectiles.
+     */
+    components?: Record<string, ComponentFunction>
+
+    /**
+     * Called when a projectile spawn batch is received from the server.
+     */
+    onSpawn?: (projectile: ClientProjectileSpawn) => any
+
+    /**
+     * Called when the server confirms a projectile impact.
+     */
+    onImpact?: (projectile: RenderedProjectileProps | null) => any
+
+    /**
+     * Called when the server destroys a projectile.
+     */
+    onDestroy?: (projectile: RenderedProjectileProps | null) => any
+}
+
 export interface RpgClient {
+    /**
+     * Default translations owned by this client module.
+     *
+     * Game-level translations provided with `provideI18n()` override module
+     * translations when they share the same locale and key.
+     */
+    i18n?: I18nMessages
+
     /**
      * Add hooks to the player or engine. All modules can listen to the hook
      * 
@@ -485,6 +624,13 @@ export interface RpgClient {
          * ```
          */
         attachToSprite?: boolean
+        /**
+         * Vue v4 compatibility alias for `attachToSprite`.
+         *
+         * Prefer `attachToSprite` in v5 projects. This is read by `@rpgjs/vue`
+         * for Vue GUI components migrated from the v4 GUI API.
+         */
+        rpgAttachToSprite?: boolean
     } | any)[],
 
     /** 
@@ -563,33 +709,36 @@ export interface RpgClient {
      * */
     sprite?: RpgSpriteHooks
 
-    /** 
-     * Reference the scenes of the game. Here you can put your own class that inherits RpgSceneMap
+    /**
+     * Reference the scenes of the game.
      * 
      * ```ts
      * import { RpgSceneMapHooks, RpgClient, defineModule } from '@rpgjs/client'
+     * import MyScene from './my-scene.ce'
      * 
      * export const sceneMap: RpgSceneMapHooks = {
-     *     
+     *     component: MyScene
      * }
      * 
      * defineModule<RpgClient>({
-     *      scenes: {
-     *          // If you put the RpgSceneMap scene, Thhe key is called mandatory `map`
-     *          map: sceneMap
-     *      }
+     *      sceneMap
      * })
      * ``` 
      * 
-     * @prop { [sceneName: string]: RpgSceneMapHooks } [scenes]
+     * @prop {RpgSceneMapHooks} [sceneMap]
      * @memberof RpgClient
      * */
+    sceneMap?: RpgSceneMapHooks
+
+    /**
+     * Legacy scene map hook container.
+     *
+     * Prefer `sceneMap` for new code.
+     */
     scenes?: {
         map: RpgSceneMapHooks
     }
 
-    sceneMap?: RpgSceneMapHooks
-
     /** 
      * Array containing the list of component animations
      * Each element defines a temporary component to display for animations like hits, effects, etc.
@@ -620,4 +769,58 @@ export interface RpgClient {
         id: string,
         component: ComponentFunction
     }[]
+
+    /**
+     * Named client-side visual macros.
+     *
+     * Use client visuals when the server needs to trigger a group of existing
+     * client visual primitives at once, such as a flash, damage text, sound,
+     * component animation, and camera shake. The server sends only the visual
+     * name and a serializable payload; the rendering details live on the client.
+     *
+     * For a single sound, flash, or component animation, prefer the direct
+     * server APIs (`playSound`, `flash`, `showComponentAnimation`). Client
+     * visuals are meant to group several visual operations and reduce bandwidth.
+     *
+     * ```ts
+     * import { defineModule, RpgClient } from '@rpgjs/client'
+     *
+     * export default defineModule<RpgClient>({
+     *   clientVisuals: {
+     *     hit({ target, data }, helpers) {
+     *       helpers.flash(target, { type: 'tint', tint: 'red' })
+     *       helpers.showHit(target, `-${data.damage}`)
+     *       helpers.sound('hit')
+     *     }
+     *   }
+     * })
+     * ```
+     *
+     * @prop {Record<string, ClientVisualHandler>} [clientVisuals]
+     * @memberof RpgClient
+     */
+    clientVisuals?: ClientVisualMap
+
+    /**
+     * Client-side projectile rendering configuration.
+     *
+     * Register a CanvasEngine component per projectile type. The server sends
+     * compact spawn/impact/destroy events and the client predicts x/y locally.
+     */
+    projectiles?: RpgProjectileHooks
+
+    /**
+     * Client-only pointer interactions attached to sprites.
+     *
+     * Use this for hover popovers, selection, drag previews, cursor changes, and
+     * explicit mouse-driven gameplay actions. Pointer feedback stays local unless
+     * the behavior calls `ctx.action(...)`.
+     */
+    interactions?:
+        | ((engine: RpgClientEngine) => void)
+        | {
+            setup?: (engine: RpgClientEngine) => void
+            load?: (engine: RpgClientEngine) => void
+            use?: Array<[RpgInteractionMatcher, RpgInteractionBehavior | ComponentFunction]>
+        }
 }