Discordia wraps the Discord API for the Luvit runtime in Lua

A wrapper over the documented Discord REST API

Discordia is a Lua wrapper for the official Discord API, and it provides a high-level, object-oriented, event-driven interface for developing Discord bots. The underlying surface is the same one every other Discord library uses, since Discord publishes a documented RESTful API that allows developers to make bots for use on their servers. What Discordia adds is shape. Instead of assembling HTTP calls by hand, a bot is written against objects. A client, a message, a channel. Sending a reply is a method call on the channel rather than a request you assemble. The events are named after what happened, with messageCreate as the one every bot author meets first, and the library dispatches them to functions you register. The audience is a developer who wants a bot without pulling in a large framework, and the code is small enough to read in one sitting, which is a genuine advantage over the heavier bot libraries in other languages.

Coroutines make asynchronous calls look synchronous

The mechanism underneath is Lua's native coroutines. The documentation says that asynchronous HTTP and WebSocket communication is internally abstracted in a way that allows end-users to write blocking-style code without blocking I/O operations. That distinction is the whole design and it is worth being precise about. A blocking style call in a bot handler usually means the coroutine yields, the runtime continues serving other connections, and the coroutine resumes when the response arrives. Nothing is frozen, but your code reads as if it were. For a bot, that matters more than it would for a general server, because a bot's work is dominated by waiting on the Discord gateway for events and on the REST API for replies. A library that made you write callbacks for both would double the ceremony of every handler. Discordia removes it, and that is the main reason to prefer it over a thinner, more literal wrapper.

Installing Luvit first, then the library

Installation is a three step sequence, and the first step is the runtime rather than the library. To install Luvit, you visit luvit.io and follow the instructions for your platform. To install Discordia, you run:

lit install SinisterRectus/discordia

Then you run your bot script with, for example, luvit bot.lua. The package manager is called lit, and the documentation describes it as Luvit's companion package manager that makes it easy to set up the Luvit runtime and its published libraries. So the install path is lit install followed by the runtime executing your script. Note that the Luvit installation itself is described as optionally automated and using pre-built luvi cores when available, so a first-time setup on an unusual platform may involve more than a single command. The runtime also ships with libraries essential to async I/O programming and networking, which is why Discordia leans on it rather than implementing its own transport.

The smallest useful bot takes about fifteen lines

The example in the documentation is a complete bot and it is short enough to be read at a glance. You require the library, create a client, register handlers for ready and messageCreate, and run the client with a token:

local discordia = require('discordia')
local client = discordia.Client()

client:on('ready', function()
	print('Logged in as '.. client.user.username)
end)

client:on('messageCreate', function(message)
	if message.content == '!ping' then
		message.channel:send('Pong!')
	end
end)

client:run('Bot INSERT_TOKEN_HERE')

Three things are worth noting about that shape. The token is passed to run with a Bot prefix, which is the newer Discord authentication form rather than the older token only form. The ready handler fires once the client is logged in, and client.user gives you the authenticated user. And the message handler checks the content against a command string and replies on the channel the message came from, so a bot that answers a ping needs no channel lookup and no message id handling. The examples directory in the repository carries this pattern further with appender.lua, basicCommands.lua, embed.lua, helpCommandExample.lua and pingPong.lua, which are the files to read when you want to know how a prefix command, an embed message or a help command is written.

The FAQ explains why the runtime choice is not incidental

The documentation devotes a section to why Lua, and a second section to why Luvit, and both answers are about the size of the thing. Lua is described as a lightweight scripting language that tends to be beginner-friendly, with the note that although it may not have the same popularity as Python or JavaScript, its expandability makes it equally as capable while remaining easy to use and often more resource efficient. Luvit is a combination of LuaJIT and libuv layered with libraries to provide server-side functionality similar to Node.js but with Lua instead of JavaScript. Compared to Node.js, Luvit advertises similar speed with reduced memory consumption, and the Discordia entry says the library is expected to perform well due to Luvit's use of LuaJIT, although it has not been benchmarked. That last clause is the important one. The performance argument is an expectation stated in the documentation, not a measurement, so if footprint is your reason for choosing this stack, you should measure your own bot rather than rely on the claim.

Porting to plain Lua is explicitly out of scope

Here is the boundary of the project, stated in its own words. The development and deployment of Discordia relies on the Luvit framework and its package manager, and porting Discordia and its dependencies to classic Lua or LuaJIT may be possible, but this is not a current project goal. That single sentence decides the adoption question for a lot of teams. If your infrastructure already runs Lua through another runtime, if a hosting platform gives you a stock Lua 5.3 interpreter with no libuv, or if you need the library to work inside an existing application rather than as its own process, Discordia will not fit without work the maintainer is not planning to do. The library also has a long history that explains its shape. The earliest version, before it had that name, was released as a Just Cause 2 Multiplayer module on 7 March 2016, using LuaSocket, LuaSec and eventually Copas to provide basic REST functionality in a sandboxed Lua 5.2 environment, with the goal of bridging game chat with a Discord client. A lack of WSS support at the time put it on hold in favour of a general purpose library, and after a stable version was finished the game bridge was redesigned to talk to Discordia over inter-process communication.

Contributing, community and where the documentation lives

The README points documentation and tutorials to the project wiki, and the repository carries a docgen.lua script at the root next to init.lua and package.lua, so the API reference appears to be generated rather than hand maintained. For contributions, pull requests are welcomed, but the documentation asks you to check with the library author before starting a major implementation, and it notes that contributions to the wiki are helpful too. There are two chat servers linked, the Discord API server for discussing Discordia alongside other Discord libraries, and an independent Discordia server. The top level of the repository is small and conventional for a Luvit package: bin/, libs/, examples/, init.lua, package.lua, docgen.lua, a CHANGELOG.md and the LICENSE. The MIT licence in that file is the permissive case, which matters for a library you may end up vendoring into a bot you distribute.

Editorial conclusion

Adopt Discordia when you want to run a Discord bot in Lua on Luvit, when a small memory footprint matters more than the wider ecosystem of a JavaScript or Python library, and when the blocking style coroutine API suits how you like to write. Do not adopt it for a bot you intend to run on a mainstream runtime, since porting to classic Lua or LuaJIT is explicitly not a current project goal, and do not adopt it expecting benchmarked performance claims, because the documentation states that has not been benchmarked. Verify first that Luvit and its package manager lit are available on your machine, that the bot token is supplied correctly to client:run, and that the event names you bind to exist in the wiki documentation.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. README
4. SinisterRectus/Discordia on GitHub