@rpgjs/client 5.0.0-beta.26 → 5.0.0-beta.28

package/src/Gui/Gui.ts

@@ -1,16 +1,28 @@
 import { Context, inject } from "@signe/di";
-import { signal, Signal, WritableSignal } from "canvasengine";
+import { signal, Signal, WritableSignal, type ComponentFunction } from "canvasengine";
 import { AbstractWebsocket, WebSocketToken } from "../services/AbstractSocket";
 import { DialogboxComponent, ShopComponent, SaveLoadComponent, MainMenuComponent, NotificationComponent, TitleScreenComponent, GameoverComponent, InputComponent } from "../components/gui";
 import { combineLatest, Subscription } from "rxjs";
-import { PrebuiltGui } from "@rpgjs/common";
+import { PrebuiltGui, type RpgContext } from "@rpgjs/common";
 
-interface GuiOptions {
+export type GuiRenderer = "canvas" | "vue";
+
+export type GuiComponent = ComponentFunction | object;
+
+export interface GuiRegistration<
+  TData = unknown,
+  TComponent extends GuiComponent = GuiComponent,
+> {
   name?: string;
   id?: string;
-  component?: any;
+  component: TComponent;
+  /**
+   * Renderer responsible for this component. CanvasEngine is the v5 default.
+   * `@rpgjs/vue` registers the official DOM overlay renderer.
+   */
+  renderer?: GuiRenderer;
   display?: boolean;
-  data?: any;
+  data?: TData;
   /**
    * Auto display the GUI when added to the system
    * @default false
@@ -21,7 +33,7 @@ interface GuiOptions {
    * The GUI will only display when all dependencies are resolved (!= undefined)
    * @returns Array of Signal dependencies
    */
-  dependencies?: () => Signal[];
+  dependencies?: () => Signal<unknown>[];
   /**
    * Attach the GUI to sprites instead of displaying globally
    * When true, the GUI will be rendered in character.ce for each sprite
@@ -34,30 +46,42 @@ interface GuiOptions {
   rpgAttachToSprite?: boolean;
 }
 
-export interface GuiInstance {
+export type GuiEntry<TData = unknown> =
+  | GuiRegistration<TData>
+  | GuiComponent;
+
+export interface GuiInstance<
+  TData = unknown,
+  TComponent extends GuiComponent = GuiComponent,
+> {
   name: string;
-  component: any;
+  component: TComponent;
+  renderer: GuiRenderer;
   display: WritableSignal<boolean>;
-  data: WritableSignal<any>;
+  data: WritableSignal<TData>;
   openId?: string;
   autoDisplay: boolean;
-  dependencies?: Signal[];
+  dependencies?: Signal<unknown>[];
   subscription?: Subscription;
   attachToSprite?: boolean;
 }
 
-type GuiState = {
+export type GuiRenderState<
+  TData = unknown,
+  TComponent extends GuiComponent = GuiComponent,
+> = {
   name: string;
-  component: any;
+  component: TComponent;
+  renderer: GuiRenderer;
   display: boolean;
-  data: any;
+  data: TData;
   openId?: string;
   attachToSprite: boolean;
 };
 
 type VueGuiBridge = {
-  updateGuiState?: (state: GuiState) => void;
-  initializeGuiStates?: (states: GuiState[]) => void;
+  updateGuiState?: (state: GuiRenderState) => void;
+  initializeGuiStates?: (states: GuiRenderState[]) => void;
 };
 
 interface GuiAction {
@@ -145,40 +169,48 @@ export class RpgGui {
    */
   attachedGuiDisplayState = signal<Record<string, boolean>>({});
 
-  constructor(private context: Context) {
-    this.webSocket = inject(context, WebSocketToken);
+  constructor(private context: RpgContext) {
+    this.webSocket = inject(context as Context, WebSocketToken);
     this.add({
       name: "rpg-dialog",
       component: DialogboxComponent,
+      renderer: "canvas",
     });
     this.add({
       name: PrebuiltGui.MainMenu,
       component: MainMenuComponent,
+      renderer: "canvas",
     });
     this.add({
       name: PrebuiltGui.Shop,
       component: ShopComponent,
+      renderer: "canvas",
     });
     this.add({
       name: PrebuiltGui.Notification,
       component: NotificationComponent,
+      renderer: "canvas",
       autoDisplay: true,
     });
     this.add({
       name: PrebuiltGui.Save,
       component: SaveLoadComponent,
+      renderer: "canvas",
     });
     this.add({
       name: PrebuiltGui.TitleScreen,
       component: TitleScreenComponent,
+      renderer: "canvas",
     });
     this.add({
       name: PrebuiltGui.Gameover,
       component: GameoverComponent,
+      renderer: "canvas",
     });
     this.add({
       name: PrebuiltGui.Input,
       component: InputComponent,
+      renderer: "canvas",
     });
 
     this.registerOptimisticReducer(PrebuiltGui.MainMenu, mainMenuOptimisticReducer);
@@ -311,21 +343,24 @@ export class RpgGui {
    * });
    * ```
    */
-  add(gui: GuiOptions | any) {
-    const component = this.resolveComponent(gui);
-    const guiId = this.resolveGuiId(gui, component);
+  add(gui: GuiEntry) {
+    const registration = this.resolveRegistration(gui);
+    const component = registration.component;
+    const guiId = registration.name || registration.id || this.resolveComponentName(component);
     if (!guiId) {
       throw new Error("GUI must have a name or id");
     }
-    const attachToSprite = this.resolveAttachToSprite(gui, component);
+    const attachToSprite = this.resolveAttachToSprite(registration, component);
+    const renderer = registration.renderer ?? this.resolveLegacyRenderer(component);
     const guiInstance: GuiInstance = {
       name: guiId,
       component,
-      display: signal<boolean>(gui.display || false),
-      data: signal<any>(gui.data || {}),
+      renderer,
+      display: signal<boolean>(registration.display || false),
+      data: signal(registration.data ?? {}),
       openId: undefined,
-      autoDisplay: gui.autoDisplay || false,
-      dependencies: gui.dependencies ? gui.dependencies() : [],
+      autoDisplay: registration.autoDisplay || false,
+      dependencies: registration.dependencies ? registration.dependencies() : [],
       attachToSprite,
     };
 
@@ -342,7 +377,7 @@ export class RpgGui {
       this._initializeVueComponents();
       
       if (guiInstance.autoDisplay) {
-        this.display(guiId, gui.data);
+        this.display(guiId, registration.data);
       } else {
         this._notifyVueGui(guiId, guiInstance.display(), guiInstance.data());
       }
@@ -354,8 +389,8 @@ export class RpgGui {
     this._initializeVueComponents();
 
     // Auto display if enabled and it's a CanvasEngine component
-    if (guiInstance.autoDisplay && typeof gui.component === 'function') {
-      this.display(guiId, gui.data);
+    if (guiInstance.autoDisplay && typeof component === 'function') {
+      this.display(guiId, registration.data);
     }
   }
 
@@ -400,15 +435,15 @@ export class RpgGui {
     return this.attachedGuiDisplayState()[playerId] === true;
   }
 
-  get(id: string): GuiInstance | undefined {
+  get<TData = unknown>(id: string): GuiInstance<TData> | undefined {
     // Check CanvasEngine GUIs first
     const canvasGui = this.gui()[id];
     if (canvasGui) {
-      return canvasGui;
+      return canvasGui as GuiInstance<TData>;
     }
     
     // Check Vue GUIs in extraGuis
-    return this.extraGuis.find(gui => gui.name === id);
+    return this.extraGuis.find(gui => gui.name === id) as GuiInstance<TData> | undefined;
   }
 
   exists(id: string): boolean {
@@ -447,7 +482,12 @@ export class RpgGui {
    * gui.display('shop', { shopId: 1 }, [playerSignal, shopSignal]);
    * ```
    */
-  display(id: string, data = {}, dependencies: Signal[] = [], openId?: string) {
+  display(
+    id: string,
+    data: unknown = {},
+    dependencies: Signal<unknown>[] = [],
+    openId?: string,
+  ) {
     if (!this.exists(id)) {
       throw throwError(id);
     }
@@ -595,7 +635,7 @@ export class RpgGui {
   }
 
   private isVueComponentInstance(gui: GuiInstance) {
-    return typeof gui.component !== "function";
+    return gui.renderer === "vue";
   }
 
   private removeCanvasGui(guiId: string) {
@@ -614,22 +654,46 @@ export class RpgGui {
     }
   }
 
-  private resolveComponent(gui: GuiOptions | any) {
-    return gui?.component ?? gui;
+  private resolveRegistration(gui: GuiEntry): GuiRegistration {
+    if (
+      typeof gui === "object"
+      && gui !== null
+      && "component" in gui
+    ) {
+      return gui as GuiRegistration;
+    }
+    return { component: gui };
+  }
+
+  private resolveComponentName(component: GuiComponent): string | undefined {
+    const named = component as { name?: unknown; __name?: unknown };
+    if (typeof named.name === "string" && named.name.length > 0) return named.name;
+    if (typeof named.__name === "string" && named.__name.length > 0) return named.__name;
+    return undefined;
   }
 
-  private resolveGuiId(gui: GuiOptions | any, component: any) {
-    return gui?.name || gui?.id || component?.name || component?.__name;
+  private resolveLegacyRenderer(component: GuiComponent): GuiRenderer {
+    return typeof component === "function" ? "canvas" : "vue";
   }
 
-  private resolveAttachToSprite(gui: GuiOptions | any, component: any) {
-    return !!(gui?.attachToSprite || gui?.rpgAttachToSprite || component?.attachToSprite || component?.rpgAttachToSprite);
+  private resolveAttachToSprite(gui: GuiRegistration, component: GuiComponent) {
+    const componentOptions = component as {
+      attachToSprite?: unknown;
+      rpgAttachToSprite?: unknown;
+    };
+    return !!(
+      gui.attachToSprite
+      || gui.rpgAttachToSprite
+      || componentOptions.attachToSprite
+      || componentOptions.rpgAttachToSprite
+    );
   }
 
-  private toGuiState(gui: GuiInstance, display = gui.display(), data = gui.data()): GuiState {
+  private toGuiState(gui: GuiInstance, display = gui.display(), data = gui.data()): GuiRenderState {
     return {
       name: gui.name,
       component: gui.component,
+      renderer: gui.renderer,
       display,
       data,
       openId: gui.openId,

package/src/RpgClient.ts

@@ -13,6 +13,7 @@ import type {
     RpgInteractionBehavior,
     RpgInteractionMatcher,
 } from './services/interactions'
+import type { GuiEntry } from './Gui/Gui'
 
 type RpgClass<T = any> = new (...args: any[]) => T
 type RpgComponent = RpgClientObject
@@ -570,69 +571,7 @@ export interface RpgClient {
      * @prop {Array<GuiOptions>} [gui]
      * @memberof RpgClient
      * */
-    gui?: ({
-        id: string,
-        component: ComponentFunction,
-        /**
-         * 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)
-         */
-        dependencies?: () => Signal[]
-        /**
-         * Attach the GUI to sprites instead of displaying globally
-         * 
-         * When set to `true`, the GUI component will be rendered directly on each sprite
-         * in the game world, rather than being displayed as a fixed overlay on the screen.
-         * This is useful for tooltips, health bars, name tags, or any UI element that
-         * should follow a specific sprite.
-         * 
-         * The GUI will be rendered in the `character.ce` component for each sprite.
-         * You can control the display state of attached GUIs from the server side using
-         * `player.showAttachedGui()` and `player.hideAttachedGui()` methods.
-         * 
-         * @default false
-         * @example
-         * ```ts
-         * import { defineModule, RpgClient } from '@rpgjs/client'
-         * import TooltipComponent from './tooltip.ce'
-         * 
-         * defineModule<RpgClient>({
-         *     gui: [
-         *         {
-         *             id: "my-tooltip",
-         *             component: TooltipComponent,
-         *             attachToSprite: true
-         *         }
-         *     ]
-         * })
-         * ```
-         * 
-         * On the server side, control the display:
-         * ```ts
-         * // Show the tooltip for this player
-         * player.showAttachedGui()
-         * 
-         * // Hide the tooltip for this player
-         * player.hideAttachedGui()
-         * 
-         * // Show tooltip for other players
-         * player.showAttachedGui([otherPlayer1, otherPlayer2])
-         * ```
-         */
-        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)[],
+    gui?: GuiEntry[],
 
     /** 
      * Array containing the list of sounds

package/src/core/inject.ts

@@ -1,17 +1,18 @@
 import { Context, inject as injector } from "@signe/di";
+import type { RpgContext } from "@rpgjs/common";
 
-export let context: Context | null = null
+export let context: RpgContext | null = null
 
-export function inject<T>(service: (new (...args: any[]) => T) | string, _context?: Context): T {
+export function inject<T>(service: (new (...args: any[]) => T) | string, _context?: RpgContext): T {
     const c = _context ?? context
     if (!c) throw new Error("Context is not set. use setInject() to set the context");
-    return injector(c, service);
+    return injector(c as Context, service);
 }
 
-export function setInject(_context: Context) {
+export function setInject(_context: RpgContext) {
     context = _context;
 }
 
 export function clearInject() {
     context = null
-}
+}

package/src/core/setup.spec.ts

@@ -0,0 +1,35 @@
+import { describe, expect, test } from "vitest";
+import { RpgClientEngine } from "../RpgClientEngine";
+import { inject } from "./inject";
+import { startGame } from "./setup";
+
+describe("startGame", () => {
+  test("initializes recursively nested RPGJS providers", async () => {
+    let engineStarted = false;
+
+    const context = await startGame({
+      providers: [
+        [
+          [
+            {
+              provide: "deep-provider",
+              useValue: 42,
+            },
+          ],
+        ],
+        {
+          provide: RpgClientEngine,
+          useValue: {
+            async start() {
+              engineStarted = true;
+            },
+          },
+        },
+      ],
+    });
+
+    expect(context.side).toBe("client");
+    expect(inject("deep-provider")).toBe(42);
+    expect(engineStarted).toBe(true);
+  });
+});

package/src/core/setup.ts

@@ -1,20 +1,22 @@
-import { Context, FactoryProvider, findProvider, findProviders, inject, injector, Providers } from "@signe/di";
+import { Context, inject, injector, type Providers } from "@signe/di";
+import type { RpgContext, RpgProviders } from "@rpgjs/common";
 import { RpgClientEngine } from "../RpgClientEngine";
 import { setInject } from "./inject";
 
 interface SetupOptions {
-  providers: Providers;
+  providers: RpgProviders;
 }
 
 
-export async function startGame(options: SetupOptions) {
+export async function startGame(options: SetupOptions): Promise<RpgContext> {
   const context = new Context();
   context['side'] = 'client'
-  setInject(context);
+  setInject(context as unknown as RpgContext);
 
-  await injector(context, options.providers);
+  const providers = (options.providers as unknown[]).flat(Infinity) as Providers;
+  await injector(context, providers);
 
   const engine = inject<RpgClientEngine>(context, RpgClientEngine);
   await engine.start();
-  return context;
+  return context as unknown as RpgContext;
 }

package/src/index.ts

@@ -22,10 +22,21 @@ export * from "./Sound";
 export * from "./Resource";
 export * from "./decorators/spritesheet";
 export * from "./utils/getEntityProp";
-export { Context } from "@signe/di";
 export { KeyboardControls, Input } from "canvasengine";
 export { Control } from "./services/keyboardControls";
 export { defineModule } from "@rpgjs/common";
+export type {
+  RpgClassProvider,
+  RpgContext,
+  RpgExistingProvider,
+  RpgFactoryProvider,
+  RpgProvider,
+  RpgProviders,
+  RpgProviderToken,
+  RpgReadableSignal,
+  RpgValueProvider,
+  RpgWritableSignal,
+} from "@rpgjs/common";
 export { RpgClientObject } from "./Game/Object";
 export { RpgClientPlayer } from "./Game/Player";
 export { RpgClientEvent } from "./Game/Event";

package/src/module.ts

@@ -1,5 +1,5 @@
 import { findModules, provideModules, registerI18nMessages } from "@rpgjs/common";
-import { FactoryProvider } from "@signe/di";
+import type { RpgFactoryProvider } from "@rpgjs/common";
 import { RpgClientEngine } from "./RpgClientEngine";
 import { RpgClient } from "./RpgClient";
 import { inject } from "@signe/di";
@@ -48,7 +48,7 @@ export type RpgClientModule = RpgClient | (new () => any);
  * provideClientModules([MyClientModule])
  * ```
  */
-export function provideClientModules(modules: RpgClientModule[]): FactoryProvider {
+export function provideClientModules(modules: RpgClientModule[]): RpgFactoryProvider {
   return provideModules(modules, "client", (modules, context) => {
     const mainModuleClient = findModules(context, 'Client')
     modules = [...mainModuleClient, ...modules]

package/src/public-api-types.spec.ts

@@ -0,0 +1,37 @@
+import { describe, expectTypeOf, test } from "vitest";
+import type { RpgContext, RpgProvider } from "@rpgjs/common";
+import {
+  provideMmorpg,
+  startGame,
+  type GuiRegistration,
+  type GuiRenderer,
+} from "./index";
+
+describe("client public API types", () => {
+  test("bootstrap and providers expose RPGJS-owned contracts", () => {
+    expectTypeOf(provideMmorpg({})).toEqualTypeOf<RpgProvider[]>();
+    const assertions = (start: typeof startGame) => {
+      expectTypeOf(start({ providers: [] })).toEqualTypeOf<Promise<RpgContext>>();
+    };
+    expectTypeOf(assertions).toBeFunction();
+  });
+
+  test("the Signe Context class is not re-exported", () => {
+    // @ts-expect-error Context is available only from direct advanced Signe usage
+    type LegacyContext = typeof import("./index")["Context"];
+    expectTypeOf<LegacyContext>();
+  });
+
+  test("GUI registrations expose renderer-neutral typed data", () => {
+    type DialogData = { message: string };
+    const registration: GuiRegistration<DialogData> = {
+      id: "dialog",
+      component: () => null,
+      renderer: "canvas",
+      data: { message: "Hello" },
+    };
+
+    expectTypeOf(registration.renderer).toEqualTypeOf<GuiRenderer | undefined>();
+    expectTypeOf(registration.data).toEqualTypeOf<DialogData | undefined>();
+  });
+});

package/src/services/AbstractSocket.ts

@@ -1,4 +1,4 @@
-import { Context } from "@signe/di";
+import type { RpgContext } from "@rpgjs/common";
 
 export const WebSocketToken = "websocket";
 
@@ -14,7 +14,7 @@ export type WebSocketMode = "standalone" | "mmorpg";
 export abstract class AbstractWebsocket {
   readonly mode?: WebSocketMode;
 
-  constructor(protected context: Context) {}
+  constructor(protected context: RpgContext) {}
 
   abstract connection(listeners?: (data: any) => void): Promise<void>;
   abstract emit(event: string, data: any): void;

package/src/services/loadMap.ts

@@ -1,5 +1,5 @@
 import { Context, inject } from "@signe/di";
-import { UpdateMapToken, UpdateMapService, type LightingState } from "@rpgjs/common";
+import { UpdateMapToken, UpdateMapService, type LightingState, type RpgContext, type RpgProvider } from "@rpgjs/common";
 import type { RpgClientMap } from "../Game/Map";
 
 export const LoadMapToken = 'LoadMapToken'
@@ -47,8 +47,8 @@ export type LoadMapOptions = (mapId: string) => Promise<MapData> | MapData
 export class LoadMapService {
   private updateMapService: UpdateMapService;
 
-  constructor(private context: Context, private options: LoadMapOptions) {
-    if (context['side'] === 'server') {
+  constructor(private context: RpgContext, private options: LoadMapOptions) {
+    if (context.side === 'server') {
       return
     }
   }
@@ -56,7 +56,7 @@ export class LoadMapService {
   initialize(): void {}
 
   async load(mapId: string) {
-    this.updateMapService ??= inject(this.context, UpdateMapToken);
+    this.updateMapService ??= inject(this.context as Context, UpdateMapToken);
     const map = await this.options(mapId.replace('map-', ''))
     await this.updateMapService.update(map);
     return map;
@@ -154,12 +154,12 @@ export class LoadMapService {
  * @see {@link LoadMapOptions} for callback function signature
  * @see {@link MapData} for return data structure
  */
-export function provideLoadMap(options: LoadMapOptions) {
+export function provideLoadMap(options: LoadMapOptions): RpgProvider[] {
   return [
     {
       provide: UpdateMapToken,
-      useFactory: (context: Context) => {
-        if (context['side'] === 'client') {
+      useFactory: (context: RpgContext) => {
+        if (context.side === 'client') {
           console.warn('UpdateMapToken is not overridden')
         }
         return
@@ -167,7 +167,7 @@ export function provideLoadMap(options: LoadMapOptions) {
     },
     {
       provide: LoadMapToken,
-      useFactory: (context: Context) => new LoadMapService(context, options),
+      useFactory: (context: RpgContext) => new LoadMapService(context, options),
     },
   ];
 }

package/src/services/mapStreaming.ts

@@ -6,6 +6,8 @@ import {
   type MapStreamChunk,
   type MapStreamManifest,
   type MapStreamPacket,
+  type RpgContext,
+  type RpgProvider,
 } from "@rpgjs/common";
 import { AbstractWebsocket, WebSocketToken } from "./AbstractSocket";
 import { LoadMapToken, type MapData, type LoadMapOptions } from "./loadMap";
@@ -221,13 +223,13 @@ class MapStreamingLoadMapService<TManifestData, TChunkData, TState> {
   private updateMap?: UpdateMapService;
 
   constructor(
-    private readonly context: Context,
+    private readonly context: RpgContext,
     private readonly options: ClientMapStreamingOptions<TManifestData, TChunkData, TState>,
   ) {}
 
   initialize(): void {
     if (this.stream) return;
-    this.socket = inject<AbstractWebsocket>(this.context, WebSocketToken);
+    this.socket = inject<AbstractWebsocket>(this.context as Context, WebSocketToken);
     this.stream = new MapStreamingClientService(this.socket, this.options);
   }
 
@@ -236,7 +238,7 @@ class MapStreamingLoadMapService<TManifestData, TChunkData, TState> {
     const map = this.socket?.mode === "standalone" && this.options.directLoad
       ? await this.options.directLoad(mapId.replace(/^map-/, ""))
       : await this.stream!.load(mapId);
-    this.updateMap ??= inject<UpdateMapService>(this.context, UpdateMapToken);
+    this.updateMap ??= inject<UpdateMapService>(this.context as Context, UpdateMapToken);
     await this.updateMap.update(map);
     return map;
   }
@@ -265,11 +267,11 @@ class MapStreamingLoadMapService<TManifestData, TChunkData, TState> {
  */
 export function provideClientMapStreaming<TManifestData, TChunkData, TState>(
   options: ClientMapStreamingOptions<TManifestData, TChunkData, TState>,
-) {
+): RpgProvider[] {
   return [
     {
       provide: LoadMapToken,
-      useFactory: (context: Context) => new MapStreamingLoadMapService(context, options),
+      useFactory: (context: RpgContext) => new MapStreamingLoadMapService(context, options),
     },
   ];
 }