Bot Documentation

Overview and Purpose

The Discord Team Auto-Balance Bot is a sophisticated Discord bot designed to manage team balancing in gaming communities and servers. The bot automates team assignment, provides spectator functionality, and includes comprehensive administrative tools for server management.

Key Features

Automatic Team Balancing: Randomly distributes members between Green and Red teams
Spectator Mode: Allows users to temporarily step away from team activities
Admin Controls: Complete user management including kick/ban functionality
Real-time Statistics: Live team distribution and server information
DM Notifications: Automatic notifications for team changes and assignments
Rate Limiting: Built-in protections against Discord API rate limits

Setup and Installation Requirements

Prerequisites

Node.js: Version 16.0 or higher
Discord Bot Token: Create a bot application at https://discord.com/developers/applications
Discord Server: Administrative access to configure roles

Discord Bot Configuration

Navigate to your bot's settings in the Discord Developer Portal and ensure the following Bot Permissions are enabled:

Send Messages
Use Slash Commands
Embed Links
Attach Files
Read Message History
Add Reactions
Manage Roles
Kick Members
Ban Members
Manage Messages

Required Discord Intents

The bot requires these Gateway Intents to function properly:

Server Members Intent
Message Content Intent

Server Role Setup

Use the stepper below to create the required roles and their basic settings.

Green Team Role 🟢

Role name: Green Team (or custom name)
Color: Green
No special permissions required

Red Team Role 🔴

Role name: Red Team (or custom name)
Color: Red
No special permissions required

Spectator Role 👁️

Role name: Spectator (or custom name)
Color: Gray
No special permissions required

Admin Role(s) 👑

One or more roles with administrative privileges
These roles will have access to admin commands

Environment Configuration

Create a .env file in the project root with the following variables:

# Required: Discord Bot Token
DISCORD_TOKEN=your_bot_token_here

# Required: Discord Server (Guild) ID
GUILD_ID=your_server_id_here

# Required: Role IDs for team management
GREEN_ROLE_ID=your_green_role_id_here
RED_ROLE_ID=your_red_role_id_here
SPECTATOR_ROLE_ID=your_spectator_role_id_here

# Required: Admin role IDs (comma-separated for multiple roles)
ADMIN_ROLE_IDS=admin_role_id1,admin_role_id2

# Optional: Command prefix (defaults to 'buck.')
COMMAND_PREFIX=buck.

Installation Steps

Follow these steps to install and start the bot.

Clone or download the bot files to your server

Install dependencies:

Run:

Install dependencies

npm install

Configure environment variables in .env file

Invite the bot to your Discord server with appropriate permissions

Start the bot:

Start bot

node bot.js

Configuration Requirements

Environment Variables

Variable

Required

Description

Example

DISCORD_TOKEN

✅

Discord bot authentication token

MTI0Nj...

GUILD_ID

✅

Target Discord server ID

123456789012345678

GREEN_ROLE_ID

✅

Green team role ID

987654321098765432

RED_ROLE_ID

✅

Red team role ID

987654321098765433

SPECTATOR_ROLE_ID

✅

Spectator role ID

987654321098765434

ADMIN_ROLE_IDS

✅

Comma-separated admin role IDs

111111111,222222222

COMMAND_PREFIX

❌

Command prefix for bot

buck.

Role Hierarchy Requirements

Admin roles must be above the team roles in the role hierarchy
Team roles should be above the spectator role if you want proper permissions
The bot's role must be above all team roles to manage them effectively

Complete Command Reference

Command Prefix

All commands use the prefix defined in COMMAND_PREFIX (defaults to buck.).

👑 Admin Commands

🔄 autobalance

Description: Rebalances existing teams by redistributing current team members randomly.

Usage: buck.autobalance

Parameters: None

Permissions: Admin role required

Example:

buck.autobalance

Response: Redistributes all current team members between Green and Red teams randomly.

Notes:

Preserves existing team assignments but rebalances distribution
Sends DM notifications to affected users
Shows processing status and final results

🗑️ reset / clear

Description: Completely resets all team assignments and rebalances everyone from scratch.

Usage: buck.reset or buck.clear

Aliases: clear (interchangeable)

Parameters: None

Permissions: Admin role required

Example:

buck.reset

Response:

Removes all team roles from existing members
Reassigns everyone to new random teams
Sends DM notifications to all users

Notes:

More comprehensive than autobalance
Useful for complete fresh starts
Takes longer to process due to complete reset

🔄 swap

Description: Swaps a specific user's team with a random user from the opposite team.

Usage: buck.swap @username or buck.swap <user_id>

Parameters:

<user> (required): User mention or user ID to swap

Permissions: Admin role required

Example:

