Interactive City-Guessing Puzzle
🔍 Behind the Build: Creating CityHexScope
Welcome to the dev blog for CityHexScope, an interactive, map-driven puzzle game built with React and TypeScript. Players are challenged to identify cities based on visual and landmark cues, using partial views rendered via the OpenFreeMap API.
🧩 Game Overview
CityHexScope tasks users with guessing city names using a limited portion of a map. The game is structured around selectable topics, each comprising a list of locations. Players navigate through rounds using hints, progress indicators, and feedback—all tracked through dynamic statistics updated in real-time.
🏗️ Key Components
- Game Topics: Each topic page allows the setup of:
- Location List: Cities with coordinates and metadata such as zoom level and available hints.
- Game Manager: The orchestrator that drives gameplay logic and integrates all sub-components:
- Scoreboard
- Progress Bar
- Option Buttons for each city
- Map via OpenFreeMap
- Controls like “Next”, “Hints”, and statistics tracking
This modular design supports easy adjustments—like adding attempt limits or new topics—without disrupting the broader codebase.
🗺️ Map Integration
The OpenFreeMap API powers the visual layer, configured with default styling and visibility settings for symbols, labels, and zoom levels.
đź“Š Game Logic & Performance Tracking
- A dedicated Metrics module calculates user success rates and endgame summaries.
- All game actions (resets, state updates, messages) are decoupled into a single module and consumed via custom hooks triggered by user interactions.
- Game stats provide ongoing performance feedback after each round, encouraging replay ability and competition.
🧪 Testing & Scalability
Testing is implemented using Vitest, ensuring hook logic and performance calculations are verified. The app layout is structured with a central Layout Component that uses React Router’s <Outlet />, allowing additional topics or pages to be introduced with minimal friction.
🎮 Gameplay Flow
Users begin by selecting a topic via the navbar. The game UI presents:
- City guess options on the left
- Remaining attempts and a live progress bar above
- A map and prompt to make a selection
- Optional hints, automatic advancement after three incorrect guesses, and instant stat updates
đź’ˇFinal Thoughts
CityHexScope was both a fun and technically rewarding project. With its modular design and clean separation of logic, it’s ready for future feature enhancements – whether that’s new topics, additional metrics, or UX upgrades.
The latest code can be found here on GitHub: SaharaHex/CityHexScope
The diagram below outlines component responsibilities and application structure – giving an overview of how the app evolved from idea to execution.
SaharaHex 