vclogbot

A Discord bot for tracking and rewarding voice channel activity with a leveling system, join/leave messages, and interactive stats commands.

---

Table of Contents

• Features
• Getting Started
• Usage
• Configuration
• Running as a Service (systemd)
• Docker
• Customization
  • Commands
  • Events
  • Locales
• Testing
• Support
• License

Features

• Voice Channel Leveling System: Tracks user time spent in voice channels and awards levels based on total time.
• Join/Leave Messages: Announces when users join or leave voice channels, including late joins (e.g., after bot restarts or mute/unmute events).
• /stats Command: Shows your current level, total voice time, and progress to the next level.
• /leaderboard Command: Displays the top users in your server by voice channel activity.
• Automatic Session Recovery: Handles missed join events and bot restarts, ensuring accurate tracking.
• Locale Support: Easily add or edit language files in locales/.
• Logging: Detailed debug and error logs for troubleshooting.
• Systemd & Docker Ready: Templates and instructions for production deployment.
• Jest for testing

---

Getting Started

1. Clone this project:

   git clone https://github.com/purinton/vclogbot.git
   cd vclogbot
   npm install

2. Set up your environment:

   • Copy .env.example to .env and fill in your Discord app token and other secrets.
   • Edit package.json (name, description, author, etc.)
   • Update this README.md as needed.

3. Start the app locally:

   npm start
   # or
   node vclogbot.mjs

Usage

Voice Channel Leveling

• Users earn experience by being in voice channels.
• Levels are calculated using a triangular formula (each level requires more time).
• Level-up messages are sent in the channel when a user advances.

Join/Leave Messages

• The bot announces when users join or leave a voice channel.
• If the bot was offline or missed a join event, it will detect the user on the next relevant event (e.g., mute/unmute) and start tracking.

Slash-Commands

• /stats — Shows your current level, total time, and progress.
• /leaderboard — Shows the top users by voice time in the server.

Configuration

• All configuration is handled via environment variables in the .env file.
• See .env.example for required and optional variables.

Running as a Service (systemd)

1. Copy vclogbot.service to /usr/lib/systemd/system/vclogbot.service.

2. Edit the paths and user/group as needed.

3. Reload systemd and start the service:

   sudo systemctl daemon-reload
   sudo systemctl enable vclogbot
   sudo systemctl start vclogbot
   sudo systemctl status vclogbot

Docker

1. Build the Docker image:

   docker build -t vclogbot .

2. Run the container:

   docker run --env-file .env vclogbot

Customization

Commands

• Add new commands in the commands/ directory.
• Each command has a .json definition (for Discord registration/localization) and a .mjs handler (for logic).

Events

• Add or modify event handlers in the events/ directory.
• Each Discord event (e.g., ready, messageCreate, interactionCreate, voiceStateUpdate) has its own handler file.

Locales

• Add or update language files in the locales/ directory.
• Localize command names, descriptions, and app responses.

Testing

• Run tests with:

  npm test

• Add your tests in the tests/ folder or alongside your code.

Folder Structure

src/           # Core logic and utilities
commands/      # Slash command definitions and handlers
events/        # Event handlers (voice, message, etc.)
locales/       # Locale JSON files
*.mjs          # Main entry and supporting modules

Best Practices

• Keep your app token secret! Never commit your .env file or token to version control.
• Use a dedicated, non-root user for running your app in production.
• Monitor logs for errors or unusual activity.
• Check Discord.js documentation for new features: https://discord.js.org/

Support

For help, questions, or to chat with the author and community, visit:

Purinton Dev on Discord

License

MIT © 2025 Russell Purinton

Links

• GitHub Repo
• GitHub Org
• GitHub Personal
• Discord