Plugin API Reference¶

This document provides a comprehensive reference for the Plugin API in @axrxvm/betterdiscordjs.

BasePlugin Class¶

All plugins must extend the BasePlugin class which provides the core plugin functionality.

Constructor¶

constructor(bot, pluginManager)

bot - The Bot instance
pluginManager - The PluginManager instance

Required Properties¶

Every plugin must define these properties:

class MyPlugin extends BasePlugin {
  constructor(bot, pluginManager) {
    super(bot, pluginManager);
    this.name = 'myplugin';
    this.version = '1.0.0';
    this.description = 'My awesome plugin';
  }
}

Optional Properties¶

this.dependencies = ['otherplugin']; // Array of required plugins
this.author = 'Your Name';
this.website = 'https://example.com';
this.enabled = true; // Whether plugin is enabled by default

Lifecycle Methods¶

onLoad()¶

Called when the plugin is loaded. Use this for initialization.

async onLoad() {
  this.logger.info(`${this.name} plugin loaded`);
  // Initialize your plugin here
}

onUnload()¶

Called when the plugin is unloaded. Use this for cleanup.

async onUnload() {
  this.logger.info(`${this.name} plugin unloaded`);
  // Cleanup resources here
}

onEnable()¶

Called when the plugin is enabled.

async onEnable() {
  this.logger.info(`${this.name} plugin enabled`);
}

onDisable()¶

Called when the plugin is disabled.

async onDisable() {
  this.logger.info(`${this.name} plugin disabled`);
}

Available Properties¶

this.bot¶

Access to the main Bot instance.

this.bot.client // Discord.js client
this.bot.commands // Command collection

this.logger¶

Plugin-specific logger.

this.logger.info('Info message');
this.logger.warn('Warning message');
this.logger.error('Error message');

this.config¶

Plugin configuration object.

// Get config value
const value = this.config.get('key', 'defaultValue');

// Set config value
this.config.set('key', 'value');

// Save config
await this.config.save();

Helper Methods¶

registerCommand(name, handler, options)¶

Register a command from within the plugin.

this.registerCommand('mycommand', async (ctx) => {
  await ctx.reply('Hello from plugin!');
}, {
  description: 'My plugin command',
  cooldown: '5s'
});

registerEvent(eventName, handler)¶

Register an event listener from within the plugin.

this.registerEvent('messageCreate', async (ctx) => {
  // Handle message
});

unregisterCommand(name)¶

Remove a command registered by this plugin.

this.unregisterCommand('mycommand');

unregisterEvent(eventName, handler)¶

Remove an event listener registered by this plugin.

this.unregisterEvent('messageCreate', this.myHandler);

Plugin Configuration¶

Config File Structure¶

Plugin configurations are stored in plugins/config.json:

{
  "pluginName": {
    "enabled": true,
    "settings": {
      "key": "value"
    }
  }
}

Accessing Configuration¶

// In your plugin
const setting = this.config.get('settings.key');
this.config.set('settings.newKey', 'newValue');
await this.config.save();

Plugin Manager API¶

Loading Plugins¶

// Load a plugin
await bot.loadPlugin('pluginName');

// Load plugin from class
await bot.loadPluginFromClass(MyPluginClass, 'customName');

// Use plugin (fluent API)
bot.use(MyPluginClass).start();

Managing Plugins¶

// Enable/disable
await bot.enablePlugin('pluginName');
await bot.disablePlugin('pluginName');

// Reload
await bot.reloadPlugin('pluginName');

// Unload
await bot.unloadPlugin('pluginName');

// Get plugin instance
const plugin = bot.getPlugin('pluginName');

// List all plugins
const plugins = bot.listPlugins();

Plugin Events¶

Plugins can listen to special plugin events:

pluginLoaded¶

Fired when any plugin is loaded.

this.bot.on('pluginLoaded', (pluginName) => {
  this.logger.info(`Plugin ${pluginName} was loaded`);
});

pluginUnloaded¶

Fired when any plugin is unloaded.

this.bot.on('pluginUnloaded', (pluginName) => {
  this.logger.info(`Plugin ${pluginName} was unloaded`);
});

Error Handling¶

Plugin Error Events¶

this.bot.on('pluginError', (pluginName, error) => {
  this.logger.error(`Plugin ${pluginName} error:`, error);
});

Try-Catch in Plugin Methods¶

async onLoad() {
  try {
    // Plugin initialization
  } catch (error) {
    this.logger.error('Failed to initialize plugin:', error);
    throw error; // Re-throw to prevent loading
  }
}

Best Practices¶

Always call super() in constructor
Handle errors gracefully in lifecycle methods
Clean up resources in onUnload()
Use plugin-specific logger for debugging
Validate dependencies in onLoad()
Use meaningful plugin names and versions
Document your plugin's configuration options

Example Plugin¶

const { BasePlugin } = require('@axrxvm/betterdiscordjs');

class ExamplePlugin extends BasePlugin {
  constructor(bot, pluginManager) {
    super(bot, pluginManager);
    this.name = 'example';
    this.version = '1.0.0';
    this.description = 'An example plugin';
    this.author = 'Your Name';
  }

  async onLoad() {
    this.logger.info('Example plugin loading...');

    // Register commands
    this.registerCommand('hello', this.helloCommand.bind(this), {
      description: 'Say hello',
      cooldown: '3s'
    });

    // Register events
    this.registerEvent('messageCreate', this.onMessage.bind(this));
  }

  async onUnload() {
    this.logger.info('Example plugin unloading...');
    // Cleanup if needed
  }

  async helloCommand(ctx) {
    await ctx.reply('Hello from Example Plugin!');
  }

  async onMessage(ctx) {
    if (ctx.raw.content.includes('example')) {
      await ctx.react('👋');
    }
  }
}

module.exports = ExamplePlugin;

Next Steps¶

Apply your plugin API knowledge:

🔌 Creating Plugins - Start building your first plugin
📝 Plugin Examples - Study real-world implementations
🏗️ Built-in Plugins - Extend existing functionality
🚀 Advanced Use Cases - Build enterprise-grade plugin systems