Skip to content

README.md

Latest commit

 

History

History
280 lines (206 loc) · 8.24 KB

README.md

File metadata and controls

280 lines (206 loc) · 8.24 KB

🗺️ Ace Map

Next.js React TypeScript License

Ace Map is an interactive map practice tool designed specifically for Class 10 CBSE students to master geographical locations through engaging, game-based learning.

✨ Features

  • 🎮 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

🚀 Getting Started

Prerequisites

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

Installation

  1. Clone the repository
git clone https://github.com/navithecoderboi/ace-map.git
cd ace-map
  1. Install dependencies
pnpm install
  1. Run the development server
pnpm dev
  1. Open your browser

Navigate to http://localhost:3000 to see the application.

Build for Production

To create an optimized production build:

pnpm build
pnpm start

🎮 How to Play

  1. Start the Game - Click the "Start" button to begin
  2. Read the Location - The location name will appear at the top
  3. Mark on Map - Click on the map where you think the location is
  4. Submit - Click "Submit" to check your answer
  5. View Result - See if you were correct and move to the next location
  6. Complete & Share - Finish all locations and share your results!

🛠️ Tech Stack

📁 Project Structure

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

🤝 Contributing

We welcome contributions from the community! Here's how you can help:

Ways to Contribute

  • 🐛 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

Development Workflow

  1. Fork the repository

Click the "Fork" button at the top right of the repository page.

  1. Clone your fork
git clone https://github.com/navithecoderboi/ace-map.git
cd ace-map
  1. Create a new branch
git checkout -b feature/your-feature-name
  1. Install dependencies
pnpm install
  1. Make your changes
  • Write clean, readable code
  • Follow the existing code style
  • Add comments where necessary
  • Test your changes thoroughly
  1. Run linting and formatting
pnpm lint
pnpm format
  1. Commit your changes
git add .
git commit -m "feat: add your feature description"

Follow Conventional Commits format:

  • feat: - New features
  • fix: - Bug fixes
  • docs: - Documentation changes
  • style: - Code style changes (formatting)
  • refactor: - Code refactoring
  • test: - Adding or updating tests
  • chore: - Maintenance tasks
  1. Push to your fork
git push origin feature/your-feature-name
  1. 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

Adding New Locations

To add new geographical locations to the game:

  1. Open src/lib/utils/places.ts
  2. Add your locations to the appropriate category array:
{
    category: "Your Category",
    places: [
        {
            name: "Location Name",
            latitude: 12.3456,
            longitude: 78.9012
        },
        // Add more places...
    ]
}
  1. Ensure coordinates are accurate (use Google Maps or similar)
  2. Test the locations in the game

Code Style Guidelines

  • 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

Testing Your Changes

Before submitting a PR:

# Run development server
pnpm dev

# Check for linting errors
pnpm lint

# Build the project
pnpm build

📜 License

This project is licensed under the MIT License - see the LICENSE file for details.

👨‍💻 Author

NaviTheCoderboi

🙏 Acknowledgments

  • 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

🌟 Show Your Support

If you find this project helpful, please consider giving it a ⭐️ on GitHub!

Made with ❤️ for CBSE Class 10 Students