A production-ready Discord bot framework built with Discordia and MongoDB — slash commands, prefix commands, anti-crash, webhook logging, and a modular src/ architecture.
Features • Quick Start • Structure • API • SQL Edition • Ecosystem
Discord Handler Lua is the Lua edition of the multi-language Discord Handler ecosystem. Built on the Discordia library, it provides a modular, event-driven foundation for Discord bots with dual command support (slash + prefix), MongoDB persistence, webhook-based logging, and an anti-crash layer.
The entry point (src/main.lua) boots in a predictable sequence: configure the package path for clean requires, initialize the anti-crash handler, connect to MongoDB, register event listeners (ready, guild create/delete, interaction create, message create), and finally present a startup report before the client goes online.
- Dual Command System — Slash commands via interactionCreate and prefix commands via messageCreate
- Modular Architecture — Separated concerns across
config/,core/,database/,events/,handlers/,models/, andcommands/ - Anti-Crash — Global error interception via
xpcallthat reports failures to a Discord webhook - Webhook Logging — Separate webhooks for error alerts and guild join/leave events
- MongoDB Integration — Persistent storage via
luamongo(stub connection indatabase/mongo.lua) - Cooldown System — Per-command cooldown tracked in
core/command_utils.lua - Environment Configuration — All secrets managed through a custom
.envparser inconfig/config.lua
git clone https://github.com/RealMtrx/Discord-Handler-Lua.git
cd Discord-Handler-LuaInstall Lua dependencies:
luarocks install discordia
luarocks install luasec
luarocks install luasocket
luarocks install dkjsonCopy .env.example to .env and fill in your values:
TOKEN=your_bot_token_here
PREFIX=!
BOT_NAME=Discord Handler
MONGO_URI=mongodb://localhost:27017/discord-handler
ERROR_WEBHOOK=https://discord.com/api/webhooks/your_webhook
GUILD_LOG_WEBHOOK=https://discord.com/api/webhooks/your_webhooklua src/main.lua| Library | Purpose |
|---|---|
discordia |
Discord API wrapper |
luasec |
TLS support |
luasocket |
Network support |
dkjson |
JSON parsing for webhooks |
Discord-Handler-Lua/
├── .env.example
├── src/
│ ├── main.lua # Entry point — boot sequence
│ ├── config/config.lua # Custom .env parser and config table
│ ├── core/
│ │ ├── command_utils.lua # Cooldown helper
│ │ ├── emojis.lua # Centralized emoji constants
│ │ └── webhook_util.lua # Webhook dispatch utility
│ ├── database/mongo.lua # MongoDB connection stub
│ ├── events/
│ │ ├── guild_create.lua # Guild join → webhook
│ │ ├── guild_delete.lua # Guild leave → webhook
│ │ ├── interaction_create.lua # Slash command dispatcher
│ │ ├── message_create.lua # Prefix command dispatcher
│ │ └── ready.lua # Ready event + startup report
│ ├── handlers/
│ │ ├── anti_crash.lua # Global error interception via xpcall
│ │ └── logger.lua # Startup report formatter
│ ├── models/user_model.lua # User data schema
│ └── commands/
│ ├── prefix/ping.lua # Example prefix command
│ └── slash/ping.lua # Example slash command
Extends package.path for clean requires, creates a discordia.Client(), wires five event handlers, and calls client:run().
Returns a table with keys matching .env:
config.token -- Bot token
config.prefix -- Command prefix (default: "!")
config.bot_name -- Display name
config.mongo_uri -- MongoDB connection string
config.error_webhook -- Error reporting URL
config.guild_log_webhook -- Guild event logging URL| Event | File | Trigger |
|---|---|---|
ready |
events/ready.lua |
Bot goes online — logs startup |
guildCreate |
events/guild_create.lua |
Bot joins a server — sends join webhook |
guildDelete |
events/guild_delete.lua |
Bot leaves a server — sends leave webhook |
interactionCreate |
events/interaction_create.lua |
Slash command used — routes to command module |
messageCreate |
events/message_create.lua |
Message sent — checks prefix, routes to prefix command |
- CommandUtils —
CommandUtils.check_cooldown(command, user_id)checks cooldown expiry - WebhookUtil —
WebhookUtil.send(webhook_url, content)fires an embed to a Discord webhook - Emojis — Centralized emoji constant map for consistent bot responses
Create src/commands/slash/your_command.lua:
local SlashCommand = {}
SlashCommand.name = 'yourcommand'
SlashCommand.description = 'Does something useful'
function SlashCommand.execute(interaction)
interaction:reply({ content = 'Done!' })
end
return SlashCommandCreate src/commands/prefix/your_command.lua:
local PrefixCommand = {}
PrefixCommand.name = 'yourcommand'
function PrefixCommand.execute(message)
message:reply('Done!')
end
return PrefixCommandThe message_create event automatically requires and dispatches modules in commands/prefix/ when the message starts with PREFIX.
A Sequelize (SQL) variant of this handler is available for teams that prefer a relational database over MongoDB:
RealMtrx/Discord-Handler-Lua-Sequelize
It replaces database/mongo.lua with a Sequelize-based connection and supports SQLite, PostgreSQL, MySQL, MariaDB, and MSSQL out of the box. All other modules — events, commands, handlers, core utilities — remain identical.
The Discord Handler ecosystem spans 26 repositories across 13 languages, each available in both MongoDB and Sequelize editions.
| Language | Repository |
|---|---|
| C++ | RealMtrx/Discord-Handler-Cpp |
| C# | RealMtrx/Discord-Handler-Cs |
| Dart | RealMtrx/Discord-Handler-Dart |
| Go | RealMtrx/Discord-Handler-Go |
| Java | RealMtrx/Discord-Handler-Java |
| JavaScript | RealMtrx/Discord-Handler-Js |
| Kotlin | RealMtrx/Discord-Handler-Kt |
| Lua | RealMtrx/Discord-Handler-Lua |
| PHP | RealMtrx/Discord-Handler-Php |
| Python | RealMtrx/Discord-Handler-Py |
| Ruby | RealMtrx/Discord-Handler-Rb |
| Rust | RealMtrx/Discord-Handler-Rs |
| TypeScript | RealMtrx/Discord-Handler ← hub |
RealMtrx/Discord-Handler — the TypeScript hub and flagship repository. Star it to support the ecosystem.
Distributed under the MIT License. See LICENSE for more information.
Built by Mtrx — Discord: 0hu2