Ace Map is an interactive map practice tool designed specifically for Class 10 CBSE students to master geographical locations through engaging, game-based learning.
- 🎮 Interactive Game Mode - Practice marking locations on an interactive map
- 📊 Progress Tracking - Track your score and time performance
- 🎯 Multiple Difficulty Levels - Choose from High, Medium, and Low strictness modes
- 📍 Category-Based Learning - Practice specific geographical categories
- ⏱️ Timer System - Challenge yourself with timed practice sessions
- 🎨 Dark/Light Mode - Comfortable viewing in any lighting condition
- 📱 Responsive Design - Works seamlessly on desktop and mobile devices
- 🎉 Results Sharing - Share your achievements with encoded result URLs
Before running this project, make sure you have the following installed:
- Node.js (v18 or higher) - Download here
- pnpm (v8 or higher) - Install with
npm install -g pnpm
- Clone the repository
git clone https://github.com/navithecoderboi/ace-map.git
cd ace-map- Install dependencies
pnpm install- Run the development server
pnpm dev- Open your browser
Navigate to http://localhost:3000 to see the application.
To create an optimized production build:
pnpm build
pnpm start- Start the Game - Click the "Start" button to begin
- Read the Location - The location name will appear at the top
- Mark on Map - Click on the map where you think the location is
- Submit - Click "Submit" to check your answer
- View Result - See if you were correct and move to the next location
- Complete & Share - Finish all locations and share your results!
- Framework: Next.js 16 with App Router
- UI Library: React 19
- Language: TypeScript
- Styling: Tailwind CSS 4
- UI Components: HeroUI
- Map Library: MapLibre GL with react-map-gl
- Animations: Framer Motion
- Code Quality: Biome
- Package Manager: pnpm
ace-map/
├── src/
│ ├── app/ # Next.js app directory
│ │ ├── page.tsx # Home page with results
│ │ ├── layout.tsx # Root layout
│ │ ├── globals.css # Global styles
│ │ └── game/ # Game page
│ │ └── page.tsx # Main game interface
│ └── lib/
│ ├── assets/ # SVG components and icons
│ ├── components/ # React components
│ │ ├── game/ # Game-related components
│ │ │ ├── Game.tsx # Main game component
│ │ │ ├── GameBar.tsx # Game controls and timer
│ │ │ ├── Main.tsx # Game state management
│ │ │ └── Pin.tsx # Map marker component
│ │ ├── BgBeams.tsx # Background effects
│ │ ├── Flow.tsx # Conditional rendering
│ │ ├── Navbar.tsx # Navigation component
│ │ ├── Result.tsx # Results display
│ │ └── Start.tsx # Game start screen
│ ├── hooks/ # Custom React hooks
│ │ ├── useIsMounted.ts
│ │ ├── useLocalStorage.ts
│ │ └── useTheme.tsx
│ └── utils/ # Utility functions
│ ├── dom.ts # DOM utilities
│ ├── game.ts # Game logic and state
│ └── places.ts # Location data
├── public/ # Static assets
├── biome.json # Biome configuration
├── next.config.ts # Next.js configuration
├── tailwind.config.ts # Tailwind configuration
├── tsconfig.json # TypeScript configuration
└── package.json # Project dependencies
We welcome contributions from the community! Here's how you can help:
- 🐛 Report Bugs - Found a bug? Open an issue
- 💡 Suggest Features - Have an idea? Share it with us!
- 📝 Improve Documentation - Help make our docs better
- 🌍 Add Locations - Contribute new geographical locations
- 🎨 Design Improvements - Enhance the UI/UX
- 🧪 Write Tests - Help improve code quality
- Fork the repository
Click the "Fork" button at the top right of the repository page.
- Clone your fork
git clone https://github.com/navithecoderboi/ace-map.git
cd ace-map- Create a new branch
git checkout -b feature/your-feature-name- Install dependencies
pnpm install- Make your changes
- Write clean, readable code
- Follow the existing code style
- Add comments where necessary
- Test your changes thoroughly
- Run linting and formatting
pnpm lint
pnpm format- Commit your changes
git add .
git commit -m "feat: add your feature description"Follow Conventional Commits format:
feat:- New featuresfix:- Bug fixesdocs:- Documentation changesstyle:- Code style changes (formatting)refactor:- Code refactoringtest:- Adding or updating testschore:- Maintenance tasks
- Push to your fork
git push origin feature/your-feature-name- Create a Pull Request
- Go to the original repository
- Click "New Pull Request"
- Select your fork and branch
- Describe your changes clearly
- Link any related issues
To add new geographical locations to the game:
- Open src/lib/utils/places.ts
- Add your locations to the appropriate category array:
{
category: "Your Category",
places: [
{
name: "Location Name",
latitude: 12.3456,
longitude: 78.9012
},
// Add more places...
]
}- Ensure coordinates are accurate (use Google Maps or similar)
- Test the locations in the game
- Use TypeScript for type safety
- Follow React best practices and hooks guidelines
- Use functional components with hooks
- Keep components small and focused
- Use meaningful variable names
- Add JSDoc comments for complex functions
- Prefer const over let when possible
Before submitting a PR:
# Run development server
pnpm dev
# Check for linting errors
pnpm lint
# Build the project
pnpm buildThis project is licensed under the MIT License - see the LICENSE file for details.
NaviTheCoderboi
- GitHub: @navithecoderboi
- Built with Next.js and React
- Maps powered by MapLibre GL
- UI components from HeroUI
- Inspired by the need for better geography practice tools for students
If you find this project helpful, please consider giving it a ⭐️ on GitHub!
Made with ❤️ for CBSE Class 10 Students