fix zoom

.github/workflows/weekly-branch-promotions.yml

@@ -1,58 +1,59 @@
-name: 🔁 Branch Promotions
+name: 🔁 Weekly Branch Promotions
 
 on:
   schedule:
-    - cron: "0 6 * * 1,4"  # Lundi et Jeudi à 6h UTC (design → develop)
+    - cron: "0 6 * * 1"
-    - cron: "0 6 * * 1" # Lundi à 6h UTC (develop → main)
   workflow_dispatch:
-    inputs:
-      promotion:
-        description: "Which promotion to run"
-        required: true
-        type: choice
-        options:
-          - design-to-develop
-          - develop-to-main
-          - both
 
 permissions:
   contents: read
   pull-requests: write
 
 concurrency:
-  group: branch-promotions
+  group: weekly-branch-promotions
   cancel-in-progress: false
 
 jobs:
-  design-to-develop:
+  open-promotion-pr:
-    name: Open design → develop
+    name: Open ${{ matrix.head }} → ${{ matrix.base }}
     runs-on: ubuntu-latest
-    if: |
+    strategy:
-      (github.event_name == 'schedule') ||
+      fail-fast: false
-      (github.event_name == 'workflow_dispatch' && (github.event.inputs.promotion == 'design-to-develop' || github.event.inputs.promotion == 'both'))
+      matrix:
+        include:
+          - head: develop
+            base: design
+            title: "chore: merge develop into design"
+          - head: design
+            base: main
+            title: "chore: merge design into main"
+
     steps:
       - name: ⬇️ Checkout
-        uses: actions/checkout@v4
+        uses: actions/checkout@v6
         with:
           fetch-depth: 0
 
       - name: 🔁 Open promotion PR
         env:
           GH_TOKEN: ${{ github.token }}
+          BASE_BRANCH: ${{ matrix.base }}
+          HEAD_BRANCH: ${{ matrix.head }}
+          PR_TITLE: ${{ matrix.title }}
         run: |
           set -euo pipefail
 
-          git fetch origin develop design
+          git fetch origin "$BASE_BRANCH" "$HEAD_BRANCH"
 
-          if git merge-base --is-ancestor origin/design origin/develop; then
+          if git merge-base --is-ancestor "origin/$HEAD_BRANCH" "origin/$BASE_BRANCH"; then
-            echo "No promotion needed: develop already contains design."
+            echo "No promotion needed: $BASE_BRANCH already contains $HEAD_BRANCH."
             exit 0
           fi
 
           existing_pr="$(gh pr list \
             --state open \
-            --base develop \
+            --base "$BASE_BRANCH" \
-            --head "$GITHUB_REPOSITORY_OWNER:design" \
+            --head "$GITHUB_REPOSITORY_OWNER:$HEAD_BRANCH" \
             --json number \
             --jq '.[0].number // empty')"
 
@@ -62,50 +63,7 @@ jobs:
           fi
 
           gh pr create \
-            --base develop \
+            --base "$BASE_BRANCH" \
-            --head design \
+            --head "$HEAD_BRANCH" \
-            --title "chore: merge design into develop" \
+            --title "$PR_TITLE" \
-            --body "Automated promotion PR from \`design\` to \`develop\`."
+            --body "Automated weekly promotion PR from \`$HEAD_BRANCH\` to \`$BASE_BRANCH\`."
-
-  develop-to-main:
-    name: Open develop → main
-    runs-on: ubuntu-latest
-    if: |
-      (github.event_name == 'schedule' && github.event.schedule == '0 6 * * 1') ||
-      (github.event_name == 'workflow_dispatch' && (github.event.inputs.promotion == 'develop-to-main' || github.event.inputs.promotion == 'both'))
-    steps:
-      - name: ⬇️ Checkout
-        uses: actions/checkout@v4
-        with:
-          fetch-depth: 0
-
-      - name: 🔁 Open promotion PR
-        env:
-          GH_TOKEN: ${{ github.token }}
-        run: |
-          set -euo pipefail
-
-          git fetch origin main develop
-
-          if git merge-base --is-ancestor origin/develop origin/main; then
-            echo "No promotion needed: main already contains develop."
-            exit 0
-          fi
-
-          existing_pr="$(gh pr list \
-            --state open \
-            --base main \
-            --head "$GITHUB_REPOSITORY_OWNER:develop" \
-            --json number \
-            --jq '.[0].number // empty')"
-
-          if [ -n "$existing_pr" ]; then
-            echo "Promotion PR already open: #$existing_pr."
-            exit 0
-          fi
-
-          gh pr create \
-            --base main \
-            --head develop \
-            --title "chore: merge develop into main" \
-            --body "Automated weekly promotion PR from \`develop\` to \`main\`."

src/components/ebike/Ebike.tsx

@@ -0,0 +1,280 @@
+import { useEffect, useRef, useState, useMemo } from "react";
+import * as THREE from "three";
+import { useFrame, useThree } from "@react-three/fiber";
+import { EbikeGPSMap } from "@/components/ebike/EbikeGPSMap";
+import { InteractableObject } from "@/components/three/interaction/InteractableObject";
+import { useLoggedGLTF } from "@/hooks/three/useLoggedGLTF";
+import { useClonedObject } from "@/hooks/three/useClonedObject";
+import { useDebugFolder } from "@/hooks/debug/useDebugFolder";
+import { animateCameraTransformTransition } from "@/world/GameCinematics";
+import { useGameStore } from "@/managers/stores/useGameStore";
+import { PLAYER_EYE_HEIGHT } from "@/data/player/playerConfig";
+import type { Vector3Tuple } from "@/types/three/three";
+
+const EBIKE_MODEL_PATH = "/models/ebike/model.gltf";
+
+export interface CameraTransform {
+  position: Vector3Tuple;
+  rotation: Vector3Tuple;
+}
+
+export const EBIKE_CAMERA_TRANSFORM: CameraTransform = {
+  position: [-3.5, 6, 0],
+  rotation: [-10, -90, 0],
+};
+
+const EBIKE_DROP_PLAYER_TRANSFORM: CameraTransform = {
+  position: [0, 1.5, -3],
+  rotation: [0, 0, 0],
+};
+
+interface EbikeProps {
+  position: Vector3Tuple;
+}
+
+export function Ebike({ position }: EbikeProps): React.JSX.Element {
+  const groupRef = useRef<THREE.Group>(null);
+  const { scene } = useLoggedGLTF(EBIKE_MODEL_PATH, {
+    scope: "Ebike",
+    position: position,
+  });
+  const model = useClonedObject(scene);
+  const movementMode = useGameStore((state) => state.player.movementMode);
+  const mainState = useGameStore((state) => state.mainState);
+  const camera = useThree((state) => state.camera);
+
+  // Map active mainState to target repair zone coordinate
+  const destPos = useMemo(() => {
+    switch (mainState) {
+      case "bike":
+        return { x: 8, y: 0, z: -6 };
+      case "pylone":
+        return { x: 64, y: 0, z: -66 };
+      case "ferme":
+        return { x: -24, y: 0, z: 42 };
+      default:
+        return undefined;
+    }
+  }, [mainState]);
+
+  // Throttled GPS start position to optimize pathfinding A* algorithm execution
+  const [gpsStartPos, setGpsStartPos] = useState<{ x: number; y: number; z: number }>({
+    x: position[0],
+    y: position[1],
+    z: position[2],
+  });
+  const lastGpsUpdatePos = useRef<THREE.Vector3>(new THREE.Vector3(...position));
+
+  const restingPosition = useRef<Vector3Tuple>([
+    position[0],
+    position[1] - PLAYER_EYE_HEIGHT,
+    position[2],
+  ]);
+  const restingRotation = useRef<number>(0);
+  const forkRef = useRef<THREE.Object3D | null>(null);
+
+  useEffect(() => {
+    if (model) {
+      const fork = model.getObjectByName("fourche");
+      if (fork) {
+        forkRef.current = fork;
+      }
+    }
+  }, [model]);
+
+  useEffect(() => {
+    (window as any).ebikeVisualGroup = groupRef;
+    (window as any).ebikeParkedPosition = restingPosition.current;
+    (window as any).ebikeParkedRotation = restingRotation.current;
+    return () => {
+      (window as any).ebikeVisualGroup = null;
+      (window as any).ebikeParkedPosition = null;
+      (window as any).ebikeParkedRotation = null;
+    };
+  }, []);
+
+  useFrame((_, delta) => {
+    if (groupRef.current) {
+      if (movementMode === "ebike") {
+        restingPosition.current = [
+          groupRef.current.position.x,
+          groupRef.current.position.y,
+          groupRef.current.position.z,
+        ];
+        restingRotation.current = groupRef.current.rotation.y;
+
+        // Smoothly rotate the front fork ("fourche") up to 15 degrees in its own Z axis
+        const steerFactor = (window as any).ebikeSteerFactor || 0;
+        if (forkRef.current) {
+          // 15 degrees is 0.26 radians
+          const targetForkRotation = steerFactor * 0.26;
+          forkRef.current.rotation.z = THREE.MathUtils.lerp(
+            forkRef.current.rotation.z,
+            targetForkRotation,
+            12 * delta
+          );
+        }
+
+        // Throttled GPS start position update to prevent performance loss
+        const currentPos = groupRef.current.position;
+        if (currentPos.distanceTo(lastGpsUpdatePos.current) > 2.0) {
+          lastGpsUpdatePos.current.copy(currentPos);
+          setGpsStartPos({ x: currentPos.x, y: currentPos.y, z: currentPos.z });
+        }
+      } else {
+        groupRef.current.position.set(...restingPosition.current);
+        groupRef.current.rotation.set(0, restingRotation.current, 0);
+
+        // Reset fork rotation when parked
+        if (forkRef.current) {
+          forkRef.current.rotation.z = 0;
+        }
+      }
+      (window as any).ebikeParkedPosition = restingPosition.current;
+      (window as any).ebikeParkedRotation = restingRotation.current;
+    }
+  });
+
+  const camPointPos: Vector3Tuple = [
+    restingPosition.current[0] + EBIKE_CAMERA_TRANSFORM.position[0],
+    restingPosition.current[1] + EBIKE_CAMERA_TRANSFORM.position[1],
+    restingPosition.current[2] + EBIKE_CAMERA_TRANSFORM.position[2],
+  ];
+  const dropPointPos: Vector3Tuple = [
+    restingPosition.current[0] + EBIKE_DROP_PLAYER_TRANSFORM.position[0],
+    restingPosition.current[1] + EBIKE_DROP_PLAYER_TRANSFORM.position[1],
+    restingPosition.current[2] + EBIKE_DROP_PLAYER_TRANSFORM.position[2],
+  ];
+
+  const handleInteract = (): void => {
+    if (movementMode === "walk") {
+      const cameraOffset = new THREE.Vector3(...EBIKE_CAMERA_TRANSFORM.position);
+      cameraOffset.applyAxisAngle(new THREE.Vector3(0, 1, 0), restingRotation.current);
+
+      const targetCamPos: Vector3Tuple = [
+        restingPosition.current[0] + cameraOffset.x,
+        restingPosition.current[1] + cameraOffset.y,
+        restingPosition.current[2] + cameraOffset.z,
+      ];
+
+      const targetRotation: Vector3Tuple = [
+        EBIKE_CAMERA_TRANSFORM.rotation[0],
+        EBIKE_CAMERA_TRANSFORM.rotation[1] + THREE.MathUtils.radToDeg(restingRotation.current),
+        EBIKE_CAMERA_TRANSFORM.rotation[2],
+      ];
+
+      animateCameraTransformTransition(targetCamPos, targetRotation, 1, () => {
+        useGameStore.getState().setPlayerMovementMode("ebike");
+      });
+    } else {
+      const currentPos = new THREE.Vector3();
+      if (groupRef.current) {
+        groupRef.current.getWorldPosition(currentPos);
+      } else {
+        currentPos.set(...position);
+      }
+
+      const targetCamPos: Vector3Tuple = [
+        currentPos.x + EBIKE_DROP_PLAYER_TRANSFORM.position[0],
+        currentPos.y + EBIKE_DROP_PLAYER_TRANSFORM.position[1],
+        currentPos.z + EBIKE_DROP_PLAYER_TRANSFORM.position[2],
+      ];
+
+      // Get camera's current rotation in degrees so we keep the exact orientation during dismount
+      const currentEuler = new THREE.Euler().setFromQuaternion(camera.quaternion, "YXZ");
+      const targetRotation: Vector3Tuple = [
+        THREE.MathUtils.radToDeg(currentEuler.x),
+        THREE.MathUtils.radToDeg(currentEuler.y),
+        THREE.MathUtils.radToDeg(currentEuler.z),
+      ];
+
+      animateCameraTransformTransition(targetCamPos, targetRotation, 1, () => {
+        useGameStore.getState().setPlayerMovementMode("walk");
+      });
+    }
+  };
+
+  const handleInteractRef = useRef(handleInteract);
+  handleInteractRef.current = handleInteract;
+
+  const debugRef = useRef({ showCameraPoints: true });
+  const debugActions = useRef({
+    toggleRide: () => {
+      handleInteractRef.current();
+    }
+  });
+
+  useDebugFolder("Ebike", (folder) => {
+    folder
+      .add(debugRef.current, "showCameraPoints")
+      .name("Show Camera Points")
+      .onChange((value: boolean) => {
+        debugRef.current.showCameraPoints = value;
+      });
+
+    folder
+      .add(debugActions.current, "toggleRide")
+      .name("Monter / Descendre");
+  });
+
+  return (
+    <>
+      <group ref={groupRef} position={position}>
+        <primitive object={model} />
+        <InteractableObject
+          kind="trigger"
+          label={
+            movementMode === "walk" ? "Monter sur le bike" : "Descendre du bike"
+          }
+          position={position}
+          radius={15}
+          onPress={handleInteract}
+        >
+          <mesh>
+            <boxGeometry args={[10, 13, 2]} />
+            <meshBasicMaterial colorWrite={false} depthWrite={false} />
+          </mesh>
+        </InteractableObject>
+
+        {/* Dynamic 3D GPS Dashboard Screen */}
+        <group position={[0, 7, 0]} rotation={[0, 90, 0]}>
+          <EbikeGPSMap
+            width={0.8}
+            height={0.8}
+            startPos={gpsStartPos}
+            destPos={destPos}
+            mapImageUrl="/map_background.png"
+            worldBounds={{
+              minX: -166,
+              maxX: 163,
+              minZ: -142,
+              maxZ: 138,
+            }}
+            zoom={4}
+          />
+        </group>
+      </group>
+
+      {debugRef.current.showCameraPoints && (
+        <>
+          <mesh position={camPointPos}>
+            <sphereGeometry args={[0.3, 16, 16]} />
+            <meshStandardMaterial
+              color="yellow"
+              emissive="yellow"
+              emissiveIntensity={0.5}
+            />
+          </mesh>
+          <mesh position={dropPointPos}>
+            <sphereGeometry args={[0.3, 16, 16]} />
+            <meshStandardMaterial
+              color="cyan"
+              emissive="cyan"
+              emissiveIntensity={0.5}
+            />
+          </mesh>
+        </>
+      )}
+    </>
+  );
+}

