feat(mobile): floating joystick, touch gameplay, responsive layout and PWA support (Closes #21)

frontend/app/globals.css

@@ -69,4 +69,51 @@ html.game-targeting body *::after {
         left: 0;
         -webkit-overflow-scrolling: touch;
     }
-}
+}
+
+/* Mobile-specific: landscape rotation prompt */
+@media (orientation: portrait) and (max-width: 768px) {
+    .game-shell .mobile-landscape-overlay {
+        display: flex;
+    }
+}
+
+@media (orientation: landscape) and (max-width: 768px) {
+    .game-shell .mobile-landscape-overlay {
+        display: none;
+    }
+}
+
+/* Hide joystick on desktop */
+@media (pointer: coarse) {
+    .mobile-only-joystick {
+        display: block;
+    }
+}
+
+@media (pointer: fine) {
+    .mobile-only-joystick {
+        display: none;
+    }
+}
+
+/* Responsive canvas scaling */
+@media screen and (max-width: 768px) {
+    .game-shell {
+        position: fixed;
+        top: 0;
+        left: 0;
+        right: 0;
+        bottom: 0;
+        -webkit-overflow-scrolling: touch;
+        overflow: hidden;
+    }
+
+    .game-shell canvas,
+    .game-shell [class*="canvas-"] {
+        max-width: 100vw;
+        max-height: 100vh;
+        width: auto;
+        height: auto;
+    }
+}

frontend/app/layout.tsx

@@ -19,6 +19,15 @@ const geistMono = Geist_Mono({
     subsets: ["latin"],
 });
 
