Command	What it does
`/hello`	Sanity-check greeting
`/say <message>`	Bot repeats your message
`/rolldice [sides]`	Roll a die (default 6 sides)
`/armeter`	Measures your "AR" percentage (just for laughs)
`/play <query>`	Play or queue a track/playlist by URL, or search text (YouTube)
`/skip`	Skip the current track
`/queue`	Show the queue as a paginated embed (◀/▶ buttons)
`/loop [queue\|song\|off]`	Loop playback. Bare `/loop` toggles looping the whole queue; `song` loops just the current track; `off` stops looping
`/clear`	Clear the queue (keeps the current track playing)

How it works

The bot is just a Lavalink client — actual audio is streamed by a separate Lavalink v4 server that runs alongside it (started with Docker). YouTube support comes from the youtube-plugin, configured in lavalink/application.yml.

Bot: Java + Gradle (JDA 6, lavalink-client)
Music server: Lavalink v4 via docker-compose.yml

Requirements

A recent JDK (Java 17+; use the latest LTS if the build complains)
Docker + Docker Compose (to run the Lavalink server)
A Discord bot token

Configuration

Copy the example env file and fill in your values:

cp .env.example .env

Variable	Required	Description
`BOT_TOKEN`	✅	Discord bot token (Developer Portal → your app → Bot)
`GUILD_ID`	optional	Test server ID for instant command registration. If unset, commands register globally (can take up to an hour)
`LAVALINK_URI`	optional	Defaults to `ws://localhost:2333` for local runs. In `docker-compose.yaml` the bot is pointed at `ws://lavalink:2333` (the service name)
`LAVALINK_PASSWORD`	✅	Shared secret between the bot and the Lavalink server. Compose passes the same value to the server as `LAVALINK_SERVER_PASSWORD`, so they always match. The bot exits if it's unset

.env is gitignored, so your token stays local.

Running

./gradlew run reads real environment variables — it does not auto-load .env. So load it into your shell first.

# 1. Start the Lavalink server (first run downloads the YouTube plugin; wait for "ready")
docker compose up -d
docker compose logs -f            # wait for "Lavalink is ready to accept connections", then Ctrl+C

# 2. Load your .env and run the bot
set -a; source .env; set +a
./gradlew run

When it connects you'll see Bot connected and ready as ... in the console. Then join a voice channel in your server and try /play <song or url>.

TODO — steps to get it running

Install a JDK (17+) and Docker
Create a Discord application + bot, and copy the bot token
Invite the bot to your server with the bot and applications.commands scopes (and the Connect + Speak voice permissions)
Enable Developer Mode in Discord and copy your server's Guild ID
cp .env.example .env and fill in BOT_TOKEN (and GUILD_ID)
Start Lavalink: docker compose up -d and wait until the logs say it's ready
Load env vars: set -a; source .env; set +a
Run the bot: ./gradlew run
In Discord, run /hello to confirm it responds, then /play from a voice channel

Run with Docker (prebuilt image)

If you'd rather not build from source, docker-compose.yaml pulls the prebuilt bot image and runs it alongside Lavalink. You only need Docker — no JDK.

Create your config and the files the bot reads at runtime, next to the compose file:
```
cp .env.example .env        # then fill in BOT_TOKEN and LAVALINK_PASSWORD
```
Make sure catchphrases.txt, always100.txt, and always90.txt exist as files here. They're mounted into the container — if any is missing, Docker creates an empty directory in its place and the mount breaks.

Pull and start both services:

docker compose pull        # fetch the bot + Lavalink images
docker compose up -d       # start in the background
docker compose logs -f     # watch logs; look for "Bot connected and ready as ..."
docker compose down        # stop

The bot connects to Lavalink over the internal Docker network automatically, so you don't set LAVALINK_URI yourself here.

Notes

Queue state is kept in memory, so it resets if the bot restarts.
YouTube occasionally breaks playback when Google changes its player. The fix is usually bumping the youtube-plugin version in lavalink/application.yml and restarting the server.