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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rpgjs/client",
-  "version": "5.0.0-beta.20",
+  "version": "5.0.0-beta.22",
   "description": "RPGJS is a framework for creating RPG/MMORPG games",
   "main": "dist/index.js",
   "types": "./dist/index.d.ts",
@@ -18,13 +18,13 @@
   "license": "MIT",
   "peerDependencies": {
     "@canvasengine/presets": "^2.0.0",
-    "canvasengine": "^2.0.0",
+    "canvasengine": "^2.0.1",
     "pixi.js": "^8.9.2"
   },
   "dependencies": {
-    "@rpgjs/common": "5.0.0-beta.20",
-    "@rpgjs/server": "5.0.0-beta.20",
-    "@rpgjs/ui-css": "5.0.0-beta.20",
+    "@rpgjs/common": "5.0.0-beta.21",
+    "@rpgjs/server": "5.0.0-beta.22",
+    "@rpgjs/ui-css": "5.0.0-beta.21",
     "@signe/di": "3.1.0",
     "@signe/room": "3.1.0",
     "@signe/sync": "3.1.0",

package/src/Gui/Gui.spec.ts

@@ -98,6 +98,25 @@ describe("RpgGui Vue integration", () => {
     });
   });
 
+  test("waits for CanvasEngine GUI dependencies before displaying", async () => {
+    const { gui } = await createGui();
+    const enabled = signal(true);
+    const ready = signal<boolean | undefined>(undefined);
+
+    gui.add({
+      id: "canvas-dependency",
+      component: CanvasGui,
+      autoDisplay: true,
+      dependencies: () => [enabled, ready],
+    });
+
+    expect(gui.isDisplaying("canvas-dependency")).toBe(false);
+
+    ready.set(true);
+
+    expect(gui.isDisplaying("canvas-dependency")).toBe(true);
+  });
+
   test("ignores stale server close events for previous GUI opens", async () => {
     const { gui, socket } = await createGui();
     await gui._initialize();

package/src/Gui/Gui.ts

@@ -449,18 +449,48 @@ export class RpgGui {
     }
 
     const guiInstance = this.get(id)!;
-    
-    // Check if it's a Vue component (in extraGuis)
     const isVueComponent = this.extraGuis.some(gui => gui.name === id);
-    
-    if (isVueComponent) {
-      // Handle Vue component display
-      this._handleVueComponentDisplay(id, data, dependencies, guiInstance, openId);
-    } else {
+
+    if (guiInstance.subscription) {
+      guiInstance.subscription.unsubscribe();
+      guiInstance.subscription = undefined;
+    }
+
+    const show = () => {
       guiInstance.openId = openId;
       guiInstance.data.set(data);
       guiInstance.display.set(true);
+      if (isVueComponent) {
+        this._notifyVueGui(id, true, data);
+      }
+    };
+
+    const deps = dependencies.length > 0
+      ? dependencies
+      : (guiInstance.dependencies ?? []);
+
+    if (deps.length > 0) {
+      const values = deps.map(dependency => dependency());
+      const subscription = new Subscription();
+      const showIfReady = () => {
+        if (values.every(value => value !== undefined)) {
+          show();
+        }
+      };
+
+      deps.forEach((dependency, index) => {
+        subscription.add(dependency.observable.subscribe((value) => {
+          values[index] = value;
+          showIfReady();
+        }));
+      });
+
+      guiInstance.subscription = subscription;
+      showIfReady();
+      return;
     }
+
+    show();
   }
 
   isDisplaying(id: string): boolean {
@@ -490,17 +520,26 @@ export class RpgGui {
       : (guiInstance.dependencies ?? []);
 
     if (deps.length > 0) {
-      // Subscribe to dependencies
-      guiInstance.subscription = combineLatest(
-        deps.map(dependency => dependency.observable)
-      ).subscribe((values) => {
+      const values = deps.map(dependency => dependency());
+      const subscription = new Subscription();
+      const showIfReady = () => {
         if (values.every(value => value !== undefined)) {
           guiInstance.openId = openId;
           guiInstance.data.set(data);
           guiInstance.display.set(true);
           this._notifyVueGui(id, true, data);
         }
+      };
+
+      deps.forEach((dependency, index) => {
+        subscription.add(dependency.observable.subscribe((value) => {
+          values[index] = value;
+          showIfReady();
+        }));
       });
+
+      guiInstance.subscription = subscription;
+      showIfReady();
       return;
     }
 

package/src/RpgClientEngine.ts

@@ -41,6 +41,12 @@ import { RpgClientInteractions } from "./services/interactions";
 import { normalizeRoomMapId } from "./utils/mapId";
 import { EventComponentResolverRegistry, type EventComponentResolver } from "./Game/EventComponentResolver";
 import { RpgClientBuiltinI18n } from "./i18n";
+import type { CameraFollowSmoothMove } from "./services/cameraFollow";
+export type {
+  CameraFollowEase,
+  CameraFollowSmoothMove,
+  CameraFollowSmoothMoveOptions,
+} from "./services/cameraFollow";
 
 interface MovementTrajectoryPoint {
   frame: number;
@@ -183,10 +189,14 @@ export class RpgClientEngine<T = any> {
   private eventComponentResolvers = new EventComponentResolverRegistry();
   /** ID of the sprite that the camera should follow. null means follow the current player */
   cameraFollowTargetId = signal<string | null>(null);
+  /** Camera follow transition options used by character components when the target changes */
+  cameraFollowSmoothMove: CameraFollowSmoothMove = false;
+  /** Incremented for each camera follow command so repeated commands on the same target are applied */
+  cameraFollowRevision = signal(0);
   /** Trigger for map shake animation */
   mapShakeTrigger: ConfigurableTrigger<MapShakeOptions> = trigger<MapShakeOptions>();
 
-  controlsReady = signal(undefined); 
+  controlsReady = signal<boolean | undefined>(undefined); 
   gamePause = signal(false);
 
   private predictionEnabled = false;
@@ -363,7 +373,7 @@ export class RpgClientEngine<T = any> {
       ...currentValues,
       values: new Map([['__default__', controlInstance]])
     }
-    this.controlsReady.set(undefined);
+    this.controlsReady.set(true);
   }
 
   async start() {
@@ -606,6 +616,12 @@ export class RpgClientEngine<T = any> {
     return find((this.canvasApp as any)?.stage);
   }
 
+  private clearCameraFollowViewportPlugins(): void {
+    const viewport = this.findViewportInstance();
+    viewport?.plugins?.remove?.("animate");
+    viewport?.plugins?.remove?.("follow");
+  }
+
   private prepareSyncPayload(data: any): any {
     const payload = { ...(data ?? {}) };
     delete payload.ack;
@@ -881,7 +897,7 @@ export class RpgClientEngine<T = any> {
     this.sceneMap.clearLightSpots();
     this.clearComponentAnimations();
     this.projectiles.setMapId(nextMapId);
-    this.cameraFollowTargetId.set(null);
+    this.resetCameraFollow(false);
     this.sceneMap.reset();
     this.sceneMap.loadPhysic();
   }
@@ -1476,19 +1492,22 @@ export class RpgClientEngine<T = any> {
    * Set the camera to follow a specific sprite
    * 
    * This method changes which sprite the camera viewport should follow.
-   * The camera will smoothly animate to the target sprite if smoothMove options are provided.
+   * The camera can smoothly animate to the target sprite before continuous follow starts.
    * 
    * ## Design
    * 
    * The camera follow target is stored in a signal that is read by sprite components.
    * Each sprite checks if it should be followed by comparing its ID with the target ID.
-   * When smoothMove options are provided, the viewport animation is handled by CanvasEngine's
-   * viewport system.
+   * When smoothMove options are provided, the transition is handled by pixi-viewport's
+   * animation plugin, then continuous follow is handled by CanvasEngine's viewport system.
    * 
    * @param targetId - The ID of the sprite to follow. Set to null to follow the current player
    * @param smoothMove - Animation options. Can be a boolean (default: true) or an object with time and ease
    * @param smoothMove.time - Duration of the animation in milliseconds (optional)
    * @param smoothMove.ease - Easing function name from https://easings.net (optional)
+   * @param smoothMove.speed - Continuous follow speed after the transition (optional)
+   * @param smoothMove.acceleration - Continuous follow acceleration after the transition (optional)
+   * @param smoothMove.radius - Center radius where the target can move without moving the viewport (optional)
    * 
    * @example
    * ```ts
@@ -1510,19 +1529,19 @@ export class RpgClientEngine<T = any> {
    */
   setCameraFollow(
     targetId: string | null,
-    smoothMove?: boolean | { time?: number; ease?: string }
+    smoothMove?: CameraFollowSmoothMove
   ): void {
-    // Store smoothMove options for potential future use with viewport animation
-    // For now, we just set the target ID and let CanvasEngine handle the viewport follow
-    // The smoothMove options could be used to configure viewport animation if CanvasEngine supports it
+    this.clearCameraFollowViewportPlugins();
+    this.cameraFollowSmoothMove = smoothMove ?? true;
     this.cameraFollowTargetId.set(targetId);
-    
-    // If smoothMove is an object, we could store it for viewport configuration
-    // This would require integration with CanvasEngine's viewport animation system
-    if (typeof smoothMove === "object" && smoothMove !== null) {
-      // Future: Apply smoothMove.time and smoothMove.ease to viewport animation
-      // For now, CanvasEngine handles viewport following automatically
-    }
+    this.cameraFollowRevision.set(this.cameraFollowRevision() + 1);
+  }
+
+  private resetCameraFollow(smoothMove: CameraFollowSmoothMove = false): void {
+    this.clearCameraFollowViewportPlugins();
+    this.cameraFollowSmoothMove = smoothMove;
+    this.cameraFollowTargetId.set(null);
+    this.cameraFollowRevision.set(this.cameraFollowRevision() + 1);
   }
 
   addParticle(particle: any) {
@@ -2611,7 +2630,7 @@ export class RpgClientEngine<T = any> {
 
       // Reset signals
       this.playerIdSignal.set(null);
-      this.cameraFollowTargetId.set(null);
+      this.resetCameraFollow(false);
       this.spriteComponentsBehind.set([]);
       this.spriteComponentsInFront.set([]);
       this.eventComponentResolvers.clear();

package/src/components/character.ce

@@ -2,7 +2,6 @@
   x={smoothX}
   y={smoothY}
   zIndex={z}
-  viewportFollow={shouldFollowCamera}
   controls
   onBeforeDestroy
   visible
@@ -76,6 +75,7 @@
   import { Particle } from "@canvasengine/presets";
   import { GameEngineToken, ModulesToken, shouldRenderLightingShadows } from "@rpgjs/common";
   import { RpgClientEngine } from "../RpgClientEngine";
+  import { applyCameraFollow, clearCameraFollowPlugins, ownsCameraFollowRevision } from "../services/cameraFollow";
   import { inject } from "../core/inject";  
   import { Direction, Animation } from "@rpgjs/common";
   import { normalizeEventComponent } from "../Game/EventComponentResolver";
@@ -360,9 +360,43 @@
   const canControls = () => isMe() && getCanMoveValue(sprite)
   const keyboardControls = client.globalConfig.keyboardControls;
   const activeDirectionKeys = new Map();
+  const activeControlDirections = new Map();
+  const activeControlDirectionReleaseTimers = new Map();
+  const CONTROL_DIRECTION_RELEASE_GRACE_MS = 160;
+
+  const hasHeldDirection = () =>
+    activeDirectionKeys.size > 0 || activeControlDirections.size > 0;
+
+  const publishMobileDebug = (type, payload = {}) => {
+    const target = typeof window !== "undefined" ? window : globalThis;
+    if (!target.__RPGJS_MOBILE_DEBUG__) return;
+    const event = {
+      source: "character",
+      type,
+      time: Date.now(),
+      isCurrentPlayer: isCurrentPlayer(),
+      animationName: animationName(),
+      realAnimationName: realAnimationName?.(),
+      activeKeyboardDirections: Array.from(activeDirectionKeys.values()),
+      activeControlDirections: Array.from(activeControlDirections.values()),
+      heldDirection: resolveHeldDirection(),
+      canControls: canControls(),
+      x: x(),
+      y: y(),
+      ...payload
+    };
+    target.__RPGJS_MOBILE_DEBUG_EVENTS__ = [
+      ...(target.__RPGJS_MOBILE_DEBUG_EVENTS__ || []).slice(-199),
+      event
+    ];
+    target.__RPGJS_MOBILE_DEBUG_LAST__ = event;
+  };
 
   const resolveHeldDirection = () => {
-    const directions = Array.from(activeDirectionKeys.values());
+    const directions = [
+      ...Array.from(activeDirectionKeys.values()),
+      ...Array.from(activeControlDirections.values()),
+    ];
     return directions[directions.length - 1];
   };
 
@@ -408,27 +442,77 @@
     );
 
   const playPredictedWalkAnimation = () => {
-    if (sprite.animationFixed) return;
-    if (sprite.animationIsPlaying && sprite.animationIsPlaying()) return;
+    if (sprite.animationFixed) {
+      publishMobileDebug("walk:skip", { reason: "animationFixed" });
+      return;
+    }
+    if (sprite.animationIsPlaying && sprite.animationIsPlaying()) {
+      publishMobileDebug("walk:skip", { reason: "animationIsPlaying" });
+      return;
+    }
     realAnimationName.set('walk');
+    publishMobileDebug("walk:set", { reason: "predicted" });
   };
 
   const resumeHeldDirectionWalkAnimation = () => {
-    if (!isCurrentPlayer()) return false;
-    if (activeDirectionKeys.size === 0) return false;
-    if (!canControls()) return false;
-    if (sprite.animationFixed) return false;
-    if (sprite.animationIsPlaying && sprite.animationIsPlaying()) return false;
+    if (!isCurrentPlayer()) {
+      publishMobileDebug("walk:resume-fail", { reason: "notCurrentPlayer" });
+      return false;
+    }
+    if (!hasHeldDirection()) {
+      publishMobileDebug("walk:resume-fail", { reason: "noHeldDirection" });
+      return false;
+    }
+    if (!canControls()) {
+      publishMobileDebug("walk:resume-fail", { reason: "cannotControl" });
+      return false;
+    }
+    if (sprite.animationFixed) {
+      publishMobileDebug("walk:resume-fail", { reason: "animationFixed" });
+      return false;
+    }
+    if (sprite.animationIsPlaying && sprite.animationIsPlaying()) {
+      publishMobileDebug("walk:resume-fail", { reason: "animationIsPlaying" });
+      return false;
+    }
     realAnimationName.set('walk');
+    publishMobileDebug("walk:set", { reason: "resumeHeldDirection" });
     return true;
   };
 
   const processMovementInput = (input) => {
     if (!canControls()) return;
+    publishMobileDebug("movement:input", { input });
     client.processInput({ input });
     playPredictedWalkAnimation();
   };
 
+  const activateControlDirection = (name, directionInput) => {
+    const releaseTimer = activeControlDirectionReleaseTimers.get(name);
+    if (releaseTimer) {
+      clearTimeout(releaseTimer);
+      activeControlDirectionReleaseTimers.delete(name);
+    }
+    activeControlDirections.delete(name);
+    activeControlDirections.set(name, directionInput);
+    publishMobileDebug("control:activate", { name, directionInput });
+    resumeHeldDirectionWalkAnimation();
+  };
+
+  const releaseControlDirection = (name) => {
+    const previousTimer = activeControlDirectionReleaseTimers.get(name);
+    if (previousTimer) clearTimeout(previousTimer);
+    activeControlDirectionReleaseTimers.set(name, setTimeout(() => {
+      activeControlDirectionReleaseTimers.delete(name);
+      activeControlDirections.delete(name);
+      publishMobileDebug("control:release", { name });
+      if (!hasHeldDirection() && animationName() === 'stand') {
+        realAnimationName.set('stand');
+        publishMobileDebug("stand:set", { reason: "controlRelease" });
+      }
+    }, CONTROL_DIRECTION_RELEASE_GRACE_MS));
+  };
+
   const processDashInput = () => {
     if (!canControls()) return;
     client.processDash({
@@ -474,29 +558,45 @@
       repeat: true,
       bind: keyboardControls.down,
       keyDown() {
+        activateControlDirection('down', Direction.Down)
         processMovementInput(Direction.Down)
       },
+      keyUp() {
+        releaseControlDirection('down')
+      },
     },
     up: {
       repeat: true,
       bind: keyboardControls.up,
       keyDown() {
+        activateControlDirection('up', Direction.Up)
         processMovementInput(Direction.Up)
       },
+      keyUp() {
+        releaseControlDirection('up')
+      },
     },
     left: {
       repeat: true,
       bind: keyboardControls.left,
       keyDown() {
+        activateControlDirection('left', Direction.Left)
         processMovementInput(Direction.Left)
       },
+      keyUp() {
+        releaseControlDirection('left')
+      },
     },
     right: {
       repeat: true,
       bind: keyboardControls.right,
       keyDown() {
+        activateControlDirection('right', Direction.Right)
         processMovementInput(Direction.Right)
       },
+      keyUp() {
+        releaseControlDirection('right')
+      },
     },
     action: {
       bind: getKeyboardControlBind(keyboardControls.action),
@@ -512,6 +612,14 @@
         processDashInput()
       },
     },
+    back: {
+      bind: keyboardControls.escape,
+      keyDown() {
+        if (canControls()) {
+          client.processAction({ action: 'escape' })
+        }
+      },
+    },
     escape: {
       bind: keyboardControls.escape,
       keyDown() {
@@ -520,6 +628,21 @@
         }
       },
     },
+    joystick: {
+      enabled: true,
+      directionMapping: {
+        top: 'up',
+        bottom: 'down',
+        left: 'left',
+        right: 'right',
+        top_left: ['up', 'left'],
+        top_right: ['up', 'right'],
+        bottom_left: ['down', 'left'],
+        bottom_right: ['down', 'right']
+      },
+      moveInterval: 50,
+      threshold: 0.1
+    },
     gamepad: {
       enabled: true
     }
@@ -1051,6 +1174,8 @@
     removeTransitionSubscription?.unsubscribe();
     animationMovementSubscription.unsubscribe();
     resumeWalkSubscriptions.forEach(subscription => subscription.unsubscribe());
+    activeControlDirectionReleaseTimers.forEach(timer => clearTimeout(timer));
+    activeControlDirectionReleaseTimers.clear();
     xSubscription.unsubscribe();
     ySubscription.unsubscribe();
     await lastValueFrom(hooks.callHooks("client-sprite-onDestroy", sprite)) 
@@ -1058,6 +1183,7 @@
   }
 
   mount((element) => {
+    let appliedCameraFollowRevision = null;
     if (typeof document !== 'undefined') {
       document.addEventListener('keydown', handleNativeActionWhileMoving);
       document.addEventListener('keyup', handleNativeActionWhileMoving);
@@ -1069,6 +1195,38 @@
         client.setKeyboardControls(element.directives.controls)
       }
     })
+
+    effect(() => {
+      const followRevision = client.cameraFollowRevision();
+      if (!shouldFollowCamera()) {
+        appliedCameraFollowRevision = null;
+        return;
+      }
+
+      const smoothMove = client.cameraFollowSmoothMove;
+      const viewport = element.props.context?.viewport;
+      const target = element.componentInstance;
+      if (!viewport || !target) {
+        appliedCameraFollowRevision = null;
+        return;
+      }
+
+      const appliedCameraFollow = applyCameraFollow({
+        viewport,
+        target,
+        smoothMove,
+        followRevision,
+        isCurrentRevision: (revision) => client.cameraFollowRevision() === revision,
+        shouldFollowCamera
+      });
+      appliedCameraFollowRevision = appliedCameraFollow ? followRevision : null;
+    })
+
+    return () => {
+      if (ownsCameraFollowRevision(appliedCameraFollowRevision, client.cameraFollowRevision())) {
+        clearCameraFollowPlugins(element.props.context?.viewport);
+      }
+    }
   })
 
   /**

package/src/components/gui/mobile/index.spec.ts

@@ -0,0 +1,94 @@
+import { describe, expect, test, vi } from "vitest";
+import { signal } from "canvasengine";
+
+const fakeEngine = {
+  controlsReady: signal(true),
+};
+
+vi.mock("../../../core/inject", () => ({
+  inject: vi.fn(() => fakeEngine),
+}));
+
+describe("withMobile", () => {
+  test("registers the mobile GUI with default options", async () => {
+    const { withMobile } = await import("./index");
+
+    const module = withMobile();
+    const gui = module.gui[0];
+
+    expect(gui.id).toBe("mobile-gui");
+    expect(gui.autoDisplay).toBe(true);
+    expect(gui.data).toEqual({});
+  });
+
+  test("passes options to the GUI and resolves enabled dependencies", async () => {
+    const { withMobile } = await import("./index");
+    const CustomJoystick = vi.fn();
+    const CustomActionButton = vi.fn();
+
+    const module = withMobile({
+      id: "touch-controls",
+      enabled: "always",
+      layout: {
+        joystickSide: "right",
+        gap: 18,
+        buttonsMargin: 44,
+        joystickMargin: [24, 60, 24, 24],
+      },
+      components: {
+        joystick: CustomJoystick,
+        buttons: {
+          action: CustomActionButton,
+        },
+      },
+      joystick: {
+        outerColor: "#111111",
+        innerColor: "#eeeeee",
+        scale: 0.8,
+        outerScale: { x: 0.8, y: 0.8 },
+        innerScale: { x: 0.9, y: 0.9 },
+        moveInterval: 40,
+        threshold: 0.2,
+      },
+      buttons: {
+        action: {
+          enabled: true,
+          width: 72,
+        },
+        back: false,
+        dash: true,
+      },
+    });
+    const gui = module.gui[0];
+    const dependencies = gui.dependencies();
+
+    expect(gui.id).toBe("touch-controls");
+    expect(gui.data.layout?.joystickSide).toBe("right");
+    expect(gui.data.components?.joystick).toBe(CustomJoystick);
+    expect(gui.data.components?.buttons?.action).toBe(CustomActionButton);
+    expect(gui.data.buttons?.action).toMatchObject({
+      enabled: true,
+      width: 72,
+    });
+    expect(gui.data.buttons?.dash).toBe(true);
+    expect(gui.data.joystick).toMatchObject({
+      outerColor: "#111111",
+      innerColor: "#eeeeee",
+      scale: 0.8,
+      outerScale: { x: 0.8, y: 0.8 },
+      innerScale: { x: 0.9, y: 0.9 },
+      moveInterval: 40,
+      threshold: 0.2,
+    });
+    expect(dependencies[0]()).toBe(true);
+    expect(dependencies[1]()).toBe(true);
+  });
+
+  test("keeps the auto detector unresolved when mobile is disabled", async () => {
+    const { withMobile } = await import("./index");
+
+    const dependencies = withMobile({ enabled: "never" }).gui[0].dependencies();
+
+    expect(dependencies[0]()).toBeUndefined();
+  });
+});