<img src="https://capsule-render.vercel.app/api?type=waving&color=gradient&height=200&section=header&text=LUNOX&fontSize=80&fontAlignY=35&animation=twinkling&fontColor=gradient"/> Shard-ready Discord music bot powered by Rainlink, Lavalink, and Discord.js v14. <a href="https://discord.gg/xhTVzbS5NU" target="_blank"> <img src="https://discordapp.com/api/guilds/1056011738950156359/widget.png?style=banner2"/> </a>

![Version][version-shield] [![MIT License][license-shield]][license-url] [![Contributors][contributors-shield]][contributors-url] [![Stargazers][stars-shield]][stars-url] [![Forks][forks-shield]][forks-url] [![Watchers][watchers-shield]][watchers-url] [![Issues][issues-shield]][issues-url] ![Node Version][node-shield] ![Discord.js][discordjs-shield] ![Rainlink][rainlink-shield]

`⚡` Quick Start

Clone and install:

git clone https://github.com/adh319/Lunox.git
cd Lunox
npm install

Create env file:

cp .env.example .env

Windows PowerShell:

Copy-Item .env.example .env

Fill all required keys in .env (TOKEN, MONGO_URI, Lavalink connection values, etc).
Add your dev ID in src/settings/config.js.
Start MongoDB + Lavalink.
Run the bot:

npm start

`📢` Main Features

☑️ Discord.js v14 + discord-hybrid-sharding architecture (auto shard/cluster mode)
☑️ Rainlink Lavalink client with configurable drivers (v3 / v4) and voice plugin enabled
☑️ Full slash command music suite: play, queue, loop, filter, seek, volume, etc.
☑️ Interactive now-playing controller with buttons (pause/resume, volume, loop, shuffle, previous, skip, stop)
☑️ Queue pagination with button-based navigation
☑️ 24/7 mode (/247) with reconnect persistence per guild
☑️ Autoplay toggle (/autoplay) with YouTube-only fallback behavior
☑️ Per-user ban system and maintenance mode (dev prefix commands)
☑️ MongoDB-backed guild/user state with periodic sync
☑️ Lyrics lookup for current song (/lyric)
☑️ Auto-leave timeout when inactive/alone (configurable)

`📌` Requirements

Node.js 18+ (LTS) (Download / Docs)
MongoDB 5+ (MongoDB Community Download)
Lavalink server (Lavalink Docs)
Java 17+ (LTS) (OpenJDK Downloads) (if you run your own Lavalink)
Discord bot token (Discord Developer Portal Guide)

`🎛️` Command Overview

| Group | Commands | | --- | --- | | General | /help, /ping | | Music | /play, /queue, /skip, /previous, /pause, /resume, /stop, /seek, /remove, /clear, /shuffle, /loop, /filter, /volume, /join, /leave, /lyric | | Settings | /247, /autoplay |

Prefix Commands (Developer / Ops)

ban, unban, maintenance, lavalink, eval, restart
Loaded from src/commands/message/dev
Intended for developer/admin use only (requires your Discord user ID in dev array in src/settings/config.js)

`🔧` Environment Variables

Create a .env file from .env.example.

General

| Key | Default | Purpose | | -------------------- | -------- | ----------------------------------------- | | TOKEN | - | Discord bot token | | PREFIX | ! | Prefix for dev message commands | | EMBED_COLOR | 5865F2 | Embed hex color (without #) | | LEAVE_TIMEOUT | 60000 | Inactivity timeout before leaving VC (ms) | | DEFAULT_VOLUME | 100 | Initial player volume | | MIN_VOLUME | 1 | Minimum volume | | MAX_VOLUME | 100 | Maximum volume | | MONGO_URI | - | MongoDB connection string | | SUPPORT_SERVER_URL | - | Support button URL | | DEBUG | false | Enable debug logs when true |

Lavalink Connection

| Key | Default | Purpose | | ------------------- | ------------------- | ----------------------------------------- | | LAVALINK_NAME | Lunox | Node name | | LAVALINK_HOST | localhost | Lavalink host | | LAVALINK_PORT | 2333 | Lavalink port | | LAVALINK_PASSWORD | youshallnotpass | Lavalink password | | LAVALINK_SECURE | false | Use secure connection (true / false) | | LAVALINK_DRIVER | lavalink/v4/koinu | Rainlink driver for your Lavalink version |

Rainlink Search

| Key | Default | Purpose | | ------------------------ | -------------- | --------------------------------- | | LAVALINK_SOURCE | sp | Source ID used for /play search | | DEFAULT_SEARCH_ENGINE | youtubeMusic | Primary search engine | | SEARCH_FALLBACK_ENGINE | youtube | Fallback search engine |

Notes:

Spotify/Apple/Deezer/Others source support depends on your Lavalink plugins and Lavalink server configuration.

`⚙️` Configuration Notes

1) Developer IDs

