OreoBot Wiki

Requirements

Before running OreoBot, make sure you have the following installed and configured:

First-Time Setup

Copycp config.example.json config.json

Copygo build -o oreobot .
./oreobot

# Or run directly:
go run .

Running the Bot

On startup OreoBot performs the following in order:

config.json — Full Reference

Every field in config.json is annotated below.

Discord

Copy"discord": {
  "token": "YOUR_BOT_TOKEN_HERE",  // Bot token from Developer Portal
  "guild_id": "YOUR_GUILD_ID",     // Right-click server → Copy Server ID
  "prefix": "!"                    // Unused — bot uses slash commands only
}

Database

Copy"database": {
  "driver": "sqlite",              // "sqlite" or "mongodb"
  "sqlite": {
    "path": "data/bot.db"          // Auto-created on first run
  },
  "mongodb": {
    "uri": "mongodb://localhost:27017",
    "database": "discord_bot"
  }
}

Permissions

Copy"permissions": {
  "admin_roles":     ["Admin", "Owner"],       // Can use admin commands
  "moderator_roles": ["Moderator", "Mod"],     // Can use mod commands
  "dj_roles":        ["DJ", "Music"]           // Can control music
}

Music

Copy"music": {
  "enabled": true,
  "backend": "lavalink",           // "direct" or "lavalink"
  "max_queue_size": 100,
  "max_song_duration": 600,        // seconds (0 = no limit)
  "allow_playlists": true,
  "default_volume": 50,
  "direct": {
    "ytdlp_path": "./yt-dlp",
    "ffmpeg_path": "ffmpeg"
  },
  "lavalink": {
    "host": "localhost",
    "port": 2333,
    "password": "youshallnotpass",
    "secure": false
  }
}

Minecraft

Copy"minecraft": {
  "enabled": false,
  "rcon_ip": "localhost",
  "rcon_port": 25575,
  "rcon_password": "your_rcon_password",
  "link_backend": "file"           // "file" or "mongodb"
}

Welcome / Leave

Copy"welcome": {
  "enabled": true,
  "channel_id": "CHANNEL_ID",
  "embed": {
    "colour": "#f74343",
    "title": "Welcome to Our Server!",
    "message": "Welcome %joined_user%! Glad to have you here.",
    "thumbnail": "USER",           // "BOT", "USER", or any image URL
    "image_enabled": false,
    "image_url": ""
  }
}

The leave block has the exact same structure.

Tickets

Copy"tickets": {
  "enabled": true,
  "panel_channel": "CHANNEL_ID",
  "log_channel": "CHANNEL_ID",
  "staff_roles": "ROLE_ID_1,ROLE_ID_2",
  "discord_category": "CATEGORY_ID",
  "max_open_per_user": 3,
  "categories": [
    {
      "id": "support",
      "name": "Support",
      "emoji": "🛠️",
      "description": "Get help with any issue",
      "staff_role": "ROLE_ID",
      "subcategories": [
        { "id": "bug", "name": "Bug Report", "emoji": "🐛", "description": "Report a bug" }
      ]
    }
  ]
}

Auto-Mod

Copy"moderation": {
  "mod_log_channel": "CHANNEL_ID",
  "auto_mod": {
    "enabled": true,
    "max_mentions": 5,
    "max_lines": 30,
    "anti_spam_seconds": 5,
    "anti_spam_count": 5
  }
}

Chat Bridge

Copy"chat_bridge": {
  "enabled": true,
  "rabbitmq_uri": "amqp://user:password@host:5672/%2F",
  "channel_id": "DISCORD_CHANNEL_ID",
  "mc_channel_id": "global",   // OreoEssentials channel (global / local / trade / staff / help / announcements)
  "ban_sync": false,            // Sync Discord bans → Minecraft bans via RCON
  "mod_sync": false             // Sync Discord /mute → Minecraft MuteService via RabbitMQ
}

No-Ping

