Lunox

Shard-ready Discord music bot powered by Rainlink, Lavalink, and Discord.js v14.

[![Version][version-shield]](version-url) [![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]](#-requirements) [![Discord.js][discordjs-shield]](https://discord.js.org/#/docs/discord.js/main/general/welcome) [![Rainlink][rainlink-shield]](https://www.npmjs.com/package/rainlink)

`⚡` 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	Support Server
`1`	Jive	Invite Link	Jive Corner
`2`	Xyvo	Invite Link	Xyvo
`3`
`4`

`🤝` Contributing

Contributions are welcome.

Read CONTRIBUTING.md for contribution flow and standards.
Open an issue before major changes.
Keep pull requests focused and clearly described.

`👥` Contributors

`🔐` License

This project is licensed under the MIT License.

You are free to use and modify the code, but include attribution to the original repository:

© 2024 adh319@github. This project is available under the MIT License.
You must include proper attribution by linking to: https://github.com/adh319/Lunox

Made by adh319
_{Lunox Discord Music Bot • Built for Excellence}

This site is open source. Improve this page.

Lunox

🧭 Table of Contents

⚡ Quick Start

📢 Main Features

📌 Requirements

🎛️ Command Overview