@blitz-bots/builder v1.0.7

BLITZ BUILDER is an NPM package that helps you build modular Discord bots using discord.js. The package provides an easy framework to create events, commands, slash commands, all within a plugin-based architecture.

Features

• Event, Command, and Slash Command Handling: Create modular events, commands, and slash commands with ease.
• Plugin-Based Architecture: Plugins can be created and loaded dynamically, allowing flexibility in bot design.
• Configurable: Central bot configuration and per-plugin configuration support.

Installation

To get started, install the package using NPM:

npm install @blitz-bots/builder

You'll also need discord.js:

npm install discord.js

Usage

1. The BLITZ Base Bot Code

First, you need to create a "base bot" that will load plugins and handle configuration. Here's an example of a basic bot setup.

File: bot.js

// bot.js (The base bot)
const { Client, Collection, IntentsBitField } = require("discord.js");
const PluginLoader = require("@blitz-bots/builder/plugin_loader");

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

// Load Config File
const config = require("config.json");

client.commands = new Collection();
client.slashCommands = new Collection();

// Load plugins from the plugins folder using the manifest
const pluginLoader = new PluginLoader(client, "./plugins");
pluginLoader.loadPlugins();

// Discord ready event
client.once("ready", () => {
  console.log(`Logged in as ${client.user.tag}`);
});

// Handle command interactions
client.on("interactionCreate", async (interaction) => {
  if (!interaction.isCommand()) return;

  const command = client.slashCommands.get(interaction.commandName);
  if (command) await command.run(interaction);
});

// Handle message-based commands
client.on("messageCreate", (message) => {
  const prefix = config.prefix;
  if (!message.content.startsWith(prefix) || message.author.bot) return;

  const args = message.content.slice(prefix.length).trim().split(/ +/);
  const commandName = args.shift().toLowerCase();
  const command = client.commands.get(commandName);

  if (command) {
    command.run(message, args);
  }
});

// Login to Discord
client.login(config.token);

2. Configuration

File: config.json

This file contains the bot's main configuration, such as the Discord token and bot prefix.

{
  "token": "YOUR_BOT_TOKEN",
  "prefix": "!"
}

• token: Your Discord bot's token.
• prefix: The command prefix for the bot.

3. Plugin Structure

Each plugin is loaded dynamically and is structured as follows:

/plugins
    /plugin_one
        /events
            message.js
        /commands
            ping.js
        /slashCommands
            hello.js
        manifest.json
        config.json (optional)

• manifest.json: Defines where the plugin’s events, commands, and slash commands are located.
• config.json (optional): Plugin-specific configuration file.

Example manifest.json for a Plugin:

{
  "name": "plugin_one",
  "description": "A test plugin for events and commands",
  "eventsPath": "./events",
  "commandsPath": "./commands",
  "slashCommandsPath": "./slashCommands",
  "configFile": "./config.json"
}

4. Events, Commands, and Slash Commands

Plugins are responsible for handling their own events, commands, and slash commands. These are dynamically loaded by the base bot.

Example Event

In the /events folder of your plugin, you can create an event file:

// plugins/plugin_one/events/messageCreate.js
module.exports = {
  name: "messageCreate",
  execute(message, client) {
    console.log(`Message received: ${message.content}`);
  },
};

Example Command

In the /commands folder of your plugin:

// plugins/plugin_one/commands/ping.js
module.exports = {
  name: "ping",
  description: "Replies with Pong!",
  execute(message, args) {
    message.reply("Pong!");
  },
};

Example Slash Command

In the /slashCommands folder of your plugin:

// plugins/plugin_one/slashCommands/hello.js
module.exports = {
  name: "hello",
  description: "Replies with hello!",
  execute(interaction) {
    interaction.reply("Hello!");
  },
};

Summary of Classes

PluginLoader

Class representing a plugin loader.

Kind: global class

• PluginLoader
  • new PluginLoader(client, pluginsPath)
  • .client : Object
  • .pluginsPath : string
  • .loadPlugins()
  • .loadEvents(eventsDir)
  • .loadCommands(commandsDir)
  • .loadSlashCommands(slashCommandsDir)

new PluginLoader(client, pluginsPath)

Creates an instance of PluginLoader.

pluginLoader.client : Object

The client object where plugins will be registered.

Kind: instance property of PluginLoader

pluginLoader.pluginsPath : string

The path to the plugins directory.

Kind: instance property of PluginLoader

pluginLoader.loadPlugins()

and loads events, commands, and slash commands based on the paths specified in the manifest.` file,

Kind: instance method of PluginLoader

pluginLoader.loadEvents(eventsDir)

Loads events from the specified directory and registers them with the client.

Kind: instance method of PluginLoader

pluginLoader.loadCommands(commandsDir)

Loads commands from the specified directory and registers them with the client.

Kind: instance method of PluginLoader

pluginLoader.loadSlashCommands(slashCommandsDir)

Loads slash commands from the specified directory and registers them with the client.

Kind: instance method of PluginLoader

Event

Class representing an event.

Kind: global class

• Event
  • new Event(name, execute)
  • .name : string
  • .execute : function
  • .register(client)

new Event(name, execute)

Creates an instance of Event.

event.name : string

The name of the event.

Kind: instance property of Event

event.execute : function

The function to execute when the event is triggered.

Kind: instance property of Event

event.register(client)

Registers the event listener with the client.

Kind: instance method of Event

Command

Class representing a command.

Kind: global class

• Command
  • new Command(name, description, execute)
  • .name : string
  • .description : string
  • .execute : function
  • .run(message, args)

new Command(name, description, execute)

Creates an instance of Command.

command.name : string

The name of the command.

Kind: instance property of Command

command.description : string

The description of the command.

Kind: instance property of Command

command.execute : function

The function to execute when the command is triggered.

Kind: instance property of Command

command.run(message, args)

Executes the command.

Kind: instance method of Command

SlashCommand

Class representing a slash command.

Kind: global class

• SlashCommand
  • new SlashCommand(name, description, [options], execute)
  • .name : string
  • .description : string
  • .options : Array.<Object>
  • .execute : function
  • .run(interaction) ⇒ Promise.<void>
  • .toJSON() ⇒ Object

new SlashCommand(name, description, options, execute)

Creates an instance of SlashCommand.

slashCommand.name : string

The name of the slash command.

Kind: instance property of SlashCommand

slashCommand.description : string

The description of the slash command.

Kind: instance property of SlashCommand

slashCommand.options : Array.<Object>

An array of options (arguments) for the slash command.

Kind: instance property of SlashCommand

slashCommand.execute : function

The function to execute when the slash command is triggered.

Kind: instance property of SlashCommand

slashCommand.run(interaction) ⇒ Promise.<void>

Executes the slash command.

Kind: instance method of SlashCommand Returns: Promise.<void> - A promise that resolves when the command has been executed.

slashCommand.toJSON() ⇒ Object

Converts the slash command to a JSON object.

Kind: instance method of SlashCommand Returns: Object - The JSON representation of the slash command.