NextJs Maplibre

← Dashboard
components/FirstPersonMapControls.tsx
Same shared pieces as Upper Map Controls: useHeldKeys for keyboard state, map-config.ts for the default origin/style/worker URL, TouchDPad for the on-screen buttons. Sharing these across both modes is what makes adding a third mode fast -- most of the boilerplate is already handled.
import * as maplibregl from "maplibre-gl";
import "maplibre-gl/dist/maplibre-gl.css";
import { useEffect, useRef } from "react";
import { useHeldKeys } from "@/lib/useHeldKeys";
import { DEFAULT_ORIGIN, DEFAULT_MAP_STYLE, MAPLIBRE_WORKER_URL } from "@/lib/map-config";
import TouchDPad from "@/components/TouchDPad";

const KEYS = ["KeyW", "KeyA", "KeyS", "KeyD", "ArrowLeft", "ArrowRight"] as const;
Collision uses the building footprints already in the vector tiles -- no extra data source. This is a textbook ray-casting point-in-polygon test: walk the polygon's edges, count how many cross a ray cast from the point, and an odd count means inside. The hole handling matters for real buildings with courtyards: inside the outer ring but inside a hole means you're actually outside the building, standing in the courtyard.
const BUILDING_SOURCE = "openmaptiles";
const BUILDING_SOURCE_LAYER = "building";

type Ring = number[][];

function pointInRing(pt: [number, number], ring: Ring): boolean {
  let inside = false;
  for (let i = 0, j = ring.length - 1; i < ring.length; j = i++) {
    const [xi, yi] = ring[i];
    const [xj, yj] = ring[j];
    const crosses =
      yi > pt[1] !== yj > pt[1] &&
      pt[0] < ((xj - xi) * (pt[1] - yi)) / (yj - yi) + xi;
    if (crosses) inside = !inside;
  }
  return inside;
}

// Polygon = [outerRing, ...holeRings].
function pointInPolygon(pt: [number, number], rings: Ring[]): boolean {
  if (!pointInRing(pt, rings[0])) return false;
  for (let k = 1; k < rings.length; k++) {
    if (pointInRing(pt, rings[k])) return false;
  }
  return true;
}
Eye height, walk/turn speed, look-ahead distance, and the origin/style are all props with defaults now, not module-level constants -- the same "configure without editing the file" story as Upper Map Controls. maxZoom stays a prop too since it's a real workaround for a real bug (see the map-constructor remark below), and someone dropping this into a different style may need a different value.
export interface FirstPersonMapControlsProps {
  origin?: [number, number];
  mapStyle?: string;
  eyeHeight?: number;
  walkSpeed?: number;
  turnSpeed?: number;
  lookAhead?: number;
  maxZoom?: number;
  enableCollision?: boolean;
}

