# Botinator

A hobby Discord bot for personal use. It's a small [JDA](https://github.com/discord-jda/JDA)
bot with a few fun slash commands and music playback powered by
[Lavalink](https://github.com/lavalink-devs/Lavalink).

> Personal project — not intended as a polished, general-purpose bot.

## Commands

| 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:

```bash
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` (matches `docker-compose.yml`) |
| `LAVALINK_PASSWORD` | optional | Defaults to `youshallnotpass` (matches `lavalink/application.yml`) |

`.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.

```bash
# 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

## 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.