+export const viewport: import("next").Viewport = {
+    width: "device-width",
+    initialScale: 1,
+    maximumScale: 1,
+    userScalable: false,
+    viewportFit: "cover",
+    themeColor: "#020617",
+};
+
 export const metadata: Metadata = {
     ...buildPageMetadata({
         title: siteTitle,

frontend/app/manifest.ts

@@ -8,6 +8,7 @@ export default function manifest(): MetadataRoute.Manifest {
         description: siteDescription,
         start_url: "/",
         display: "standalone",
+        orientation: "landscape",
         background_color: "#08111f",
         theme_color: "#08111f",
         lang: "es-AR",

frontend/app/play/page.tsx

@@ -68,6 +68,7 @@ import {
 } from "../../lib/viewport";
 
 const DEFAULT_WS_URL = process.env.NEXT_PUBLIC_WS_URL || "ws://localhost:7666";
+import LandscapePrompt from "../../components/game/input/LandscapePrompt";
 const OverviewModal = dynamic(() => import("../../components/OverviewModal"), {
     ssr: false,
 });
@@ -3857,6 +3858,7 @@ export default function Home() {
     return (
         <Suspense fallback={<main className="min-h-screen bg-black" />}>
             <HomeContent />
-        </Suspense>
+        <LandscapePrompt />
+            </Suspense>
     );
 }

frontend/components/game/core/MapRendererCore.tsx

@@ -69,6 +69,8 @@ import { useAssetPipeline } from "./useAssetPipeline";
 import { useMovementSync, type LocalPendingMove } from "./useMovementSync";
 import { useCombatController, type TargetingMode } from "./useCombatController";
 import { useKeyboardGameplay } from "./useKeyboardGameplay";
+import { useTouchGameplay } from "./useTouchGameplay";
+import Joystick from "../input/Joystick";
 import { useNpcAdminTools } from "./useNpcAdminTools";
 import { useHudStateController } from "./useHudStateController";
 import { useSceneController } from "./useSceneController";
@@ -1333,6 +1335,18 @@ export default function MapRenderer({
         setIsDebugMode,
     });
 
+    const {
+        onJoystickMove,
+        onJoystickMoveEnd,
+    } = useTouchGameplay({
+        isMounted,
+        engineRef,
+        movementKeyPriorityRef,
+        movementPressCountsRef,
+        canProcessMovementInput,
+        syncMovementState,
+    });
+
     const { clearUseItemQueues } = useOutgoingRequests({
         websocketRef,
         engineRef,
@@ -2073,6 +2087,12 @@ export default function MapRenderer({
                     }
                 />
             </div>
+            <div className="mobile-only-joystick">
+            <Joystick
+                onMove={onJoystickMove}
+                onMoveEnd={onJoystickMoveEnd}
+            />
+            </div>
         </div>
     );
 }

frontend/components/game/core/useTouchGameplay.ts

@@ -0,0 +1,144 @@
+import { useCallback, useEffect, useRef } from "react";
+import type { Engine } from "../engine/Engine";
+
+type UseTouchGameplayOptions = {
+  isMounted: boolean;
+  engineRef: { current: Engine | null };
+  movementKeyPriorityRef: { current: number[] };
+  movementPressCountsRef: { current: Map<number, number> };
+  syncMovementState: (engine: Engine) => void;
+  canProcessMovementInput: () => boolean;
+};
+
+/**
+ * Touch gameplay hook that bridges the virtual joystick to the engine's
+ * movement system, bypassing the keyboard event path (which rejects
+ * synthetic events via isTrusted).
+ *
+ * Instead of dispatching KeyboardEvent, it directly manipulates
+ * movementPressCountsRef and movementKeyPriorityRef — the same
+ * refs the keyboard hook uses, so syncMovementState works correctly.
+ */
+export function useTouchGameplay({
+  isMounted,
+  engineRef,
+  movementKeyPriorityRef,
+  movementPressCountsRef,
+  syncMovementState,
+  canProcessMovementInput,
+}: UseTouchGameplayOptions) {
+  const isMoving = useRef(false);
+  const currentDirection = useRef<number | null>(null);
+
+  /**
+   * Engine KEY_CODES: W=87, A=65, S=83, D=68
+   * The movementKeyPriorityRef stores KEY_CODES values (87, 65, 83, 68),
+   * and the engine's update loop maps them to DIRECTIONS via moveTo().
+   *
+   * Angles: 0 = right, PI/2 = down, PI = left, -PI/2 = up
+   */
+  const KEY_W = 87; // UP
+  const KEY_A = 65; // LEFT
+  const KEY_S = 83; // DOWN
+  const KEY_D = 68; // RIGHT
+
+  const angleToKeyCode = useCallback((angle: number): number => {
+    const normalized = ((angle % (Math.PI * 2)) + Math.PI * 2) % (Math.PI * 2);
+    const sector = Math.round(normalized / (Math.PI / 2)) % 4;
+    // 0=right(D), 1=down(S), 2=left(A), 3=up(W)
+    const keyCodes: Record<number, number> = {
+      0: KEY_D,
+      1: KEY_S,
+      2: KEY_A,
+      3: KEY_W,
+    };
+    return keyCodes[sector];
+  }, []);
+
+  const handleMove = useCallback(
+    (angle: number, _force: number) => {
+      if (!isMounted) return;
+      const keyCode = angleToKeyCode(angle);
+
+      // Only update if direction changed
+      if (keyCode !== currentDirection.current) {
+        currentDirection.current = keyCode;
+
+        // Clear all previous touch directions
+        movementPressCountsRef.current.clear();
+
+        // Set the new direction with count 1
+        movementPressCountsRef.current.set(keyCode, 1);
+
+        // Push to front of priority (same as keyboard handleKeyDown)
+        movementKeyPriorityRef.current =
+          movementKeyPriorityRef.current.filter(
+            (code) => code !== keyCode,
+          );
+        movementKeyPriorityRef.current.unshift(keyCode);
+
+        if (!isMoving.current) {
+          isMoving.current = true;
+        }
+
+        const activeEngine = engineRef.current;
+        if (activeEngine && canProcessMovementInput()) {
+          syncMovementState(activeEngine);
+        }
+      }
+    },
+    [
+      isMounted,
+      angleToKeyCode,
+      movementKeyPriorityRef,
+      movementPressCountsRef,
+      engineRef,
+      canProcessMovementInput,
+      syncMovementState,
+    ],
+  );
+
+  const handleMoveEnd = useCallback(() => {
+    if (!isMounted) return;
+
+    isMoving.current = false;
+    currentDirection.current = null;
+
+    // Clear touch movement (same as keyboard keyup path)
+    movementPressCountsRef.current.clear();
+    movementKeyPriorityRef.current =
+      movementKeyPriorityRef.current.filter(
+        (code) =>
+          code !== KEY_W &&
+          code !== KEY_A &&
+          code !== KEY_S &&
+          code !== KEY_D,
+      );
+
+    const activeEngine = engineRef.current;
+    if (activeEngine && canProcessMovementInput()) {
+      syncMovementState(activeEngine);
+    }
+  }, [
+    isMounted,
+    movementKeyPriorityRef,
+    movementPressCountsRef,
+    engineRef,
+    canProcessMovementInput,
+    syncMovementState,
+  ]);
+
+  // Cleanup on unmount
+  useEffect(() => {
+    return () => {
+      if (isMoving.current) {
+        handleMoveEnd();
+      }
+    };
+  }, [isMoving, handleMoveEnd]);
+
+  return {
+    onJoystickMove: handleMove,
+    onJoystickMoveEnd: handleMoveEnd,
+  };
+}