Copy"no_ping": {
  "enabled": true,
  "protected_roles": ["ROLE_ID_1", "ROLE_ID_2"],  // Role IDs (right-click role → Copy ID)
  "message": "{user} You are not allowed to ping **{role}**!",
  "delete_message": true
}

Counting Game

Copy"counting_game": {
  "enabled": true,
  "channel_id": "COUNTING_CHANNEL_ID",
  "fail_resets": true,           // Reset to 0 on wrong number
  "delete_wrong": true,          // Delete wrong numbers
  "delete_non_numbers": true     // Delete non-number messages
}

Custom Commands

Copy"custom_commands": [
  {
    "name": "rules",
    "description": "Server rules",
    "message": "**Rules:**\n1. Be respectful\n2. No spam",
    "ephemeral": true
  }
]

lang.yml — Language Settings

All bot messages are defined in lang.yml. Open it and change the first line to switch languages:

Copy# Options: "en" (English) or "fr" (French)
active_language: en

Permission System

OreoBot uses a layered permission system:

Commands — Moderation

All moderation commands require Moderator or Admin unless noted.

Commands — Ticket System

Initial Setup

Commands

Commands — Auto-Role

Automatically assign a role to every new member when they join.

Commands — Role Menus

Create self-assignable role menus that members can interact with using buttons. A menu can hold up to 20 roles.

Quick Start

Copy/rolemenu create title:Pick your roles mode:multi
/rolemenu add menu_id:MENU_ID role:@Gamer label:Gamer
/rolemenu post menu_id:MENU_ID channel:#roles

Commands — Giveaways

Run giveaways with automatic timer, random winner selection, and reroll support. Giveaway timers survive bot restarts.

Commands — Music

Play music in voice channels. Requires music.enabled: true in config.json. Music controls require a DJ role.

Commands — Minecraft Integration

Connect your Discord server to a Minecraft server via RCON.

Setup

In your Minecraft server.properties:

Copyenable-rcon=true
rcon.port=25575
rcon.password=your_password

In config.json:

Copy"minecraft": {
  "enabled": true,
  "rcon_ip": "your.server.ip",
  "rcon_port": 25575,
  "rcon_password": "your_password"
}

OreoEssentials Plugin

OreoEssentials is a companion Minecraft plugin that extends OreoBot's Minecraft integration. It must be installed on your Minecraft server to enable account linking and live player-data lookups.

How the bridge works

When a user runs a bot command that needs Minecraft data (like /mc profile), OreoBot sends a special RCON command to your server. OreoEssentials intercepts that command, reads the requested data (balance, homes, online status…), and replies through the RCON response. OreoBot then formats the reply and posts it as a Discord embed.

Account linking system

The linking flow is a two-step handshake between Discord and Minecraft. OreoEssentials owns the in-game half; OreoBot owns the Discord half.

In-game command — /discord

OreoEssentials registers the /discord command for players inside Minecraft:

Link storage backend — config.yml

OreoEssentials stores pending and confirmed link data. The backend is configured in OreoEssentials' config.yml:

Copydiscord:
  link_backend: "file"   # "file" (default) or "mongodb" for cross-network

RCON extension commands (oe-discord)

These are server-side-only commands registered by DiscordRconExtension. They are called automatically by OreoBot over RCON — players cannot run them. Each returns a one-line OK: … result or ERR: … on failure.

What REQUIRES OreoEssentials

What works WITHOUT OreoEssentials

Everything that doesn't require live player data or in-game linking still works normally:

• Check server status — /mc status
• List online players — /mc players
• Run RCON commands — /mc command
• Manage the whitelist — /mc whitelist
• Broadcast messages in-game — /mc say

Commands — Utility

Commands — Custom Commands

Define your own slash commands that reply with a fixed message. They appear alongside all built-in commands and are registered with Discord automatically on every startup.

Configuration

