• Stars
    star
    504
  • Rank 84,597 (Top 2 %)
  • Language
    Go
  • License
    BSD 3-Clause "New...
  • Created over 6 years ago
  • Updated 2 months ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

Go module for interacting with the documented Discord's bot interface; Gateway, REST requests and voice

About

Go module with context support that handles some of the difficulties from interacting with Discord's bot interface for you; websocket sharding, auto-scaling of websocket connections, advanced caching (cache replacement strategies to restrict memory usage), helper functions, middlewares and lifetime controllers for event handlers, etc.

This package is intented to be used with the gateway to keep the cache up to date. You should treat data as read only, since they simply represent the discord state. To change the discord state you can use the REST methods and the gateway commands, which will eventually update your local state as well.

If you want a more lightweight experience you can disable/reject events that you do not need or want to keep track of. Be careful as this might break certain things.

Tips

  • Use disgord.Snowflake, not snowflake.Snowflake.
  • Use disgord.Time, not time.Time when dealing with Discord timestamps.

You must explicitly set intents if you want certain gateway events.

client := disgord.New(disgord.Config{
    Intents: disgord.IntentDirectMessages | disgord.IntentDirectMessageReactions,
})
client := disgord.New(disgord.Config{
    Intents: disgord.AllIntents(),
})

Starter guide

This project uses Go Modules for dealing with dependencies, remember to activate module support in your IDE

Examples can be found in examples and some open source projects Disgord projects in the wiki

I highly suggest reading the Discord API documentation and the Disgord go doc.

Simply use this github template to create your first new bot!

API / Interface

In short Disgord uses the builder pattern by respecting resources

The Client or Session holds are the relevant methods for interacting with Discord. The API is split by resource, such that Guild related information is found in Client.Guild(guild_id), while user related info is found in Client.User(user_id), gateway interaction is found in Client.Gateway(), the same for Channel, CurrentUser, Emoji, AuditLog, etc.

Cancellation is supported by calling .WithContext(context.Context before the final REST call (.Get(), .Update(), etc.).

Events

every event goes through the cache layer!

For Events, Disgord uses the reactor pattern. This supports both channels and functions. You chose your preference.

REST

If the request is a standard GET request, the cache is always checked first to reduce delay, network traffic and load on the Discord servers. And on responses, regardless of the http method, the data is copied into the cache.

// bypasses local cache
client.CurrentUser().Get(disgord.IgnoreCache)
client.Guild(guildID).GetMembers(disgord.IgnoreCache)

// always checks the local cache first
client.CurrentUser().Get()
client.Guild(guildID).GetMembers()

// with cancellation
deadline, _ := context.WithDeadline(context.Background(), time.Now().Add(2*time.Second))
client.CurrentUser().WithContext(deadline).Get()

Voice

Whenever you want the bot to join a voice channel, a websocket and UDP connection is established. So if your bot is currently in 5 voice channels, then you have 5 websocket connections and 5 udp connections open to handle the voice traffic.

Cache

The cache tries to represent the Discord state as accurate as it can. Because of this, the cache is immutable by default. Meaning the does not allow you to reference any cached objects directly, and every incoming and outgoing data of the cache is deep copied.

Contributing

Please see the CONTRIBUTING.md file (Note that it can be useful to read this regardless if you have the time)

You can contribute with pull requests, issues, wiki updates and helping out in the discord servers mentioned above.

To notify about bugs or suggesting enhancements, simply create a issue. The more the better. But be detailed enough that it can be reproduced and please provide logs.

To contribute with code, always create an issue before you open a pull request. This allows automating change logs and releases.

Remember to have stringer installed to run go generate: go get -u golang.org/x/tools/cmd/stringer

Sponsors

JetBrains

A Special thanks to the following companies for sponsoring this project!

Software used

Q&A

NOTE: To see more examples go to the examples folder. See the GoDoc for a in-depth introduction on the various topics.

1. How do I find my bot token and/or add my bot to a server?

Tutorial here: https://github.com/andersfylling/disgord/wiki/Get-bot-token-and-add-it-to-a-server
2. Is there an alternative Go package?

Yes, it's called DiscordGo (https://github.com/bwmarrin/discordgo). Its purpose is to provide a 
minimalistic API wrapper for Discord, it does not handle multiple websocket sharding, scaling, etc. 
behind the scenes such as Disgord does. Currently I do not have a comparison chart of Disgord and 
DiscordGo. But I do want to create one in the future, for now the biggest difference is that 
Disgord does not support self bots.
3. Why make another Discord lib in Go?

I'm trying to take over the world and then become a intergalactic war lord. Have to start somewhere.
4. Will Disgord support self bots?

No. Self bots are againts ToS and could result in account termination (see
https://support.discord.com/hc/en-us/articles/115002192352-Automated-user-accounts-self-bots-). 
In addition, self bots aren't a part of the official Discord API, meaning support could change at
any time and Disgord could break unexpectedly if this feature were to be added.

More Repositories

1

disgord-starter

Template repository for Disgord bots
Go
8
star
2

discordgateway

A discord gateway module that separates Discord logic from the websocket logic
Go
7
star
3

sorting-nine-inputs-requires-twenty-five-comparisons

A third party c++20 implementation of the paper "Sorting nine inputs requires twenty-five comparisons"
C++
7
star
4

fmtnazi

fmtnazi is a discord bot that formats messages containing code blocks
Go
6
star
5

stack-guru

Discord nootropics bot
PHP
4
star
6

domain-for-sale

single server platform for multiple domains that are for sale
HTML
4
star
7

snowflake

Go Snowflake for Discord
Go
4
star
8

jailbot

Discord bot that uses shared data between servers to keep banned people banned on a "international" Guild level.
Go
4
star
9

uci

UCI library written in C++14 to deal with incoming and outgoing UCI commands
C++
3
star
10

david

Chess engine written from scratch using C++17
C++
3
star
11

php_components

Different php scripts to speed up programming time.
PHP
2
star
12

deplog

auto-wrapper for GoLang projects that want to support dependency injection for any logger
Go
2
star
13

ccdb

Crypto-Currency-Discord-Bot written in Go, using the Unison library to display a crypto currency.
Go
2
star
14

dailyprogrammer

Tackling tasks in reddit.com/r/dailyprogrammer using different languages as suited
1
star
15

IMT2681-2

Go
1
star
16

genetic-sudoku

Solving a empty Sudoku board using genetic algorithm in C++17
C++
1
star
17

sailsjs-email-server

email server based on sailsjs, simplesmtp, nodemailer and so on.
JavaScript
1
star
18

movegengo

Chess module for generating legal moves for Go
Go
1
star
19

rolerboler

Discord bot that handles assignment of roles to users
Go
1
star
20

MJL

Minimalistic Javascript Library
1
star
21

djp

Discord JSON Parser
Go
1
star
22

addy

A basic Dependency Injection library
Java
1
star
23

movegencpp

Chess Move Generator written in C++17 with iterator pattern
C++
1
star
24

ddp

Discord docs parser
Go
1
star
25

curious

A go library that let you list all projects using a given import path
Go
1
star
26

discord-auto-nicknamer

Go
1
star