Custom Events

This page explains how to run Athena custom events for your AthenaBot plugin.

---

1. Setting up the event file

1. Create a new event file in /plugins/<plugin_name>/src/events/.

2. Name the file with a unique event listener name, such as myLevelUpListener.js.

3. Set event.discord to the Athena custom event name you want to listen to, such as athena:levelUp.

const event = require('../../../../main/discord/core/events/event.js');

module.exports = class myLevelUpListener extends event {
  constructor(heart) {
    super(heart, { name: 'myLevelUpListener', event: { discord: 'athena:levelUp', bypassManager: false, dm: false, bypassRestrictions: true, permissionLevel: null } });
  }

  async execute(userId, newLevel) {
    try {
      this.heart.core.console.log(this.heart.core.console.type.log, `${userId} reached level ${newLevel}`);
    }
    catch (err) {
      this.heart.core.console.log(this.heart.core.console.type.error, `An issue occurred while executing event ${this.getName()}`);
      new this.heart.core.error.interface(this.heart, err);
    }
  }
};

Parameters

• name: Unique identifier for your listener file.

• discord: The Athena custom event name.

• bypassManager: Keep false unless you fully understand the side effects.

• dm: Keep false for Athena custom events.

• bypassRestrictions: Keep true.

• permissionLevel: Keep null for Athena custom events.

The important value is event.discord. It must exactly match the emitted event name.

---

2. Running the event

Athena events are not fired by Discord.js. You run them by calling Athena’s eventManager.emitSafe from your feature logic.

const didEmit = await this.heart.manager.discord.eventManager.emitSafe('athena:levelUp', userId, newLevel);
if (!didEmit) {
  this.heart.core.console.log(this.heart.core.console.type.warn, 'Event levelUp emitted but no listener was registered');
}

If you emit:

emitSafe('athena:levelUp', userId, newLevel)

Your listener should be:

async execute(userId, newLevel) {
  // ...
}

---

3. Additional information

• Event names are case-sensitive.

• Do not rename athena:* events unless all emitters and listeners are updated together.

• IDs are Discord snowflakes unless the event signature states otherwise.

• Object payloads should be treated as internal APIs that may evolve.

---

4. Athena custom event catalog

Signatures are shown as EventName(arg1, arg2, ...).

Core

• athena:error(errorInterface)

Economy

• athena:bankUpgrade(userId, bankLevel)

• athena:shopPurchase(userId, itemId, cost)

• athena:jobUpgrade(userId, jobKey, jobLevel)

• athena:lootboxRollPurchase(userId, purchasedRolls)

• athena:lootboxOpen(userId, rewardType, rewardAmount)

• athena:questClaim(userId, period, finishedQuestCount, rewards)

• athena:rankUpgrade(userId, newRank)

Fun

• athena:levelUp(userId, level)

• athena:countingGameSuccess(userId, counterValue)

• athena:countingGameFail(userId, evaluatedInput, expectedCounter)

• athena:hangmanEnd(userId, won, streak, winStreakCurrent)

• athena:higherLowerEnd(userId, streak, highscore)

• athena:starboardSend(userId, messageId, reactionCount)

• athena:starboardReaction(userId, messageId, reactionCount)

Giveaway

• athena:giveawayEnter(userId, giveawayMessageId, entryCount)

• athena:giveawayLeave(userId, giveawayMessageId, entryCount)

Join to create

• athena:tempVoiceCreate(voiceChannelId, ownerUserId, sourceChannelId)

• athena:tempVoiceDelete(voiceChannelId, ownerUserId)

• athena:tempVoiceOwnerChange(voiceChannelId, previousOwnerUserId, newOwnerUserId)

• athena:tempVoiceOwnerSet(voiceChannelId, executorUserId, newOwnerUserId)

• athena:tempVoiceName(voiceChannelId, executorUserId, newName)

• athena:tempVoiceLimit(voiceChannelId, executorUserId, newLimit)

