First See Me is a location-based mobile-first web game that brings the Pokémon GO experience to the browser. Explore your real-world surroundings, discover unique creatures, and capture them to build your collection.

• 📍 Real-time Map: Powered by Mapbox GL JS, featuring a custom dark-themed game map that follows your GPS position.
• 👾 Dynamic Spawning: Creatures appear in your vicinity based on real-world coordinates and rarity weights.
• ⚔️ 3D Encounter System: Immersive capture experience using React Three Fiber (R3F) and Three.js.
• 🎒 Inventory Management: Track your collection, see creature details, and monitor your progress.
• 🛠️ Real-time Admin Panel: A built-in dashboard for live configuration of spawn rates, creature stats, and game balance without restarts.
• 📱 Mobile First: Optimized for touch interactions and high-performance mobile browser experience.

• Frontend: React 19, TypeScript
• Build Tool: Vite 8
• Map & Geo: Mapbox GL JS v3
• 3D Engine: Three.js & @react-three/fiber
• Animation: @react-spring/three & @use-gesture/react
• State Management: Zustand
• Package Manager: Bun

• Bun installed on your machine.
• A Mapbox Access Token.

1. Clone the repository:

   git clone <repository-url>
   cd first-see-me

2. Install dependencies:

   bun install

3. Configure environment: Create a .env file in the root directory and add your Mapbox token:

   VITE_MAPBOX_TOKEN=your_mapbox_token_here

4. Run the development server:

   bun dev

   The app will be available at http://localhost:5678.

src/
├── components/          # React components (Map, HUD, Encounter, etc.)
│   ├── Admin/           # Admin configuration dashboard
│   ├── Encounter/       # 3D capture mechanics and models
│   ├── Map/             # Mapbox implementation and markers
│   └── HUD/             # Heads-up display and navigation
├── store/               # Zustand state management (Game & Admin)
├── hooks/               # Custom hooks (Geolocation, Spawn logic)
├── config/              # Static game configurations
└── public/              # Static assets and 3D models

The game includes a powerful Admin Panel at /admin. This panel allows developers to:

• Modify creature statistics and rarity in real-time.
• Adjust spawn radii and intervals.
• Tweak catch rates and XP rewards.

Changes are persisted to admin-config.json via a custom Vite server middleware.

Built with ❤️ for location-aware gaming.