buck.swap @JohnDoe

Response: Swaps JohnDoe's team with a random user from the opposite team and sends DM notifications to both users.

Notes:

User must already be on a team (Green or Red)
Cannot swap bot users
Both users receive detailed DM notifications about the swap

👢 kick [reason]

Description: Kicks a user from the Discord server.

Usage: buck.kick @username [reason] or buck.kick <user_id> [reason]

Parameters:

<user> (required): User mention or user ID to kick
[reason] (optional): Reason for the kick

Permissions: Admin role required

Example:

buck.kick @Troublemaker Breaking server rules

Response: Kicks the user and shows confirmation with reason.

Notes:

Cannot kick bot users
Cannot kick yourself
Respects Discord role hierarchy
Reason is optional but recommended for moderation logs

🔨 ban [reason] [delete_days]

Description: Bans a user from the Discord server with optional message deletion.

Usage: buck.ban @username [reason] [delete_days] or buck.ban <user_id> [reason] [delete_days]

Parameters:

<user> (required): User mention or user ID to ban
[reason] (optional): Reason for the ban
[delete_days] (optional): Number of days of messages to delete (0-7)

Permissions: Admin role required

Example:

buck.ban @Spammer Severe spam violation 7

Response: Bans the user, deletes 7 days of their messages, and shows confirmation.

Notes:

Cannot ban bot users
Cannot ban yourself
Respects Discord role hierarchy
Delete days must be between 0-7 (Discord limitation)
If delete_days not specified, defaults to 0

📊 Public Commands

❓ commands / help

Description: Displays comprehensive help message with all available commands.

Usage: buck.commands or buck.help

Parameters: None

Permissions: None (available to all users)

Example:

buck.commands

Response: Shows organized help embed with admin commands, public commands, and usage tips.

📈 teamcount / teams / status

Description: Shows current team distribution and balance statistics.

Usage: buck.teamcount, buck.teams, or buck.status

Parameters: None

Permissions: None (available to all users)

Example:

buck.teamcount

Response: Shows embed with:

Current member counts for each team
Unassigned member count
Balance ratio and difference
Balance status indicator (Perfectly Balanced/Well Balanced/Slightly Unbalanced/Unbalanced)

Notes:

Updates in real-time
Color-coded balance status
Helpful for admins to determine if balancing is needed

👁️ spectate

Description: Enter spectator mode by removing team roles and adding spectator role.

Usage: buck.spectate

Parameters: None

Permissions: None (available to all users)

Example:

buck.spectate

Response:

Removes any existing team roles
Adds spectator role
Sends DM confirmation
Shows public confirmation message

Notes:

Stores user's previous team for easy return
Can receive DM notifications even in spectator mode
Useful for taking breaks from team activities

🟢 unspectate

Description: Leave spectator mode and return to team activities.

Usage: buck.unspectate

Parameters: None

Permissions: None (available to all users)

Example:

buck.unspectate

Response:

Removes spectator role
Returns user to their previous team (if stored)
Auto-assigns to smaller team if no previous team stored
Sends DM confirmation with team assignment

Notes:

Automatically balances team sizes when auto-assigning
Preserves user's previous team preference when possible

👤 userinfo / user

Description: Displays detailed information about a specific user.

Usage: buck.userinfo @username, buck.userinfo <user_id>, buck.user @username, or buck.user <user_id>

Parameters:

<user> (required): User mention or user ID to look up

Permissions: None (available to all users)

Example:

buck.userinfo @JaneDoe

Response: Shows detailed embed with:

Username and ID
Account creation date and server join date
Current team status (Green Team/Red Team/Spectating/Not on team)
Bot status
DM settings
Roles list

Notes:

Defaults to command author if no user specified
Shows account age in days
Displays role hierarchy (highest first)

🏢 serverinfo / server

Description: Displays comprehensive server statistics and information.

Usage: buck.serverinfo or buck.server

Parameters: None

Permissions: None (available to all users)

Example:

buck.serverinfo

Response: Shows detailed embed with:

Server name and ID
Owner information
Creation date and age
Member statistics (total, humans, bots)
Team distribution breakdown
Channel counts (text, voice, categories)
Role count
Boost level and count
Server features

Bot Features and Capabilities

Core Features

Team Management
- Automatic random team assignment
- Team balance monitoring and reporting
- Support for three states: Green Team, Red Team, Spectator
User Experience
- Rich embed responses for better readability
- DM notifications for team changes
- Real-time status updates
- Intuitive command structure
Administrative Tools
- Complete user moderation (kick/ban)
- Team manipulation (swap individual users)
- Bulk team operations (autobalance/reset)
- Comprehensive user and server information
Performance & Reliability
- Built-in rate limiting to respect Discord API limits
- Graceful error handling with user-friendly messages
- Comprehensive logging for debugging
- Graceful shutdown handling