Edit src/settings/config.js:

dev: ["123456789012345678"],

These IDs can access developer-only flows and bypass maintenance lock.

2) Emoji Mapping

Customize player and pagination emojis in src/settings/emoji.js.

3) Lavalink Source IDs

LAVALINK_SOURCE should match source IDs enabled in Lavalink.

Examples:

yt -> YouTube search (ytsearch)
ytm -> YouTube Music search (ytmsearch)
sc -> SoundCloud search (scsearch)
sp -> Spotify search (spsearch) when plugin/source is enabled
am -> Apple Music search (amsearch) when plugin/source is enabled
dz -> Deezer search (dzsearch) when plugin/source is enabled

Use only IDs supported by your Lavalink server/plugins.

LavaSrc reference (supported URLs & queries): https://github.com/topi314/LavaSrc?tab=readme-ov-file#supported-urls-and-queries

`🚀` Installation (Local)

Clone repository:

git clone https://github.com/adh319/Lunox.git
cd Lunox

Install dependencies:

npm install

Configure environment:

cp .env.example .env

Windows PowerShell:

Copy-Item .env.example .env

Fill all required keys in .env
Configure developer IDs in src/settings/config.js
Start Lavalink + MongoDB
Start the bot:

npm start

`🐳` Installation (Docker)

This repository includes:

Dockerfile for the bot image
docker-compose.yml for bot + MongoDB

Important

Lavalink is external in current compose setup.
Set LAVALINK_HOST to your Lavalink host (host.docker.internal is used as compose default).

Run

docker compose up -d --build

Stop

docker compose down

`🔐` Permissions Needed

At minimum, ensure the bot can:

ViewChannel
SendMessages
EmbedLinks
ReadMessageHistory
Connect
Speak

For stage channels, also allow:

RequestToSpeak
PrioritySpeaker

`🧪` Troubleshooting

Bot offline: verify TOKEN and intents in Discord Developer Portal
No music playback: verify Lavalink host/port/password/driver and Java/Lavalink logs
Autoplay not working: autoplay currently depends on YouTube track context
Leaves VC too quickly: increase LEAVE_TIMEOUT or enable /247
No DB persistence: verify MONGO_URI connectivity
Missing debug output: set DEBUG=true

💖 Support the Project

If you find Lunox useful, consider supporting continued development:

GitHub Sponsors — https://github.com/sponsors/adh319
PayPal — https://paypal.me/LunoxBot
Ko-fi — https://ko-fi.com/lunoxbot

`🤖` Bots Using This Source Code

If you're using this source code and want your bot listed below, submit a pull request by editing the table with your details:

| No. | Bot Name | Invite Link | Su

Lunox

Install / Use

README

`🧭` Table of Contents

`⚡` Quick Start

`📢` Main Features

`📌` Requirements

`🎛️` Command Overview

Prefix Commands (Developer / Ops)

`🔧` Environment Variables

General

Lavalink Connection

Rainlink Search

`⚙️` Configuration Notes

1) Developer IDs

2) Emoji Mapping

3) Lavalink Source IDs

`🚀` Installation (Local)

`🐳` Installation (Docker)

Important

Run

Stop

`🔐` Permissions Needed

`🧪` Troubleshooting

💖 Support the Project

`🤖` Bots Using This Source Code

Lunox

Install / Use

README

🧭 Table of Contents

⚡ Quick Start

📢 Main Features

📌 Requirements

🎛️ Command Overview

Prefix Commands (Developer / Ops)

🔧 Environment Variables

General

Lavalink Connection

Rainlink Search

⚙️ Configuration Notes

1) Developer IDs

2) Emoji Mapping

3) Lavalink Source IDs

🚀 Installation (Local)

🐳 Installation (Docker)

Important

Run

Stop

🔐 Permissions Needed

🧪 Troubleshooting

💖 Support the Project

🤖 Bots Using This Source Code

`🧭` Table of Contents

`⚡` Quick Start

`📢` Main Features

`📌` Requirements

`🎛️` Command Overview

`🔧` Environment Variables

`⚙️` Configuration Notes

`🚀` Installation (Local)

`🐳` Installation (Docker)

`🔐` Permissions Needed

`🧪` Troubleshooting

`🤖` Bots Using This Source Code