• athena:tempVoiceVisibility(voiceChannelId, executorUserId, visibility)

• athena:tempVoiceKick(voiceChannelId, executorUserId, targetUserId)

• athena:tempVoiceBlacklist(voiceChannelId, executorUserId, targetUserId)

• athena:tempVoiceUnblacklist(voiceChannelId, executorUserId, targetUserId)

Management

• athena:applySavedRoles(userId, roleCount)

• athena:autoRole(userId, roleCount)

• athena:saveRoles(userId, roleCount)

• athena:pollVote(userId, pollId, optionId)

• athena:pollVoteRevoke(userId, pollId, optionId)

• athena:suggestionCreate(userId, suggestionNumber)

• athena:suggestionStatus(staffUserId, suggestionId, status)

• athena:suggestionReview(staffUserId, suggestionId, approved)

Moderation

• athena:blacklist(type, targetUserId, executorUserId, punishmentId)

• athena:unblacklist(type, targetUserId, executorUserId, punishmentId)

• athena:ban(targetUserId, executorUserId, punishmentId, manual)

• athena:unban(targetUserId, executorUserId, punishmentId, manual)

• athena:kick(targetUserId, executorUserId, punishmentId, manual)

• athena:mute(targetUserId, executorUserId, punishmentId, manual)

• athena:unmute(targetUserId, executorUserId, punishmentId, manual)

• athena:warn(targetUserId, executorUserId, punishmentId)

• athena:unwarn(targetUserId, executorUserId, punishmentId)

• athena:strike(targetUserId, executorUserId, punishmentId, strikeAmount)

• athena:automodAction(userId, ruleName, warning)

Music

• athena:nodeConnect(nodeName)

• athena:nodeDisconnect(nodeName, disconnectCount)

• athena:nodeError(nodeName, errorMessageOrNull)

• athena:playerCreate(guildIdOrNull, defaultVolume)

• athena:trackStart(guildId, requesterUserId, title)

• athena:trackEnd(guildId, titleOrNull, remainingQueueLength)

• athena:queueEnd(guildId, textChannelId)

Security

• athena:autoVerify(userId)

• athena:verifyFail(userId, remainingAttempts)

• athena:verifySuccess(userId)

Social

• athena:twitchLive(username, messageId, viewerCount)

• athena:twitchOffline(username)

• athena:youtubeNotification(authorName, videoId, discordChannelId)

Staff management

• athena:verifyStaffRoles()

• athena:verifyStaffRolesFail(invalidRoleIds)

• athena:strikelistView(viewerUserId, targetMemberId, punishmentId, page)

• athena:taskClaim(userId, taskId)

• athena:taskEditOpen(userId, taskId, type)

• athena:taskEdit(userId, taskId, type)

Tickets

• athena:ticketCreate(ticket)

• athena:ticketAdd(ticket, addedUserId)

• athena:ticketRemove(ticket, removedUserId)

• athena:ticketRename(ticket, newName)

• athena:ticketClaim(ticket, claimerUserId)

• athena:ticketUnclaim(ticket, unclaimerUserId)

• athena:ticketClose(ticket)

• athena:ticketLower(ticket, level)

• athena:ticketElevate(ticket, level)

• athena:applicationStart(userId, applicationIndex)

• athena:applicationSubmit(userId, applicationIndex, answersCount, submitted)

• athena:applicationCancel(userId, applicationIndex)

• athena:applicationChannelCreate(application)

• athena:applicationChatAllow(applicantUserId, staffUserId, appChannelId)

• athena:applicationChatDeny(applicantUserId, staffUserId, appChannelId)

• athena:applicationHistoryView(staffUserId, applicantUserId, appChannelId)

• athena:applicationAccept(application, roleName, staffUserId)

• athena:applicationDeny(application, staffUserId, reason, timeoutMs)

• athena:applicationAutoClose(application)