How We Make an HD Map

01 Overview

02 What the pipeline produces

Per built-in map, five things exist: four files in the repo and one pyramid in Blob storage. Sizes below are the actual current files in apps/web/public/maps/.

The no-map fallback, default.jpg, is separate from all of this: a single 2200×2200 JPEG (~118 KB), procedurally generated, with no HD variant, no thumbnail, and no tile pyramid. It's what a room shows before a commander picks or uploads a map.

03 Source image requirements

04 The pipeline, step by step

1. Right-size the web images.

   # --src is the folder holding the source PNGs
   node scripts/optimize-maps.mjs "C:/path/to/dir/with/*_map.png"

   For each of zesty, bakurani, ozeti: resizes the source to 2048px and 4096px wide (WebP, quality 80, effort: 5) and a 480px JPEG thumbnail (quality 70), all via sharp with withoutEnlargement: true. Writes directly into apps/web/public/maps/. A handful of resizes per map — the script has no timing instrumentation, but this is seconds, not minutes, on typical hardware.

2. Cut and upload the tile pyramid.

   node scripts/tile-maps.mjs \
     [--maps=zesty,bakurani,ozeti]  # default: all three
     [--max-level=6]                # default; 16384px top level
     --src="<folder with the source PNGs>"
     [--concurrency=16]             # parallel Blob uploads
     [--quality=80]                 # tile WebP quality
     [--tmp=<dir>] [--keep-local]

   Requires BLOB_READ_WRITE_TOKEN in the environment (copy it from apps/web/.env.local). Per map: downscales the source to 256 × 2^maxLevel px if it's larger (a no-op for a source already at or under that size), then runs sharp(...).webp({ quality }).tile({ size: 256, layout: "google" }) to write a Google-style pyramid to a temp directory, then uploads every tile to Vercel Blob at tiles/<id>/<z>/<x>/<y>.webp through a fixed-concurrency pool (default 16 at once), retrying a failed upload up to 4 times with exponential backoff.

   It's resumable: before uploading, it lists what's already at that Blob prefix and skips any tile whose path already exists, so a re-run after a partial failure only uploads what's missing. Local tiling itself is noted in the script's own log line as taking "a minute" for a 16384px pyramid; the network upload of ~5,461 tiles/map is the slower, connection-dependent part. When it's done it prints a tiles: { baseUrl, maxLevel, tileSize } block per map to paste into packages/shared/src/index.ts.

3. (Unrelated) Regenerate the fallback.

   node scripts/generate-map.mjs

   Rewrites public/maps/default.jpg from a deterministic (seeded) procedural SVG — no source image needed, no tiles, no HD variant. Only touches that one file.

05 How the client renders it

L = clamp(round(log2(scale * mapWidth / tileSize)), 0, maxLevel)

06 Adding a new built-in map — checklist

1. Source it. Get a square PNG at least 16384px on a side, named <id>_map.png, in the scripts' source directory.
2. Register it in both scripts. Add { id, file } to ALL_MAPS in both optimize-maps.mjs and tile-maps.mjs — they're two separate hardcoded arrays with no shared config, easy to update one and forget the other.
3. Run node scripts/optimize-maps.mjs to produce <id>.webp, <id>-hd.webp, <id>-thumb.jpg in apps/web/public/maps/.
4. Run node scripts/tile-maps.mjs --maps=<id> (needs BLOB_READ_WRITE_TOKEN) to cut and upload the pyramid. Copy the printed tiles: { baseUrl, maxLevel, tileSize } block.
5. Add the map to packages/shared/src/index.ts: extend the MapId union and add a MapInfo entry to MAPS with the url/hdUrl/thumb paths and the pasted tiles block.
6. Commit the four repo files (<id>.webp, -hd.webp, -thumb.jpg) — the tile pyramid lives only in Blob, not in git.
7. Verify it shows up: the map picker in create-room-flow.tsx and room-controls.tsx both map over the MAPS array automatically, and POST /api/rooms accepts map=<id> via mapById() — nothing else to wire.

07 Custom maps uploaded by a commander

08 Gotchas

• The HD swap is currently dead code for every built-in map. All three (zesty, bakurani, ozeti) have a tile pyramid, and MapCanvas.tsx skips the 4096px HD preload/swap entirely whenever a pyramid exists. The -hd.webp files still get generated and shipped (2.6–4.7 MB each) but nothing currently loads them for a built-in map. They'd only matter again for a built-in map added without tiling, or if tiling were ever turned off.
• The on-disk tile layout is row-then-column, not x-then-y. sharp's layout: "google" writes <z>/<y>/<x>.webp locally — the opposite of the "z/x/y" shorthand the URLs use after re-keying. tile-maps.mjs's own header comment calls this out as "verified empirically," i.e. found by trial and error, not documented anywhere upstream.
• Re-tiling a map doesn't overwrite old tiles. The upload step skips any Blob path that already exists (that's what makes it resumable), so replacing a map's source image and re-running tile-maps.mjs silently keeps every old tile that shares a path with a new one — old and new tiles only differ if the pyramid shape (max level) changes. Deleting the old tiles/<id>/ prefix from Blob first is necessary for an actual re-tile, and this script doesn't do that for you.
• next.config.ts's image remotePatterns (for *.public.blob.vercel-storage.com) doesn't apply to any of this. Every map image in the app — base, HD, thumb, and every tile — is rendered through a plain <img> tag, not next/image. Confirmed by grep: no next/image import anywhere under src/features/map. The remote pattern config exists for Blob URLs in general but isn't exercised by the map pipeline.
• Two scripts, two hardcoded map lists. optimize-maps.mjs and tile-maps.mjs each define their own ALL_MAPS array with the same three entries. Nothing keeps them in sync — adding a map to one and forgetting the other is a straightforward way to end up with a WebP file and no tile pyramid, or vice versa.
• Provenance is one Reddit post. The three source PNGs come from a community post, recorded in SOURCE.md. No elevation data exists in any of them; they are flat overhead images.
• Blob cleanup for expired rooms is unconfirmed. Room records expire from KV 24 hours after last activity (ROOM_TTL_S), but no code was found in this repo that deletes a custom map's Blob object when its room expires — the KV record disappears, the image may not. Flagged, not confirmed either way.

09 Reference

Constants pulled directly from the source, with the file each one comes from.