export default function FirstPersonMapControls({
  origin = DEFAULT_ORIGIN,
  mapStyle = DEFAULT_MAP_STYLE,
  eyeHeight = 1.6,
  walkSpeed = 20,
  turnSpeed = 1.2, // rad/s -- ~69 deg/s, a full 360 in ~5s
  lookAhead = 20,
  maxZoom = 19,
  enableCollision = true,
}: FirstPersonMapControlsProps) {
  const mapContainerRef = useRef<HTMLDivElement | null>(null);
  const keysDownRef = useHeldKeys(KEYS);
Same underlying bug either way: MapLibre derives its worker URL from import.meta.url, which isn't a real http(s) URL under Turbopack, so it silently falls back to "" -- the worker then loads this page's HTML instead of the worker script, and zero map tiles ever load, with no console error. The fix now lives once in lib/map-config.ts (MAPLIBRE_WORKER_URL) instead of being duplicated in every map component.
maplibregl.setWorkerUrl(MAPLIBRE_WORKER_URL);
The walking position (player.x/y) is tracked in flat meters, not lng/lat -- that's just simpler math for "move forward" and "turn". originMercator + metresToMercatorUnits() convert 1 meter into MapLibre's internal Mercator coordinate units at this specific origin (that scale factor changes with latitude), and toLngLat() converts a meter offset back into a real map coordinate whenever the camera needs updating. All of this is keyed off the origin prop now instead of a hardcoded constant.
const originMercator = maplibregl.MercatorCoordinate.fromLngLat(origin);
const metresToMercatorUnits = originMercator.meterInMercatorCoordinateUnits();
const player = { x: 0, y: 0, heading: Math.PI / 2 };

const toLngLat = (x: number, y: number) =>
  new maplibregl.MercatorCoordinate(
    originMercator.x + x * metresToMercatorUnits,
    originMercator.y - y * metresToMercatorUnits,
  ).toLngLat();
True eye-level math (see updateCamera below) computes a required zoom of about 21.5 for a 20m look-ahead distance. This style's vector data only exists natively at zoom 14 -- that's ~7.5 levels of overzoom, and past a certain point this particular style's layers stop rendering entirely (confirmed by testing: real tiles were loading over the network, but the canvas painted nothing but a flat background color). zoom: maxZoom here is just the map's starting point; the actual clamp happens every frame in updateCamera. As in Upper Map Controls, the default attribution is disabled and re-added at top-right, then force-collapsed via classList -- it never auto-collapses on its own here (that only happens once the map is dragged, and interactive:false means dragging never occurs), so without the extra line it would sit fully expanded on top of the D-pad forever.
const map = new maplibregl.Map({
  container: mapContainerRef.current,
  style: mapStyle,
  center: origin,
  zoom: maxZoom,
  pitch: 89,
  maxPitch: 89,
  interactive: false,
  canvasContextAttributes: { antialias: true },
  attributionControl: false,
});
map.addControl(new maplibregl.AttributionControl({ compact: true }), "top-right");
mapContainerRef.current
  .querySelector(".maplibregl-ctrl-attrib")
  ?.classList.remove("maplibregl-compact-show");
Collision needs the building footprints near the player. querySourceFeatures reads them straight out of the vector tiles already loaded for rendering -- no second data source, no network request. It's cached in a variable rather than queried per-frame (that would be far too slow), and refreshed on the sourcedata event so newly streamed-in tiles become solid as you walk toward them. The returned geometry is already in [lng, lat], which is why collidesAt can convert the player's meter position with toLngLat and compare directly.
let buildings: maplibregl.GeoJSONFeature[] = [];
const refreshBuildings = () => {
  buildings = map.querySourceFeatures(BUILDING_SOURCE, {
    sourceLayer: BUILDING_SOURCE_LAYER,
  });
};
map.on("load", refreshBuildings);
map.on("sourcedata", (e) => {
  if (e.sourceId === BUILDING_SOURCE && e.isSourceLoaded) refreshBuildings();
});

const collidesAt = (x: number, y: number) => {
  if (!enableCollision) return false;
  const lngLat = toLngLat(x, y);
  const pt: [number, number] = [lngLat.lng, lngLat.lat];
  return buildings.some((f) => f.geometry && pointInBuilding(pt, f.geometry));
};
Each frame: figure out where the eye is and a point lookAhead meters ahead of it, ask MapLibre's calculateCameraOptionsFromTo for the camera settings that would put a real eye at that position looking at that target -- then clamp the zoom it computes down to maxZoom before applying it, which is the actual fix for the blank-screen overzoom bug described above.
const updateCamera = () => {
  const eye = toLngLat(player.x, player.y);
  const ahead = toLngLat(
    player.x + Math.cos(player.heading) * lookAhead,
    player.y + Math.sin(player.heading) * lookAhead,
  );
  const cam = map.calculateCameraOptionsFromTo(eye, eyeHeight, ahead, eyeHeight);
  map.jumpTo({ ...cam, zoom: Math.min(cam.zoom ?? maxZoom, maxZoom) });
};
The actual walk loop, run every animation frame. dt is the real time since the last frame (clamped to 50ms so a stutter/tab-switch can't cause one huge teleport). Left/Right arrows rotate player.heading (looking around). Forward/back (W/S) and strafe (A/D) are combined into a single dx/dy step -- strafe uses the perpendicular direction, which is why its sin/cos are swapped with one sign flipped versus forward/back.
const keysDown = keysDownRef.current;
let lastFrameTime = performance.now();
let frame = 0;
const loop = (now: number) => {
  const dt = Math.min(0.05, (now - lastFrameTime) / 1000);
  lastFrameTime = now;

  if (keysDown.has("ArrowLeft")) player.heading += turnSpeed * dt;
  if (keysDown.has("ArrowRight")) player.heading -= turnSpeed * dt;

  let forward = 0;
  if (keysDown.has("KeyW")) forward += walkSpeed * dt;
  if (keysDown.has("KeyS")) forward -= walkSpeed * dt;

  let strafe = 0;
  if (keysDown.has("KeyD")) strafe += walkSpeed * dt;
  if (keysDown.has("KeyA")) strafe -= walkSpeed * dt;

  const dx =
    Math.cos(player.heading) * forward + Math.sin(player.heading) * strafe;
  const dy =
    Math.sin(player.heading) * forward - Math.cos(player.heading) * strafe;
Collision resolution, and the part with a genuine trap in it. The obvious approach -- test each axis separately and apply whichever ones individually clear -- looks right but lets a diagonal walk corner-cut straight through a building: a small per-frame step can land outside the footprint on X alone and outside on Y alone while the combined diagonal step is squarely inside it. So: try the full move first, and only if that's blocked fall back to sliding along a single axis (which is what keeps you scraping along a wall instead of stopping dead). Note the else-if -- applying both fallbacks would just rebuild the same blocked diagonal.
  const nx = player.x + dx;
  const ny = player.y + dy;
  if (!collidesAt(nx, ny)) {
    player.x = nx;
    player.y = ny;
  } else if (!collidesAt(nx, player.y)) {
    player.x = nx;
  } else if (!collidesAt(player.x, ny)) {
    player.y = ny;
  }

  updateCamera();
  frame = requestAnimationFrame(loop);
};
frame = requestAnimationFrame(loop);
Cleanup is simpler than before, too: keyboard listener teardown lives inside useHeldKeys now, so this effect only cancels its own animation frame loop and tears down the map.
return () => {
  cancelAnimationFrame(frame);
  map.remove();
};
Same inline-style reasoning as Upper Map Controls: maplibre-gl.css's own .maplibregl-map { position: relative } rule would beat a Tailwind class and collapse this div to 0 height, so the position/inset are set inline instead.
<div ref={mapContainerRef} style={{ position: "absolute", inset: 0 }} />
Six buttons instead of Upper Map Controls' four -- turn left/right (arrows) plus forward/strafe-left/back/strafe-right -- but it's still just a config array handed to the same shared TouchDPad. Adding a mode with different controls never means rewriting button JSX, only describing which keys go where.
<TouchDPad
  keysDownRef={keysDownRef}
  buttons={[
    { key: "ArrowLeft", label: "◀", gridArea: "1 / 1" },
    { key: "KeyW", label: "W", gridArea: "1 / 2" },
    { key: "ArrowRight", label: "▶", gridArea: "1 / 3" },
    { key: "KeyA", label: "A", gridArea: "2 / 1" },
    { key: "KeyS", label: "S", gridArea: "2 / 2" },
    { key: "KeyD", label: "D", gridArea: "2 / 3" },
  ]}
/>
That's the whole thing explained. Here's the same component as a single, self-contained file -- copy it into any React/Next.js project and it works as-is.
FirstPersonMapControls.tsx
"use client";

/**
 * Drop-in MapLibre eye-level first-person walker -- move with W/A/S/D (or the
 * on-screen buttons) and turn with the Left/Right arrow keys. W/S walk
 * forward/back, A/D strafe sideways (they don't turn you), Left/Right rotate
 * the view -- the classic keyboard-only FPS scheme for when there's no
 * mouse-look.
 *
 * Walking into a building blocks you (enableCollision, on by default), using
 * the building footprints from the vector tiles themselves.
 *
 * Setup: npm install maplibre-gl react react-dom
 *
 * Three things this component works around, in case you hit them elsewhere:
 *  1. The worker script loads from a CDN (pin the version to match your
 *     installed maplibre-gl) because MapLibre's default worker-URL detection
 *     (import.meta.url) breaks under bundlers like Turbopack/Webpack.
 *  2. True eye-level camera math computes a very high zoom (~21+) for a
 *     realistic look-ahead distance. Many vector styles only have native
 *     tile data up to zoom ~14 and stop rendering anything past a certain
 *     amount of overzoom. maxZoom below clamps the computed zoom so
 *     buildings/streets stay visible -- raise it if your style supports
 *     deeper zoom, lower it if things still look blank.
 *  3. Collision resolves the full diagonal move first and only falls back to
 *     single-axis sliding. Testing each axis separately and applying both
 *     lets a diagonal walk corner-cut straight through a building.
 */

import * as maplibregl from "maplibre-gl";
import "maplibre-gl/dist/maplibre-gl.css";
import { useEffect, useRef } from "react";

const KEYS = ["KeyW", "KeyA", "KeyS", "KeyD", "ArrowLeft", "ArrowRight"] as const;
type Key = (typeof KEYS)[number];

// Building footprints for collision. These names come from the OpenMapTiles
// schema the default style uses -- change them to match your own style.
const BUILDING_SOURCE = "openmaptiles";
const BUILDING_SOURCE_LAYER = "building";

type Ring = number[][];

// Standard ray-casting point-in-polygon test.
function pointInRing(pt: [number, number], ring: Ring): boolean {
  let inside = false;
  for (let i = 0, j = ring.length - 1; i < ring.length; j = i++) {
    const [xi, yi] = ring[i];
    const [xj, yj] = ring[j];
    const crosses =
      yi > pt[1] !== yj > pt[1] &&
      pt[0] < ((xj - xi) * (pt[1] - yi)) / (yj - yi) + xi;
    if (crosses) inside = !inside;
  }
  return inside;
}

// Polygon = [outerRing, ...holeRings]. Inside the outer ring but inside a
// hole means outside the shape (courtyards, etc).
function pointInPolygon(pt: [number, number], rings: Ring[]): boolean {
  if (!pointInRing(pt, rings[0])) return false;
  for (let k = 1; k < rings.length; k++) {
    if (pointInRing(pt, rings[k])) return false;
  }
  return true;
}

function pointInBuilding(pt: [number, number], geometry: GeoJSON.Geometry): boolean {
  if (geometry.type === "Polygon") {
    return pointInPolygon(pt, geometry.coordinates as Ring[]);
  }
  if (geometry.type === "MultiPolygon") {
    return (geometry.coordinates as Ring[][]).some((rings) =>
      pointInPolygon(pt, rings),
    );
  }
  return false;
}

export interface FirstPersonMapControlsProps {
  /** [lng, lat] to start walking from. */
  origin?: [number, number];
  /** Any MapLibre style URL. */
  mapStyle?: string;
  /** Eye height in meters. */
  eyeHeight?: number;
  /** Walking speed in meters/second. */
  walkSpeed?: number;
  /** Turning speed in radians/second. */
  turnSpeed?: number;
  /** How far ahead (meters) the camera looks. */
  lookAhead?: number;
  /** Zoom is clamped to this to keep the style rendering (see note above). */
  maxZoom?: number;
  /** Block walking through building footprints. Defaults to on. */
  enableCollision?: boolean;
}

export default function FirstPersonMapControls({
  origin = [10.1815, 36.7992],
  mapStyle = "https://tiles.openfreemap.org/styles/liberty",
  eyeHeight = 1.6,
  walkSpeed = 4,
  turnSpeed = 1.2, // rad/s -- ~69 deg/s, a full 360 in ~5s
  lookAhead = 20,
  maxZoom = 19,
  enableCollision = true,
}: FirstPersonMapControlsProps) {
  const mapContainerRef = useRef<HTMLDivElement | null>(null);
  const keysDownRef = useRef<Set<Key>>(new Set());

  useEffect(() => {
    if (!mapContainerRef.current) return;

    maplibregl.setWorkerUrl(
      "https://unpkg.com/maplibre-gl@6.6.0/dist/maplibre-gl-worker.mjs",
    );

    const originMercator = maplibregl.MercatorCoordinate.fromLngLat(origin);
    const metresToMercatorUnits = originMercator.meterInMercatorCoordinateUnits();
    const player = { x: 0, y: 0, heading: Math.PI / 2 };

    const toLngLat = (x: number, y: number) =>
      new maplibregl.MercatorCoordinate(
        originMercator.x + x * metresToMercatorUnits,
        originMercator.y - y * metresToMercatorUnits,
      ).toLngLat();

    const map = new maplibregl.Map({
      container: mapContainerRef.current,
      style: mapStyle,
      center: origin,
      zoom: maxZoom,
      pitch: 89,
      maxPitch: 89,
      interactive: false,
      canvasContextAttributes: { antialias: true },
      attributionControl: false,
    });
    map.addControl(new maplibregl.AttributionControl({ compact: true }), "top-right");
    mapContainerRef.current
      .querySelector(".maplibregl-ctrl-attrib")
      ?.classList.remove("maplibregl-compact-show");

    // Building footprints currently loaded nearby, refreshed as new tiles
    // stream in while walking -- cheap to test against every frame, too
    // expensive to re-query the vector source every frame.
    let buildings: maplibregl.GeoJSONFeature[] = [];
    const refreshBuildings = () => {
      buildings = map.querySourceFeatures(BUILDING_SOURCE, {
        sourceLayer: BUILDING_SOURCE_LAYER,
      });
    };
    map.on("load", refreshBuildings);
    map.on("sourcedata", (e) => {
      if (e.sourceId === BUILDING_SOURCE && e.isSourceLoaded) refreshBuildings();
    });

    const collidesAt = (x: number, y: number) => {
      if (!enableCollision) return false;
      const lngLat = toLngLat(x, y);
      const pt: [number, number] = [lngLat.lng, lngLat.lat];
      return buildings.some((f) => f.geometry && pointInBuilding(pt, f.geometry));
    };

    const updateCamera = () => {
      const eye = toLngLat(player.x, player.y);
      const ahead = toLngLat(
        player.x + Math.cos(player.heading) * lookAhead,
        player.y + Math.sin(player.heading) * lookAhead,
      );
      const cam = map.calculateCameraOptionsFromTo(eye, eyeHeight, ahead, eyeHeight);
      map.jumpTo({ ...cam, zoom: Math.min(cam.zoom ?? maxZoom, maxZoom) });
    };

    const keysDown = keysDownRef.current;
    const onKeyDown = (e: KeyboardEvent) => {
      if ((KEYS as readonly string[]).includes(e.code)) keysDown.add(e.code as Key);
    };
    const onKeyUp = (e: KeyboardEvent) => {
      keysDown.delete(e.code as Key);
    };
    window.addEventListener("keydown", onKeyDown);
    window.addEventListener("keyup", onKeyUp);

    let lastFrameTime = performance.now();
    let frame = 0;
    const loop = (now: number) => {
      const dt = Math.min(0.05, (now - lastFrameTime) / 1000);
      lastFrameTime = now;

      if (keysDown.has("ArrowLeft")) player.heading += turnSpeed * dt;
      if (keysDown.has("ArrowRight")) player.heading -= turnSpeed * dt;

      let forward = 0;
      if (keysDown.has("KeyW")) forward += walkSpeed * dt;
      if (keysDown.has("KeyS")) forward -= walkSpeed * dt;

      let strafe = 0;
      if (keysDown.has("KeyD")) strafe += walkSpeed * dt;
      if (keysDown.has("KeyA")) strafe -= walkSpeed * dt;

      const dx =
        Math.cos(player.heading) * forward + Math.sin(player.heading) * strafe;
      const dy =
        Math.sin(player.heading) * forward - Math.cos(player.heading) * strafe;

      // Full diagonal move first, then fall back to sliding along one axis.
      // Applying both axes independently would let a diagonal walk
      // corner-cut through a building (each axis alone clears the footprint
      // even when the combined step doesn't).
      const nx = player.x + dx;
      const ny = player.y + dy;
      if (!collidesAt(nx, ny)) {
        player.x = nx;
        player.y = ny;
      } else if (!collidesAt(nx, player.y)) {
        player.x = nx;
      } else if (!collidesAt(player.x, ny)) {
        player.y = ny;
      }

      updateCamera();
      frame = requestAnimationFrame(loop);
    };
    frame = requestAnimationFrame(loop);

    return () => {
      cancelAnimationFrame(frame);
      window.removeEventListener("keydown", onKeyDown);
      window.removeEventListener("keyup", onKeyUp);
      keysDown.clear();
      map.remove();
    };
  }, [origin, mapStyle, eyeHeight, walkSpeed, turnSpeed, lookAhead, maxZoom, enableCollision]);

  const buttonStyle: React.CSSProperties = {
    font: "700 18px system-ui, sans-serif",
    color: "#e6edf3",
    background: "linear-gradient(180deg, rgba(255,255,255,0.16), rgba(255,255,255,0.03))",
    border: "1px solid rgba(255,255,255,0.14)",
    borderRadius: 10,
    width: 52,
    height: 52,
    boxShadow: "0 2px 5px rgba(0,0,0,0.3), inset 0 1px 0 rgba(255,255,255,0.18)",
    touchAction: "none",
    transition: "transform 0.08s ease, filter 0.08s ease",
  };

  return (
    <>
      <div ref={mapContainerRef} style={{ position: "absolute", inset: 0 }} />
      {/* Plain CSS for press feedback -- simplest way to add a ":active" rule
          from inside a single self-contained component file. */}
      <style>{`.touch-dpad-btn:active { transform: scale(0.93); filter: brightness(1.2); }`}</style>
      <div
        style={{
          position: "absolute",
          bottom: 16,
          left: "50%",
          transform: "translateX(-50%)",
          display: "grid",
          gridTemplateColumns: "repeat(3, 52px)",
          gridTemplateRows: "repeat(2, 52px)",
          gap: 8,
          padding: 10,
          borderRadius: 16,
          background: "rgba(13, 17, 23, 0.55)",
          backdropFilter: "blur(8px)",
          WebkitBackdropFilter: "blur(8px)",
          border: "1px solid rgba(255,255,255,0.08)",
          boxShadow: "0 8px 24px rgba(0,0,0,0.35)",
        }}
      >
        <button
          type="button"
          className="touch-dpad-btn"
          style={{ ...buttonStyle, gridArea: "1 / 1" }}
          onPointerDown={(e) => {
            e.preventDefault();
            e.currentTarget.setPointerCapture(e.pointerId);
            keysDownRef.current.add("ArrowLeft");
          }}
          onLostPointerCapture={() => keysDownRef.current.delete("ArrowLeft")}
        >
          ◀
        </button>
        <button
          type="button"
          className="touch-dpad-btn"
          style={{ ...buttonStyle, gridArea: "1 / 2" }}
          onPointerDown={(e) => {
            e.preventDefault();
            e.currentTarget.setPointerCapture(e.pointerId);
            keysDownRef.current.add("KeyW");
          }}
          onLostPointerCapture={() => keysDownRef.current.delete("KeyW")}
        >
          W
        </button>
        <button
          type="button"
          className="touch-dpad-btn"
          style={{ ...buttonStyle, gridArea: "1 / 3" }}
          onPointerDown={(e) => {
            e.preventDefault();
            e.currentTarget.setPointerCapture(e.pointerId);
            keysDownRef.current.add("ArrowRight");
          }}
          onLostPointerCapture={() => keysDownRef.current.delete("ArrowRight")}
        >
          ▶
        </button>
        <button
          type="button"
          className="touch-dpad-btn"
          style={{ ...buttonStyle, gridArea: "2 / 1" }}
          onPointerDown={(e) => {
            e.preventDefault();
            e.currentTarget.setPointerCapture(e.pointerId);
            keysDownRef.current.add("KeyA");
          }}
          onLostPointerCapture={() => keysDownRef.current.delete("KeyA")}
        >
          A
        </button>
        <button
          type="button"
          className="touch-dpad-btn"
          style={{ ...buttonStyle, gridArea: "2 / 2" }}
          onPointerDown={(e) => {
            e.preventDefault();
            e.currentTarget.setPointerCapture(e.pointerId);
            keysDownRef.current.add("KeyS");
          }}
          onLostPointerCapture={() => keysDownRef.current.delete("KeyS")}
        >
          S
        </button>
        <button
          type="button"
          className="touch-dpad-btn"
          style={{ ...buttonStyle, gridArea: "2 / 3" }}
          onPointerDown={(e) => {
            e.preventDefault();
            e.currentTarget.setPointerCapture(e.pointerId);
            keysDownRef.current.add("KeyD");
          }}
          onLostPointerCapture={() => keysDownRef.current.delete("KeyD")}
        >
          D
        </button>
      </div>
    </>
  );
}