src/components/ebike/EbikeGPSMap.tsx

@@ -0,0 +1,469 @@
+import React, { useRef, useEffect, useState, useMemo } from 'react';
+import * as THREE from 'three';
+import { findClosestWaypoint, findWaypointPath } from '@/pathfinding/WaypointAStar';
+import type { Waypoint } from '@/pathfinding/types';
+function computeImageSource(
+  img: HTMLImageElement | HTMLCanvasElement,
+  baseBounds: { minX: number; maxX: number; minZ: number; maxZ: number },
+  bounds: { minX: number; maxX: number; minZ: number; maxZ: number }
+) {
+  const imgW = img.width;
+  const imgH = img.height;
+
+  const baseW = baseBounds.maxX - baseBounds.minX;
+  const baseH = baseBounds.maxZ - baseBounds.minZ;
+
+  if (baseW === 0 || baseH === 0) {
+    return { sx: 0, sy: 0, sW: imgW, sH: imgH };
+  }
+
+  const sx = ((bounds.minX - baseBounds.minX) / baseW) * imgW;
+  const sy = ((bounds.minZ - baseBounds.minZ) / baseH) * imgH;
+  const sW = ((bounds.maxX - bounds.minX) / baseW) * imgW;
+  const sH = ((bounds.maxZ - bounds.minZ) / baseH) * imgH;
+
+  return { sx, sy, sW, sH };
+}
+
+export interface EbikeGPSMapProps {
+  /**
+   * 3D world position of the player/bike (GPS start point)
+   * If omitted, snaps to [0,0,0]
+   */
+  startPos?: { x: number; y: number; z: number } | undefined;
+  destPos?: { x: number; y: number; z: number } | undefined;
+
+  /**
+   * Optional custom URL to the map background texture.
+   * If not provided, renders a high-tech minimalist neon blueprint map dynamically.
+   */
+  mapImageUrl?: string;
+
+  /**
+   * Optional explicit bounds for mapping coordinates.
+   * If omitted, bounds are calculated automatically to perfectly fit the road network!
+   */
+  worldBounds?: {
+    minX: number;
+    maxX: number;
+    minZ: number;
+    maxZ: number;
+  };
+
+  /**
+   * Width of the 3D plane mesh (default: 1)
+   */
+  width?: number;
+
+  /**
+   * Height of the 3D plane mesh (default: 1)
+   */
+  height?: number;
+
+  /**
+   * Optional world position for the GPS screen (defaults to origin)
+   */
+  position?: [number, number, number];
+
+  /**
+   * Resolution of the offscreen canvas used for the map texture.
+   * Higher values yield sharper rendering at the cost of GPU memory.
+   * Default: 1024 (1024×1024 px)
+   */
+  canvasSize?: number;
+
+  /**
+   * Zoom level applied to the map view.
+   * 1 = full world bounds, 2 = 2× zoom-in centred on the player, etc.
+   * Values < 1 zoom out beyond the calculated world bounds.
+   * Default: 1
+   */
+  zoom?: number;
+}
+
+/**
+ * EbikeGPSMap
+ * A premium, state-of-the-art 3D GPS navigation screen for the Ebike.
+ * Loads the road network, runs A* pathfinding, and renders a glowing, animated
+ * orange path over a sleek high-tech map background.
+ */
+export const EbikeGPSMap: React.FC<EbikeGPSMapProps> = ({
+  startPos = { x: 0, y: 0, z: 0 },
+  destPos,
+  mapImageUrl,
+  worldBounds,
+  width = 1,
+  height = 1,
+  position = [0, 0, 0],
+  canvasSize = 1024,
+  zoom = 1,
+}) => {
+  const [waypoints, setWaypoints] = useState<Waypoint[]>([]);
+  const [mapImage, setMapImage] = useState<HTMLImageElement | HTMLCanvasElement | null>(null);
+
+  // Offscreen high-res canvas for crystal clear rendering
+  const [offscreenCanvas] = useState(() => {
+    const canvas = document.createElement('canvas');
+    canvas.width = canvasSize;
+    canvas.height = canvasSize;
+    return canvas;
+  });
+
+  // Resize the canvas whenever canvasSize changes
+  useEffect(() => {
+    offscreenCanvas.width = canvasSize;
+    offscreenCanvas.height = canvasSize;
+    if (textureRef.current) {
+      textureRef.current.needsUpdate = true;
+    }
+  }, [canvasSize, offscreenCanvas]);
+
+  const textureRef = useRef<THREE.CanvasTexture | null>(null);
+  const animTimeRef = useRef<number>(0);
+
+  // Load waypoints (localStorage with /roadNetwork.json fallback)
+  useEffect(() => {
+    const saved = localStorage.getItem('la-fabrik-waypoints');
+    if (saved) {
+      try {
+        const parsed = JSON.parse(saved);
+        if (Array.isArray(parsed) && parsed.length > 0) {
+          setWaypoints(parsed);
+          return;
+        }
+      } catch (e) {
+        console.error('[GPS Component] Error loading local storage waypoints', e);
+      }
+    }
+
+    // Fallback to static roadNetwork.json
+    fetch('/roadNetwork.json')
+      .then((res) => {
+        if (res.ok) return res.json();
+        throw new Error('Not found');
+      })
+      .then((data) => {
+        if (Array.isArray(data)) {
+          setWaypoints(data);
+        }
+      })
+      .catch((err) => {
+        console.log('[GPS Component] No default road network found.', err);
+      });
+  }, []);
+
+  // Pre-load background map image (standard HTML5 Image loader)
+  // Since the user's PNG is already transparent, we don't need fetch or pixel manipulation!
+  useEffect(() => {
+    if (!mapImageUrl) {
+      setMapImage(null);
+      return;
+    }
+
+    const img = new Image();
+    img.onload = () => {
+      setMapImage(img);
+    };
+    img.onerror = () => {
+      console.warn(`[GPS Component] Failed to load map background image from ${mapImageUrl}. Falling back to dynamic vector map.`);
+      setMapImage(null);
+    };
+    img.src = mapImageUrl;
+  }, [mapImageUrl]);
+
+  // Determine grid boundaries (before zoom)
+  const baseBounds = useMemo(() => {
+    if (worldBounds) return worldBounds;
+
+    if (waypoints.length === 0) {
+      return { minX: -200, maxX: 200, minZ: -200, maxZ: 200 };
+    }
+
+    const xs = waypoints.map((w) => w.x);
+    const zs = waypoints.map((w) => w.z);
+    const minX = Math.min(...xs);
+    const maxX = Math.max(...xs);
+    const minZ = Math.min(...zs);
+    const maxZ = Math.max(...zs);
+
+    // Padding (15% to ensure full view breathing room)
+    const padX = (maxX - minX) * 0.15 || 40;
+    const padZ = (maxZ - minZ) * 0.15 || 40;
+
+    return {
+      minX: minX - padX,
+      maxX: maxX + padX,
+      minZ: minZ - padZ,
+      maxZ: maxZ + padZ,
+    };
+  }, [waypoints, worldBounds]);
+
+  // Apply zoom: shrink the view window around the player position
+  const bounds = useMemo(() => {
+    const clampedZoom = Math.max(0.1, zoom);
+    if (clampedZoom === 1) return baseBounds;
+
+    const centerX = startPos.x;
+    const centerZ = startPos.z;
+    const halfW = (baseBounds.maxX - baseBounds.minX) / 2 / clampedZoom;
+    const halfH = (baseBounds.maxZ - baseBounds.minZ) / 2 / clampedZoom;
+
+    return {
+      minX: centerX - halfW,
+      maxX: centerX + halfW,
+      minZ: centerZ - halfH,
+      maxZ: centerZ + halfH,
+    };
+  }, [baseBounds, zoom, startPos]);
+
+  // Snapped positions
+  const startPosSnapped = useMemo(() => {
+    if (waypoints.length === 0) return null;
+    return findClosestWaypoint(waypoints, startPos);
+  }, [waypoints, startPos]);
+
+  const destPosSnapped = useMemo(() => {
+    if (!destPos || waypoints.length === 0) return null;
+    return findClosestWaypoint(waypoints, destPos);
+  }, [waypoints, destPos]);
+
+  // Calculated active A* route
+  const activePath = useMemo(() => {
+    if (!startPosSnapped || !destPosSnapped || waypoints.length === 0) return [];
+    return findWaypointPath(waypoints, startPosSnapped, destPosSnapped);
+  }, [waypoints, startPosSnapped, destPosSnapped]);
+
+  // Translation helper: 3D world to Canvas pixels
+  const worldToCanvas = (wx: number, wz: number, canvasSize: number) => {
+    const { minX, maxX, minZ, maxZ } = bounds;
+    const px = ((wx - minX) / (maxX - minX)) * canvasSize;
+    const py = ((wz - minZ) / (maxZ - minZ)) * canvasSize;
+    return { x: px, y: py };
+  };
+
+
+
+  // Draw loop
+  const draw = () => {
+    const canvas = offscreenCanvas;
+    const ctx = canvas.getContext('2d', { willReadFrequently: true, alpha: true });
+    if (!ctx) return;
+
+    const size = canvas.width;
+
+    ctx.clearRect(0, 0, size, size);
+
+    // 1. Draw Map Background (Image or premium blueprint vectors)
+    if (mapImage) {
+      const src = computeImageSource(mapImage, baseBounds, bounds);
+      const sx = Math.max(0, Math.min(mapImage.width, src.sx));
+      const sy = Math.max(0, Math.min(mapImage.height, src.sy));
+      const sW = Math.max(1, Math.min(mapImage.width - sx, src.sW));
+      const sH = Math.max(1, Math.min(mapImage.height - sy, src.sH));
+
+      ctx.drawImage(mapImage, sx, sy, sW, sH, 0, 0, size, size);
+      ctx.globalAlpha = 1.0;
+    } else {
+      // Dynamic Sci-fi background grid (Background is transparent!)
+
+      // Sci-fi subgrid
+      ctx.strokeStyle = 'rgba(30, 41, 59, 0.4)';
+      ctx.lineWidth = 1;
+      const step = size / 32;
+      for (let x = 0; x < size; x += step) {
+        ctx.beginPath();
+        ctx.moveTo(x, 0);
+        ctx.lineTo(x, size);
+        ctx.stroke();
+      }
+      for (let y = 0; y < size; y += step) {
+        ctx.beginPath();
+        ctx.moveTo(0, y);
+        ctx.lineTo(size, y);
+        ctx.stroke();
+      }
+
+      // Aesthetic concentric radar topo-rings
+      ctx.strokeStyle = 'rgba(71, 85, 105, 0.06)';
+      ctx.lineWidth = 2;
+      for (let r = size / 6; r < size; r += size / 6) {
+        ctx.beginPath();
+        ctx.arc(size / 2, size / 2, r, 0, 2 * Math.PI);
+        ctx.stroke();
+      }
+
+      // Faint diagonal technical accents
+      ctx.strokeStyle = 'rgba(56, 189, 248, 0.03)';
+      ctx.lineWidth = 1;
+      ctx.beginPath();
+      ctx.moveTo(0, 0);
+      ctx.lineTo(size, size);
+      ctx.stroke();
+      ctx.beginPath();
+      ctx.moveTo(size, 0);
+      ctx.lineTo(0, size);
+      ctx.stroke();
+    }
+
+    // 2. Draw Active Orange Glowing Path (Neon Highway effect)
+    if (activePath.length > 1) {
+      // Pass 1: Wide transparent orange bloom
+      ctx.beginPath();
+      let pt = worldToCanvas(activePath[0]!.x, activePath[0]!.z, size);
+      ctx.moveTo(pt.x, pt.y);
+      for (let i = 1; i < activePath.length; i++) {
+        pt = worldToCanvas(activePath[i]!.x, activePath[i]!.z, size);
+        ctx.lineTo(pt.x, pt.y);
+      }
+      ctx.strokeStyle = 'rgba(249, 115, 22, 0.2)'; // Faint bright orange
+      ctx.lineWidth = 20;
+      ctx.lineCap = 'round';
+      ctx.lineJoin = 'round';
+      ctx.shadowBlur = 30;
+      ctx.shadowColor = '#f97316'; // Neon Orange
+      ctx.stroke();
+
+      // Pass 2: Saturated glow core
+      ctx.beginPath();
+      pt = worldToCanvas(activePath[0]!.x, activePath[0]!.z, size);
+      ctx.moveTo(pt.x, pt.y);
+      for (let i = 1; i < activePath.length; i++) {
+        pt = worldToCanvas(activePath[i]!.x, activePath[i]!.z, size);
+        ctx.lineTo(pt.x, pt.y);
+      }
+      ctx.strokeStyle = '#f97316'; // Vibrant orange
+      ctx.lineWidth = 8;
+      ctx.shadowBlur = 12;
+      ctx.shadowColor = '#ea580c';
+      ctx.stroke();
+
+      // Pass 3: High-intensity white core
+      ctx.beginPath();
+      pt = worldToCanvas(activePath[0]!.x, activePath[0]!.z, size);
+      ctx.moveTo(pt.x, pt.y);
+      for (let i = 1; i < activePath.length; i++) {
+        pt = worldToCanvas(activePath[i]!.x, activePath[i]!.z, size);
+        ctx.lineTo(pt.x, pt.y);
+      }
+      ctx.strokeStyle = '#fff7ed'; // Cream white
+      ctx.lineWidth = 3;
+      ctx.shadowBlur = 0; // Turn off shadows for the core
+      ctx.stroke();
+
+      // 3. Energy Particle Pulse animation tracing the road
+      const segments: { start: { x: number; y: number }; end: { x: number; y: number }; len: number }[] = [];
+      let totalLen = 0;
+      for (let i = 0; i < activePath.length - 1; i++) {
+        const p1 = worldToCanvas(activePath[i]!.x, activePath[i]!.z, size);
+        const p2 = worldToCanvas(activePath[i + 1]!.x, activePath[i + 1]!.z, size);
+        const len = Math.sqrt(Math.pow(p2.x - p1.x, 2) + Math.pow(p2.y - p1.y, 2));
+        segments.push({ start: p1, end: p2, len });
+        totalLen += len;
+      }
+
+      if (totalLen > 0) {
+        const targetLen = totalLen * animTimeRef.current;
+        let currentLen = 0;
+        let dotPt = segments[0]!.start;
+
+        for (const seg of segments) {
+          if (currentLen + seg.len >= targetLen) {
+            const ratio = (targetLen - currentLen) / seg.len;
+            dotPt = {
+              x: seg.start.x + (seg.end.x - seg.start.x) * ratio,
+              y: seg.start.y + (seg.end.y - seg.start.y) * ratio,
+            };
+            break;
+          }
+          currentLen += seg.len;
+        }
+
+        // Draw multiple glowing pulses along the path
+        ctx.beginPath();
+        ctx.arc(dotPt.x, dotPt.y, 8, 0, 2 * Math.PI);
+        ctx.fillStyle = '#ffffff';
+        ctx.shadowBlur = 15;
+        ctx.shadowColor = '#f97316';
+        ctx.fill();
+        ctx.shadowBlur = 0;
+      }
+    }
+
+    // 4. Draw Snap Markers (Start and End)
+    if (destPosSnapped) {
+      const pt = worldToCanvas(destPosSnapped.x, destPosSnapped.z, size);
+      const pulseSize = 12 + Math.sin(Date.now() * 0.007) * 4;
+
+      // Pulse ring
+      ctx.beginPath();
+      ctx.arc(pt.x, pt.y, pulseSize, 0, 2 * Math.PI);
+      ctx.strokeStyle = 'rgba(249, 115, 22, 0.4)';
+      ctx.lineWidth = 3;
+      ctx.stroke();
+
+      // Solid target core
+      ctx.beginPath();
+      ctx.arc(pt.x, pt.y, 6, 0, 2 * Math.PI);
+      ctx.fillStyle = '#ea580c'; // Deep target orange
+      ctx.strokeStyle = '#ffffff';
+      ctx.lineWidth = 2;
+      ctx.fill();
+      ctx.stroke();
+    }
+
+    if (startPosSnapped) {
+      const pt = worldToCanvas(startPosSnapped.x, startPosSnapped.z, size);
+
+      // Start Marker (Player Arrow/Dot)
+      ctx.beginPath();
+      ctx.arc(pt.x, pt.y, 8, 0, 2 * Math.PI);
+      ctx.fillStyle = '#0ea5e9'; // Cool cyberpunk sky blue
+      ctx.strokeStyle = '#ffffff';
+      ctx.lineWidth = 2.5;
+      ctx.fill();
+      ctx.stroke();
+
+      // Tech details
+      ctx.beginPath();
+      ctx.arc(pt.x, pt.y, 3, 0, 2 * Math.PI);
+      ctx.fillStyle = '#ffffff';
+      ctx.fill();
+    }
+
+    // 5. Update WebGL Texture
+    if (textureRef.current) {
+      textureRef.current.needsUpdate = true;
+    }
+  };
+
+  // 60 FPS animation ticker
+  useEffect(() => {
+    let animId: number;
+    const tick = () => {
+      animTimeRef.current += 0.004; // Slow, premium sweep speed
+      if (animTimeRef.current > 1) animTimeRef.current = 0;
+
+      draw();
+
+      animId = requestAnimationFrame(tick);
+    };
+    animId = requestAnimationFrame(tick);
+    return () => cancelAnimationFrame(animId);
+  }, [waypoints, startPos, destPos, bounds, mapImage]);
+
+  return (
+    <mesh castShadow receiveShadow position={position as any}>
+      <planeGeometry args={[width, height]} />
+      <meshBasicMaterial toneMapped={false} transparent={true} opacity={1} depthWrite={false} side={THREE.DoubleSide}>
+        <canvasTexture
+          ref={textureRef}
+          attach="map"
+          image={offscreenCanvas}
+          format={THREE.RGBAFormat}
+          minFilter={THREE.LinearFilter}
+          magFilter={THREE.LinearFilter}
+        />
+      </meshBasicMaterial>
+    </mesh>
+  );
+};

