Roster Control Discord Bot

A Discord bot with unified whitelist management for Squad game servers, featuring automatic Discord role-based access control, Steam account linking, and comprehensive admin tools.

Overview

Roster Control features a unified whitelist system that automatically synchronizes Discord roles with Squad server access. Users with designated Discord roles are automatically granted whitelist access, while administrators can also manually manage individual entries. The system integrates with MariaDB for persistent storage, BattleMetrics API for server/player data, and SquadJS for real-time player events and secure Steam account linking.

Features

Core Features

• Unified Whitelist System: Automatic Discord role-based Squad server access with database-driven management
• Role-Based Access Control: Discord roles automatically grant/revoke Squad server whitelist access
• Steam Account Linking: Secure in-game verification system for Steam-Discord account connections
• On-Duty Admin Management: Manual /onduty and /offduty commands with automated triggers
• Manual Whitelist Management: Add/remove specific players with /whitelist commands
• Real-Time Monitoring: Track player join/leave events via SquadJS integration
• Audit Logging: Complete audit trail of all roster and admin actions
• Confidence-Based Security: Staff roles require high-confidence Steam account links

Planned Features

• RCON Integration: Automated kicks/bans for roster violations
• Automated Reporting: Daily/weekly activity summaries
• Multi-Server Support: Manage multiple Squad servers
• Custom Notifications: Alert admins of specific events

Technology Stack

• Node.js with Discord.js v14
• MariaDB with Sequelize ORM
• SquadJS for Squad server integration
• BattleMetrics API for player data
• Winston for logging
• Umzug for database migrations

Installation

Prerequisites

• Node.js 18+
• MariaDB server
• Discord Bot Token
• BattleMetrics API Token
• Squad server with RCON access

Setup

1. Clone and Install

   git clone <repository-url>
   cd roster-control
   npm install

2. Environment Configuration

   Copy the example environment file and update it with your settings:

   cp .env.example .env
   # Edit .env with your settings

3. Database Setup

   Option A: Quick Setup (Single Command)

   # Create database with default settings
   mysql -u root -p -e "CREATE DATABASE roster_control CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;"

   Option B: Secure Setup (Recommended)

   Connect to MariaDB and run these commands:

   -- Connect to MariaDB as root
   mysql -u root -p
   
   -- Create the database with proper character encoding
   CREATE DATABASE roster_control CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
   
   -- Create a dedicated user for the application
   CREATE USER 'roster_user'@'localhost' IDENTIFIED BY 'your_secure_password_here';
   
   -- Grant privileges to the user
   GRANT ALL PRIVILEGES ON roster_control.* TO 'roster_user'@'localhost';
   
   -- Apply privileges
   FLUSH PRIVILEGES;
   
   -- Verify setup
   SHOW DATABASES;
   USE roster_control;
   SELECT @@character_set_database, @@collation_database;
   EXIT;

   Update your .env file with the database credentials:

   DB_HOST=localhost
   DB_PORT=3306
   DB_NAME=roster_control
   DB_USER=roster_user  # or 'root' if using Option A
   DB_PASSWORD=your_secure_password_here

   Test Database Connection:

   npm run test:db

   Run migrations (happens automatically on startup):

   npm start

4. Discord Bot Setup

   • Create application at https://discord.com/developers/applications
   • Create bot and copy token to .env
   • Invite bot to server with appropriate permissions:
     • Send Messages
     • Use Slash Commands
     • Embed Links
     • Read Message History

Usage

Commands

Admin Management

• /onduty <admin_id> - Designate admin as on-duty
• /offduty <admin_id> - Remove admin from on-duty status

Roster Management

• /whitelist add <player_id> type:<source> - Add player to whitelist
• /whitelist remove <player_id> - Remove player from whitelist
• /whitelist list - Display current roster

Player Activity

• /activity <player_id> - Show player's recent activity

Utility

• /ping - Test bot connectivity
• /help - Show available commands

Permissions

Commands are restricted based on roles and on-duty status:

• Whitelist commands: Require on-duty admin status
• Admin commands: Require admin role
• General commands: Available to all users

Database Schema

Tables

• Players: Player ID, Username, Roster Status, Activity History
• Admins: Admin ID, On-Duty Status, Duty History
• Servers: Server ID, Name, Connection Details
• AuditLog: Action tracking with timestamps and details

Migrations

Database schema is managed through Umzug migrations that run automatically on startup. Migration files are located in /migrations/.

Deployment

Pterodactyl Panel

1. Create new Node.js application
2. Upload project files
3. Configure .env file
4. Set startup command: npm start
5. Allocate sufficient memory (recommended: 512MB+)

Manual Deployment

# Production start
npm run start

# Development with auto-restart
npm run dev

# Development with debugger
npm run dev:debug

# Deploy commands to development servers
npm run deploy:commands:dev

# Deploy commands to production servers
npm run deploy:commands:prod

Logging

Winston logging is configured with multiple levels:

• Error: Critical errors and exceptions
• Warn: Non-critical issues
• Info: General application flow
• Debug: Detailed debugging information

Logs are written to both console and file (logs/combined.log).

Monitoring

Health Checks

• Database connection status
• Discord bot connectivity
• SquadJS connection status
• BattleMetrics API availability

Performance Metrics

• Command response times
• Database query performance
• Memory usage
• Event processing rates

Troubleshooting

Common Issues

Bot not responding to commands

• Verify Discord token and permissions
• Check bot is online in Discord
• Ensure slash commands are registered

Database connection errors

• Verify MariaDB is running
• Check connection credentials in .env
• Ensure database exists and user has permissions

SquadJS connection issues

• Verify Squad server RCON settings
• Check firewall rules for RCON port
• Confirm RCON password is correct

BattleMetrics API errors

• Verify API token is valid
• Check rate limiting (max 60 requests/minute)
• Ensure server ID is correct

Logs Location

• Application logs: logs/combined.log
• Error logs: logs/error.log
• Database logs: Check MariaDB error log

Development

Project Structure

roster-control/
├── commands/          # Discord slash commands
├── events/            # Discord bot events
├── models/            # Sequelize database models
├── migrations/        # Database migration files
├── utils/             # Utility functions
├── logs/              # Log files
├── config/            # Configuration files
└── index.js           # Main application entry

Adding Commands

1. Create command file in /commands/
2. Follow existing command structure
3. Register command in command handler
4. Test with /ping equivalent

Database Changes

1. Create migration file in /migrations/
2. Update corresponding Sequelize model
3. Test migration up/down functionality
4. Document schema changes

Security Considerations

• Environment Variables: Store sensitive data in .env (gitignored)
• Database Access: Use dedicated database user with minimal permissions
• API Tokens: Regularly rotate BattleMetrics and Discord tokens
• RCON Security: Restrict RCON access to trusted IPs only

Support

For issues or questions:

1. Check logs for error details
2. Verify configuration settings
3. Test individual components (database, Discord, SquadJS)
4. Review recent changes in audit log

License

Internal use only - not for public distribution.