⚡ Event Dispatching & Music Events
🏠 Documentation Hub > Architecture > Events System
Reverb uses an event-driven architecture that separates Discord Gateway Client Events from Moonlink Audio Streaming Events.
1. Event Flow Architecture
2. Discord Gateway Events (src/events/)
Gateway events listen directly to discord.js client.on(event.name, ...) and are loaded by src/handler/clientEvents.js:
🌐 Client Subsystem (src/events/client/)
| Event File | Discord Event | Responsibility |
|---|---|---|
clientReady.js | clientReady | Logs login success, displays ASCII banner, initializes Moonlink client with client.user.id, restores 24/7 connections, and registers slash commands. |
raw.js | raw | Intercepts low-level Discord voice gateway payloads (VOICE_SERVER_UPDATE, VOICE_STATE_UPDATE) and passes them into Moonlink's packet handler. |
💬 Command Subsystem (src/events/commands/)
| Event File | Discord Event | Responsibility |
|---|---|---|
messageCreate.js | messageCreate | Resolves prefix commands, verifies bot channel permissions, checks channel whitelists (auto-deleting warnings after 8s), enforces DJ authorization, and executes message commands. |
interactionCreate.js | interactionCreate | Handles Slash Command execution, subcommand routing, permission validation, and ephemeral error responses. |
autoComplete.js | interactionCreate (Autocomplete) | Powers live search suggestions for commands (e.g. searching playlists or filter names). |
📻 System & Song Requests Subsystem (src/events/system/)
| Event File | Discord Event | Responsibility |
|---|---|---|
setupButtons.js | interactionCreate (Button) | Intercepts button clicks on the persistent player view (player_pause, player_skip, player_stop, player_loop, etc.), verifies same voice channel and DJ permissions. |
setupSystem.js | messageCreate | Intercepts plain text or song links sent into the #reverb-song-requests channel, auto-deletes the prompt, and queues the track. |
3. Moonlink Audio Streaming Events (src/events/music/)
Loaded dynamically by reverbManager from src/events/music/:
🔌 Node Lifecycle (src/events/music/node/)
nodeConnected.js: Fired when the WebSocket handshake with NodeLink or Lavalink succeeds. Checks and re-establishes active 24/7 guild sessions.nodeReady.js: Fired when the audio server signals readiness to handle audio players.nodeDisconnect.js: Triggered when the node connection drops; schedules reconnection.nodeError.js: Captures and logs socket communication errors.nodeReconnect.js/nodeReconnecting.js: Handles exponential backoff reconnect attempts.nodeResume.js/nodeCreate.js/nodeDestroy.js: Tracks node cluster lifecycle.
🎛️ Player Lifecycle (src/events/music/player/)
playerCreate.js: Emitted when a new guild audio player is instantiated.playerDestroy.js: Cleans up guild player data and resets channel voice status.playerPause.js: Synchronizes interactive button states when music is paused/resumed.playerChangedVolume.js: Fires when volume is adjusted.playerChangedLoop.js: Synchronizes loop indicators (track,queue,off).filtersUpdate.js: Logs DSP equalizer and timescale filter changes.
🎵 Track Lifecycle (src/events/music/track/)
trackStart.js:- Sets Discord voice channel status (
🎵 • Song Title). - Sends Now Playing card in the active text channel.
- Updates the persistent player view in
#reverb-song-requests.
- Sets Discord voice channel status (
trackEnd.js:- Cleans up previous track card from chat.
- Resets voice channel status when playback terminates.
- Updates persistent player card.
📜 Queue Lifecycle (src/events/music/queue/)
queueAdd.js: Fired when new tracks are queued; immediately refreshes the up-next list in the setup view.queueRemove.js: Fired when a track is removed or moved in the queue.queueEnd.js: Fired when the last track in the queue finishes. If 24/7 mode is not enabled, starts the idle disconnect countdown.
⏭️ Next Step
Proceed to Frequently Asked Questions or the Error Solutions Guide.