vngeoguessr/docs/features.md

Game Features

Location Coverage

• Three-level region tree: Vietnam → nine provinces → 75 districts and towns, generated into src/data/regions/ and traversed through src/lib/regions.js
• Play at any level: the whole country, one province, or one district
• Pre-2025-merger boundaries: Da Lat sits under Lam Dong, Duc Hoa under Long An
• Partial by design: see the Coverage note in project-overview.md for the three distinct reasons a region can be unavailable

Street View System

• Prebuilt panorama indexes: each province ships a list of Mapillary panorama ids, their coordinates, and the district each falls in, built offline by scripts/build-pano-index.mjs and scripts/assign-pano-districts.mjs
• Mapillary vector tiles: the index is built from the z14 image layer, not from /images?bbox= search, which returns HTTP 500 in exactly the dense districts the game wants to play. See the header of src/lib/mapillary.js
• Runtime cost is one lookup: fetchPanoramaById resolves a chosen id in ~230ms; a couple of alternates are tried in case an image was deleted upstream
• Country draws pick a province first, uniformly, so Vietnam rounds are not 97% Ha Noi and Ho Chi Minh by panorama count
• No immediate repeats: the last 50 panoramas a player was shown are excluded from their next draw, across every region. A location is recorded as seen when the round is created, so skipping one also stops it coming back. The exclusion is a preference, not a rule: where it would empty a small region's pool it is dropped and a repeat allowed, because a repeat beats telling the player a region they can see has no coverage
• The player identity behind that is a cookie and nothing more: vng_pid is an httpOnly UUID the server mints, holds no personal data, is never shown to the player, and is never joined to their username or scores. Its one other use is a HyperLogLog of distinct players per day (see Play statistics), which can be counted but never read back. It is not the username, deliberately — that lives in localStorage, is renameable, and is shared by anyone who types it
• Panoramas only: non-panoramic images are filtered out when the index is built, so every indexed point is a panorama. The flag itself is not stored
• Thumbnail display: thumb_2048_url, falling back to thumb_original_url
• Attribution overlay: every panorama shows the Mapillary logo (linking to the Mapillary homepage, never the per-image page — the image id is the round's answer) and a CC BY-SA 4.0 link, as the Mapillary Terms of Use require. /credits lists all data sources and licenses; the home page footer links to it

Interactive Maps

• Leaflet Integration: OpenStreetMap-based interactive mapping. Tiles come from Geoapify when NEXT_PUBLIC_GEOAPIFY_KEY is set at build time (free tier allows commercial use), falling back to the OSM public server otherwise; the choice is centralized in src/lib/map-tiles.js
• Click-to-Place: Intuitive guess marker placement
• Map Search: search box on the guess map finds districts (offline, diacritic- and alias-aware: quận 7, q7, hoàn kiếm) and streets/places (Photon geocoder, bounded to the played region). Selecting a result only pans/zooms the map — it never places the guess marker

Anti-Cheat Security

• Redis Session Management: target coordinates stored server-side in Redis
• Debug API closed in production: /api/debug/pano and /api/debug/region-coverage return panorama coordinates, which is the answer to any live round. On Vercel production they answer only a request carrying DEBUG_ACCESS_KEY as the x-debug-key header or the vng_debug cookie (src/lib/debug-access.js); unset, they are closed. Local, test and preview deployments keep them open. The /debug pages still render in production but their data calls fail without the key
• Validated input: the username rule lives once in src/lib/username.js (2-20 characters of letters, digits, -, _, any script) and is enforced by the name prompt and by /api/guess; a colon is excluded because the distance boards pack username:distance:timestamp into one member. Guess coordinates must be finite numbers, checked before the session is consumed so a malformed submit costs nothing. A sessionId that is not a UUID is replaced on /api/new-game and rejected on /api/skip; only server-minted ids reach the keyspace
• Server-resolved region: the district a panorama sits in is decided at session creation and never sent to the client; a regionCode in the guess request body is ignored
• UUID Session IDs: unique session identifiers via crypto.randomUUID()
• 30-minute Expiry: automatic Redis session cleanup
• Single-use sessions: the session is claimed with an atomic DEL before any score is written, so a replayed or concurrent submit scores exactly once. The failure carries a reason (session-expired, session-consumed, invalid-guess, invalid-username, invalid-request) and the result dialog words each one differently, so an expired round is not reported as a failed write
• Skipped rounds get a fresh id: the skip request deletes the old session without being awaited, so the next round never reuses that id -- a late delete used to land after the new round's write and kill it
• Server-side Calculations: all distance and scoring computed server-side using Turf.js

Scoring System

Distance-based points (0-5 scale). One ladder for every region — the size of the region the player picked does not change a threshold (SCORE_BANDS in src/lib/game.js):

• 0-50m: 5 points
• 50m-100m: 4 points
• 100m-200m: 3 points
• 200m-500m: 2 points
• 500m-1km: 1 point
• beyond: 0 points

A guess is graded on absolute precision, so a point means the same thing on every board and a country round is only won by pinning the street. The ladder is shown on the result dialog.

Below 3 points the dialog adds one display-only line the ladder cannot say: "Right district", "Right province, wrong district" or "Wrong province". The server locates the guess against the generated boundaries (src/lib/region-locate.js, server-only) and returns it as hit and guessedRegion on gameResult. It changes no score. After the reveal the dialog also links the answer's coordinates to OpenStreetMap -- only after the guess, never before.

The headline score and the leaderboards agree: every board above the panorama's district is credited the same points for the round (submitRoundScore in src/lib/leaderboard.js). Each level's added points are returned as points on its gameResult.levels entry. Scores earned under the earlier region-scaled ladder stay on the boards as they were recorded.

Sound & Music

• Sound effects: nine one-shots on the play flow — a click when Play or Back changes screen, a pop when the guess pin lands, a rising sound on submit, a jingle tiered off the score (4-5 points, 1-3, a miss), a transition into the next round, a flat blip on skip, and a low tone when the panorama viewer fails to start or a guess is not recorded. The click is deliberately limited to the two buttons that navigate: on every button in the chrome it became noise within a few rounds
• Background music: one ambient loop at roughly a third of the effects' volume, so it sits under the panorama rather than competing with it. It is mounted app-wide rather than per page, which is what lets it play unbroken across the menu and a round — and means it also plays on Credits and the debug pages
• Two switches, both on by default: music and effects toggle independently from the header, beside the theme switch, and both choices persist in localStorage. The game header collapses them into a single mute-everything button below the sm breakpoint, where there is no room for the pair
• Nothing plays before a gesture: every browser blocks audio until the player interacts, so no audio file is even fetched until the first click or keypress — which also means music on iOS starts at the first tap, not on load
• All assets are CC0: sourced from Kenney and OpenGameArt, with per-file provenance in public/audio/SOURCES.md and credit on /credits

Leaderboards

• Rollup fan-out: one guess credits the district its panorama sat in, then that district's province, then Vietnam — three score boards and three distance boards. A panorama that fell outside every district outline credits two levels instead of three; no province currently has such a panorama
• Score Leaderboards: accumulated points, one entry per user per board
• Distance Leaderboards: best-distance records, multiple entries per user
• Existing scores preserved: Vietnam keeps the pre-existing leaderboard:vietnam / distance:vietnam keys rather than starting a new leaderboard:city:vn. HN, DN and TPHCM kept their codes, so their boards carried over untouched. Only two codes moved — Da Lat's board was backfilled into Lam Dong's and Duc Hoa's into Long An's by a one-shot copy script (applied and verified 2026-09-01, then removed; it survives in git history). No score was reset
• Redis Sorted Sets: persistent leaderboard data using ZINCRBY/ZADD/ZRANGE
• Score boards are never trimmed; the top 200 is a serving window: a score board holds one member per name, so it grows with the player count. It used to be trimmed to 200, which deleted the running total of anyone below the cut -- their next round restarted from zero, and once 200th place held more than one round's points nobody new could ever get on. Distance boards gain a member every round and are still trimmed to 200. Scores are added with one atomic ZINCRBY, so two rounds under one name finishing together both count
• Real-time Ranking: rank calculated with ZREVRANK/ZRANK
• Persistent Storage: no expiration on leaderboard data

The leaderboard:city: / distance:city: key prefix is kept deliberately — renaming it would orphan every score already recorded under it.

Sharing

• Share button on the result dialog: builds three lines -- the picked region, the score as five squares with the distance, and the region's /game/{slug} URL (src/lib/share.js) -- and hands them to the platform share sheet, or the clipboard where there is none. Never coordinates, the panorama id or the resolved district: the same panorama can be dealt again
• Link previews: the root layout and every region page carry Open Graph and Twitter card metadata, so a shared link unfurls with the region's name. metadataBase comes from NEXT_PUBLIC_SITE_URL, else Vercel's production URL, else localhost

Play statistics

• Two keys per UTC day (src/lib/stats.js): stats:{day} is a hash of round counts keyed {pickedLevel}:{score}; stats:players:{day} is a HyperLogLog of vng_pid values. Together they give rounds/day, distinct players, rounds per player, the zero-score share per level, and a return rate from the union of several days against their sum. Both expire after 90 days. Nothing per player is stored; the HyperLogLog only counts
• Cost: two Redis commands per round plus an occasional EXPIRE. A failed write is logged and never fails the guess
• Reading them: npm run stats [days] prints the last N days