🔥 Hybcord v3.0 - The Complete Discord Bot Framework

Build modern Discord bots in JavaScript AND Python with slash commands, buttons, menus, and more!

🚀 Quick Start (60 seconds!)

1. Install

npm install hybcord discord.js

2. Create config.json

{
  "prefix": "!",
  "bot_token": "YOUR_BOT_TOKEN",
  "client_id": "YOUR_CLIENT_ID"
}

3. Create bot.js

const { Client, GatewayIntentBits } = require('discord.js');
const { HybridCommandHandler } = require('hybcord');
const config = require('./config.json');

const client = new Client({
    intents: [
        GatewayIntentBits.Guilds,
        GatewayIntentBits.GuildMessages,
        GatewayIntentBits.MessageContent
    ]
});

const hybrid = new HybridCommandHandler(client, {
    config: config,
    clientId: config.client_id,
    token: config.bot_token
});

client.once('ready', async () => {
    console.log('Bot ready!');
    await hybrid.loadCommands();
});

client.on('messageCreate', (msg) => hybrid.handleMessage(msg));
client.on('interactionCreate', (int) => hybrid.handleInteraction(int));

client.login(config.bot_token);

4. Create a command

Prefix command (commands/ping.js):

module.exports = {
    description: 'Ping pong!',
    async execute(message, args, sharedData) {
        await message.reply('🏓 Pong!');
    }
};

Slash command (commands/hello.js):

module.exports = {
    type: 'slash',
    description: 'Say hello',
    async execute(interaction, sharedData) {
        await interaction.reply('👋 Hello!');
    }
};

5. Run

node bot.js

Test: Type !ping or /hello in Discord!

✨ Features

🎯 Core Features

• ✅ Slash Commands - Modern Discord slash commands
• ✅ Prefix Commands - Traditional !command style
• ✅ Buttons & Menus - Interactive components
• ✅ Context Menus - Right-click commands
• ✅ Event Handlers - Both JS and Python
• ✅ Dual Language - Write in JavaScript OR Python

🛠️ Advanced Features

• ✅ Auto Help Command - Generates automatically
• ✅ Command Categories - Organize in folders
• ✅ Command Aliases - Multiple names per command
• ✅ Sub-commands - !settings view, !settings edit
• ✅ Cooldowns - Prevent spam
• ✅ Permissions - Discord permission checks
• ✅ Hot Reload - Update commands without restart
• ✅ Config System - Shared config.json
• ✅ Database Integration - Pass DB to all commands
• ✅ Utility Functions - Share code everywhere

📚 Complete Guide

Installation

# Install hybcord
npm install hybcord discord.js

# Copy Python helper (for Python commands)
cp node_modules/hybcord/discord_hybrid.py .

Slash Commands

// commands/userinfo.js
module.exports = {
    type: 'slash',
    description: 'Get user information',
    options: [
        {
            name: 'user',
            type: 6, // USER type
            description: 'The user',
            required: false
        }
    ],
    
    async execute(interaction, sharedData) {
        const user = interaction.options.getUser('user') || interaction.user;
        
        await interaction.reply({
            embeds: [{
                title: `${user.username}'s Info`,
                thumbnail: { url: user.displayAvatarURL() },
                fields: [
                    { name: 'ID', value: user.id },
                    { name: 'Tag', value: user.tag }
                ]
            }]
        });
    }
};

Buttons & Select Menus

Button Command:

// commands/panel.js
module.exports = {
    async execute(message, args, sharedData) {
        await message.reply({
            content: 'Click a button:',
            components: [{
                type: 1,
                components: [
                    {
                        type: 2,
                        label: 'Click Me!',
                        style: 1,
                        custom_id: 'my_button'
                    }
                ]
            }]
        });
    }
};

// commands/my_button.js
module.exports = {
    type: 'button',
    customId: 'my_button',
    
    async execute(interaction, sharedData) {
        await interaction.reply('Button clicked! 🎉');
    }
};