src/components/three/models/SimpleModel.tsx

@@ -1,7 +1,6 @@
-import { useEffect, useMemo } from "react";
+import { useMemo } from "react";
 import { useLoggedGLTF } from "@/hooks/three/useLoggedGLTF";
 import type { ModelTransformProps, Vector3Tuple } from "@/types/three/three";
-import { disposeObject3D } from "@/utils/three/dispose";
 
 export interface SimpleModelConfig extends ModelTransformProps {
   modelPath: string;
@@ -30,12 +29,6 @@ export function SimpleModel({
   });
   const model = useMemo(() => scene.clone(true), [scene]);
 
-  useEffect(() => {
-    return () => {
-      disposeObject3D(model);
-    };
-  }, [model]);
-
   const parsedScale =
     typeof scale === "number" ? ([scale, scale, scale] as Vector3Tuple) : scale;
 

src/components/three/world/SkyModel.tsx

@@ -1,9 +1,8 @@
 import { useFrame, useThree } from "@react-three/fiber";
 import { useGLTF } from "@react-three/drei";
-import { Component, useEffect, useMemo, useRef, type ReactNode } from "react";
+import { Component, useMemo, useRef, type ReactNode } from "react";
 import * as THREE from "three";
 import { useLoggedGLTF } from "@/hooks/three/useLoggedGLTF";
-import { disposeObject3D } from "@/utils/three/dispose";
 
 interface SkyModelProps {
   modelPath: string;
@@ -81,12 +80,6 @@ function SkyModelContent({
   });
   const model = useMemo(() => createSkyModel(scene), [scene]);
 
-  useEffect(() => {
-    return () => {
-      disposeObject3D(model);
-    };
-  }, [model]);
-
   useFrame(() => {
     groupRef.current?.position.copy(camera.position);
   });
@@ -129,5 +122,5 @@ function createSkyMaterial<T extends THREE.Material>(material: T): T {
   return skyMaterial as T;
 }
 
-useGLTF.preload("/models/skybox/model.gltf");
+useGLTF.preload("/models/skybox/skybox.gltf");
 useGLTF.preload(LEGACY_SKY_MODEL_PATH);

src/components/three/world/TerrainModel.tsx

@@ -1,73 +0,0 @@
-import { useEffect, useMemo, useRef } from "react";
-import * as THREE from "three";
-import { useGLTF } from "@react-three/drei";
-import type { Vector3Tuple } from "@/types/three/three";
-import { disposeObject3D } from "@/utils/three/dispose";
-
-const TERRAIN_MODEL_PATH = "/models/terrain/model.gltf";
-const TERRAIN_DEFAULT_POSITION: Vector3Tuple = [0, 0, 0];
-
-interface TerrainModelProps {
-  position?: Vector3Tuple;
-  rotation?: Vector3Tuple;
-  scale?: Vector3Tuple;
-  receiveShadow?: boolean;
-  visible?: boolean;
-  groupRef?: React.RefObject<THREE.Group>;
-  onLoaded?: () => void;
-}
-
-function applyTerrainMaterialSettings(
-  scene: THREE.Object3D,
-  receiveShadow: boolean,
-): void {
-  scene.traverse((child) => {
-    if (child instanceof THREE.Mesh) {
-      child.receiveShadow = receiveShadow;
-    }
-  });
-}
-
-export function TerrainModel({
-  position = TERRAIN_DEFAULT_POSITION,
-  rotation = [0, 0, 0],
-  scale = [1, 1, 1],
-  receiveShadow = true,
-  visible = true,
-  groupRef,
-  onLoaded,
-}: TerrainModelProps): React.JSX.Element {
-  const internalRef = useRef<THREE.Group>(null);
-  const ref = groupRef ?? internalRef;
-  const { scene } = useGLTF(TERRAIN_MODEL_PATH);
-
-  const terrainModel = useMemo(() => {
-    const model = scene.clone(true);
-    applyTerrainMaterialSettings(model, receiveShadow);
-    return model;
-  }, [scene, receiveShadow]);
-
-  useEffect(() => {
-    return () => {
-      disposeObject3D(terrainModel);
-    };
-  }, [terrainModel]);
-
-  useEffect(() => {
-    onLoaded?.();
-  }, [onLoaded]);
-
-  return (
-    <group
-      ref={ref}
-      position={position}
-      rotation={rotation}
-      scale={scale}
-      visible={visible}
-    >
-      <primitive object={terrainModel} />
-    </group>
-  );
-}
-
-useGLTF.preload(TERRAIN_MODEL_PATH);

src/data/player/playerConfig.ts

@@ -4,6 +4,7 @@ export const PLAYER_EYE_HEIGHT = 1.75;
 export const PLAYER_CAPSULE_RADIUS = 0.35;
 
 export const PLAYER_WALK_SPEED = 11;
+export const PLAYER_EBIKE_SPEED = 25;
 export const PLAYER_AIR_CONTROL_FACTOR = 0.35;
 export const PLAYER_JUMP_SPEED = 9;
 export const PLAYER_GRAVITY = 30;

src/data/world/environmentConfig.ts

@@ -1,5 +1,5 @@
 export const GAME_SCENE_SKY_MODEL_PATH = "/models/skybox/skybox.gltf";
 export const GAME_SCENE_FALLBACK_SKY_MODEL_PATH = "/models/sky/model.glb";
-export const GAME_SCENE_SKY_MODEL_SCALE = 100;
+export const GAME_SCENE_SKY_MODEL_SCALE = 300;
 export const GAME_SCENE_FALLBACK_SKY_MODEL_SCALE = 1;
 export const PHYSICS_SCENE_BACKGROUND_COLOR = "#0b1018";

src/data/world/fogConfig.ts

@@ -1,18 +0,0 @@
-import { TERRAIN_COLORS } from "@/data/world/terrainConfig";
-
-export const FOG_CONFIG = {
-  enabled: true,
-  color: "#c8dbbe",
-  near: 50,
-  far: 70,
-};
-
-export const CHUNK_CONFIG = {
-  enabled: true,
-  chunkSize: 40,
-  loadRadius: 70,
-  unloadRadius: 80,
-  updateInterval: 500,
-};
-
-export const GROUND_PLANE_COLOR = TERRAIN_COLORS.grass1.hex;

src/data/world/graphicsConfig.ts

@@ -1,13 +0,0 @@
-export const GRAPHICS_DEFAULTS = {
-  dynamicGrass: true,
-  dynamicTrees: true,
-  dynamicClouds: true,
-  shadowsEnabled: true,
-  grassDensity: 1.0,
-};
-
-export const GRAPHICS_BOUNDS = {
-  grassDensity: { min: 0.1, max: 2.0, step: 0.1 },
-};
-
-export type GraphicsState = typeof GRAPHICS_DEFAULTS;

src/data/world/terrainConfig.ts

@@ -1,108 +0,0 @@
-export const TERRAIN_COLORS = {
-  grass1: {
-    hex: "#84C66B",
-    rgb: [132, 198, 107] as const,
-    type: "grass" as const,
-    grassTipColor: "#84C66B",
-  },
-  grass2: {
-    hex: "#67B058",
-    rgb: [103, 176, 88] as const,
-    type: "grass" as const,
-    grassTipColor: "#67B058",
-  },
-  grass3: {
-    hex: "#A3CA5B",
-    rgb: [163, 202, 91] as const,
-    type: "grass" as const,
-    grassTipColor: "#A3CA5B",
-  },
-  potager: {
-    hex: "#342420",
-    rgb: [52, 36, 32] as const,
-    type: "tile" as const,
-    tileModel: "/models/potager/potager.gltf",
-    tileSize: 1,
-  },
-  terre: {
-    hex: "#513E2C",
-    rgb: [81, 62, 44] as const,
-    type: "none" as const,
-  },
-  chemin: {
-    hex: "#F5D896",
-    rgb: [245, 216, 150] as const,
-    type: "tile" as const,
-    tileModel: "/models/chemins/model.gltf",
-    tileSize: 1,
-  },
-  eau: {
-    hex: "#91DAF5",
-    rgb: [145, 218, 245] as const,
-    type: "water" as const,
-  },
-  cailloux: {
-    hex: "#B6D3DE",
-    rgb: [182, 211, 222] as const,
-    type: "none" as const,
-  },
-} as const;
-
-export type TerrainColorKey = keyof typeof TERRAIN_COLORS;
-export type TerrainType = "grass" | "tile" | "water" | "none";
-
-export const GRASS_BASE_COLOR = "#1a3a1a";
-
-export const COLOR_TOLERANCE = 15;
-
-export function colorMatchesTerrain(
-  r: number,
-  g: number,
-  b: number,
-  targetRgb: readonly [number, number, number],
-  tolerance: number = COLOR_TOLERANCE,
-): boolean {
-  return (
-    Math.abs(r - targetRgb[0]) <= tolerance &&
-    Math.abs(g - targetRgb[1]) <= tolerance &&
-    Math.abs(b - targetRgb[2]) <= tolerance
-  );
-}
-
-export function getTerrainTypeFromColor(
-  r: number,
-  g: number,
-  b: number,
-): TerrainColorKey | null {
-  for (const [key, config] of Object.entries(TERRAIN_COLORS)) {
-    if (colorMatchesTerrain(r, g, b, config.rgb)) {
-      return key as TerrainColorKey;
-    }
-  }
-  return null;
-}
-
-export function isGrassZone(r: number, g: number, b: number): boolean {
-  return (
-    colorMatchesTerrain(r, g, b, TERRAIN_COLORS.grass1.rgb) ||
-    colorMatchesTerrain(r, g, b, TERRAIN_COLORS.grass2.rgb) ||
-    colorMatchesTerrain(r, g, b, TERRAIN_COLORS.grass3.rgb)
-  );
-}
-
-export function getGrassTipColor(
-  r: number,
-  g: number,
-  b: number,
-): string | null {
-  if (colorMatchesTerrain(r, g, b, TERRAIN_COLORS.grass1.rgb)) {
-    return TERRAIN_COLORS.grass1.grassTipColor;
-  }
-  if (colorMatchesTerrain(r, g, b, TERRAIN_COLORS.grass2.rgb)) {
-    return TERRAIN_COLORS.grass2.grassTipColor;
-  }
-  if (colorMatchesTerrain(r, g, b, TERRAIN_COLORS.grass3.rgb)) {
-    return TERRAIN_COLORS.grass3.grassTipColor;
-  }
-  return null;
-}

src/data/world/windConfig.ts

@@ -1,15 +0,0 @@
-export const WIND_DEFAULTS = {
-  speed: 0.3,
-  direction: Math.PI * 0.25,
-  strength: 1.0,
-  noiseScale: 0.9,
-};
-
-export const WIND_BOUNDS = {
-  speed: { min: 0, max: 2, step: 0.1 },
-  direction: { min: -Math.PI, max: Math.PI, step: 0.1 },
-  strength: { min: 0, max: 3, step: 0.1 },
-  noiseScale: { min: 0.1, max: 5, step: 0.1 },
-};
-
-export type WindState = typeof WIND_DEFAULTS;

src/hooks/three/useClonedObject.ts

@@ -1,15 +1,6 @@
-import { useEffect, useMemo } from "react";
+import { useMemo } from "react";
-import * as THREE from "three";
+import type * as THREE from "three";
-import { disposeObject3D } from "@/utils/three/dispose";
 
 export function useClonedObject<T extends THREE.Object3D>(object: T): T {
-  const clone = useMemo(() => object.clone(true) as T, [object]);
+  return useMemo(() => object.clone(true) as T, [object]);
-
-  useEffect(() => {
-    return () => {
-      disposeObject3D(clone);
-    };
-  }, [clone]);
-
-  return clone;
 }

src/hooks/world/useGraphicsSettings.ts

@@ -1,58 +0,0 @@
-import { useWorldSettingsStore } from "@/managers/stores/useWorldSettingsStore";
-import type { GraphicsState } from "@/data/world/graphicsConfig";
-
-export function useGraphicsSettings(): GraphicsState {
-  return useWorldSettingsStore((state) => state.graphics);
-}
-
-export function useSetGraphicsSettings(): (
-  graphics: Partial<GraphicsState>
-) => void {
-  return useWorldSettingsStore((state) => state.setGraphics);
-}
-
-export function useDynamicGrass(): boolean {
-  return useWorldSettingsStore((state) => state.graphics.dynamicGrass);
-}
-
-export function useDynamicTrees(): boolean {
-  return useWorldSettingsStore((state) => state.graphics.dynamicTrees);
-}
-
-export function useDynamicClouds(): boolean {
-  return useWorldSettingsStore((state) => state.graphics.dynamicClouds);
-}
-
-export function useShadowsEnabled(): boolean {
-  return useWorldSettingsStore((state) => state.graphics.shadowsEnabled);
-}
-
-export function useGrassDensity(): number {
-  return useWorldSettingsStore((state) => state.graphics.grassDensity);
-}
-
-export function useGraphicsSetters() {
-  const setDynamicGrass = useWorldSettingsStore(
-    (state) => state.setDynamicGrass
-  );
-  const setDynamicTrees = useWorldSettingsStore(
-    (state) => state.setDynamicTrees
-  );
-  const setDynamicClouds = useWorldSettingsStore(
-    (state) => state.setDynamicClouds
-  );
-  const setShadowsEnabled = useWorldSettingsStore(
-    (state) => state.setShadowsEnabled
-  );
-  const setGrassDensity = useWorldSettingsStore(
-    (state) => state.setGrassDensity
-  );
-
-  return {
-    setDynamicGrass,
-    setDynamicTrees,
-    setDynamicClouds,
-    setShadowsEnabled,
-    setGrassDensity,
-  };
-}

src/hooks/world/useWind.ts

@@ -1,22 +0,0 @@
-import { useWorldSettingsStore } from "@/managers/stores/useWorldSettingsStore";
-import type { WindState } from "@/data/world/windConfig";
-
-export function useWind(): WindState {
-  return useWorldSettingsStore((state) => state.wind);
-}
-
-export function useSetWind(): (wind: Partial<WindState>) => void {
-  return useWorldSettingsStore((state) => state.setWind);
-}
-
-export function useWindSpeed(): number {
-  return useWorldSettingsStore((state) => state.wind.speed);
-}
-
-export function useWindDirection(): number {
-  return useWorldSettingsStore((state) => state.wind.direction);
-}
-
-export function useWindStrength(): number {
-  return useWorldSettingsStore((state) => state.wind.strength);
-}

src/managers/stores/useGameStore.ts

@@ -7,8 +7,13 @@ import {
   type MissionStep,
   type RepairMissionId,
 } from "@/types/gameplay/repairMission";
+import {
+  PLAYER_WALK_SPEED,
+  PLAYER_EBIKE_SPEED,
+} from "@/data/player/playerConfig";
 
 export type MainGameState = "intro" | "bike" | "pylone" | "ferme" | "outro";
+export type PlayerMovementMode = "walk" | "ebike";
 export type { MissionStep, RepairMissionId };
 
 interface IntroState {
@@ -30,10 +35,16 @@ interface MissionFlowState {
   playerName: string;
 }
 
+interface PlayerState {
+  movementMode: PlayerMovementMode;
+  currentSpeed: number;
+}
+
 interface GameState {
   mainState: MainGameState;
   isCinematicPlaying: boolean;
   missionFlow: MissionFlowState;
+  player: PlayerState;
   intro: IntroState;
   bike: MissionState & {
     isRepaired: boolean;
@@ -56,6 +67,7 @@ interface GameActions {
   hideDialog: () => void;
   setActivityCity: (activityCity: boolean) => void;
   setCanMove: (canMove: boolean) => void;
+  setPlayerMovementMode: (mode: PlayerMovementMode) => void;
   setIntroStep: (step: GameStep) => void;
   setIntroState: (intro: Partial<IntroState>) => void;
   setPlayerName: (playerName: string) => void;
@@ -209,6 +221,10 @@ function createInitialGameState(): GameState {
       dialogMessage: null,
       playerName: "",
     },
+    player: {
+      movementMode: "walk",
+      currentSpeed: PLAYER_WALK_SPEED,
+    },
     intro: {
       currentStep: "intro",
       dialogueAudio: null,
@@ -249,6 +265,14 @@ export const useGameStore = create<GameStore>()((set) => ({
     set((state) => ({
       missionFlow: { ...state.missionFlow, activityCity },
     })),
+  setPlayerMovementMode: (mode) =>
+    set((state) => ({
+      player: {
+        ...state.player,
+        movementMode: mode,
+        currentSpeed: mode === "ebike" ? PLAYER_EBIKE_SPEED : PLAYER_WALK_SPEED,
+      },
+    })),
   setCanMove: (canMove) =>
     set((state) => ({
       missionFlow: { ...state.missionFlow, canMove },

src/managers/stores/useWorldSettingsStore.ts

@@ -1,88 +0,0 @@
-import { create } from "zustand";
-import { WIND_DEFAULTS, type WindState } from "@/data/world/windConfig";
-import {
-  GRAPHICS_DEFAULTS,
-  type GraphicsState,
-} from "@/data/world/graphicsConfig";
-
-interface WorldSettingsState {
-  wind: WindState;
-  graphics: GraphicsState;
-}
-
-interface WorldSettingsActions {
-  setWind: (wind: Partial<WindState>) => void;
-  setWindSpeed: (speed: number) => void;
-  setWindDirection: (direction: number) => void;
-  setWindStrength: (strength: number) => void;
-  setGraphics: (graphics: Partial<GraphicsState>) => void;
-  setDynamicGrass: (enabled: boolean) => void;
-  setDynamicTrees: (enabled: boolean) => void;
-  setDynamicClouds: (enabled: boolean) => void;
-  setShadowsEnabled: (enabled: boolean) => void;
-  setGrassDensity: (density: number) => void;
-  resetToDefaults: () => void;
-}
-
-type WorldSettingsStore = WorldSettingsState & WorldSettingsActions;
-
-const DEFAULT_STATE: WorldSettingsState = {
-  wind: { ...WIND_DEFAULTS },
-  graphics: { ...GRAPHICS_DEFAULTS },
-};
-
-export const useWorldSettingsStore = create<WorldSettingsStore>()((set) => ({
-  ...DEFAULT_STATE,
-
-  setWind: (windUpdate) =>
-    set((state) => ({
-      wind: { ...state.wind, ...windUpdate },
-    })),
-
-  setWindSpeed: (speed) =>
-    set((state) => ({
-      wind: { ...state.wind, speed },
-    })),
-
-  setWindDirection: (direction) =>
-    set((state) => ({
-      wind: { ...state.wind, direction },
-    })),
-
-  setWindStrength: (strength) =>
-    set((state) => ({
-      wind: { ...state.wind, strength },
-    })),
-
-  setGraphics: (graphicsUpdate) =>
-    set((state) => ({
-      graphics: { ...state.graphics, ...graphicsUpdate },
-    })),
-
-  setDynamicGrass: (dynamicGrass) =>
-    set((state) => ({
-      graphics: { ...state.graphics, dynamicGrass },
-    })),
-
-  setDynamicTrees: (dynamicTrees) =>
-    set((state) => ({
-      graphics: { ...state.graphics, dynamicTrees },
-    })),
-
-  setDynamicClouds: (dynamicClouds) =>
-    set((state) => ({
-      graphics: { ...state.graphics, dynamicClouds },
-    })),
-
-  setShadowsEnabled: (shadowsEnabled) =>
-    set((state) => ({
-      graphics: { ...state.graphics, shadowsEnabled },
-    })),
-
-  setGrassDensity: (grassDensity) =>
-    set((state) => ({
-      graphics: { ...state.graphics, grassDensity },
-    })),
-
-  resetToDefaults: () => set(DEFAULT_STATE),
-}));

src/pages/backgroundmap/page.tsx

@@ -0,0 +1,251 @@
+import React, { useState, useEffect, useRef, useMemo } from 'react';
+import { Canvas, useFrame, useThree } from '@react-three/fiber';
+import { MapControls, OrthographicCamera, useGLTF } from '@react-three/drei';
+import * as THREE from 'three';
+
+// ----------------------------------------------------------------------------
+// 1. Terrain Scene
+// ----------------------------------------------------------------------------
+function TerrainScene() {
+  const { scene } = useGLTF('/models/terrain/terrain.glb');
+  return (
+    <group>
+      <ambientLight intensity={1.5} />
+      <directionalLight position={[10, 20, 10]} intensity={2} />
+      <primitive object={scene} />
+    </group>
+  );
+}
+
+// ----------------------------------------------------------------------------
+// 2. Waypoint Overlay (Debug visualization)
+// ----------------------------------------------------------------------------
+function WaypointOverlay({ waypoints, visible }: { waypoints: any[], visible: boolean }) {
+  if (!visible) return null;
+  return (
+    <group>
+      {waypoints.map((w) => (
+        <mesh key={w.id} position={[w.x, w.y + 1, w.z]}>
+          <sphereGeometry args={[0.3, 16, 16]} />
+          <meshBasicMaterial color="#10b981" />
+        </mesh>
+      ))}
+    </group>
+  );
+}
+
+// ----------------------------------------------------------------------------
+// 3. Camera Manager (Handles Orthographic Math & Downloads)
+// ----------------------------------------------------------------------------
+function CameraManager({
+  autoBounds,
+  boundsTextRef
+}: {
+  autoBounds: any,
+  boundsTextRef: React.RefObject<HTMLPreElement | null>
+}) {
+  const { camera, gl, scene } = useThree();
+  const controlsRef = useRef<any>(null);
+
+  // Apply Auto-Bounds function
+  useEffect(() => {
+    const applyAutoBounds = () => {
+      if (camera instanceof THREE.OrthographicCamera && autoBounds) {
+        const width = autoBounds.maxX - autoBounds.minX;
+        const height = autoBounds.maxZ - autoBounds.minZ;
+        const centerX = (autoBounds.minX + autoBounds.maxX) / 2;
+        const centerZ = (autoBounds.minZ + autoBounds.maxZ) / 2;
+
+        camera.position.set(centerX, 200, centerZ);
+        camera.left = -width / 2;
+        camera.right = width / 2;
+        camera.top = height / 2;
+        camera.bottom = -height / 2;
+        camera.zoom = 1;
+        camera.updateProjectionMatrix();
+
+        if (controlsRef.current) {
+          controlsRef.current.target.set(centerX, 0, centerZ);
+          controlsRef.current.update();
+        }
+      }
+    };
+
+    (window as any).applyAutoBounds = applyAutoBounds;
+    // Initial apply
+    applyAutoBounds();
+
+    return () => { delete (window as any).applyAutoBounds; };
+  }, [camera, autoBounds]);
+
+  // Track dynamic bounds without triggering React re-renders!
+  useFrame(() => {
+    if (camera instanceof THREE.OrthographicCamera && boundsTextRef.current) {
+      const width = (camera.right - camera.left) / camera.zoom;
+      const height = (camera.top - camera.bottom) / camera.zoom;
+      const minX = Math.round(camera.position.x - width / 2);
+      const maxX = Math.round(camera.position.x + width / 2);
+      const minZ = Math.round(camera.position.z - height / 2);
+      const maxZ = Math.round(camera.position.z + height / 2);
+
+      // Direct DOM mutation for 60fps performance (prevents WebGL Context Lost!)
+      boundsTextRef.current.innerText = JSON.stringify({ minX, maxX, minZ, maxZ }, null, 2);
+    }
+  });
+
+  // Attach screenshot capture logic
+  useEffect(() => {
+    (window as any).downloadMapScreenshot = () => {
+      // Force an immediate render frame to ensure no UI overlays are missing
+      gl.render(scene, camera);
+      const dataUrl = gl.domElement.toDataURL("image/png");
+      const a = document.createElement("a");
+      a.href = dataUrl;
+      a.download = "map_background.png";
+      a.click();
+    };
+    return () => { delete (window as any).downloadMapScreenshot; };
+  }, [gl, camera, scene]);
+
+  return <MapControls ref={controlsRef} enableRotate={false} dampingFactor={0.05} />;
+}
+
+// ----------------------------------------------------------------------------
+// 4. Main Page Route Component
+// ----------------------------------------------------------------------------
+export function BackgroundMapPage() {
+  const [waypoints, setWaypoints] = useState<any[]>([]);
+  const [showWaypoints, setShowWaypoints] = useState(true);
+  const boundsTextRef = useRef<HTMLPreElement>(null);
+
+  // Load road network waypoints to compute perfect GPS bounds
+  useEffect(() => {
+    const saved = localStorage.getItem('la-fabrik-waypoints');
+    if (saved) {
+      setWaypoints(JSON.parse(saved));
+    } else {
+      fetch('/roadNetwork.json')
+        .then(res => res.json())
+        .then(data => setWaypoints(data))
+        .catch(() => { });
+    }
+  }, []);
+
+  // Compute exact bounds that the EbikeGPSMap will use by default
+  const autoBounds = useMemo(() => {
+    if (waypoints.length === 0) return null;
+    const xs = waypoints.map(w => w.x);
+    const zs = waypoints.map(w => w.z);
+    const minX = Math.min(...xs);
+    const maxX = Math.max(...xs);
+    const minZ = Math.min(...zs);
+    const maxZ = Math.max(...zs);
+
+    // CRITICAL: We MUST force the camera bounds to be a PERFECT SQUARE.
+    // If the camera is rectangular, the exported PNG will be distorted when drawn
+    // on the EbikeGPSMap's 1024x1024 canvas!
+    const width = maxX - minX;
+    const height = maxZ - minZ;
+    const maxDim = Math.max(width, height);
+
+    const centerX = (minX + maxX) / 2;
+    const centerZ = (minZ + maxZ) / 2;
+
+    const paddedDim = maxDim * 1.15 || 100;
+
+    return {
+      minX: centerX - paddedDim / 2,
+      maxX: centerX + paddedDim / 2,
+      minZ: centerZ - paddedDim / 2,
+      maxZ: centerZ + paddedDim / 2,
+    };
+  }, [waypoints]);
+
+  return (
+    <div style={{ width: '100vw', height: '100vh', background: '#050505', display: 'flex', justifyContent: 'center', alignItems: 'center' }}>
+      {/* 
+        CRITICAL: The DOM element MUST be a perfect square so the resulting PNG 
+        is exactly 1:1, preventing stretching in the EbikeGPSMap canvas texture! 
+      */}
+      <div style={{ width: 'min(100vw, 100vh)', height: 'min(100vw, 100vh)', background: '#000', position: 'relative' }}>
+        <Canvas gl={{ preserveDrawingBuffer: true, antialias: true, alpha: false }}>
+          <OrthographicCamera makeDefault position={[0, 200, 0]} near={0.1} far={1000} />
+          <TerrainScene />
+          <WaypointOverlay waypoints={waypoints} visible={showWaypoints} />
+          <CameraManager autoBounds={autoBounds} boundsTextRef={boundsTextRef} />
+        </Canvas>
+      </div>
+
+      {/* Premium Glassmorphic UI Dashboard */}
+      <div style={{
+        position: 'absolute', top: 24, left: 24,
+        background: 'rgba(15, 23, 42, 0.85)', padding: 24,
+        borderRadius: 16, border: '1px solid #334155',
+        color: 'white', fontFamily: 'system-ui, sans-serif',
+        backdropFilter: 'blur(12px)', width: 360,
+        boxShadow: '0 20px 25px -5px rgba(0, 0, 0, 0.5)'
+      }}>
+        <h2 style={{ margin: '0 0 16px 0', fontSize: '1.4rem', color: '#38bdf8' }}>GPS Map Generator</h2>
+
+        <p style={{ fontSize: '0.9rem', color: '#94a3b8', marginBottom: 20, lineHeight: 1.5 }}>
+          1. Cadrez votre carte (ou utilisez le <b>Cadrage Automatique</b>).<br />
+          2. Masquez les waypoints (fond visuel seul).<br />
+          3. Cliquez sur <b>Capturer la carte</b>.
+        </p>
+
+        <button
+          onClick={() => setShowWaypoints(!showWaypoints)}
+          style={{
+            width: '100%', padding: '12px', marginBottom: 12,
+            background: showWaypoints ? '#1e293b' : '#334155',
+            border: '1px solid #475569', color: 'white',
+            borderRadius: 8, cursor: 'pointer', fontWeight: 600,
+            transition: 'all 0.2s'
+          }}
+        >
+          {showWaypoints ? '👁️ Masquer Waypoints' : '👁️‍🗨️ Afficher Waypoints'}
+        </button>
+
+        <button
+          onClick={() => {
+            if ((window as any).applyAutoBounds) (window as any).applyAutoBounds();
+          }}
+          style={{
+            width: '100%', padding: '12px', marginBottom: 16,
+            background: '#1e293b', border: '1px solid #475569',
+            color: '#10b981', borderRadius: 8, cursor: 'pointer', fontWeight: 600,
+            transition: 'all 0.2s'
+          }}
+        >
+          🎯 Cadrage Automatique
+        </button>
+
+        <button
+          onClick={() => {
+            if ((window as any).downloadMapScreenshot) (window as any).downloadMapScreenshot();
+          }}
+          style={{
+            width: '100%', padding: '14px', background: '#0ea5e9',
+            border: 'none', color: 'white', borderRadius: 8,
+            cursor: 'pointer', fontWeight: 'bold', fontSize: '1rem',
+            boxShadow: '0 4px 6px -1px rgba(14, 165, 233, 0.4)'
+          }}
+        >
+          📸 Capturer la carte (.png)
+        </button>
+
+        <div style={{ marginTop: 24, padding: 16, background: '#020617', borderRadius: 10, fontSize: '0.85rem' }}>
+          <div style={{ color: '#64748b', marginBottom: 8, fontWeight: 600 }}>Limites Actuelles (worldBounds):</div>
+          <pre ref={boundsTextRef} style={{ margin: 0, color: '#10b981', fontFamily: 'monospace' }}>
+            Calcul...
+          </pre>
+          <div style={{ color: '#ef4444', marginTop: 12, fontSize: '0.75rem', lineHeight: 1.4 }}>
+            *Si vous décadrez à la souris, vous devrez copier ces valeurs exactes dans la prop <code>worldBounds</code> de votre composant <b>EbikeGPSMap</b> !
+            <br /><br />
+            Astuce : Utilisez le <b>Cadrage Automatique</b> pour ne rien avoir à configurer.
+          </div>
+        </div>
+      </div>
+    </div>
+  );
+}

src/pathfinding/AStar.ts

@@ -0,0 +1,122 @@
+import { Grid } from './Grid';
+import type { GridNode, Position } from './types';
+
+/**
+ * Calculates the octile heuristic distance between two nodes.
+ * Ideal for 8-directional grid movement.
+ */
+function getOctileDistance(nodeA: GridNode, nodeB: GridNode): number {
+  const dx = Math.abs(nodeA.x - nodeB.x);
+  const dy = Math.abs(nodeA.y - nodeB.y);
+  
+  const D = 1;       // Orthogonal movement cost
+  const D2 = 1.414;  // Diagonal movement cost (approx Math.sqrt(2))
+
+  return D * (dx + dy) + (D2 - 2 * D) * Math.min(dx, dy);
+}
+
+/**
+ * Finds the shortest path between start and end positions on the grid.
+ * Returns an array of Positions representing the path, or an empty array if no path is found.
+ */
+export function findPath(
+  grid: Grid,
+  startPos: Position,
+  endPos: Position,
+  allowDiagonals: boolean = true
+): Position[] {
+  grid.reset();
+
+  const startNode = grid.getNode(Math.floor(startPos.x), Math.floor(startPos.y));
+  const endNode = grid.getNode(Math.floor(endPos.x), Math.floor(endPos.y));
+
+  if (!startNode || !endNode) {
+    return [];
+  }
+
+  // If the destination node itself is blocked, we try to find the nearest walkable neighbor
+  if (!endNode.walkable) {
+    const endNeighbors = grid.getNeighbors(endNode, allowDiagonals);
+    if (endNeighbors.length === 0) {
+      return [];
+    }
+    // Set destination to the closest walkable neighbor
+    let closestNeighbor = endNeighbors[0]!;
+    let minDist = getOctileDistance(startNode, closestNeighbor);
+    for (let i = 1; i < endNeighbors.length; i++) {
+      const neighbor = endNeighbors[i]!;
+      const dist = getOctileDistance(startNode, neighbor);
+      if (dist < minDist) {
+        minDist = dist;
+        closestNeighbor = neighbor;
+      }
+    }
+    // Reroute to that walkable neighbor
+    return findPath(grid, startPos, { x: closestNeighbor.x, y: closestNeighbor.y }, allowDiagonals);
+  }
+
+  const openSet: GridNode[] = [startNode];
+  const closedSet = new Set<GridNode>();
+
+  startNode.g = 0;
+  startNode.h = getOctileDistance(startNode, endNode);
+  startNode.f = startNode.h;
+
+  while (openSet.length > 0) {
+    // Find the node in openSet with the lowest f value
+    let lowIndex = 0;
+    for (let i = 1; i < openSet.length; i++) {
+      const node = openSet[i]!;
+      const lowNode = openSet[lowIndex]!;
+      if (node.f < lowNode.f) {
+        lowIndex = i;
+      }
+    }
+
+    const currentNode = openSet[lowIndex]!;
+
+    // Check if we reached the destination
+    if (currentNode === endNode) {
+      const path: Position[] = [];
+      let temp: GridNode | null = currentNode;
+      while (temp !== null) {
+        path.push({ x: temp.x, y: temp.y });
+        temp = temp.parent;
+      }
+      return path.reverse();
+    }
+
+    // Remove currentNode from openSet and add to closedSet
+    openSet.splice(lowIndex, 1);
+    closedSet.add(currentNode);
+
+    const neighbors = grid.getNeighbors(currentNode, allowDiagonals);
+
+    for (const neighbor of neighbors) {
+      if (closedSet.has(neighbor)) {
+        continue;
+      }
+
+      // Calculate cost to move to this neighbor (1 for orthogonal, 1.414 for diagonal)
+      const isDiagonal = neighbor.x !== currentNode.x && neighbor.y !== currentNode.y;
+      const moveCost = isDiagonal ? 1.414 : 1;
+      const tentativeG = currentNode.g + moveCost;
+
+      let neighborInOpenSet = openSet.includes(neighbor);
+
+      if (!neighborInOpenSet || tentativeG < neighbor.g) {
+        neighbor.parent = currentNode;
+        neighbor.g = tentativeG;
+        neighbor.h = getOctileDistance(neighbor, endNode);
+        neighbor.f = neighbor.g + neighbor.h;
+
+        if (!neighborInOpenSet) {
+          openSet.push(neighbor);
+        }
+      }
+    }
+  }
+
+  // Return empty if no path is found
+  return [];
+}

src/pathfinding/GPSMinimap.tsx

@@ -0,0 +1,207 @@
+import React, { useRef, useEffect, useState, useMemo } from 'react';
+import * as THREE from 'three';
+import { useGPS } from './useGPS';
+import type { WorldBounds } from './useGPS';
+
+// ==========================================
+// 1. Premium 2D HUD GPS Overlay Component
+// ==========================================
+
+export interface GPSMinimapHUDProps {
+  bwMaskUrl: string;
+  colorMapUrl: string;
+  gridWidth: number;
+  gridHeight: number;
+  worldBounds: WorldBounds;
+  playerPos: { x: number; z: number };
+  destPos?: { x: number; z: number };
+  size?: number; // Size of HUD in pixels
+}
+
+/**
+ * A beautiful, glassmorphic 2D HUD overlay that renders the GPS Minimap
+ * in the corner of the screen.
+ */
+export const GPSMinimapHUD: React.FC<GPSMinimapHUDProps> = ({
+  bwMaskUrl,
+  colorMapUrl,
+  gridWidth,
+  gridHeight,
+  worldBounds,
+  playerPos,
+  destPos,
+  size = 200,
+}) => {
+  const canvasRef = useRef<HTMLCanvasElement | null>(null);
+  
+  const gpsOptions = useMemo(() => ({
+    bwMaskUrl,
+    colorMapUrl,
+    gridWidth,
+    gridHeight,
+    worldBounds,
+  }), [bwMaskUrl, colorMapUrl, gridWidth, gridHeight, worldBounds]);
+
+  const { calculateWorldPath, renderGPSToCanvas, loading, error } = useGPS(gpsOptions);
+
+  useEffect(() => {
+    if (loading || error || !canvasRef.current) return;
+
+    // Calculate A* path in world coordinates
+    const path = destPos ? calculateWorldPath(playerPos, destPos) : [];
+
+    // Render path onto HUD canvas
+    renderGPSToCanvas(canvasRef.current, path, playerPos, destPos, {
+      pathColor: '#3b82f6', // Premium vibrant blue
+      pathWidth: 5,
+      playerColor: '#ef4444', // Hot red for player
+      playerSize: 6,
+      destColor: '#10b981', // Emerald green for destination
+      destSize: 6,
+    });
+  }, [playerPos, destPos, loading, error, calculateWorldPath, renderGPSToCanvas]);
+
+  return (
+    <div style={hudStyles.container(size)}>
+      {loading && <div style={hudStyles.statusText}>Initializing GPS...</div>}
+      {error && <div style={{ ...hudStyles.statusText, color: '#ef4444' }}>GPS Error: {error}</div>}
+      
+      {!loading && !error && (
+        <canvas
+          ref={canvasRef}
+          width={size * 2} // Double size for retina/high-DPI screens
+          height={size * 2}
+          style={hudStyles.canvas(size)}
+        />
+      )}
+    </div>
+  );
+};
+
+// ==========================================
+// 2. 3D Handlebar Screen Mesh Component (R3F)
+// ==========================================
+
+export interface GPSBikeScreenProps {
+  bwMaskUrl: string;
+  colorMapUrl: string;
+  gridWidth: number;
+  gridHeight: number;
+  worldBounds: WorldBounds;
+  playerPos: { x: number; z: number };
+  destPos?: { x: number; z: number };
+  width?: number; // 3D Plane Width
+  height?: number; // 3D Plane Height
+}
+
+/**
+ * A Three.js 3D plane mesh that renders the GPS dynamically as a CanvasTexture.
+ * This can be directly attached to the bike's handlebars in your 3D world.
+ */
+export const GPSBikeScreen: React.FC<GPSBikeScreenProps> = ({
+  bwMaskUrl,
+  colorMapUrl,
+  gridWidth,
+  gridHeight,
+  worldBounds,
+  playerPos,
+  destPos,
+  width = 0.4,
+  height = 0.4,
+}) => {
+  // Offscreen canvas to render the GPS texture onto
+  const [offscreenCanvas] = useState(() => {
+    const canvas = document.createElement('canvas');
+    canvas.width = 512;
+    canvas.height = 512;
+    return canvas;
+  });
+
+  const textureRef = useRef<THREE.CanvasTexture | null>(null);
+
+  const gpsOptions = useMemo(() => ({
+    bwMaskUrl,
+    colorMapUrl,
+    gridWidth,
+    gridHeight,
+    worldBounds,
+  }), [bwMaskUrl, colorMapUrl, gridWidth, gridHeight, worldBounds]);
+
+  const { calculateWorldPath, renderGPSToCanvas, loading } = useGPS(gpsOptions);
+
+  useEffect(() => {
+    if (loading) return;
+
+    // Calculate A* path
+    const path = destPos ? calculateWorldPath(playerPos, destPos) : [];
+
+    // Render path onto our offscreen canvas
+    renderGPSToCanvas(offscreenCanvas, path, playerPos, destPos, {
+      pathColor: '#60a5fa', // Bright neon blue
+      pathWidth: 8,
+      playerColor: '#ff0055', // Neon pink-red for bike
+      playerSize: 10,
+      destColor: '#00ffcc', // Vibrant cyan for target
+      destSize: 10,
+    });
+
+    // Notify Three.js that the texture needs an update
+    if (textureRef.current) {
+      textureRef.current.needsUpdate = true;
+    }
+  }, [playerPos, destPos, loading, calculateWorldPath, renderGPSToCanvas, offscreenCanvas]);
+
+  return (
+    <mesh castShadow receiveShadow>
+      <planeGeometry args={[width, height]} />
+      <meshBasicMaterial toneMapped={false}>
+        <canvasTexture
+          ref={textureRef}
+          attach="map"
+          image={offscreenCanvas}
+          minFilter={THREE.LinearFilter}
+          magFilter={THREE.LinearFilter}
+        />
+      </meshBasicMaterial>
+    </mesh>
+  );
+};
+
+// ==========================================
+// Styles for HUD (Premium Glassmorphism)
+// ==========================================
+
+const hudStyles = {
+  container: (size: number): React.CSSProperties => ({
+    position: 'absolute',
+    bottom: '24px',
+    right: '24px',
+    width: `${size}px`,
+    height: `${size}px`,
+    borderRadius: '24px',
+    overflow: 'hidden',
+    border: '1px solid rgba(255, 255, 255, 0.15)',
+    boxShadow: '0 8px 32px 0 rgba(0, 0, 0, 0.37), 0 0 15px rgba(59, 130, 246, 0.2)',
+    backdropFilter: 'blur(8px)',
+    WebkitBackdropFilter: 'blur(8px)',
+    background: 'rgba(15, 23, 42, 0.6)', // Sleek dark slate
+    display: 'flex',
+    alignItems: 'center',
+    justifyContent: 'center',
+    zIndex: 1000,
+    pointerEvents: 'none',
+    transition: 'all 0.3s cubic-bezier(0.4, 0, 0.2, 1)',
+  }),
+  canvas: (size: number): React.CSSProperties => ({
+    width: `${size}px`,
+    height: `${size}px`,
+    display: 'block',
+  }),
+  statusText: {
+    color: '#94a3b8',
+    fontFamily: 'system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif',
+    fontSize: '12px',
+    fontWeight: 500,
+    letterSpacing: '0.05em',
+  } as React.CSSProperties,
+};

src/pathfinding/Grid.ts

@@ -0,0 +1,100 @@
+import type { GridNode } from './types';
+
+export class Grid {
+  public width: number;
+  public height: number;
+  private nodes: GridNode[][];
+
+  constructor(walkableMatrix: boolean[][]) {
+    this.height = walkableMatrix.length;
+    this.width = this.height > 0 ? (walkableMatrix[0]?.length ?? 0) : 0;
+    this.nodes = [];
+
+    for (let y = 0; y < this.height; y++) {
+      const row: GridNode[] = [];
+      const sourceRow = walkableMatrix[y];
+      for (let x = 0; x < this.width; x++) {
+        row.push({
+          x,
+          y,
+          walkable: sourceRow ? (sourceRow[x] ?? false) : false,
+          g: 0,
+          h: 0,
+          f: 0,
+          parent: null,
+        });
+      }
+      this.nodes.push(row);
+    }
+  }
+
+  public getNode(x: number, y: number): GridNode | null {
+    if (x >= 0 && x < this.width && y >= 0 && y < this.height) {
+      const row = this.nodes[y];
+      return row ? (row[x] ?? null) : null;
+    }
+    return null;
+  }
+
+  /**
+   * Resets g, h, f values and parents for all nodes in the grid,
+   * preparing it for a new A* calculation.
+   */
+  public reset(): void {
+    for (let y = 0; y < this.height; y++) {
+      const row = this.nodes[y];
+      if (!row) continue;
+      for (let x = 0; x < this.width; x++) {
+        const node = row[x];
+        if (!node) continue;
+        node.g = 0;
+        node.h = 0;
+        node.f = 0;
+        node.parent = null;
+      }
+    }
+  }
+
+  /**
+   * Retrieves neighboring nodes. Supports 8-directional movement.
+   */
+  public getNeighbors(node: GridNode, allowDiagonals: boolean = true): GridNode[] {
+    const neighbors: GridNode[] = [];
+    const { x, y } = node;
+
+    // Relative coordinates of 8 neighbors
+    const directions = [
+      { dx: 0, dy: -1, isDiagonal: false }, // N
+      { dx: 1, dy: 0, isDiagonal: false },  // E
+      { dx: 0, dy: 1, isDiagonal: false },  // S
+      { dx: -1, dy: 0, isDiagonal: false }, // W
+    ];
+
+    if (allowDiagonals) {
+      directions.push(
+        { dx: 1, dy: -1, isDiagonal: true },  // NE
+        { dx: 1, dy: 1, isDiagonal: true },   // SE
+        { dx: -1, dy: 1, isDiagonal: true },  // SW
+        { dx: -1, dy: -1, isDiagonal: true }  // NW
+      );
+    }
+
+    for (const dir of directions) {
+      const neighbor = this.getNode(x + dir.dx, y + dir.dy);
+      if (neighbor && neighbor.walkable) {
+        // Prevent corner cutting if both orthogonal neighbors are blocked
+        if (dir.isDiagonal) {
+          const ortho1 = this.getNode(x + dir.dx, y);
+          const ortho2 = this.getNode(x, y + dir.dy);
+          const isBlocked = (!ortho1 || !ortho1.walkable) && (!ortho2 || !ortho2.walkable);
+          if (isBlocked) {
+            continue; // Skip this diagonal neighbor to avoid squeezing through corners
+          }
+        }
+        neighbors.push(neighbor);
+      }
+    }
+
+    return neighbors;
+  }
+}

src/pathfinding/ImageToGrid.ts

@@ -0,0 +1,75 @@
+import { Grid } from './Grid';
+
+/**
+ * Loads an image from a URL.
+ */
+function loadImage(url: string): Promise<HTMLImageElement> {
+  return new Promise((resolve, reject) => {
+    const img = new Image();
+    img.crossOrigin = 'anonymous'; // Enable CORS just in case
+    img.onload = () => resolve(img);
+    img.onerror = (err) => reject(new Error(`Failed to load image at ${url}: ${err}`));
+    img.src = url;
+  });
+}
+
+/**
+ * Loads a B&W image and scales it to gridWidth x gridHeight.
+ * Higher dimensions = higher accuracy but slower pathfinding.
+ * Lower dimensions = extremely fast pathfinding.
+ * 
+ * Walkable roads should be white (or light gray). Non-walkable areas should be black.
+ * 
+ * @param imageUrl The path or URL of the B&W navigation mask.
+ * @param gridWidth The target width of our A* pathfinding grid.
+ * @param gridHeight The target height of our A* pathfinding grid.
+ * @param threshold Brightness threshold (0-255) above which a pixel is considered walkable (default: 128).
+ */
+export async function createGridFromImage(
+  imageUrl: string,
+  gridWidth: number,
+  gridHeight: number,
+  threshold: number = 128
+): Promise<Grid> {
+  const img = await loadImage(imageUrl);
+
+  // Create an offscreen canvas to scale and analyze the image
+  const canvas = document.createElement('canvas');
+  canvas.width = gridWidth;
+  canvas.height = gridHeight;
+  const ctx = canvas.getContext('2d');
+
+  if (!ctx) {
+    throw new Error('Could not get 2D context for offscreen canvas');
+  }
+
+  // Draw and scale the image onto the canvas
+  ctx.drawImage(img, 0, 0, gridWidth, gridHeight);
+
+  // Retrieve pixel data
+  const imgData = ctx.getImageData(0, 0, gridWidth, gridHeight);
+  const data = imgData.data;
+
+  // Initialize a 2D boolean matrix representing the walkable grid
+  const walkableMatrix: boolean[][] = [];
+
+  for (let y = 0; y < gridHeight; y++) {
+    const row: boolean[] = [];
+    for (let x = 0; x < gridWidth; x++) {
+      // Each pixel has 4 channels: R, G, B, A
+      const index = (y * gridWidth + x) * 4;
+      const r = data[index] ?? 0;
+      const g = data[index + 1] ?? 0;
+      const b = data[index + 2] ?? 0;
+
+      // Calculate brightness (standard grayscale weighting)
+      const brightness = 0.299 * r + 0.587 * g + 0.114 * b;
+
+      // If bright enough, it is a road (walkable)
+      row.push(brightness >= threshold);
+    }
+    walkableMatrix.push(row);
+  }
+
+  return new Grid(walkableMatrix);
+}

src/pathfinding/WaypointAStar.ts

@@ -0,0 +1,145 @@
+import type { Waypoint, WaypointNode } from './types';
+
+/**
+ * Calculates Euclidean 3D distance between two points.
+ */
+function getDistance3D(
+  posA: { x: number; y: number; z: number },
+  posB: { x: number; y: number; z: number }
+): number {
+  return Math.sqrt(
+    Math.pow(posA.x - posB.x, 2) +
+    Math.pow(posA.y - posB.y, 2) +
+    Math.pow(posA.z - posB.z, 2)
+  );
+}
+
+/**
+ * Finds the closest Waypoint in a list to a target 3D world position.
+ */
+export function findClosestWaypoint(
+  waypoints: Waypoint[],
+  pos: { x: number; y: number; z: number }
+): Waypoint | null {
+  if (waypoints.length === 0) return null;
+
+  let closest = waypoints[0]!;
+  let minDist = getDistance3D(closest, pos);
+
+  for (let i = 1; i < waypoints.length; i++) {
+    const wp = waypoints[i]!;
+    const dist = getDistance3D(wp, pos);
+    if (dist < minDist) {
+      minDist = dist;
+      closest = wp;
+    }
+  }
+
+  return closest;
+}
+
+/**
+ * Runs A* pathfinding on a network of 3D Waypoints.
+ * 
+ * @param waypoints List of all waypoints in the road network.
+ * @param startWorldPos Player's current 3D world position.
+ * @param endWorldPos Targeted 3D world destination.
+ * @returns Array of Waypoints representing the path from start to end, or empty array if none found.
+ */
+export function findWaypointPath(
+  waypoints: Waypoint[],
+  startWorldPos: { x: number; y: number; z: number },
+  endWorldPos: { x: number; y: number; z: number }
+): Waypoint[] {
+  if (waypoints.length === 0) return [];
+
+  // 1. Find the closest starting and ending waypoints in the network
+  const startWp = findClosestWaypoint(waypoints, startWorldPos);
+  const endWp = findClosestWaypoint(waypoints, endWorldPos);
+
+  if (!startWp || !endWp) return [];
+  if (startWp.id === endWp.id) return [startWp];
+
+  // 2. Map all waypoints to A* search nodes
+  const nodeMap = new Map<number, WaypointNode>();
+  waypoints.forEach((wp) => {
+    nodeMap.set(wp.id, {
+      ...wp,
+      g: Infinity,
+      h: Infinity,
+      f: Infinity,
+      parent: null,
+    });
+  });
+
+  const startNode = nodeMap.get(startWp.id)!;
+  const endNode = nodeMap.get(endWp.id)!;
+
+  // 3. Initialize open and closed sets
+  const openSet: WaypointNode[] = [startNode];
+  const closedSet = new Set<number>(); // Set of waypoint IDs
+
+  startNode.g = 0;
+  startNode.h = getDistance3D(startNode, endNode);
+  startNode.f = startNode.h;
+
+  while (openSet.length > 0) {
+    // Find node with lowest f score
+    let lowIndex = 0;
+    for (let i = 1; i < openSet.length; i++) {
+      const node = openSet[i]!;
+      const lowNode = openSet[lowIndex]!;
+      if (node.f < lowNode.f) {
+        lowIndex = i;
+      }
+    }
+
+    const currentNode = openSet[lowIndex]!;
+
+    // Reached destination! Reconstruct the path
+    if (currentNode.id === endNode.id) {
+      const path: Waypoint[] = [];
+      let temp: WaypointNode | null = currentNode;
+      while (temp !== null) {
+        // Find corresponding raw Waypoint
+        const rawWp = waypoints.find((w) => w.id === temp!.id);
+        if (rawWp) {
+          path.push(rawWp);
+        }
+        temp = temp.parent;
+      }
+      return path.reverse();
+    }
+
+    // Move from open to closed set
+    openSet.splice(lowIndex, 1);
+    closedSet.add(currentNode.id);
+
+    // Process neighbors
+    for (const neighborId of currentNode.connections) {
+      if (closedSet.has(neighborId)) continue;
+
+      const neighborNode = nodeMap.get(neighborId);
+      if (!neighborNode) continue;
+
+      // Distance from currentNode to neighbor is physical 3D distance
+      const tentativeG = currentNode.g + getDistance3D(currentNode, neighborNode);
+
+      let neighborInOpenSet = openSet.some((node) => node.id === neighborId);
+
+      if (!neighborInOpenSet || tentativeG < neighborNode.g) {
+        neighborNode.parent = currentNode;
+        neighborNode.g = tentativeG;
+        neighborNode.h = getDistance3D(neighborNode, endNode);
+        neighborNode.f = neighborNode.g + neighborNode.h;
+
+        if (!neighborInOpenSet) {
+          openSet.push(neighborNode);
+        }
+      }
+    }
+  }
+
+  // No path found
+  return [];
+}

src/pathfinding/index.ts

@@ -0,0 +1,10 @@
+export * from './types';
+export * from './Grid';
+export * from './AStar';
+export * from './ImageToGrid';
+export * from './useGPS';
+export * from './GPSMinimap';
+export * from './WaypointAStar';
+export * from './useWaypointGPS';
+
+

src/pathfinding/types.ts

@@ -0,0 +1,40 @@
+export interface Position {
+  x: number;
+  y: number;
+}
+
+export interface GridNode {
+  x: number;
+  y: number;
+  walkable: boolean;
+  g: number;
+  h: number;
+  f: number;
+  parent: GridNode | null;
+}
+
+export interface GridSize {
+  width: number;
+  height: number;
+}
+
+export interface Waypoint {
+  id: number;
+  x: number;
+  y: number;
+  z: number;
+  connections: number[];
+}
+
+export interface WaypointNode {
+  id: number;
+  x: number;
+  y: number;
+  z: number;
+  connections: number[];
+  g: number;
+  h: number;
+  f: number;
+  parent: WaypointNode | null;
+}
+

src/pathfinding/useGPS.ts

@@ -0,0 +1,243 @@
+import { useState, useEffect, useCallback, useRef } from 'react';
+import { Grid } from './Grid';
+import { createGridFromImage } from './ImageToGrid';
+import { findPath } from './AStar';
+import type { Position } from './types';
+
+export interface WorldBounds {
+  minX: number;
+  maxX: number;
+  minZ: number;
+  maxZ: number;
+}
+
+export interface UseGPSOptions {
+  bwMaskUrl: string;
+  colorMapUrl: string;
+  gridWidth: number;   // The "width of the array pathfinding" (resolution scaling)
+  gridHeight: number;  // The "height of the array pathfinding"
+  worldBounds: WorldBounds;
+  allowDiagonals?: boolean;
+}
+
+export function useGPS({
+  bwMaskUrl,
+  colorMapUrl,
+  gridWidth,
+  gridHeight,
+  worldBounds,
+  allowDiagonals = true,
+}: UseGPSOptions) {
+  const [grid, setGrid] = useState<Grid | null>(null);
+  const [loading, setLoading] = useState<boolean>(true);
+  const [error, setError] = useState<string | null>(null);
+  
+  // Cache the images so they don't reload every frame
+  const colorMapImgRef = useRef<HTMLImageElement | null>(null);
+
+  // Initialize the pathfinding grid
+  useEffect(() => {
+    let active = true;
+    setLoading(true);
+    setError(null);
+
+    async function initGrid() {
+      try {
+        const pathfindingGrid = await createGridFromImage(bwMaskUrl, gridWidth, gridHeight);
+        
+        // Pre-load color map image for canvas drawing
+        const colorMapImg = new Image();
+        colorMapImg.crossOrigin = 'anonymous';
+        await new Promise((resolve, reject) => {
+          colorMapImg.onload = resolve;
+          colorMapImg.onerror = reject;
+          colorMapImg.src = colorMapUrl;
+        });
+
+        if (active) {
+          setGrid(pathfindingGrid);
+          colorMapImgRef.current = colorMapImg;
+          setLoading(false);
+        }
+      } catch (err: any) {
+        if (active) {
+          setError(err.message || 'Failed to initialize GPS system');
+          setLoading(false);
+        }
+      }
+    }
+
+    initGrid();
+
+    return () => {
+      active = false;
+    };
+  }, [bwMaskUrl, colorMapUrl, gridWidth, gridHeight]);
+
+  /**
+   * Translates 3D World coordinates (X, Z) into 2D Grid coordinates (col, row)
+   */
+  const worldToGrid = useCallback(
+    (worldX: number, worldZ: number): Position => {
+      const { minX, maxX, minZ, maxZ } = worldBounds;
+      
+      // Calculate percentages across the bounds
+      const pctX = (worldX - minX) / (maxX - minX);
+      const pctZ = (worldZ - minZ) / (maxZ - minZ);
+      
+      // Map to grid dimensions
+      const gridX = Math.max(0, Math.min(gridWidth - 1, Math.floor(pctX * gridWidth)));
+      const gridY = Math.max(0, Math.min(gridHeight - 1, Math.floor(pctZ * gridHeight)));
+      
+      return { x: gridX, y: gridY };
+    },
+    [worldBounds, gridWidth, gridHeight]
+  );
+
+  /**
+   * Translates 2D Grid coordinates (col, row) back into 3D World coordinates (X, Z)
+   */
+  const gridToWorld = useCallback(
+    (gridX: number, gridY: number): { x: number; z: number } => {
+      const { minX, maxX, minZ, maxZ } = worldBounds;
+      
+      const pctX = gridX / gridWidth;
+      const pctZ = gridY / gridHeight;
+      
+      const worldX = minX + pctX * (maxX - minX);
+      const worldZ = minZ + pctZ * (maxZ - minZ);
+      
+      return { x: worldX, z: worldZ };
+    },
+    [worldBounds, gridWidth, gridHeight]
+  );
+
+  /**
+   * Runs the A* calculation using 3D world coordinates.
+   * Returns path in 3D world space.
+   */
+  const calculateWorldPath = useCallback(
+    (startWorld: { x: number; z: number }, endWorld: { x: number; z: number }): { x: number; z: number }[] => {
+      if (!grid) return [];
+
+      const startGrid = worldToGrid(startWorld.x, startWorld.z);
+      const endGrid = worldToGrid(endWorld.x, endWorld.z);
+
+      const gridPath = findPath(grid, startGrid, endGrid, allowDiagonals);
+      
+      // Convert path coordinates back to 3D space
+      return gridPath.map((node) => gridToWorld(node.x, node.y));
+    },
+    [grid, worldToGrid, gridToWorld, allowDiagonals]
+  );
+
+  /**
+   * Updates an HTML5 `<canvas>` element with the background color map, 
+   * a path line, and the player/destination indicators.
+   */
+  const renderGPSToCanvas = useCallback(
+    (
+      canvas: HTMLCanvasElement,
+      path: { x: number; z: number }[],
+      playerWorldPos?: { x: number; z: number },
+      destWorldPos?: { x: number; z: number },
+      options: {
+        pathColor?: string;
+        pathWidth?: number;
+        playerColor?: string;
+        playerSize?: number;
+        destColor?: string;
+        destSize?: number;
+      } = {}
+    ) => {
+      const ctx = canvas.getContext('2d');
+      if (!ctx || !colorMapImgRef.current) return;
+
+      const {
+        pathColor = '#3b82f6', // Premium blue
+        pathWidth = 6,
+        playerColor = '#ef4444', // Red dot for player
+        playerSize = 8,
+        destColor = '#10b981', // Green dot for flag
+        destSize = 8,
+      } = options;
+
+      const canvasWidth = canvas.width;
+      const canvasHeight = canvas.height;
+
+      // 1. Draw background color map
+      ctx.clearRect(0, 0, canvasWidth, canvasHeight);
+      ctx.drawImage(colorMapImgRef.current, 0, 0, canvasWidth, canvasHeight);
+
+      // Helper: translate world coordinates to Canvas pixels
+      const worldToCanvas = (wx: number, wz: number): Position => {
+        const { minX, maxX, minZ, maxZ } = worldBounds;
+        const px = ((wx - minX) / (maxX - minX)) * canvasWidth;
+        const py = ((wz - minZ) / (maxZ - minZ)) * canvasHeight;
+        return { x: px, y: py };
+      };
+
+      // 2. Draw A* Path Line
+      if (path.length > 1) {
+        ctx.beginPath();
+        const startNode = path[0]!;
+        const startPt = worldToCanvas(startNode.x, startNode.z);
+        ctx.moveTo(startPt.x, startPt.y);
+
+        for (let i = 1; i < path.length; i++) {
+          const node = path[i]!;
+          const pt = worldToCanvas(node.x, node.z);
+          ctx.lineTo(pt.x, pt.y);
+        }
+
+        ctx.strokeStyle = pathColor;
+        ctx.lineWidth = pathWidth;
+        ctx.lineCap = 'round';
+        ctx.lineJoin = 'round';
+        
+        // Add a soft glow effect for premium feel
+        ctx.shadowBlur = 8;
+        ctx.shadowColor = pathColor;
+        ctx.stroke();
+        
+        // Reset shadow for subsequent drawings
+        ctx.shadowBlur = 0;
+      }
+
+      // 3. Draw Destination Indicator
+      if (destWorldPos) {
+        const destPt = worldToCanvas(destWorldPos.x, destWorldPos.z);
+        ctx.beginPath();
+        ctx.arc(destPt.x, destPt.y, destSize, 0, 2 * Math.PI);
+        ctx.fillStyle = destColor;
+        ctx.strokeStyle = '#ffffff';
+        ctx.lineWidth = 2;
+        ctx.fill();
+        ctx.stroke();
+      }
+
+      // 4. Draw Player Indicator
+      if (playerWorldPos) {
+        const playerPt = worldToCanvas(playerWorldPos.x, playerWorldPos.z);
+        ctx.beginPath();
+        ctx.arc(playerPt.x, playerPt.y, playerSize, 0, 2 * Math.PI);
+        ctx.fillStyle = playerColor;
+        ctx.strokeStyle = '#ffffff';
+        ctx.lineWidth = 2;
+        ctx.fill();
+        ctx.stroke();
+      }
+    },
+    [worldBounds]
+  );
+
+  return {
+    grid,
+    loading,
+    error,
+    calculateWorldPath,
+    renderGPSToCanvas,
+    worldToGrid,
+    gridToWorld,
+  };
+}

src/pathfinding/useWaypointGPS.ts

@@ -0,0 +1,212 @@
+import { useState, useEffect, useCallback, useRef } from 'react';
+import { findWaypointPath } from './WaypointAStar';
+import type { Waypoint } from './types';
+import type { WorldBounds } from './useGPS';
+
+export interface UseWaypointGPSOptions {
+  roadNetworkUrl: string; // URL/Path to roadNetwork.json
+  colorMapUrl: string;    // URL/Path to color_map.png
+  worldBounds: WorldBounds;
+}
+
+export function useWaypointGPS({
+  roadNetworkUrl,
+  colorMapUrl,
+  worldBounds,
+}: UseWaypointGPSOptions) {
+  const [waypoints, setWaypoints] = useState<Waypoint[]>([]);
+  const [loading, setLoading] = useState<boolean>(true);
+  const [error, setError] = useState<string | null>(null);
+
+  const colorMapImgRef = useRef<HTMLImageElement | null>(null);
+
+  // Load waypoint list and background color map image
+  useEffect(() => {
+    let active = true;
+    setLoading(true);
+    setError(null);
+
+    async function initGPS() {
+      try {
+        // 1. Fetch the road network JSON
+        const response = await fetch(roadNetworkUrl);
+        if (!response.ok) {
+          throw new Error(`Failed to load road network from ${roadNetworkUrl}`);
+        }
+        const data: Waypoint[] = await response.json();
+
+        // 2. Pre-load the color map image
+        const colorMapImg = new Image();
+        colorMapImg.crossOrigin = 'anonymous';
+        await new Promise((resolve, reject) => {
+          colorMapImg.onload = resolve;
+          colorMapImg.onerror = reject;
+          colorMapImg.src = colorMapUrl;
+        });
+
+        if (active) {
+          setWaypoints(data);
+          colorMapImgRef.current = colorMapImg;
+          setLoading(false);
+        }
+      } catch (err: any) {
+        if (active) {
+          setError(err.message || 'Failed to initialize Waypoint GPS');
+          setLoading(false);
+        }
+      }
+    }
+
+    initGPS();
+
+    return () => {
+      active = false;
+    };
+  }, [roadNetworkUrl, colorMapUrl]);
+
+  /**
+   * Calculates the shortest path between start and end world points.
+   */
+  const calculateRoute = useCallback(
+    (
+      startWorld: { x: number; y: number; z: number },
+      endWorld: { x: number; y: number; z: number }
+    ): Waypoint[] => {
+      if (waypoints.length === 0) return [];
+      return findWaypointPath(waypoints, startWorld, endWorld);
+    },
+    [waypoints]
+  );
+
+  /**
+   * Renders the road network path, player position, and waypoint target onto a canvas.
+   */
+  const renderGPSToCanvas = useCallback(
+    (
+      canvas: HTMLCanvasElement,
+      path: Waypoint[],
+      playerWorldPos?: { x: number; y: number; z: number },
+      destWorldPos?: { x: number; y: number; z: number },
+      options: {
+        pathColor?: string;
+        pathWidth?: number;
+        playerColor?: string;
+        playerSize?: number;
+        destColor?: string;
+        destSize?: number;
+        showAllWaypoints?: boolean; // Debug mode
+      } = {}
+    ) => {
+      const ctx = canvas.getContext('2d');
+      if (!ctx || !colorMapImgRef.current) return;
+
+      const {
+        pathColor = '#10b981', // Premium emerald green
+        pathWidth = 6,
+        playerColor = '#ff0055', // Neon pink-red for bike
+        playerSize = 8,
+        destColor = '#00ffcc', // Neon cyan for target
+        destSize = 8,
+        showAllWaypoints = false,
+      } = options;
+
+      const canvasWidth = canvas.width;
+      const canvasHeight = canvas.height;
+
+      // 1. Draw color map background
+      ctx.clearRect(0, 0, canvasWidth, canvasHeight);
+      ctx.drawImage(colorMapImgRef.current, 0, 0, canvasWidth, canvasHeight);
+
+      // Helper: translate world coordinates (X, Z) to Canvas pixels (x, y)
+      const worldToCanvas = (wx: number, wz: number) => {
+        const { minX, maxX, minZ, maxZ } = worldBounds;
+        const px = ((wx - minX) / (maxX - minX)) * canvasWidth;
+        const py = ((wz - minZ) / (maxZ - minZ)) * canvasHeight;
+        return { x: px, y: py };
+      };
+
+      // 2. [Debug] Draw all network connections
+      if (showAllWaypoints && waypoints.length > 0) {
+        ctx.strokeStyle = 'rgba(255, 255, 255, 0.15)';
+        ctx.lineWidth = 1.5;
+        const drawn = new Set<string>();
+
+        waypoints.forEach((wp) => {
+          const startPt = worldToCanvas(wp.x, wp.z);
+          wp.connections.forEach((connId) => {
+            const other = waypoints.find((w) => w.id === connId);
+            if (other) {
+              const key = wp.id < other.id ? `${wp.id}-${other.id}` : `${other.id}-${wp.id}`;
+              if (!drawn.has(key)) {
+                drawn.add(key);
+                const endPt = worldToCanvas(other.x, other.z);
+                ctx.beginPath();
+                ctx.moveTo(startPt.x, startPt.y);
+                ctx.lineTo(endPt.x, endPt.y);
+                ctx.stroke();
+              }
+            }
+          });
+        });
+      }
+
+      // 3. Draw calculated A* path line
+      if (path.length > 1) {
+        ctx.beginPath();
+        const startNode = path[0]!;
+        const startPt = worldToCanvas(startNode.x, startNode.z);
+        ctx.moveTo(startPt.x, startPt.y);
+
+        for (let i = 1; i < path.length; i++) {
+          const node = path[i]!;
+          const pt = worldToCanvas(node.x, node.z);
+          ctx.lineTo(pt.x, pt.y);
+        }
+
+        ctx.strokeStyle = pathColor;
+        ctx.lineWidth = pathWidth;
+        ctx.lineCap = 'round';
+        ctx.lineJoin = 'round';
+
+        // Add soft premium path glow
+        ctx.shadowBlur = 8;
+        ctx.shadowColor = pathColor;
+        ctx.stroke();
+        ctx.shadowBlur = 0; // Reset
+      }
+
+      // 4. Draw Destination target
+      if (destWorldPos) {
+        const destPt = worldToCanvas(destWorldPos.x, destWorldPos.z);
+        ctx.beginPath();
+        ctx.arc(destPt.x, destPt.y, destSize, 0, 2 * Math.PI);
+        ctx.fillStyle = destColor;
+        ctx.strokeStyle = '#ffffff';
+        ctx.lineWidth = 2;
+        ctx.fill();
+        ctx.stroke();
+      }
+
+      // 5. Draw Player / Bike
+      if (playerWorldPos) {
+        const playerPt = worldToCanvas(playerWorldPos.x, playerWorldPos.z);
+        ctx.beginPath();
+        ctx.arc(playerPt.x, playerPt.y, playerSize, 0, 2 * Math.PI);
+        ctx.fillStyle = playerColor;
+        ctx.strokeStyle = '#ffffff';
+        ctx.lineWidth = 2;
+        ctx.fill();
+        ctx.stroke();
+      }
+    },
+    [worldBounds, waypoints]
+  );
+
+  return {
+    waypoints,
+    loading,
+    error,
+    calculateRoute,
+    renderGPSToCanvas,
+  };
+}

src/router.tsx

@@ -6,6 +6,8 @@ import {
 } from "@tanstack/react-router";
 import { HomePage } from "@/pages/page";
 import { EditorPage } from "@/pages/editor/page";
+import { WaypointEditorPage } from "@/pages/waypoint/page";
+import { BackgroundMapPage } from "@/pages/backgroundmap/page";
 import {
   DocsAnimationRoute,
   DocsAudioRoute,
@@ -43,6 +45,18 @@ const editorRoute = createRoute({
   component: EditorPage,
 });
 
+const waypointRoute = createRoute({
+  getParentRoute: () => rootRoute,
+  path: "/waypoint",
+  component: WaypointEditorPage,
+});
+
+const backgroundMapRoute = createRoute({
+  getParentRoute: () => rootRoute,
+  path: "/backgroundmap",
+  component: BackgroundMapPage,
+});
+
 const docsRoute = createRoute({
   getParentRoute: () => rootRoute,
   path: "/docs",
@@ -78,6 +92,8 @@ const docsChildRoutes = [
 const routeTree = rootRoute.addChildren([
   indexRoute,
   editorRoute,
+  waypointRoute,
+  backgroundMapRoute,
   docsRoute.addChildren(docsChildRoutes),
 ]);
 

src/utils/three/dispose.ts

@@ -1,42 +0,0 @@
-import * as THREE from "three";
-
-export function disposeObject3D(object: THREE.Object3D): void {
-  object.traverse((child) => {
-    if (child instanceof THREE.Mesh) {
-      child.geometry?.dispose();
-
-      if (Array.isArray(child.material)) {
-        for (const material of child.material) {
-          disposeMaterial(material);
-        }
-      } else if (child.material) {
-        disposeMaterial(child.material);
-      }
-    }
-  });
-}
-
-function disposeMaterial(material: THREE.Material): void {
-  material.dispose();
-
-  for (const key of Object.keys(material)) {
-    const value = (material as Record<string, unknown>)[key];
-    if (value instanceof THREE.Texture) {
-      value.dispose();
-    }
-  }
-}
-
-export function disposeInstancedMesh(mesh: THREE.InstancedMesh): void {
-  mesh.geometry?.dispose();
-
-  if (Array.isArray(mesh.material)) {
-    for (const material of mesh.material) {
-      disposeMaterial(material);
-    }
-  } else if (mesh.material) {
-    disposeMaterial(mesh.material);
-  }
-
-  mesh.dispose();
-}

src/world/GameCinematics.tsx

@@ -9,6 +9,7 @@ import type {
   CinematicManifest,
 } from "@/types/cinematics/cinematics";
 import type { DialogueManifest } from "@/types/dialogues/dialogues";
+import type { Vector3Tuple } from "@/types/three/three";
 import { logger } from "@/utils/core/Logger";
 import { loadCinematicManifest } from "@/utils/cinematics/loadCinematicManifest";
 import { loadDialogueManifest } from "@/utils/dialogues/loadDialogueManifest";
@@ -16,6 +17,11 @@ import { queueDialogueById } from "@/utils/dialogues/playDialogue";
 
 export function GameCinematics(): null {
   const camera = useThree((state) => state.camera);
+
+  useEffect(() => {
+    setGlobalCamera(camera);
+  }, [camera]);
+
   const [manifest, setManifest] = useState<CinematicManifest | null>(null);
   const [dialogueManifest, setDialogueManifest] =
     useState<DialogueManifest | null>(null);
@@ -171,3 +177,118 @@ function playCinematic(
 
   timelineRef.current = timeline;
 }
+
+let cameraTransitionTimeline: gsap.core.Timeline | null = null;
+let globalCamera: THREE.Camera | null = null;
+
+export function setGlobalCamera(camera: THREE.Camera | null): void {
+  globalCamera = camera;
+}
+
+export function animateCameraTransition(
+  targetPosition: Vector3Tuple,
+  targetLookAt: Vector3Tuple,
+  duration: number = 1,
+  onComplete?: () => void,
+): void {
+  if (!globalCamera) {
+    logger.warn("GameCinematics", "Camera not found for transition");
+    onComplete?.();
+    return;
+  }
+
+  const camera = globalCamera;
+
+  cameraTransitionTimeline?.kill();
+  useGameStore.getState().setCinematicPlaying(true);
+
+  const target = new THREE.Vector3(...targetLookAt);
+
+  cameraTransitionTimeline = gsap.timeline({
+    onUpdate: () => camera.lookAt(target),
+    onComplete: () => {
+      cameraTransitionTimeline = null;
+      useGameStore.getState().setCinematicPlaying(false);
+      onComplete?.();
+    },
+  });
+
+  cameraTransitionTimeline.to(camera.position, {
+    x: targetPosition[0],
+    y: targetPosition[1],
+    z: targetPosition[2],
+    duration,
+    ease: "power2.inOut",
+  });
+
+  cameraTransitionTimeline.to(
+    target,
+    {
+      x: targetLookAt[0],
+      y: targetLookAt[1],
+      z: targetLookAt[2],
+      duration,
+      ease: "power2.inOut",
+    },
+    0,
+  );
+}
+
+export function animateCameraTransformTransition(
+  targetPosition: Vector3Tuple,
+  targetRotation: Vector3Tuple,
+  duration: number = 1,
+  onComplete?: () => void,
+): void {
+  if (!globalCamera) {
+    logger.warn("GameCinematics", "Camera not found for transition");
+    onComplete?.();
+    return;
+  }
+
+  const camera = globalCamera;
+
+  cameraTransitionTimeline?.kill();
+  useGameStore.getState().setCinematicPlaying(true);
+
+  // Convert target rotation in degrees to quaternion
+  const targetEuler = new THREE.Euler(
+    THREE.MathUtils.degToRad(targetRotation[0]),
+    THREE.MathUtils.degToRad(targetRotation[1]),
+    THREE.MathUtils.degToRad(targetRotation[2]),
+    "YXZ"
+  );
+  const startQuaternion = camera.quaternion.clone();
+  const endQuaternion = new THREE.Quaternion().setFromEuler(targetEuler);
+
+  const transitionObj = { progress: 0 };
+
+  cameraTransitionTimeline = gsap.timeline({
+    onUpdate: () => {
+      camera.quaternion.copy(startQuaternion).slerp(endQuaternion, transitionObj.progress);
+    },
+    onComplete: () => {
+      cameraTransitionTimeline = null;
+      useGameStore.getState().setCinematicPlaying(false);
+      onComplete?.();
+    },
+  });
+
+  cameraTransitionTimeline.to(camera.position, {
+    x: targetPosition[0],
+    y: targetPosition[1],
+    z: targetPosition[2],
+    duration,
+    ease: "power2.inOut",
+  });
+
+  cameraTransitionTimeline.to(
+    transitionObj,
+    {
+      progress: 1,
+      duration,
+      ease: "power2.inOut",
+    },
+    0,
+  );
+}

src/world/GameStageContent.tsx

@@ -1,4 +1,5 @@
 import { RepairGame } from "@/components/three/gameplay/RepairGame";
+import { Ebike } from "@/components/ebike/Ebike";
 import { useGameStore } from "@/managers/stores/useGameStore";
 import type { RepairMissionId } from "@/types/gameplay/repairMission";
 import type { Vector3Tuple } from "@/types/three/three";
@@ -56,6 +57,7 @@ export function GameStageContent(): React.JSX.Element {
       {mainState === "intro" ? (
         <StageAnchor color="#7dd3fc" position={[0, 4, 0]} />
       ) : null}
+      <Ebike position={[0, 10, 0]} />
       {GAME_REPAIR_ZONES.map((zone) => (
         <RepairGame
           key={zone.mission}