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

package/src/components/character.ce

@@ -2,7 +2,6 @@
   x={smoothX}
   y={smoothY}
   zIndex={z}
-  viewportFollow={shouldFollowCamera}
   controls
   onBeforeDestroy
   visible
@@ -24,12 +23,12 @@
   <Particle emit={emitParticleTrigger} settings={particleSettings} zIndex={1000} name={particleName} />
   <Container>
     @for (graphicObj of renderedGraphics) {
-      <Container scale={graphicScale(graphicObj)}>
+      <Container scale={graphicContainerScale(graphicObj)}>
         <Sprite 
           sheet={sheet(graphicObj)} 
           direction 
           tint 
-          hitbox
+          hitbox={graphicHitbox(graphicObj)}
           shadowCaster={shadowCaster(graphicObj)}
           flash={flashConfig}
         />
@@ -76,6 +75,8 @@
   import { Particle } from "@canvasengine/presets";
   import { GameEngineToken, ModulesToken, shouldRenderLightingShadows } from "@rpgjs/common";
   import { RpgClientEngine } from "../RpgClientEngine";
+  import { applyCameraFollow, clearCameraFollowPlugins, ownsCameraFollowRevision } from "../services/cameraFollow";
+  import { resolveScaledHitboxAnchor, scaleHitboxForGraphicDisplay, toPositiveNumber } from "./character-hitbox";
   import { inject } from "../core/inject";  
   import { Direction, Animation } from "@rpgjs/common";
   import { normalizeEventComponent } from "../Game/EventComponentResolver";
@@ -360,9 +361,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 +443,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 +559,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 +613,14 @@
         processDashInput()
       },
     },