Select Menu:

// commands/choose.js
module.exports = {
    async execute(message, args, sharedData) {
        await message.reply({
            content: 'Choose an option:',
            components: [{
                type: 1,
                components: [{
                    type: 3,
                    custom_id: 'my_select',
                    options: [
                        { label: 'Option 1', value: 'opt1' },
                        { label: 'Option 2', value: 'opt2' },
                        { label: 'Option 3', value: 'opt3' }
                    ]
                }]
            }]
        });
    }
};

// commands/my_select.js
module.exports = {
    type: 'select',
    customId: 'my_select',
    
    async execute(interaction, sharedData) {
        const choice = interaction.values[0];
        await interaction.reply(`You chose: ${choice}`);
    }
};

Context Menus (Right-Click)

// commands/getUserId.js
module.exports = {
    type: 'context',
    name: 'Get User ID',
    contextType: 'USER',
    
    async execute(interaction, sharedData) {
        const user = interaction.targetUser;
        await interaction.reply({
            content: `${user.username}'s ID: \`${user.id}\``,
            ephemeral: true
        });
    }
};

Command Categories

Organize commands in folders:

commands/
├── admin/
│   ├── ban.js
│   └── kick.js
├── fun/
│   ├── meme.js
│   └── joke.py
└── utility/
    ├── ping.js
    └── info.js

Auto-generates help with categories! 📚

Command Aliases

module.exports = {
    name: 'userinfo',
    aliases: ['ui', 'user', 'whois'],
    
    async execute(message, args, sharedData) {
        // Works with: !userinfo, !ui, !user, !whois
    }
};

Sub-commands

module.exports = {
    name: 'settings',
    description: 'Bot settings',
    
    subcommands: {
        view: async (message, args, sharedData) => {
            await message.reply('Viewing settings...');
        },
        
        edit: async (message, args, sharedData) => {
            await message.reply('Editing settings...');
        },
        
        reset: async (message, args, sharedData) => {
            await message.reply('Settings reset!');
        }
    },
    
    async execute(message, args, sharedData) {
        await message.reply('Use: !settings <view|edit|reset>');
    }
};

Usage: !settings view, !settings edit, !settings reset

Cooldowns & Permissions

module.exports = {
    cooldown: 10, // 10 seconds
    permissions: ['Administrator'], // Requires admin
    
    async execute(message, args, sharedData) {
        // Only admins can use, max once per 10 seconds
    }
};

Hot Reload

// Reload single command
await hybrid.reloadCommand('ping');

// Reload all commands
await hybrid.reloadAll();

Auto Help Command

Enable in handler options:

const hybrid = new HybridCommandHandler(client, {
    autoHelp: true, // Default: true
    helpStyle: 'embed' // or 'text'
});

Auto-generates !help command with categories!

Python Commands

Copy the helper:

cp node_modules/hybcord/discord_hybrid.py .

Create command (commands/calculate.py):

#!/usr/bin/env python3
from discord_hybrid import get_context

ctx = get_context()

if len(ctx.args) < 2:
    ctx.reply("Usage: !calculate <num1> <num2>")
else:
    num1 = float(ctx.args[0])
    num2 = float(ctx.args[1])
    result = num1 + num2
    ctx.reply(f"Result: {result}")

Config System

config.json:

{
  "prefix": "!",
  "bot_name": "My Bot",
  "owner_id": "YOUR_ID",
  "api_keys": {
    "weather": "abc123"
  }
}

Access in commands:

// JavaScript
const prefix = sharedData.config.prefix;
const apiKey = sharedData.config.api_keys.weather;

# Python
prefix = ctx.get_config('prefix', '!')
api_key = ctx.config['api_keys']['weather']

Database Integration

// In bot.js
const { MongoClient } = require('mongodb');
const mongoClient = new MongoClient('mongodb://localhost:27017');
await mongoClient.connect();

