Home

discljord

If you haven't checked out the README.md on this project yet, you should probably do that first. It'll give you a basic idea of how to build super simple bots with discljord!

Now that you've familiarized yourself with the very basics and made a simple hello world bot, you'll need to familiarize yourself with the principles of how discljord works. One of the goals of discljord was for the library to not be very far removed from Discord's own documentation in terms of how things are handled.

Architecture

Bots made with discljord have three primary components, as was touched on in the readme briefly. These three components are the gateway connection (discljord.connections), the bot logic (your own code), and the HTTP API connection (discljord.messaging).

Your code will generally only have to handle some surface-level concerns with the first and last of these. Namely it will have to start them, call their API methods (full documentation for discljord's functions can be found in the doc folder), and for the gateway connection you'll have to handle events.

Gateway API

In order to use the Gateway API, you'll have to handle events. These will arrive on a core.async channel which you pass in to discljord at the creation of the connection. Events are taken raw from Discord in their JSON format, and are then converted directly into Clojure data structures with minimal modification. Objects are changed to maps, arrays are changed to vectors, and string keys in objects are changed to keywords, after being downcased and having underscores replaced with hyphens. For example, the following JSON is what Discord sends through the Gateway API on a message being created (a MESSAGE_CREATE event):

{
  "id": "0987654321",
  "channel_id": "5674839021",
  "content": "This is a message",
  "author": {
    "id": "1234567890",
    "username": "sample text",
    ...
  },
  ...
}

Some fields have been omitted, but this is more than enough to illustrate. This event will get translated into Clojure data structures and sent directly on to your code to handle, in the following form:

{:id "0987654321"
 :channel-id "5674839021"
 :content "This is a message"
 :author {:id "1234567890"
          :username "sample text"
          ...}
 ...}

If you're ever confused about the data you're getting out of an event, refer back to Discord's own API docs, and it will illustrate exactly what should be coming through on the event.

HTTP API

The HTTP API is used to send messages, change permissions on channels, create guilds, and so on. It has been entirely wrapped in functions which you can call from the discljord.messaging namespace, and most of the time the names are pretty self-explanatory. However, in some cases you may have to contend with deeply nested structures, most specifically when dealing with embeds. In these cases, I've tried to provide specs which you can use to see how to fill these out correctly, however if you like Discord's API docs, they should be entirely accurate as well, since any nested data you pass to the functions is converted directly into JSON with no transformations (this means that if Discord's API docs use an underscore, you'll have to use an underscore as well, even if you're using it in a keyword). At a later date I may make an additional allowance to have hyphens along with underscores, but not yet.

Discljord handles all the rate-limiting which goes into working with Discord's HTTP API, and it should be transparent to you as the bot developer. Currently there is an issue where if you send enough messages to trip the rate limit, any additional messages may arrive out of order, however I intend to fix this at a later date if it proves to be an issue.

The only other notable thing to remember with the HTTP API and associated functions is that when sending a file in create-message! (and this applies to attachments too), they can only be instances of type java.io.File, most easily created with the function clojure.java.io/file.

Event Handling

Very little has been said about actually handling events up until now, and this is because there's very little to say at this point. The only function discljord provides to help with handling events is discljord.events/message-pump! which starts a message pump which you can use (and which my current bots are using). This is only minimal help, but that's the intention since providing small layers of abstraction allows you to more easily drop down if needed when the abstraction doesn't support what you want to do. However, that still requires layers of abstration, which rolls us cleanly into...

Future Plans

My current plans for discljord are to continue making bots with it and begin to pull out some commonalities in how event handling is done and in things like commands, etc. Once I've determined some of those commonalities, I'll begin making some additional namespaces which you can pull from to help with those common tasks, as discljord becomes more fully-featured as a bot-making DSL, and not just a library to handle the networking.