Event API

Integrate your addons into core bot logic, unlocking a new level of power.

✨ Features

• Event-driven architecture — React to Discord and bot events

• Backward compatibility — Legacy addons still work

• Priority system — Control execution order of handlers

• Error isolation — One addon's error won't crash others

• Rich context — Access client, config, and language data

• Async support — Full Promise / async-await support

🚀 Quick Start

Example: HelloWorld Addon

A simple addon that responds to messages, welcomes new members, and reacts to tickets being created:

module.exports = {
    // Give your addon a unique name
    name: 'HelloWorld',
    
    // Optional metadata
    // version: '1.0.0'
    // description: '...'
    // author: 'Your Name'
    
    events: {
        // Respond to messages
        'discord:messageCreate': async (eventData, context) => {
            const { message } = eventData;
            if (message.author.bot) return;
            
            if (message.content.toLowerCase() === '!hello') {
                await message.channel.send(`Hello ${message.author.username}! 👋`);
            }
        },
        
        // Welcome new members
        'discord:guildMemberAdd': async (eventData, context) => {
            const { member } = eventData;
            console.log(`New member joined: ${member.user.username}`);
            
            const channel = member.guild.channels.cache.find(
                ch => ch.name === 'welcome' || ch.name === 'general'
            );
            if (channel) {
                await channel.send(`Welcome ${member.user.username}! 🎉`);
            }
        },
        
        // React to tickets being created
        'ticket:created': async (eventData, context) => {
            const { ticket, user } = eventData;
            console.log(`Ticket #${ticket.ticketId} was created by ${user.username}`);
        }
    }
};

With this addon:

• Type !hello → Bot replies with a greeting

• New members join → Welcome message in #welcome or #general

• Ticket is created → Logged in console

📡 Event Reference

Discord Events

Listen to Discord.js events with the discord: prefix:

Event	What It Does	Key Data
discord:messageCreate	New message sent	message
discord:messageUpdate	Message edited	message, oldMessage
discord:messageDelete	Message deleted	message
discord:guildMemberAdd	User joins server	member
discord:guildMemberRemove	User leaves server	member
discord:guildMemberUpdate	User roles/nickname changed	oldMember, newMember
discord:voiceStateUpdate	Voice channel changes	oldState, newState
discord:channelCreate	Channel created	channel
discord:channelDelete	Channel deleted	channel
discord:roleCreate	Role created	role
discord:roleDelete	Role deleted	role
discord:guildBanAdd	User banned	ban
discord:guildBanRemove	User unbanned	ban
discord:interactionCreate	Slash command/button used	interaction
discord:ready	Bot started	client

Bot Business Logic Events

Ticket Events

Event	What It Does	Key Data
ticket:created	New ticket opened	ticket, user, ticketType, questions
ticket:closed	Ticket closed/resolved	ticket, closedBy, closeReason, isAutoAlert
ticket:deleted	Ticket channel deleted	ticket, guild, user
ticket:claimed	Staff member claims ticket	ticket, claimer
ticket:unclaimed	Staff member unclaims ticket	ticket, unclaimer
ticket:reviewed	User reviews service	ticket, rating, feedback, reviewer

Suggestion Events

Event	What It Does	Key Data
suggestion:created	New suggestion submitted	suggestion, author, text, message
suggestion:accepted	Suggestion approved by staff	suggestion, acceptedBy, reason, originalAuthor
suggestion:denied	Suggestion rejected by staff	suggestion, deniedBy, reason, originalAuthor

Leveling Events

Event	What It Does	Key Data
level:up	User gains XP and levels up	user, newLevel, oldLevel, xpGained, userData

Music Events

Event	What It Does	Key Data
music:trackStart	Track starts playing	track, requestedBy, queue
music:trackAdded	Track added to queue	track, requestedBy, queue

Giveaway Events

Event	What It Does	Key Data
giveaway:created	New giveaway started	giveaway, prize, winnerCount, hostedBy
giveaway:ended	Giveaway finished, winners selected	giveaway, winners, prize, totalEntries

Invite Events

Event	What It Does	Key Data
invite:memberJoined	Member joins via tracked invite	member, inviter, inviterInviteCount

Moderation Events

Event	What It Does	Key Data
moderation:ban	User banned	target, moderator, reason, guild, case
moderation:unban	User unbanned	target, moderator, reason, guild, case
moderation:kick	Member kicked	target, moderator, reason, guild, case
moderation:warn	Warning issued	target, moderator, reason, guild, warning
moderation:unwarn	Warning removed	target, moderator, guild, warningId
moderation:timeout	Timeout applied	target, moderator, durationMs, guild, endTime
moderation:timeout_clear	Timeout removed	target, moderator, guild, case
moderation:tempban	Temporary ban applied	target, moderator, reason, guild, sanction

Addon Lifecycle Events

Event	What It Does	Key Data
addon:loaded	Addon loaded successfully	name, path, type
addon:unloaded	Addon unloaded	name, path
addon:registered	Addon registered with event system	name, events

🔧 Custom Events

Emit and listen for your own events:

// Emit
global.addonLoader.getEventManager().emitSafe('my-addon:custom-event', {
    data: 'some data',
    user,
    guild
});

