Technical Documentation

Guides for setup, installation, configurations, and core codebase architectures. Select your bot below.

Overview

Snax is a high-performance, robust, and clean Discord music bot built on top of Discord.js v14. It utilizes Lavalink (via the Kazagumo wrapper and Shoukaku connector) to deliver ultra-low latency, crystal-clear audio streaming.

By offloading audio decoding and streaming tasks to a dedicated Lavalink node, Snax achieves maximum resource efficiency, stability, and zero stuttering, even when playing large playlists. It supports hybrid controls: classic prefix commands (default: $) and modern Application slash (/) commands.

Primary Function: Dedicated Music Playback & Controller UI

Default Prefix: $ (customizable per-server using $setprefix)

Project Structure

Snax-Bot/
├── index.js                  — App bootstrap and client login
├── config/
│   ├── config.json           — Default configuration settings
│   ├── config.js             — Environment wrapper merging config with .env
│   ├── slashOptionsMap.js    — Options layout for slash commands
│   └── activity.json         — Status activity definitions
├── lavalink_music/           — Music sub-system module
│   ├── commands/             — Music command script executors (13 commands)
│   ├── events/               — Lavalink Node and player event listeners
│   ├── embeds.js             — UI Builders for playback controller embeds
│   ├── interaction.js        — Controller button component interaction handlers
│   └── player.js             — Connection configurations and Kazagumo player manager
├── events/                   — Client-wide Discord gateway events
├── utils/                    — Core utilities
│   ├── antiSpam.js           — rolling-window spam prevention algorithm
│   ├── serverLogger.js       — Auditing channel creation & log logger
│   ├── globalLogger.js       — Home server log manager (tracks bot status)
│   ├── logger.js             — Colorized terminal logging utilities
│   ├── slashDeploy.js        — Slash commands publisher API
│   └── voiceCheck.js         — Voice channel state validator
├── install.bat               — 1-click Windows installer script
└── setup_mac.sh              — 1-click macOS/Linux installation script

Setup & Installation

Prerequisites

Installation Steps

  1. Run Setup script:
    - Windows: Double-click install.bat
    - macOS/Linux: Run bash setup_mac.sh in terminal
  2. Configure `.env` settings: Configure your secret tokens and Lavalink node details in the newly created .env file (see Configuration section).
  3. Start the bot: Execute node index.js in the console.

Configuration

Environment Secrets (.env)

Bot_Token=YOUR_DISCORD_BOT_TOKEN
OWNER_ID=YOUR_USER_ID
LAVALINK_HOST=LAVALINK_NODE_IP_OR_HOST
LAVALINK_PORT=LAVALINK_NODE_PORT
LAVALINK_PASSWORD=LAVALINK_NODE_PASSWORD
LAVALINK_SECURE=true_OR_false

Runtime Settings (config/config.json)

FieldDefaultDescription
prefix"$"Default prefix for text commands.
defaultVolume100Starting volume scale (0-100).
leaveOnEmptytrueLeave VC when all other members disconnect.
leaveOnEmptyCooldown30000Cooldown in ms before leaving empty VC.
leaveOnEndfalseLeave VC when the queue finishes.
selfDeaftrueDeafens the bot to reduce bandwidth.
embed.color"#5865F2"Primary hex color used for rich embeds.

Music System (Lavalink)

The music system runs independently inside the lavalink_music/ subsystem, leveraging Shoukaku and Kazagumo wrappers. This architecture abstracts node management and queue handling.

Audio Playback Pipeline

  • Command: The user executes $play <query>.
  • VC Check: voiceCheck.js ensures the member and bot are in compatible voice channels.
  • Player Resolve: Retrieves the existing player instance or initializes one using player.createPlayer().
  • Track Search: Kazagumo queries Lavalink. If a playlist is resolved, all tracks load. YouTube Shorts are converted automatically.
  • Lavalink Streaming: Lavalink decodes and streams the track directly to Discord's voice servers, avoiding server CPU bottle-necking.

Interactive Controller Cards

When a track begins playing, the bot sends an embed controller interface. Users can interact via buttons:

  • ⏯️ Play/Pause: Toggles current track pause state.
  • ⏭️ Skip: Plays the next queued song.
  • ⏹️ Stop: Clears queue, stops player, and disconnects.
  • 🔄 Loop/LoopQ: Loops track or loop queue.
  • 🔀 Shuffle: Re-orders the queue.
  • ➕ Autoplay: Automates endless queue generation.

Anti-Spam System

