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
• Names shown in Vietnamese: every province and district carries an accented nameVi ("Hoàn Kiếm", "Quận 7"), derived by the boundary script from its OSM query, and regionName() in src/lib/regions.js is what the interface, the API's region.name and the share text show. The ASCII name stays as the stable form for codes, logs and search aliases; the map search matches either spelling. The country stays "Vietnam" in an English interface. The font loads the vietnamese subset for the glyphs
• 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, within an eight-second budget for the whole draw. A region with nothing left to show is a 404 with the coverage message; Mapillary not answering is a 502, never reported as missing coverage
• 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. Production means Vercel's production environment, or a production build anywhere Vercel's variables are absent. Local development, tests 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. /api/new-game mints a fresh session id every round and ignores any the client offers; a sessionId that is not a UUID is rejected on /api/guess and /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. After the claim the score fan-out settles per level: the levels that wrote are returned in gameResult.levels, gameResult.partial marks a level that did not, and only a round where no level wrote is reported as unsaved. The response is gameResult alone. 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
• Every round gets a fresh id: a reused id let a late skip delete, or a guess claiming the previous round, land on the new round's session 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.

Daily Challenge

• One panorama, the same for everyone, once a day at /daily. The pick is deterministic from the day (pickPanoBySeed in src/lib/pano-index.js, province first like a country round) and cached in Redis as daily:{day} for 48 hours, so the Postgres draw happens once a day. The image URL is resolved from Mapillary on every request, as every round does, so a signed URL that stops working never breaks the day; a pick deleted upstream is forgotten and the next seeded candidate takes over. Only proof counts as deletion: a Mapillary 400 or 404, or an image with no thumbnail (isImageGone in src/lib/errors.js). A timeout, a 5xx, a 403 or a malformed answer keeps the pick (the request fails with a 502), so a Mapillary blip cannot give one day two panoramas. The pick is written with SET NX, so two instances that draw differently still serve the first one
• Days roll over at midnight Vietnam time (src/lib/daily-calendar.js), numbered from 2026-09-20 as #1
• Scored, counted, never credited: /api/daily opens an ordinary session flagged mode: 'daily'; /api/guess scores it on the same ladder and counts it under its own daily level in the statistics, but credits no leaderboard. The panorama is the same all day and the answer is in the first guess response, so any board the daily fed would be five points for two requests, repeatable all day. No skipping; the submit button says "Submit final guess"
• No daily leaderboard, on purpose: the only identity is a cookie and a localStorage name, so a dated board would be won by whoever opened the most private windows. One attempt per day is enforced by the browser alone (src/lib/daily-progress.js): the finished round is stored with its panorama, pin and result, and reopening /daily shows that instead of a second attempt. Clearing storage means playing again; since the daily feeds no board, that only cheats the player
• Streak: consecutive days played, kept in the same record. The day after the last play extends it, the same day keeps it, a gap restarts it. Shown in the game header, the result dialog, the share text and the home page card

Sharing

• Daily share text: VNGeoGuessr Daily #N, the squares line, and the streak once it is above one, linking to /daily
• 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 EXPIRE on the hash for each new field of the day and one on the HyperLogLog for each new player. A failed write is logged and never fails the guess
• Reading them: npm run stats [days] prints the last N days