const hybrid = new HybridCommandHandler(client, {
    database: mongoClient.db('mybot')
});

// In any command
const users = sharedData.database.collection('users');
const user = await users.findOne({ id: message.author.id });

Utility Functions

// In bot.js
const utils = {
    formatDate: (date) => new Date(date).toLocaleString(),
    randomColor: () => Math.floor(Math.random() * 16777215)
};

const hybrid = new HybridCommandHandler(client, { utils });

// In any command
const color = sharedData.utils.randomColor();

📁 Project Structure

your-bot/
├── bot.js                 # Main bot file
├── config.json            # Configuration
├── discord_hybrid.py      # Python helper
├── package.json
├── commands/              # All commands
│   ├── admin/            # Category folder
│   │   ├── ban.js
│   │   └── kick.js
│   ├── fun/              # Category folder
│   │   ├── meme.js
│   │   └── joke.py
│   ├── ping.js           # Prefix command
│   └── hello.js          # Slash command
└── events/               # Event handlers
    ├── ready.js
    └── guildMemberAdd.js

🎨 Full Example

See the example/ folder in the package for a complete working bot with:

• ✅ Slash commands
• ✅ Buttons & menus
• ✅ Context menus
• ✅ Categories
• ✅ Config system
• ✅ Database example
• ✅ Event handlers
• ✅ Python commands

🆕 What's New in v3.0

Major Features

• ✅ Slash Commands - Full slash command support
• ✅ Buttons & Select Menus - Interactive components
• ✅ Context Menus - Right-click commands
• ✅ Auto Help Generator - Automatic help command
• ✅ Command Categories - Folder-based organization
• ✅ Command Aliases - Multiple names per command
• ✅ Sub-commands - Better command structure
• ✅ Hot Reload - Reload without restart

Improvements

• ✅ Better error handling
• ✅ Cleaner code structure
• ✅ More examples
• ✅ Enhanced documentation

📋 Requirements

• Node.js 16.9.0 or higher
• discord.js v14.0.0 or higher
• Python 3.7+ (only for Python commands)

🔧 Handler Options

new HybridCommandHandler(client, {
    // Paths
    commandsPath: './commands',    // Commands folder
    eventsPath: './events',        // Events folder
    
    // Slash commands
    clientId: 'YOUR_CLIENT_ID',    // For slash commands
    token: 'YOUR_BOT_TOKEN',       // For slash commands
    
    // Features
    autoHelp: true,                // Auto help command
    helpStyle: 'embed',            // 'embed' or 'text'
    
    // Shared data
    config: {},                     // Config object
    database: null,                 // Database connection
    utils: {},                      // Utility functions
    cache: new Map(),              // Shared cache
    
    // Python
    pythonExecutable: 'python3',   // Python command
    configPath: './config.json'    // Config file path
})

❓ FAQ

Q: How do I get my bot token and client ID?
A: Go to Discord Developer Portal, create an application, and get your token from the Bot tab and client ID from OAuth2.

Q: Do slash commands work immediately?
A: Slash commands can take up to 1 hour to register globally. Use guild commands for instant testing.

Q: Can I use both prefix and slash commands?
A: Yes! Hybcord supports both simultaneously.

Q: Do I need Python installed?
A: Only if you want to write commands in Python. JavaScript-only bots don't need Python.

Q: How do I update to v3.0?
A: npm update hybcord - Check CHANGELOG for breaking changes.

📄 License

MIT License - see LICENSE file

🌟 Support the Project

If Hybcord helped you, please:

• ⭐ Star on NPM
• 📢 Share with others
• 💬 Leave a review
• 🐛 Report bugs

📞 Get Help

• 📦 NPM Page: https://www.npmjs.com/package/hybcord
• 📖 Documentation: Check the example/ folder
• 💬 Issues: Report bugs or request features on NPM

Built with ❤️ for Discord bot developers

Hybcord - The framework that grows with your bot