123 lines
5.1 KiB
Markdown
123 lines
5.1 KiB
Markdown
# 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.yaml`
|
|
|
|
## Requirements
|
|
|
|
- A JDK (builds on Java 17+; CI and the Docker image use Java 25)
|
|
- 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` 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.
|
|
|
|
```bash
|
|
# 1. Start ONLY the Lavalink server — not the bot container — so it doesn't clash
|
|
# with the bot you're running from source. (First run downloads the YouTube
|
|
# plugin; wait for "ready".)
|
|
docker compose up -d lavalink
|
|
docker compose logs -f lavalink # 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
|
|
```
|
|
|
|
> `docker compose up -d` (no service name) would start the **bot container too**,
|
|
> giving you two bots. For source development, always pass `lavalink` explicitly.
|
|
|
|
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`, `LAVALINK_PASSWORD` (and `GUILD_ID`)
|
|
- [ ] Start Lavalink only: `docker compose up -d lavalink` 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.
|
|
|
|
1. Create your config and the files the bot reads at runtime, next to the compose file:
|
|
|
|
```bash
|
|
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.
|
|
|
|
2. Pull and start both services:
|
|
|
|
```bash
|
|
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.
|