🕸️ Light Hunt AR

The Ultimate Face Tracking AR Experience ✨

An immersive augmented reality game where your face becomes the playground 🎯

Hunt colorful orbs floating around your head using cutting-edge face tracking technology

🎮 Play Live Demo | 📱 Mobile Optimized | 🏆 Leaderboard

---

🌟 What Makes Light Hunt Special?

🎯 Feature	🚀 Technology	✨ Experience
Face Tracking	MindAR Face Detection	No markers needed - just your face!
Real-time 3D	Three.js + WebGL	Smooth 60fps orb animations
Progressive Scoring	Smart Probability System	Rare orbs worth more points
Global Competition	Firebase Realtime DB	Compete with players worldwide
Cross-platform	PWA Ready	Desktop, Mobile, Tablet support

---

🎮 How to Play

1. 🔍 Allow camera access - We need to see your beautiful face!
2. 👤 Position yourself - Center your face in the frame
3. 🎯 Hunt orbs - Tap/click the colorful orbs floating around you
4. 🏆 Beat the clock - Capture as many as possible in 120 seconds
5. 📊 Climb the leaderboard - Compete for the top spot globally!

🎨 Orb Types & Values

• 🪙 Blue Orb: 1 point (Common - 60% spawn rate)
• 💩 Red Orb: 2 points (Rare - 8% spawn rate)
• 🌿 Green Orb: 3 points (Rare - 8% spawn rate)
• ☕ Yellow Orb: 4 points (Rare - 8% spawn rate)
• 🐱 Orange Cat: 5 points (Legendary - 4% spawn rate)

---

👥 Meet Our Incredible Team

Miriam 🎨 UI/UX Design Lead @Kuroimichan4

Daniel García ⚡ Frontend Engineer @DarksAces

Daniel Zorita 🔧 Backend & Firebase @DZorita

Ruth Daniela 🕸️ AR/VR Specialist @RuthDanielaAguirre

Carles 🎵 Sound & Effects @Carles2311

---

🛠️ Tech Stack & Architecture

graph TB
    A[👤 User Face] --> B[📷 Camera Feed]
    B --> C[🧠 MindAR Face Detection]
    C --> D[📍 Anchor Points]
    D --> E[🎯 Three.js Scene]
    E --> F[✨ Orb Spawning]
    F --> G[🎮 User Interaction]
    G --> H[📊 Score System]
    H --> I[☁️ Firebase Database]
    I --> J[🏆 Global Leaderboard]

Loading

Frontend	AR & 3D	Backend	DevOps

---

🚀 Quick Start

Prerequisites

• Node.js 18+
• pnpm package manager
• Modern browser with WebGL support
• Camera access (required for AR)

Installation

# 📦 Clone the repository
git clone https://github.com/your-team/light-hunt-ar.git
cd light-hunt-ar

# ⚡ Install dependencies
pnpm install

# 🔧 Set up environment variables
cp .env.example .env
# Add your Firebase config to .env

# 🚀 Start development server
pnpm dev

🌍 Environment Setup

# .env file
VITE_FIREBASE_API_KEY=your_api_key_here
VITE_FIREBASE_AUTH_DOMAIN=your_project.firebaseapp.com
VITE_FIREBASE_PROJECT_ID=your_project_id
VITE_FIREBASE_STORAGE_BUCKET=your_project.appspot.com
VITE_FIREBASE_MESSAGING_SENDER_ID=123456789
VITE_FIREBASE_APP_ID=1:123456789:web:abcdef123456

---

📁 Project Structure

light-hunt-ar/
├── 🎮 src/
│   ├── 🎯 game/
│   │   ├── ar.js          # Face tracking & AR logic
│   │   ├── createOrb.js   # 3D orb generation system
│   │   └── audio.js       # Sound effects manager
│   ├── 🎨 components/
│   │   ├── LoginModal.jsx    # User authentication
│   │   ├── LobbyScreen.jsx   # Game lobby
│   │   └── Leaderboard.jsx   # Global rankings
│   ├── ☁️ services/
│   │   └── firebase.js    # Database integration
│   └── 📱 App.jsx         # Main application
├── 🌐 public/
│   └── 🔊 sounds/        # Audio assets
└── ⚙️ config files

---

🎯 Key Features

🧠 Advanced Face Tracking

• No markers required - works with any face
• 68 facial landmarks detection
• Optimized for mobile devices
• Real-time performance at 60fps

🎮 Immersive Gameplay

• Physics-based orb animations with realistic bobbing
• Progressive difficulty system
• Haptic feedback on mobile devices
• Particle effects for enhanced visual appeal

🏆 Competitive Elements

• Real-time global leaderboard
• Anonymous login system
• Score persistence across sessions
• Achievement system (coming soon)

📱 Cross-Platform Support

• PWA ready - install as mobile app
• Responsive design for all screen sizes
• Offline capability for core gameplay
• WebGL optimization for smooth performance

---

🎵 Sound Design

Our audio system provides an immersive 3D soundscape:

• 🎼 Ambient Music: Dynamic background scoring
• 🔔 Orb Spawn: Satisfying audio feedback for new orbs
• ✨ Capture Sounds: Rewarding success audio
• 🎯 Spatial Audio: 3D positioned sound effects

---

📊 Performance Metrics

Metric	Target	Current	Status
First Paint	< 1.5s	1.2s	✅
AR Initialize	< 3.0s	2.8s	✅
Frame Rate	60 FPS	58-60 FPS	✅
Bundle Size	< 2MB	1.8MB	✅
Lighthouse Score	> 90	94	✅

---

🚀 Deployment

Production Build

# 🏗️ Build for production
pnpm build

# 🔍 Preview production build
pnpm preview

🌐 Live on Vercel

Every push to main automatically deploys to: https://game-jam-psi.vercel.app/

📱 Mobile Testing

• ✅ Chrome Mobile: Full support
• ✅ Safari Mobile: Full support
• ✅ Firefox Mobile: Beta support

---

🤝 Contributing

We welcome contributions! Please see our Contributing Guidelines for details.

🐛 Found a Bug?

1. Check existing Issues
2. Create a new issue with detailed reproduction steps
3. Include browser/device information

💡 Feature Ideas?

1. Open a Feature Request
2. Describe the enhancement in detail
3. Explain the use case and benefits

---

📄 License

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

---

🙏 Acknowledgments

Special thanks to:

• MindAR for the incredible AR framework
• Three.js for 3D graphics capabilities
• Firebase for backend infrastructure
• Vercel for seamless deployment
• Our amazing beta testers for valuable feedback

---

🎯 Ready to Hunt Some Orbs?

---

Made with ❤️ by the Light Hunt Team | © 2026