An in-memory rolling 10-second window tracks message frequency. If a user exceeds threshold limits executing commands, the bot penalizes them.

User TierWarning (10s)Timeout Penalty (10s)
Normal User4 commands7 commands (2-minute timeout)
BypassExe Holders15 commands20 commands (2-minute timeout)
SupBypass / Admins / OwnersImmuneImmune (No limits applied)

Event Reference

Discord Client Gateway Events

  • ready: Establishes activity presence; fetches application owner ID dynamically.
  • messageCreate: Evaluates prefix/mentions, runs anti-spam filters, checks default command group mappings, and executes commands.
  • interactionCreate: Handles slash commands and interactive buttons.
  • guildCreate: Automatically establishes a private #snax-log channel on server entry.

Lavalink Player Lifecycle Events

  • playerStart: Fires when a track begins, dispatching the controller embed interface.
  • playerEmpty: Fires when the queue ends, alerting the text channel.
  • error: Logs node connection exceptions.

Utility Modules

  • utils/permissions.js: Handles local prefix cache settings. Sets up default group access (which maps @everyone for music).
  • utils/antiSpam.js: Rate-limiting tracker maps.
  • utils/serverLogger.js: Establishes private channel logging workflows.
  • utils/voiceCheck.js: Ensures users are in a voice channel before sending playback instructions.

Dependencies

PackageRequired VersionPurpose
discord.js^14.26.4Core Discord gateway API integration
dotenv^17.4.2Loads variables from local .env environment
kazagumo^3.4.3Lavalink queue controller & track parser
shoukaku^4.3.0Lavalink WebSocket wrapper connector

Notes & Limitations

  • Voice State Permissions: Ensure your bot application has the Privileged Voice State Intent enabled in the Discord Developer Portal, alongside Message Content.
  • Lavalink Node: Snax relies on an active Lavalink server node. If the node falls offline, music commands will fail with connection exception logs.

Overview

Musico is a highly modular, security-focused Discord bot built with discord.js v14. It integrates a robust member onboarding/verification workflow system, custom Role-Based Access Control (RBAC) permission database, server moderation tools, voice channel management utilities, and proactive anti-spam protection — all operating from a lightweight, local file-based data engine.

Primary Function: Granular Administration, Verification, and Moderation

Default Prefix: ! (customizable per-server using !setprefix)

Project Structure

musico/
├── index.js                  — Entry point. Loads handlers and client login
├── package.json              — Node project definition
├── README.md                 — High-level summary guide
├── validate_bot.js           — Automated procedure auditing commands & permissions
├── .env                      — Hidden credential settings (tokens, owners)
├── config/
│   ├── config.json           — Configurations (prefix, onboarding strictness, questions)
│   └── config.js             — Loader merging config.json with .env values
├── handlers/
│   ├── commandHandler.js     — Dynamically loads commands/ files
│   └── eventHandler.js       — Dynamically registers events/ files
├── commands/                 — Directory housing the 40 individual commands
├── events/                   — gateway trigger handlers (guildMemberAdd, interactionCreate...)
├── utils/
│   ├── permissions.js        — RBAC DB manager, prefix configuration, hierarchy check
│   ├── permissionCommandHelper.js — Resolves targets and updates group assignments
│   ├── antiSpam.js           — Command rate-limiter, warnings, auto-timeouts
│   ├── serverLogger.js       — Creates & logs rich embeds to #snax-log
│   ├── logger.js             — Local terminal console log coloring
│   └── verification.js       — Questionnaires, verification chats, rules agreements
└── data/
    └── permissions.json      — Local database containing each server's settings

Setup & Installation

Prerequisites

  • Node.js v18 or higher
  • Gateway Intents: Enable Message Content Intent and Server Members Intent in your Discord Developer Portal application settings.

Setup Workflow

  1. Install project dependencies: npm install.
  2. Create a .env file in the project root: 
    Bot_Token=YOUR_DISCORD_BOT_TOKEN
OWNER_ID=YOUR_USER_ID
HOME_SERVER_ID=YOUR_HOME_SERVER_ID
  3. Audit command configurations and registrations: 
    npm run validate
  4. Run the bot application: npm start (or node index.js).

Configuration System

The configuration loader (config/config.js) dynamically merges environmental variables inside .env with options configured in config/config.json.

Verification Questionnaire Config

Inside config.json, the verification block defines the onboarding rules and multiple-choice questions structure:

"verification": {
  "strictness": "HIGH",
  "verifiedRole": "Verified",
  "verificationChannel": "verify-here",
  "rulesChannel": "rules",
  "questions": [
    {
      "id": "rules_agree",
      "type": "button",
      "question": "Do you agree to respect server rules?",
      "options": ["Yes, I agree", "No"],
      "correctAnswer": "Yes, I agree"
    }
  ]
}

Permission System (RBAC)

Permissions are checked dynamically from local JSON storage using hierarchy rules.

Hierarchy Resolution (Highest to Lowest)

  1. Bot Owner: Full bypass (bypasses spam, commands, rules checks).
  2. Server Owner: Absolute bypass inside their guild.
  3. AdminExe Holders: Bypass all command execution permissions.
  4. Explicit Group Mappings: Matches user or role IDs inside the command's designated permission group.
  5. Default Group: Matches if the group contains @everyone.
  6. Denied: Execution rejected, warns the user.

Permission Groups & Inheritance

GroupAccess Scope
DefaultGeneral utilities (ping, help, hello).
VoiceExeVoice state modifications (mute, deafen, dragreq, addme).
setNickExeNickname modifications (setnick, remnick).
ChatExeLocal chat moderation (purge, timeout).
ManagerExeBans, kicks, unbans. Can allocate lower permissions.
AdminExeAdministrative configurations, prefixes, verification, promotions.

Security Cooldown Delay (pendingAdminExe)

To protect servers from rogue staff accounts, assigning a user or role to the AdminExe group does not grant permissions instantly. Instead:

  • The target is cached in pendingAdminExe in permissions.json.
  • A 10-minute cooldown timer is initiated.
  • The user must wait 10 minutes before their first subsequent command check activates their full AdminExe role privileges.
  • AdminExe assignments can be revoked immediately (clearing the delay state).

Anti-Spam System

Monitors command triggers within a rolling 10-second window. Spam violations result in timeouts.

  • Normal Users: 4 commands triggers a Warning (auto-deleted in 5 seconds). 7 commands triggers a 2-minute timeout penalty.
  • BypassExe Users: 15 commands triggers warning, 20 triggers timeout.
  • Immunity: Server Owners, Bot Owner, AdminExe, ManagerExe, and SupBypass group holders bypass all rate-limits.

Onboarding Verification

Protects server entries against automated spammers. Strictness levels determine member join flows:

  • OFF: Onboarding disabled.
  • LOW: Welcomes member and auto-assigns the verified role.
  • MEDIUM: Rules agreement button posted. Clicking rules button grants role.
  • HIGH: Creates temporary private channel #verify-username. Member clicks button to launch a questionnaire. Correct answers grant verified role; incorrect answers prompt "Retry". Channel deletes after 10-second countdown.
  • STRICT: Follows HIGH mode. Upon quiz completion, results are forwarded to #snax-log with [Approve] and [Deny] button panels. Staff must manually approve access.

Server Logging (#snax-log)

Audit system tracking internal security actions. The bot automatically creates a private text channel named snax-log if it is missing.

Logged Events: Permission assignments/revocations, cooldown queues, timeout infractions, questionnaire logs, staff approvals/denials, and exception stack traces.

Event Reference

  • ready: Loads client application details and parses bot owner ID.
  • messageCreate: Parses prefix command targets, manages anti-spam limits, audits client authorizations, and executes commands.
  • guildCreate: Configures default DB options on joining new servers.
  • guildMemberAdd: Captures incoming members and starts the verification flow.
  • interactionCreate: Evaluates verification button responses and help menu category selection dropdowns.

Utility Modules

  • utils/permissions.js: Integrates local data reads and writes to permissions.json.
  • utils/verification.js: Handles questionnaire prompts, private channel generation, role assignments, and approval panel embeds.
  • utils/antiSpam.js: Monitors command execution timestamps.

Adding New Commands

  1. Create a new script file inside commands/.
  2. Implement standard command exports containing name, description, and async execute(message, args, client, config).
  3. Map the command name to a specific permission group in COMMAND_GROUPS inside utils/permissions.js (if omitted, defaults to OwnerOnly).
  4. Verify structure using npm run validate and restart.

Dependencies

  • discord.js (v14.15.3 or higher)
  • dotenv (v16.4.5 or higher)

Troubleshooting & FAQ

Q: Why is my AdminExe candidate pending?
A: This is a security delay. Cooldown runs for 10 minutes. The candidate gets full permissions upon executing a command after the cooldown expires.

Q: Verification HIGH/STRICT mode does not assign roles or channels.
A: Ensure the bot role has "Manage Channels" and "Manage Roles" enabled. The bot's role hierarchy must sit above the role configured to be assigned to verified members.