Technical Capabilities

Language: Node.js with discord.js library
Memory Management: Efficient role caching and member management
Rate Limiting: Automatic delays to prevent API abuse
Error Recovery: Continues operation after individual failures
Cross-Platform: Runs on Windows, macOS, and Linux

Permission Requirements

Admin Role Verification

Admin Role Check: isAdmin(member) function validates permissions
Role Hierarchy: Respects Discord's role hierarchy system
Multiple Admin Roles: Supports comma-separated list of admin role IDs

Protected Commands

The following commands require admin permissions:

autobalance
reset / clear
swap
kick
ban

Role Hierarchy Requirements

Bot Role: Must be higher than team roles in hierarchy
Admin Roles: Must be higher than bot role for full control
Team Roles: Should be manageable by bot role

Error Handling and Limitations

Error Handling Features

Comprehensive Try-Catch Blocks
- All major operations wrapped in error handling
- Graceful degradation on individual failures
Discord-Specific Error Codes
- Handles Discord API error codes (e.g., 50007 for DM failures)
- Provides appropriate responses for different error types
User-Friendly Error Messages
- Clear error descriptions for users
- Detailed console logging for administrators
- Contextual error information
Rate Limit Management
- Automatic delays between operations (1 second per 5 operations)
- Prevents hitting Discord API rate limits
- Continues operation after rate limit delays

Current Limitations

Single Server Operation
- Bot only operates in the configured guild (server)
- Cannot manage multiple servers simultaneously
Team Count Limitation
- Designed for two-team systems (Green vs Red)
- Does not support additional teams
Member Fetching Requirements
- Must fetch complete member list for accurate balancing
- Large servers may experience delays during initial fetch
DM Limitations
- Users with DMs disabled cannot receive notifications
- Error code 50007 handled gracefully but no fallback notification
Role Management Constraints
- Cannot create roles (must be pre-created by server admin)
- Requires proper role hierarchy for full functionality

Performance Considerations

Memory Usage: Caches guild members and roles for performance
API Rate Limits: Implements delays to stay within Discord limits
Processing Time: Large servers may take time to process bulk operations
Concurrent Operations: Handles one operation at a time to prevent conflicts

Troubleshooting and FAQ

Common Issues

Q: Bot doesn't respond to commands

Check if bot is online (should show "Bot is online as...")
Verify command prefix in .env file
Ensure bot has been invited to server with proper permissions
Check that commands are being sent in the correct server

Q: "You don't have permission" error

Verify your role is included in ADMIN_ROLE_IDS
Check role hierarchy (admin role must be above bot role)
Ensure role IDs in .env are correct

Q: Team balancing not working

Check that team role IDs in .env are correct
Verify bot role is above team roles in hierarchy
Ensure server has members to balance

Q: DM notifications not received

Check if user has DMs disabled in Discord privacy settings
Bot handles this gracefully but cannot send notifications
Error will show in console logs

Q: Role assignment fails

Verify bot has "Manage Roles" permission
Check role hierarchy is set correctly
Ensure team roles exist in server

Debug Information

The bot provides extensive console logging for troubleshooting:

Bot startup and connection status
Command execution and results
Error details with context
Member fetching progress
DM delivery status

Support

For additional support or bug reports:

Check console logs for detailed error information
Verify all environment variables are set correctly
Ensure Discord permissions are properly configured
Test with a small server first for configuration validation

This documentation was generated based on analysis of the bot.js source code and covers all implemented features and functionality.

Good evening

Overview and Purpose

Key Features

Setup and Installation Requirements

Prerequisites

Discord Bot Configuration

Required Discord Intents

Server Role Setup

Green Team Role 🟢

Red Team Role 🔴

Spectator Role 👁️

Admin Role(s) 👑

Environment Configuration

Installation Steps

Configuration Requirements

Environment Variables

Role Hierarchy Requirements

Complete Command Reference

Command Prefix

👑 Admin Commands

🔄 autobalance

🗑️ reset / clear

🔄 swap

👢 kick [reason]

🔨 ban [reason] [delete_days]

📊 Public Commands

❓ commands / help

📈 teamcount / teams / status

👁️ spectate

🟢 unspectate

👤 userinfo / user

🏢 serverinfo / server

Bot Features and Capabilities

Core Features

Technical Capabilities

Permission Requirements

Admin Role Verification

Protected Commands

Role Hierarchy Requirements

Error Handling and Limitations

Error Handling Features

Current Limitations

Performance Considerations

Troubleshooting and FAQ

Common Issues

Debug Information

Support