mirror of
https://github.com/tiennm99/vngeoguessr.git
synced 2026-10-11 03:13:56 +00:00
tiennm99
00a8f8b627
A round now carries two regions. The one the player picked is public and comes back in every response; the one the panorama actually sits in is a secret, and it is what the leaderboard fans out from. Revealing the second before the guess would collapse a country-wide round to a single district, so it joins the exact coordinates on the never-serialized list -- including in the session lookup handler, which echoes fields back to whoever holds the session id, and that is the player. Session consumption is now a claim rather than a courtesy. Reading a session and then deleting it is not a guard: ten concurrent submits all read it alive, all delete it, and all score. DEL is atomic and returns how many keys it removed, so exactly one caller sees a 1 -- the route scores only if it won that. Consuming before the writes also closes the sequential case, where a failure partway through the fan-out would otherwise leave the session alive for half an hour and let a retry re-credit every level that already succeeded. A guess lost to a mid-write failure is the accepted cost. Region parsing lives in one place. Four routes accept a region, and four slightly different ideas about casing and defaulting is how a typo becomes a leaderboard key nobody reads. Unknown and uncovered codes are rejected with a 400 that names the region, rather than served as an empty board that looks exactly like a region nobody has played yet. Sessions created before this change still score, at province level, since they carry no district. They expire within half an hour, so the fallback can go a release from now. The debug coverage route serves any region with an outline rather than only the five provinces. Its directory keeps the city-coverage name for now: the page that calls it cannot be read in this environment, and renaming the route without updating its caller would break it.
VNGeoGuessr
A GeoGuessr clone focused on Vietnamese locations with accurate boundary detection and anti-cheat security. Play geolocation guessing games across 5 Vietnamese locations using real street-level imagery.
🎮 Features
- 5 Vietnamese Locations: Ha Noi, Da Nang, Ho Chi Minh, Da Lat, Duc Hoa (Long An)
- 360° Street View: Mapillary panoramic images with PhotoSphere viewer
- Anti-Cheat Security: Server-side session management prevents cheating
- Distance-Based Scoring: 0-5 point system based on accuracy
- Persistent Leaderboards: Redis-powered top 200 player rankings
- Accurate Boundaries: Nominatim API + Turf.js for precise city detection
📚 Documentation
For detailed information about this project, see the documentation in /docs/:
- Project Overview - Project summary and key characteristics
- Features - Complete feature list and game mechanics
- Tech Stack - Technology stack and dependencies
- Development Guidelines - Development setup and coding standards
- Game Flow - Complete gameplay flow documentation
- Project Structure - Codebase organization and architecture
🚀 Getting Started
Prerequisites
- Node.js 18+
- npm 11+
- Redis server (for leaderboards)
Development
# Install dependencies
npm install
# Start development server
npm run dev
# Build for production
npm run build
# Start production server
npm start
# Run linting
npm run lint
Open http://localhost:3000 to play the game.
🏗️ Built With
- Frontend: Next.js 15 + React 19 + Tailwind CSS 4
- Street View: Mapillary API + PhotoSphere Viewer
- Maps: Leaflet + OpenStreetMap
- Geographic Data: Nominatim API + Turf.js
- Storage: Redis (leaderboards) + In-memory sessions
- UI Components: shadcn/ui
🎯 How to Play
- Enter your username
- Select a Vietnamese location
- View the 360° street panorama
- Place your guess on the map
- Earn points based on accuracy (closer = more points)
- Compete for the top 200 leaderboard spots!
📋 Development Notes
- JavaScript Only: No TypeScript files
- Individual Parameters: Functions use separate parameters, not object destructuring
- Server-Side Security: Game coordinates never sent to client
- Session Management: Automatic cleanup after 30 minutes
🤝 Contributing
This project follows specific development guidelines. Please read the Development Guidelines before contributing.