From 076e616b9c7a5cc661b163ba611bd71a662afb06 Mon Sep 17 00:00:00 2001 From: FernandoJVideira <03.pleaser-minster@icloud.com> Date: Wed, 18 Mar 2026 03:57:32 +0000 Subject: [PATCH] feat: readme --- README.md | 97 ++++++++++++++++++++++++++++++ internal/commands/help/help.go | 107 +++++++++++++++------------------ 2 files changed, 147 insertions(+), 57 deletions(-) create mode 100644 README.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..2a01daf --- /dev/null +++ b/README.md @@ -0,0 +1,97 @@ +# Velox Bot + +A Discord bot written in Go with a PostgreSQL backing store. + +It currently includes: + +- Fun commands (`/ping`, `/joke`, `/dice`, `/rps`, …) +- Leveling system (opt-in per server via `/slvl toggle`) +- Meeting rooms (voice lobby → auto-created temporary voice channels) +- Scheduling (1:1 sessions with DM invites + reaction-based accept/decline/reschedule) +- Projects (list/create projects + helpers) +- Music (Lavalink-powered `/play`, `/queue`, `/volume`) + +## Requirements + +- Go (see `go.mod`) +- PostgreSQL 16+ (or use the provided `docker-compose.yml`) +- (Optional) [Air](https://github.com/air-verse/air) for live reload during development +- (Optional) Lavalink if you want music commands + +## Configuration + +The app loads environment variables from `.env` (see `internal/config/config.go`). + +Required: + +- `BOT_TOKEN`: Discord bot token +- `APP_ID`: Discord application ID +- `GUILD_ID`: Target guild/server ID (commands are registered per-guild) +- `DB_HOST`: Postgres connection string (pgx), e.g. `postgres://velox:velox_pwd@localhost:5432/velox?sslmode=disable` + +Optional (music): + +- `LAVALINK_HOST`: Lavalink WebSocket/HTTP host (depends on your Lavalink setup) +- `LAVALINK_PASSWORD`: Lavalink password + +## Database setup + +If you use the compose file: + +```bash +docker compose up -d +``` + +Then apply the schema: + +```bash +psql "postgres://velox:velox_pwd@localhost:5432/velox?sslmode=disable" -f schema.sql +``` + +## Run + +Plain Go: + +```bash +go run . +``` + +With live reload (Air): + +```bash +air +``` + +If you use `just`, a small workflow is included: + +```bash +just up # start postgres +just start # start postgres + run air +just down # stop postgres +``` + +## Commands (high-level) + +- **Fun** + - `/ping`, `/joke [type]`, `/coinflip`, `/dice ` + - `/rps `, `/rpsstats`, `/rpsleaderboard` (server only) +- **Help** + - `/help` (sends a DM with command reference) +- **Leveling** + - `/slvl ...` admin/config + - `/rank`, `/leaderboard`, `/rewards` +- **Meetings** (**Manage Server**) + - `/meeting set-lobby`, `/meeting lock`, `/meeting lock-private`, `/meeting unlock`, `/meeting invite`, `/meeting uninvite` +- **Timezone** + - `/timezone set`, `/timezone show` +- **Scheduling** + - `/schedule create`, `/schedule list`, `/schedule reschedule` +- **Projects** + - `/projects list`, `/projects create`, `/projects add-helper` +- **Music** (requires **DJ** role) + - `/play`, `/queue`, `/volume` + +## Notes + +- Slash commands are registered to the configured `GUILD_ID` on startup. +- Some features require server permissions (e.g. **Manage Server**) or roles (e.g. **DJ** for music). diff --git a/internal/commands/help/help.go b/internal/commands/help/help.go index b259579..b090c68 100644 --- a/internal/commands/help/help.go +++ b/internal/commands/help/help.go @@ -42,80 +42,73 @@ func HelpHandler(s *discordgo.Session, i *discordgo.InteractionCreate) { embed := &discordgo.MessageEmbed{ Title: "Velox Bot Help", - Description: "Here is the help for the bot.", + Description: "Command reference. Some commands require server permissions or roles.", Color: 0xFFA500, Fields: []*discordgo.MessageEmbedField{ { - Name: "Fun Commands", - Value: "Small utility + games.", + Name: "Fun", + Value: "" + + "`/ping` — Pong!\n" + + "`/joke [type]` — Random joke (optional category)\n" + + "`/coinflip` — Flip a coin\n" + + "`/dice ` — Roll dice (e.g. `d20`, `2d20+1`, `2#d20+1`)\n" + + "`/rps ` — Rock Paper Scissors (server only)\n" + + "`/rpsstats` — Your RPS score (server only)\n" + + "`/rpsleaderboard` — Top RPS scores (server only)", }, { - Name: "/ping", - Value: "Pong!", + Name: "Music (requires **DJ** role)", + Value: "" + + "`/play ` — Play a song (search or URL)\n" + + "`/queue` — Show the current queue\n" + + "`/volume <0-150>` — Set playback volume", }, { - Name: "/joke [type]", - Value: "Get a random joke (optional category).", + Name: "Scheduling (1:1 sessions)", + Value: "" + + "`/schedule create user:@someone datetime:\"YYYY-MM-DD HH:MM\" [description]` — Create a session\n" + + "`/schedule list` — List your upcoming sessions\n" + + "`/schedule reschedule id: datetime:\"YYYY-MM-DD HH:MM\"` — Request a new time\n\n" + + "Invites are sent via DM; react with ✅ / ❌ / 🔁 to respond.", }, { - Name: "/coinflip", - Value: "Flip a coin.", + Name: "Timezone", + Value: "" + + "`/timezone set ` — Set your timezone (e.g. `Europe/Lisbon`)\n" + + "`/timezone show` — Show your timezone", }, { - Name: "/dice ", - Value: "Roll dice expressions (e.g. `d20`, `2d20+1`, `2#d20+1`).", + Name: "Projects", + Value: "" + + "`/projects list` — List active projects\n" + + "`/projects create name:\"...\" [description]` — Create a project (**Manage Server**)\n" + + "`/projects add-helper project-id: user:@someone` — Add helper (**Manage Server**)", }, { - Name: "/rps ", - Value: "Play Rock Paper Scissors (server only).", + Name: "Meetings (**Manage Server**)", + Value: "" + + "`/meeting set-lobby channel:#voice` — Set voice lobby used to create meetings\n" + + "`/meeting lock` — Lock your meeting room\n" + + "`/meeting lock-private` — Lock + hide your meeting room\n" + + "`/meeting unlock` — Unlock your meeting room\n" + + "`/meeting invite user:@someone` — Allow a user to join\n" + + "`/meeting uninvite user:@someone` — Remove a user's permission", }, { - Name: "/rpsstats", - Value: "Show your RPS score (server only).", + Name: "Leveling", + Value: "" + + "`/slvl toggle` — Enable/disable leveling (**Manage Server**)\n" + + "`/slvl set user:@someone level:` — Set user level (**Manage Server**)\n" + + "`/slvl set-channel channel:#channel` — Level-up message channel (**Manage Server**)\n" + + "`/slvl set-message message:\"...\"` — Custom level-up message (**Manage Server**)\n" + + "`/slvl set-reward level: role:@role` — Role rewards (**Manage Server**)\n" + + "`/rank [user]` — Your rank card (server only)\n" + + "`/leaderboard` — Top levels (server only)\n" + + "`/rewards` — List configured rewards (server only)", }, { - Name: "/rpsleaderboard", - Value: "Show top RPS scores (server only).", - }, - { - Name: "/help", - Value: "Get help with the bot.", - }, - { - Name: "Leveling System", - Value: `The leveling system is a system that allows users to gain XP and level up. The system is based on the amount of messages sent in a server. The more messages you send, the more XP you gain. The more XP you gain, the higher your level will be. The leveling system is disabled by default, however you can enable/disable it by using the /slvl toggle command. You can also configure the leveling system by using the /slvl command.`, - }, - { - Name: "/slvl toggle", - Value: "Toggle the leveling system.", - }, - { - Name: "/slvl set", - Value: "Set the level of a user.", - }, - { - Name: "/slvl set-channel", - Value: "Set the channel for level-up messages.", - }, - { - Name: "/slvl set-message", - Value: "Set the custom level-up message.", - }, - { - Name: "/slvl set-reward", - Value: "Set a role reward for a level.", - }, - { - Name: "/rank [user]", - Value: "Show a rank card (server only).", - }, - { - Name: "/leaderboard", - Value: "Show top levels (server only).", - }, - { - Name: "/rewards", - Value: "List configured level rewards (server only).", + Name: "Other", + Value: "`/help` — Show this help in DMs", }, }, Author: &author,