velox-bot/docs/features.md

Features

What each module does and how it behaves. For the exact options of every command, see the Command reference. To change how a module works, see the Development guide.

Unless a section says otherwise, a module is off in a new server and a server admin turns it on.

Security

Anti-raid and anti-nuke, modelled on Wick. Code: internal/security, commands in internal/commands/security.

Join Gate checks every new member: no avatar, account too new, invite links or blocked words in the name, unverified bots. Each check has its own action. It also removes bots added by anyone who is not trusted.

Raid mode starts when many members join in a short time. Raiders are timed out, kicked or banned, invites can be paused, staff are alerted, and raid mode ends after a quiet period or when staff end it with /security end-raid. It survives a bot restart: the quiet timer carries on and the summary still lists everyone caught.

Anti-nuke counts destructive actions per person from the audit log: deleting channels or roles, mass bans and kicks, creating webhooks, granting dangerous permissions. Someone who is not the owner or trusted and goes over a limit is quarantined: their roles are removed and saved, and they are timed out. /security release gives every role back.

Lockdown (/lockdown, /unlock) locks one channel, every channel, or joins. Unlocking puts back exactly the permission overwrite that was there before.

Snapshots save the server's roles and channels. They are taken every 6 hours while anti-nuke is on (the last three are kept) and on request with /security snapshot. /security restore recreates deleted roles and channels and reverts dangerous permission changes. It can also run automatically after a stopped nuke.

Heat is the anti-spam system. Each member has a score that rises with messages and cools over time. Spam, repeats, mass mentions and invite links max it, which deletes the message and times the member out (the timeout doubles for repeat offences). A wave of spammers turns on heat panic (newcomers are timed out on sight for 10 minutes), and a mention flood can lock the server. Members with Manage Messages and trusted members are exempt.

Alerts go to a channel you choose, and critical ones (raids, stopped nukes, restores, spam waves, removed bots) are also DMed to the owner and trusted users, because the alert channel may be the first thing a nuker deletes. One setting turns the DMs off.

Rules that hold everywhere in this module:

• Turning protection off, changing limits, releasing a quarantine and unlocking need the server owner or someone on the trusted list. Editing the trusted list needs the owner. Discord's own command permissions are never relied on, because admins can change them.
• The owner and the bot are never punished.
• Roles that are configured (such as the quarantine role) are checked when they are used, not only when saved. A quarantine role that gained dangerous permissions is not assigned.
• Messages ping only the configured alert role, and names are escaped.

Thresholds, Join Gate filters and heat settings are set on the dashboard. The bot's role must be above the roles it protects against: it can only quarantine members whose highest role is below its own.

Tickets

Support tickets in private threads. Code: internal/tickets, commands in internal/commands/tickets.

1. An admin runs /tickets setup, adds categories with /tickets category add (each with its own staff role), and posts the panel with /tickets panel.
2. The panel has a category dropdown and a Create ticket button. A short form asks what the ticket is about.
3. A private thread is created in the ticket channel. The opener and the category's staff role can see it.
4. Staff can /ticket claim. Anyone involved can /ticket add someone, staff can /ticket remove, and the opener or staff can /ticket close [reason].
5. Closing locks and archives the thread and posts a transcript to the log channel.

The bot needs View Channel, Send Messages, Embed Links, Create Private Threads, Send Messages in Threads and Manage Threads in the ticket channel, and Attach Files in the log channel. Give the staff role Manage Threads there too, so staff see every ticket.

The flows go through small interfaces for Discord and the database, so they are tested without either. The slash commands and buttons only translate interactions into those calls.

Moderation

/moderation with purge, timeout, kick, ban, unban, untimeout and slowmode. Each subcommand checks the matching Discord permission in the handler (Manage Messages, Moderate Members, Kick Members, Ban Members, Manage Channels). Durations accept 10m, 1h, 2h30m and so on, up to 28 days. Actions are written to the log channel if logging is on.

Logging

