🏆 PTBP - Discord Gaming Leaderboard Bot

A feature-rich Discord bot for tracking player performance, managing leaderboards, and recording match statistics with AI-powered scoreboard recognition.

✨ Features

📊 Leaderboard Management

• Dynamic Leaderboards - Automatically updated leaderboards with real-time player rankings
• Multiple Sort Options - Sort by Points, K/D Ratio, Total Kills, Objective Time, Assists, or MVP count
• Animated GIFs - Toggle between static images and animated GIFs with glowing avatar effects
• Tier System - Organize players into custom tiers based on point thresholds
• Pagination - Navigate through large leaderboards with easy-to-use controls

🎮 Match Recording

• AI-Powered OCR - Automatic scoreboard recognition using Tesseract or Google Cloud Vision
• Manual Tagging - Tag players manually when automatic recognition needs assistance
• Match History - Complete history of all matches with detailed statistics
• Point System - Customizable points allocation based on performance

🎨 Visual Effects

• Glowing Avatars - Top 3 players get animated glowing effects in GIF mode
  • 🥇 Gold glow for 1st place
  • 🥈 Silver glow for 2nd place
  • 🥉 Bronze glow for 3rd place
• Profile Cards - Beautiful player profile cards with stats and achievements
• Custom Backgrounds - Support for default, URL, or uploaded leaderboard backgrounds

👥 Player Management

• IGN Linking - Link Discord accounts to in-game names
• Auto-Detection - Automatically match Discord users to game statistics
• Profile Commands - View detailed player statistics and rankings

🔧 Admin Controls

• Channel Configuration - Set results and log channels via commands
• Tier Role Management - Automatic Discord role assignment based on performance
• OCR Provider Selection - Choose between Tesseract and Google Cloud Vision
• Auto-Record Toggle - Enable/disable automatic match recording

🚀 Quick Start

Prerequisites

• Node.js 18+
• Discord Bot Token (Create one here)
• (Optional) Google Cloud Vision API credentials for enhanced OCR

Installation

1. Clone the repository

   git clone <repository-url>
   cd ptbp

2. Install dependencies

   npm install

3. Configure environment variables

   cp .env.example .env

   Edit .env and add your credentials:

   DISCORD_TOKEN=your_discord_bot_token
   BOT_CLIENT_ID=your_bot_client_id

4. Start the bot

   npm start

📝 Configuration

Environment Variables

Variable	Required	Description
DISCORD_TOKEN	✅	Your Discord bot token
BOT_CLIENT_ID	✅	Your bot's client ID
LOG_CHANNEL_ID	❌	Channel for logging invalid scoreboards
RESULTS_CHANNEL_ID	❌	Channel for posting results
GOOGLE_APPLICATION_CREDENTIALS	❌	Path to Google Cloud credentials
GROQ_API_KEY	❌	Groq API key for AI features
UPDATE_INTERVAL_SECONDS	❌	Leaderboard update interval (default: 60)

Discord Commands

User Commands

• /leaderboard [sort_by] - View the current leaderboard
• /setign <ign> - Link your Discord account to an in-game name
• /profile [@user] - View player profile and statistics

Admin Commands

• /setresults <channel> - Set the results channel
• /setlog <channel> - Set the log channel
• /setmanager <role> - Set the manager role
• /settierroles - Configure tier roles and point requirements
• /setocr <provider> - Choose OCR provider (tesseract/google)
• /toggleanimation <mode> - Toggle between static/animated leaderboards
• /toggleautorecord - Enable/disable auto-recording

🎯 How It Works

1. Scoreboard Upload - Users post game scoreboard screenshots in the designated channel
2. AI Recognition - The bot uses OCR to extract player names and statistics
3. Point Allocation - Points are automatically calculated and distributed
4. Leaderboard Update - Rankings update in real-time
5. Role Assignment - Players automatically receive tier roles based on performance

🖼️ Leaderboard Modes

Static Mode

Clean, crisp PNG images with:

• Player avatars with rank-colored frames
• Tier group headers
• Detailed statistics
• Pagination controls

Animated Mode

Engaging GIF animations featuring:

• ✨ Pulsing glow effects on top 3 avatars
• 🎨 Color-coded glows (Gold, Silver, Bronze)
• 🔄 Smooth animation loop
• All features from static mode

📊 Tier System

Configure up to 5 tiers with custom:

• Role assignments
• Point thresholds
• Custom colors for visual grouping

Players automatically receive roles and are grouped in the leaderboard based on their points.

🔄 Deployment

Production Build

npm run build
npm run start:prod

24/7 Uptime

The bot includes a health endpoint for monitoring services like UptimeRobot:

https://your-domain.com/health

Procfile (for Heroku/Railway)

web: npm run start:prod

🛠️ Technology Stack

• Runtime: Node.js with TypeScript
• Framework: NestJS
• Discord Library: discord.js v14
• OCR: Tesseract.js / Google Cloud Vision
• Image Processing: node-canvas
• Animation: gifencoder
• AI: Groq SDK (optional)

📈 Statistics Tracked

• Points - Total points earned
• Kills - Total eliminations
• Deaths - Times eliminated
• K/D Ratio - Kill/Death ratio
• Assists - Team assists
• Objective Time - Time on objective
• MVP - MVP awards count

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

📄 License

This project is open source and available under the MIT License.

🆘 Support

For issues, questions, or suggestions:

1. Check the documentation
2. Review existing issues
3. Create a new issue with detailed information

🎉 Acknowledgments

Built with ❤️ for gaming communities who want professional leaderboard tracking.

---

Made with NestJS and Discord.js | Powered by AI | Built for Gamers