mirror of
https://github.com/tiennm99/vngeoguessr.git
synced 2026-10-20 00:15:57 +00:00
tiennm99
c9a35dca9a
Reconcile every doc with the shipped code. All six described a flat five-city model, and features.md, tech-stack.md, game-flow.md and project-structure.md still documented the dart-throw over /images?bbox= that the prebuilt panorama indexes replaced. project-overview.md gains a Coverage note that classifies absent coverage into its three causes -- not yet added, no street imagery, missing from the boundary -- because a note that only says "partial" teaches maintainers to ignore real gaps. Cu Chi is named as the one instance of the third, which is the only one that is a defect. A context hook had been denying access to src/app/debug/coverage/page.js, so this also lands the two items earlier phases recorded as undeliverable: the api/debug/city-coverage -> region-coverage rename, and the page's migration from a flat city list to RegionSelect. With its last caller gone, game.js drops CITIES, cities, cityNames, cityCenters and cityBboxes; getCityIndex, indexedCities and fetchCityPanorama take names that match what they now take. Selecting a district with no boundary returned a 400 and left the previous region's panorama count and outline on screen beside the error, so Ho Chi Minh's 184,938 read as Cu Chi's. The error path now clears everything derived from the previous region, and a null boundary removes the outline rather than skipping the redraw. Two plan-time claims did not survive contact with the code and the docs follow the code: VN scores like any other node rather than being a zero-scoring exploration mode, and the fan-out credits two levels when a panorama falls outside every district outline.
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.