// Listen in your addon
module.exports = { name: 'CustomEvents', events: {
    'my-addon:custom-event': async (eventData, context) => {
        const { data, user, guild } = eventData;
        // Handle custom event
    }
}
};

🧰 Context Object

Every handler receives:

{
    client: Client,       // Discord.js client
    config: Object,       // Bot config
    lang: Object,         // Language config
    eventName: String,    // Current event
    timestamp: Date,      // Emitted at
    guild: Guild|null,    // Guild if available
    user: User|null       // User if available
}

⚙️ Advanced Features

Priority System

Control execution order:

module.exports = {
    name: 'HighPriority',
    priority: 100, // Higher runs first
    events: { /* ... */ }
};

Error Handling

Addons run independently:

module.exports = { name: 'Example', events: {
    'discord:messageCreate': async (eventData, context) => {
        try {
            // your logic
        } catch (err) {
            console.error('Error in my addon:', err);
            // Won't crash other addons
        }
    }
} };

Database Integration

Use Mongoose inside addons:

const mongoose = require('mongoose');

const mySchema = new mongoose.Schema({
    guildId: String,
    data: String
});

const MyModel = mongoose.model('MyData', mySchema);

// Call from an event handler
async function saveGuildData(guild) {
    await MyModel.findOneAndUpdate(
    { guildId: guild.id },
    { data: 'updated' },
    { upsert: true }
);
}

Conditional Event Handling

Run logic only in certain channels/users:

module.exports = { name: 'Example', events: { 'discord:messageCreate': async (eventData, context) => {
    const { message } = eventData;
    
    // Only in specific channels
    if (!['general', 'bot-commands'].includes(message.channel.name)) return;
    
    // Only non-bots
    if (message.author.bot) return;
    
    // Your logic here
} } };

🔄 Migration from Legacy Addons

Legacy Format (still works)

module.exports = {
    run: async (client) => {
        client.on('messageCreate', async message => {
            if (message.content === '!hello') {
                await message.channel.send('Hello!');
            }
        });
    }
};

New Event API Format

module.exports = {
    name: 'MyAddon',
    version: '1.0.0',
    events: {
        'discord:messageCreate': async (eventData, context) => {
            const { message } = eventData;
            if (message.content === '!hello') {
                await message.channel.send('Hello!');
            }
        }
    },
    
    // Optional: Keep initialization logic
    run: async (client, eventManager) => {
        console.log('Addon initialized!');
    }
};

Key Differences

• Legacy → run function, no name property

• New → name required, uses events

• New format benefits: event-driven API, enable/disable, error isolation, priorities

📋 Requirements Summary

Absolutely Required

• name (string) — Unique addon identifier

Required (pick one)

• events (object) — Event handlers

• run (function) — Init function

Optional (defaults)

• version → '1.0.0'

• description → ''

• author → 'Unknown'

• priority → 0

• permissions → []

• dependencies → []

Minimal Working Addon

module.exports = {
    name: 'Minimal',
    events: {
        'discord:messageCreate': async (eventData, context) => {
            // Your code here
        }
    }
};

💡 Practical Examples

Staff Notification System

module.exports = {
    name: 'StaffNotifications',
    events: {
        'ticket:created': async ({ ticket, user, ticketType }) => {
            const staffChannel = ticket.guild.channels.cache.find(ch => ch.name === 'staff-alerts');
            if (staffChannel) {
                await staffChannel.send(`🎫 New ${ticketType.Name} ticket #${ticket.ticketId} by ${user.username}`);
            }
        },
        
        'suggestion:created': async ({ suggestion, author, text }) => {
            const staffChannel = suggestion.guild.channels.cache.find(ch => ch.name === 'suggestions');
            if (staffChannel) {
                const message = await staffChannel.send(`💡 New suggestion: "${text}" by ${author.username}`);
                await message.react('👍');
                await message.react('👎');
            }
        }
    }
};

Level Rewards System

module.exports = {
    name: 'LevelRewards',
    events: {
        'level:up': async ({ user, newLevel, guild }) => {
            const member = guild.members.cache.get(user.id);
            
            // Milestone rewards
            if (newLevel === 10) {
                const role = guild.roles.cache.find(r => r.name === 'Active Member');
                if (role) await member.roles.add(role);
            }
            
            if (newLevel === 50) {
                const role = guild.roles.cache.find(r => r.name === 'Veteran');
                if (role) await member.roles.add(role);
            }
            
            // Celebrate big milestones
            if (newLevel % 25 === 0) {
                const channel = guild.channels.cache.find(ch => ch.name === 'general');
                if (channel) {
                    await channel.send(`🎉 ${user.username} reached level ${newLevel}! Amazing! 🎉`);
                }
            }
        }
    }
};

Warning Logger

module.exports = {
    name: 'ModLogger',
    events: {
        'moderation:warn': async ({ target: user, reason, guild }) => {
            const logChannel = guild.channels.cache.find(ch => ch.name === 'mod-logs');
            if (logChannel) {
                await logChannel.send({
                    embeds: [{
                        title: '🛡️ Warning',
                        description: `**User:** ${user.username}\n**Reason:** ${reason}`,
                        color: 0xff6b6b,
                        timestamp: new Date()
                    }]
                });
            }
        }
    }
};