When enabled with /config enablelogging and a channel set with /config setlogchannel, the bot logs edited and deleted messages, joins and leaves, member and role updates, bans and unbans, and moderation actions. Code: internal/events/logging.go and internal/modlog.

Leveling

Opt in per server with /slvl toggle. Code: internal/db/services/level (the rules) and internal/events/event_handlers.go (the message handler).

• Every message may give 1 to 3 XP. Below level 5 every message counts. From level 5 on, a message counts with a chance of 1 in level / 4, so leveling slows down.
• 100 XP makes a level, and XP resets to 0.
• A level-up posts the level-up message (set with /slvl set-message, variables {user} and {level}) in the channel chosen with /slvl set-channel, or in the channel of the message.
• /slvl set-reward gives a role at a level. /rank draws a rank card (internal/rankcard), /leaderboard shows the top 10 and /rewards lists role rewards.

Music

Lavalink-powered playback. Code: internal/music, commands in internal/commands/music.

• /play takes a name or a URL, /queue shows the queue, /volume sets 0 to 150 percent. These need a role called DJ.
• The now-playing message has buttons for playback and repeat. Buttons also check for the DJ role.
• /music toggle (Manage Server) turns music on or off in a server.
• The dashboard shows the queue and can control playback. It does so through the music_commands table and a NOTIFY (see Database).
• Music needs a Lavalink server. Without LAVALINK_HOST the rest of the bot works and music does not.

Meeting rooms

Join a lobby voice channel and get your own temporary room. Code: internal/events/meeting_voice.go, commands in internal/commands/meeting.

• A server can have up to 10 lobbies (/meeting add-lobby, remove-lobby, lobbies). The limit is enforced by a database trigger, so the bot and the dashboard obey the same rule.
• When someone joins a lobby, the bot creates a voice channel in the same category with the lobby's user limit and bitrate, named after the lobby and the time, and moves the member in.
• When the temporary room is empty, it is deleted.
• If a lobby channel is deleted in Discord, it is dropped from the lobbies.
• /meeting lock, lock-private (also hides the room), unlock, invite and uninvite act on the room you are in. Every /meeting subcommand, including these, currently needs Manage Server.

Scheduling and timezones

1:1 sessions between two members. Code: internal/commands/schedule, internal/db/services/schedule, reminders in internal/events/schedule_reminders.go.

• Each member sets a timezone with /timezone set (an IANA name such as Europe/Lisbon).
• /schedule create opens a form (date, time in your timezone, optional description) and DMs the other member a request with Accept, Decline and Propose different time buttons.
• /schedule list shows your upcoming sessions, and /schedule reschedule proposes a new time (in UTC, 2006-01-02 15:04). The other side can accept or decline the proposal.
• Every minute, a loop DMs the participants of sessions starting within 10 minutes.

Projects

A simple list of ongoing projects. /projects create opens a form (name, optional description), /projects list shows active projects with creators and helpers, /projects add-helper and /projects close manage them. Creating, adding helpers and closing need Manage Server.

Welcome messages and default role

Set up with /config (Manage Server). Code: internal/events/welcome.go.

• A welcome message in a channel, and an optional DM, both templates where {user} becomes a mention and {server} the server name. An optional GIF or image URL goes in the welcome embed.
• A default role is granted when a member joins.
• Bots are skipped, and members the security engine removes get nothing.

Twitch alerts

/config addstreamer, removestreamer and settwitchnotificationchannel (Manage Server). Every 30 seconds a loop checks each configured streamer and posts in the notification channel when one goes live. Code: internal/events/twitch_live.go. It needs TWITCH_CLIENT_ID.

Onboarding

When the bot is added to a server, it applies safe defaults (modules off) and DMs setup instructions to the person who invited it, falling back to the server owner. Code: internal/events/onboarding.go.

Fun

/ping, /joke [type], /coinflip, /dice (expressions like d20, 2d20+1, 2#d20+1, parsed in internal/diceexpr), and /rps with /rpsstats and /rpsleaderboard.

Help

/help DMs a command reference. The text is hand-written in internal/commands/help/help.go, so update it when you add or change a command.