GHBot - Discord Sound Effects Bot

A modern Discord bot built with Discord.js v14 that provides sound effects, text commands, fun facts, and scheduled events for Discord servers.

✨ Features

🔊 Sound Effects

• Prefix commands: !sfx <sound> - Classic text-based commands
• Slash commands: /sfx with autocomplete - Modern Discord UI with searchable sound effects
• Automatic sound discovery from the sfx/ directory
• Configurable volume and channel restrictions per guild

💬 Text Commands

• Fun Facts: Random or specific fact retrieval (!funfact [number])
• Ham Facts: Ham-related facts (!hamfact [number])
• Static Commands: Custom text responses loaded from configuration files
• Ankhbot Import: Support for imported Ankhbot command databases

🎭 Interactive Features

• Role Management: Self-service role assignment (!role add/remove <role>)
• Dance Command: ASCII art dance animation
• Voice Controls: Join/leave voice channels (!join, !leave)

⏰ Scheduling

• Scheduled Events: Cron-based message scheduling with role pings
• Activity Rotation: Automatic bot status updates

🛠️ Admin Features

• Dynamic Configuration: SQLite database for persistent, per-server settings
• Auto-Registration: New guilds automatically configured when bot is added
• Live Configuration: /config slash commands for real-time settings updates
• Soft Delete: Guild settings preserved when bot is temporarily removed
• Hot Reload: Configuration files update without restart
• Admin Commands: Bot management and restart capabilities
• Blacklist System: Block specific users from using commands

🚀 Quick Start

Prerequisites

• Node.js 20 LTS (for Docker) or 22+ LTS (for local development)
• pnpm package manager
• Discord Bot Token (see Discord Setup section below)

Installation

1. Clone the repository

   git clone https://github.com/greenham/ghbot.git
   cd ghbot
   

2. Install dependencies

   pnpm install
   

3. Configure the bot

   cp config.example.json config.json
   # Edit config.json with your bot token and existing guild settings (optional)
   

   Note: The bot uses a SQLite database for guild configurations. If you have existing guilds in config.json, they will be automatically imported to the database on first run. For new deployments, guilds are auto-registered when the bot is added to servers.

4. Set up Discord Bot (see Discord Setup section below)

5. Run the bot

   # Development mode with auto-reload (local Node.js)
   pnpm dev
   
   # Production mode with Docker Compose
   pnpm start
   
   # Production mode with local Node.js
   pnpm start:prod
   

🐳 Docker Deployment

Recommended: Docker Compose

# Start the bot with Docker Compose
pnpm start

# View logs
pnpm logs

# Restart the bot (useful after config changes)
pnpm restart

# Stop the bot
pnpm stop

# Quick rebuild and restart (after code changes)
pnpm boom

# Manual build and start
pnpm build && pnpm start

Benefits of Docker Compose:

• Update config.json, sfx/, and conf/ files without rebuilding the image
• SQLite database persistence via mounted ./data volume
• Automatic restart on failure
• Easy log management
• Resource limits and health checks

Alternative: Direct Docker

# Build the Docker image
pnpm image:build

# Run the container
pnpm image:run

📖 Usage

Sound Effects

Prefix Command:

!sfx albert          # Play 'albert' sound effect
!sfx                 # List all available sounds

Slash Command:

/sfx sound: albert   # Play with autocomplete suggestions

Text Commands

!funfact             # Random fun fact
!funfact 42          # Specific fun fact #42
!hamfact             # Random ham fact
!dance               # ASCII dance animation

Role Management

!role add streamer   # Add the 'streamer' role
!role remove vip     # Remove the 'vip' role

Voice Commands

!join                # Join your voice channel
!leave               # Leave current voice channel

Configuration Management

Dynamic Configuration (Administrator only):

/config show         # View current server settings
/config prefix !     # Set command prefix
/config sfx true     # Enable/disable sound effects
/config volume 0.8   # Set SFX volume (0.1-1.0)
/config funfacts true # Enable/disable fun facts
/config hamfacts true # Enable/disable ham facts
/config sfxchannels general|music # Set allowed SFX channels (regex)
/config roles streamer|vip|member # Set self-assignable roles

🔧 Discord Setup

Creating a Discord Bot

1. Go to Discord Developer Portal

   • Visit https://discord.com/developers/applications
   • Click "New Application" and give it a name

2. Create Bot User

   • Go to the "Bot" section
   • Click "Add Bot"
   • Copy the bot token for your config.json

3. Enable Required Intents Under "Privileged Gateway Intents", enable:

   • SERVER MEMBERS INTENT (Required for role management)
   • MESSAGE CONTENT INTENT (Required for prefix commands)

4. Bot Permissions When inviting the bot, ensure it has these permissions:

   • Send Messages
   • Embed Links
   • Read Message History
   • Connect (for voice channels)
   • Speak (for voice channels)
   • Use Voice Activity
   • Manage Roles (if using role commands)

5. Invite Bot to Server

   • Go to "OAuth2 > URL Generator"
   • Select "bot" and "applications.commands" scopes
   • Select the permissions listed above
   • Use the generated URL to invite your bot

⚙️ Configuration

Database-Driven Configuration

The bot uses SQLite database for persistent guild configurations. Configuration can be managed in three ways:

1. Automatic Registration (Recommended for Public Bot)

When the bot is added to a new server, it automatically:

• Creates default configuration with sensible settings
• Sends a welcome message explaining features
• Registers slash commands for the server

2. Live Configuration via Slash Commands

Administrators can use /config commands to modify settings in real-time:

• /config show - View current server settings
• /config prefix <prefix> - Change command prefix
• /config sfx <true/false> - Enable/disable sound effects
• And more (see Configuration Management section above)

3. Seed Data from config.json (Optional)

For initial deployment or migrating existing servers, create config.json:

{
  "botName": "YourBot",
  "debug": false,
  "discord": {
    "token": "YOUR_BOT_TOKEN",
    "adminUserId": "YOUR_DISCORD_USER_ID",
    "guilds": [
      {
        "id": "GUILD_ID",
        "internalName": "My Server",
        "prefix": "!",
        "enableSfx": true,
        "sfxVolume": 0.5,
        "enableFunFacts": true,
        "enableHamFacts": true,
        "scheduledEvents": [
          {
            "id": "daily-reminder",
            "schedule": {
              "hour": 7,
              "minute": 30,
              "tz": "America/Los_Angeles"
            },
            "channelId": "CHANNEL_ID",
            "message": "Good morning!",
            "pingRoleId": "ROLE_ID"
          }
        ]
      }
    ],
    "activities": ["Playing sounds", "Serving facts"],
    "blacklistedUsers": []
  }
}

Migration Process: On first startup with an empty database, the bot will automatically import all guilds and settings from config.json into the database. After migration, the database becomes the primary configuration source.

Sound Effects Setup

1. Add .mp3 or .wav files to the sfx/ directory
2. Files are automatically discovered (filename becomes command name)
3. Sounds appear in slash command autocomplete

Static Commands

Edit conf/text_commands with pipe-separated commands:

hello|Hello there!
wiki,wikipedia|https://wikipedia.org
help,commands|Available commands: !sfx, !funfact, !hamfact

Scheduled Events (Advanced)

For config.json seeding only - Scheduled events are stored in the database:

"scheduledEvents": [
  {
    "id": "daily-greeting",
    "schedule": {
      "hour": 9,
      "minute": 0,
      "tz": "America/New_York"
    },
    "channelId": "CHANNEL_ID",
    "message": "Good morning everyone!",
    "pingRoleId": "ROLE_ID"
  },
  {
    "id": "weekly-reminder",
    "schedule": "0 10 * * 1",
    "channelId": "CHANNEL_ID",
    "message": "Happy Monday!"
  }
]

Schedule Formats Supported:

• Object format: {"hour": 9, "minute": 30, "tz": "America/Los_Angeles"} (with timezone)
• Cron format: "0 9 * * *" (standard cron expression)

🏗️ Architecture

src/
├── index.js                 # Main bot entry point
├── config/
│   ├── config.js            # Hybrid configuration manager (database + file)
│   └── intents.js          # Discord gateway intents
├── commands/
│   ├── prefix/             # Traditional prefix commands (!sfx, !funfact, etc.)
│   └── slash/              # Modern slash commands (/sfx, /config)
├── services/
│   ├── databaseService.js  # SQLite database operations
│   ├── voiceService.js     # Voice connection management
│   ├── commandLoader.js    # Static/Ankhbot command loader
│   ├── sfxManager.js       # Sound effect file management
│   └── schedulerService.js # Scheduled events handler
└── utils/
    └── helpers.js          # Utility functions

data/
└── ghbot.db                # SQLite database (auto-created)

🧪 Development

Running in Development Mode

pnpm dev  # Uses nodemon for auto-reload

Adding New Commands

Prefix Command Example:

// src/commands/prefix/hello.js
module.exports = {
  name: "hello",
  description: "Say hello",

  async execute(message, args, guildConfig) {
    await message.channel.send("Hello there!");
  },
};

Slash Command Example:

// src/commands/slash/ping.js
const { SlashCommandBuilder } = require("discord.js");

module.exports = {
  data: new SlashCommandBuilder()
    .setName("ping")
    .setDescription("Replies with Pong!"),

  async execute(interaction, guildConfig) {
    await interaction.reply("Pong!");
  },
};

📊 System Requirements

• Node.js: 20 LTS (Docker) or 22+ LTS (local development)
• Memory: 256MB+ RAM
• Storage: 500MB+ (depending on sound effects and database)
• Network: Stable internet connection for Discord API
• Database: SQLite (auto-created, no external database required)

🔧 Troubleshooting

Common Issues

"Used disallowed intents" Error

• Enable required intents in Discord Developer Portal (see Discord Setup section above)
• Ensure SERVER MEMBERS INTENT and MESSAGE CONTENT INTENT are enabled

Voice/Audio Issues

• Ensure ffmpeg is installed (handled automatically in Docker)
• Check bot has Connect and Speak permissions
• Verify voice channel isn't full or restricted

Slash Commands Not Appearing

• Commands register on bot startup
• May take up to 1 hour to appear globally
• Try restarting the bot

Permission Errors

• Ensure bot has necessary permissions in channels
• Check role hierarchy (bot role should be above managed roles)

Debug Mode

Enable debug logging in config.json:

{
  "debug": true
}

🤝 Contributing

1. Fork the repository
2. Create a feature branch: git checkout -b feature/amazing-feature
3. Commit changes: git commit -m 'Add amazing feature'
4. Push to branch: git push origin feature/amazing-feature
5. Open a Pull Request

📄 License

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

🙏 Acknowledgments

• Built with Discord.js v14
• Audio processing via @discordjs/voice
• Inspired by the original AnkhBot command system
• Special thanks to the Discord.js community

📞 Support

• Create an Issue for bug reports
• Check the Discord Setup section above for configuration help
• Review CLAUDE.md for development guidance

---

Made with ❤️ for Discord communities