+    back: {
+      bind: keyboardControls.escape,
+      keyDown() {
+        if (canControls()) {
+          client.processAction({ action: 'escape' })
+        }
+      },
+    },
     escape: {
       bind: keyboardControls.escape,
       keyDown() {
@@ -520,6 +629,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
     }
@@ -562,7 +686,7 @@
   }
 
   const graphicScale = (graphicObject) => {
-    const scale = graphicObject?.displayScale ?? graphicObject?.scale;
+    const scale = graphicObject?.scale;
     if (Array.isArray(scale)) return scale;
     if (typeof scale === 'number') return [scale, scale];
     if (scale && typeof scale === 'object') {
@@ -573,12 +697,34 @@
     return undefined;
   }
 
+  const graphicContainerScale = (graphicObject) => {
+    const scale = graphicObject?.displayScale;
+    if (Array.isArray(scale)) return scale;
+    if (typeof scale === 'number') return [scale, scale];
+    if (scale && typeof scale === 'object') {
+      const x = typeof scale.x === 'number' ? scale.x : 1;
+      const y = typeof scale.y === 'number' ? scale.y : x;
+      return [x, y];
+    }
+    return [1, 1];
+  }
+
+  const multiplyScale = (left, right) => {
+    const a = normalizePair(left);
+    const b = normalizePair(right);
+    return [a[0] * b[0], a[1] * b[1]];
+  }
+
+  const graphicHitbox = (graphicObject) => {
+    const box = hitbox();
+    const scale = graphicEffectiveScale(graphicObject);
+    return scaleHitboxForGraphicDisplay(box, scale);
+  }
+
   const shadowCaster = (graphicObject) => {
     const box = hitbox();
     const bounds = graphicBounds();
-    const scale = graphicScale(graphicObject);
-    const scaleY = Array.isArray(scale) && typeof scale[1] === 'number' ? Math.abs(scale[1]) : 1;
-    const height = Math.max(bounds?.height ?? box?.h ?? 32, box?.h ?? 32) * scaleY;
+    const height = Math.max(bounds?.height ?? box?.h ?? 32, box?.h ?? 32);
 
     return {
       enabled: shadowsEnabled,
@@ -599,11 +745,6 @@
   const imageDimensions = signal({});
   const loadingImageDimensions = new Set();
 
-  const toPositiveNumber = (value) => {
-    const number = typeof value === 'number' ? value : parseFloat(value);
-    return Number.isFinite(number) && number > 0 ? number : undefined;
-  };
-
   const toFiniteNumber = (value, fallback = 0) => {
     const number = typeof value === 'number' ? value : parseFloat(value);
     return Number.isFinite(number) ? number : fallback;
@@ -703,6 +844,13 @@
     return frame?.[prop] ?? textureOptions?.[prop] ?? graphicObject?.[prop];
   };
 
+  const graphicEffectiveScale = (graphicObject) => {
+    const textureOptions = resolveTextureOptions(graphicObject);
+    const frame = resolveFirstAnimationFrame(textureOptions);
+    const spriteScale = normalizePair(optionValue('scale', frame, textureOptions, graphicObject) ?? graphicScale(graphicObject));
+    return multiplyScale(spriteScale, graphicContainerScale(graphicObject));
+  };
+
   const resolveFrameSize = (textureOptions, dimensions) => {
     const framesWidth = toPositiveNumber(textureOptions?.framesWidth) ?? 1;
     const framesHeight = toPositiveNumber(textureOptions?.framesHeight) ?? 1;
@@ -723,31 +871,6 @@
     };
   };
 
-  const resolveHitboxAnchor = (spriteWidth, spriteHeight, realSize, box) => {
-    if (!spriteWidth || !spriteHeight || !box) {
-      return [0, 0];
-    }
-
-    const heightOfSprite = typeof realSize === 'number' ? realSize : realSize?.height;
-    const resolvedHeight = toPositiveNumber(heightOfSprite) ?? spriteHeight;
-    const gap = Math.max(0, (spriteHeight - resolvedHeight) / 2);
-    const hitboxTopLeftX = clampRatio((spriteWidth - box.w) / 2 / spriteWidth);
-    const hitboxTopLeftY = clampRatio((spriteHeight - box.h - gap) / spriteHeight);
-    const hitboxCenterX = clampRatio(hitboxTopLeftX + box.w / 2 / spriteWidth);
-    const hitboxCenterY = clampRatio(hitboxTopLeftY + box.h / 2 / spriteHeight);
-    const footY = clampRatio((spriteHeight - gap) / spriteHeight);
-
-    switch (box.anchorMode ?? 'top-left') {
-      case 'center':
-        return [hitboxCenterX, hitboxCenterY];
-      case 'foot':
-        return [hitboxCenterX, footY];
-      case 'top-left':
-      default:
-        return [hitboxTopLeftX, hitboxTopLeftY];
-    }
-  };
-
   const loadImageDimensions = (image) => {
     const source = resolveImageSource(image);
     if (!source || imageDimensions()[source] || loadingImageDimensions.has(source)) {
@@ -827,14 +950,15 @@
         return;
       }
 
+      const scale = graphicEffectiveScale(graphicObject);
       const explicitAnchor = normalizeAnchor(optionValue('anchor', frame, textureOptions, graphicObject));
-      const anchor = explicitAnchor ?? resolveHitboxAnchor(
+      const anchor = explicitAnchor ?? resolveScaledHitboxAnchor(
         spriteWidth,
         spriteHeight,
         optionValue('spriteRealSize', frame, textureOptions, graphicObject),
-        box
+        box,
+        scale
       );
-      const scale = normalizePair(optionValue('scale', frame, textureOptions, graphicObject) ?? graphicScale(graphicObject));
       const x = toFiniteNumber(optionValue('x', frame, textureOptions, graphicObject), 0);
       const y = toFiniteNumber(optionValue('y', frame, textureOptions, graphicObject), 0);
       const leftEdge = -anchor[0] * spriteWidth * scale[0];
@@ -1051,6 +1175,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 +1184,7 @@
   }
 
   mount((element) => {
+    let appliedCameraFollowRevision = null;
     if (typeof document !== 'undefined') {
       document.addEventListener('keydown', handleNativeActionWhileMoving);
       document.addEventListener('keyup', handleNativeActionWhileMoving);
@@ -1069,6 +1196,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();
+  });
+});

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

@@ -1,24 +1,92 @@
 import { inject } from "../../../core/inject";
 import { RpgClientEngine } from "../../../RpgClientEngine";
 import MobileGui from "./mobile.ce";
-import { signal } from "canvasengine";
+import { computed } from "canvasengine";
+import type { ButtonProps, ComponentFunction, JoystickSettings } from "canvasengine";
+
+export type MobileGuiEnabled = "auto" | "always" | "never" | (() => boolean);
+export type MobileGuiJoystickSide = "left" | "right";
+export type MobileGuiMargin = number | [number, number, number, number];
+
+export interface MobileGuiLayoutOptions {
+    joystickSide?: MobileGuiJoystickSide;
+    margin?: MobileGuiMargin;
+    buttonsMargin?: MobileGuiMargin;
+    joystickMargin?: MobileGuiMargin;
+    gap?: number;
+}
+
+export interface MobileJoystickComponentProps extends JoystickSettings {
+    defaultProps: JoystickSettings;
+}
+
+export interface MobileButtonComponentProps extends ButtonProps {
+    controlName: "action" | "back" | "dash";
+    defaultProps: ButtonProps;
+}
+
+export interface MobileGuiComponentsOptions {
+    joystick?: ComponentFunction<MobileJoystickComponentProps>;
+    buttons?: {
+        action?: ComponentFunction<MobileButtonComponentProps>;
+        back?: ComponentFunction<MobileButtonComponentProps>;
+        dash?: ComponentFunction<MobileButtonComponentProps>;
+    };
+}
+
+export interface MobileGuiButtonOptions extends Partial<ButtonProps> {
+    enabled?: boolean;
+    component?: ComponentFunction<MobileButtonComponentProps>;
+    container?: Record<string, unknown>;
+}
+
+export interface MobileGuiJoystickOptions extends Partial<JoystickSettings> {
+    component?: ComponentFunction<MobileJoystickComponentProps>;
+    moveInterval?: number;
+    threshold?: number;
+}
+
+export interface MobileGuiOptions {
+    id?: string;
+    enabled?: MobileGuiEnabled;
+    layout?: MobileGuiLayoutOptions;
+    components?: MobileGuiComponentsOptions;
+    joystick?: false | MobileGuiJoystickOptions;
+    buttons?: {
+        action?: boolean | MobileGuiButtonOptions;
+        back?: boolean | MobileGuiButtonOptions;
+        dash?: boolean | MobileGuiButtonOptions;
+    };
+}
 
 function isMobile() {
+    if (typeof navigator === "undefined") return false;
     return /Android|iPhone|iPad|iPod|Windows Phone|webOS|BlackBerry/i.test(navigator.userAgent);
-  }
+}
+
+function resolveEnabled(enabled: MobileGuiEnabled = "auto") {
+    if (enabled === "always") return true;
+    if (enabled === "never") return false;
+    if (typeof enabled === "function") return enabled();
+    return isMobile();
+}
 
-export const withMobile = () => (
+export const withMobile = (options: MobileGuiOptions = {}) => (
     {
         gui: [
             {
-                id: 'mobile-gui',
+                id: options.id ?? 'mobile-gui',
                 component: MobileGui,
                 autoDisplay: true,
+                data: options,
                 dependencies: () => {
                     const engine = inject(RpgClientEngine);
-                    return [signal(isMobile() ||undefined), engine.controlsReady]
+                    return [
+                        computed(() => resolveEnabled(options.enabled) || undefined),
+                        engine.controlsReady
+                    ]
                 }
             }
         ]
     }
-)
+)