Copy"custom_commands": [
  {
    "name": "rules",           // Slash command name — users type /rules
    "description": "Server rules",
    "message": "**Rules:**\n1. Be respectful\n2. No spam",
    "ephemeral": true          // true = only the caller sees the reply
  },
  {
    "name": "discord",
    "description": "Join our Discord",
    "message": "Join us at: https://discord.gg/example",
    "ephemeral": false         // false = reply visible to the whole channel
  }
]

Chat Bridge — Discord ↔ Minecraft

The Chat Bridge creates a live, bidirectional link between a Discord text channel and your Minecraft server's chat. Messages sent in the Discord channel appear in Minecraft, and Minecraft chat appears in Discord — in real time, over RabbitMQ.

How it works

Configuration — config.json

Copy"chat_bridge": {
  "enabled": true,
  "rabbitmq_uri": "amqp://user:password@your-server:5672/%2F",
  "channel_id": "YOUR_DISCORD_CHANNEL_ID",   // The Discord channel used for the bridge
  "mc_channel_id": "global",                 // OreoEssentials channel name (see table below)
  "ban_sync": false,                          // true = Discord ban → Minecraft ban via RCON
  "mod_sync": false                           // true = Discord /mute → Minecraft mute via RabbitMQ
}

OreoEssentials Channels — mc_channel_id values

OreoEssentials' channel system separates different types of in-game chat. The mc_channel_id in your bot config must exactly match one of the channel IDs configured in OreoEssentials' config.yml. The default channels are:

OreoEssentials — Required config.yml Changes

For the chat bridge to work end-to-end, OreoEssentials' config.yml must match the bot config on two critical points:

Copy# OreoEssentials config.yml — chat bridge relevant settings

discord:
  link_backend: "mongodb"   # MUST match minecraft.link_backend in bot config.json
                             # "mongodb" → shared MongoDB store (works across servers)
                             # "file"    → local JSON files (single-server only)

chat_sync:
  enabled: true
  rabbitmq_uri: "amqp://user:password@your-server:5672/%2F"  # Identical to bot config

  channels:
    - id: "global"
      name: "Global"
      default: true
      cross_server: true
    - id: "local"
      name: "Local"
      radius: 100
    - id: "trade"
      name: "Trade"
    - id: "staff"
      name: "Staff"
      staff_only: true
    - id: "help"
      name: "Help"
    - id: "announcements"
      name: "Announcements"

  default_channel: "global"

Ban & Mod Sync

Message Format

The Discord @mention only appears next to the player name if the Minecraft player has a linked Discord account.

Troubleshooting the Bridge

No-Ping Protection

Automatically detect and delete messages that ping a protected role, then post a warning. Useful for protecting Admin, VIP, or any sensitive role from unsolicited @mentions.

Configuration

Copy"no_ping": {
  "enabled": true,
  "protected_roles": ["ROLE_ID_1", "ROLE_ID_2"],   // Role IDs, NOT role names
  "message": "{user} You are not allowed to ping **{role}**!",
  "delete_message": true    // true = also delete the offending message
}

How to get a Role ID

Counting Game

Turn a dedicated channel into a collaborative counting game. Members take turns posting the next number in sequence. Wrong numbers, repeated users, and non-number messages are all handled automatically.

Configuration

Copy"counting_game": {
  "enabled": true,
  "channel_id": "YOUR_COUNTING_CHANNEL_ID",
  "fail_resets": true,           // true = reset count to 0 on a wrong number
  "delete_wrong": true,          // true = delete wrong-number messages automatically
  "delete_non_numbers": true     // true = delete any non-number messages from the channel
}

Welcome & Leave Messages

Automatically post an embed when someone joins or leaves your server.

Placeholders

Thumbnail Options

Auto-Moderation

Automatically handle common spam and abuse patterns.

Copy"auto_mod": {
  "enabled": true,
  "max_mentions": 5,
  "max_lines": 30,
  "anti_spam_seconds": 5,
  "anti_spam_count": 5
}

Database & Storage

Troubleshooting