Remora.Discord

Remora.Discord is a C# library for interfacing with the Discord API. It is built to fulfill a need for robust, feature-complete, highly available and concurrent bots.

Want to chat with users and developers? Come join us!

Features
Goals
Status
1. Gateway
2. REST
Installation
Usage
Contributing

1. Features

Extensive API coverage - does anything and everything you need
Modern and active - uses contemporary technologies and usage patterns
Fully asynchronous - do many things at once at scale
Modular - swap parts of the library with your own implementations at will
Integrated - slash commands, traditional interfaces, or stateless bots

2. Goals

Remora.Discord originates from the original author's frustration with many inconsistencies in various APIs in the C#/Discord ecosystem, both in relation to the Discord API itself and the language usage within existing solutions.

Therefore, Remora.Discord defines the following three goals that guides its development. These are shorter summaries - to read the full goal definitions and see examples, please refer to the Contributing Guidelines.

2.1 Correctness

Correctness, in the context of Remora.Discord, means that the API available to the end user should as faithfully and accurately represent the actual reality of data presented to or from an API; that is, no data or structure of data should meaningfully change between the library receiving it and the user accessing it.

2.2 Robustness

Robustness refers to a focus on never allowing problems originating from user data or real-life runtime conditions to bring down or otherwise corrupt the end user's application. The end user should be confident that, should an error arise, they will be aware of the fault potential before even compiling the application.

2.3 True Asynchronicity and Concurrency

Remora.Discord aims to be truly asynchronous from the ground up, respecting and utilizing established best practices for C# and the TPL. Furthermore, it aims to be concurrent, allowing end users to react to and perform actions upon many incoming events at once.

3. Status

Remora.Discord is currently fully usable, and has been released for public consumption.

3.1 Gateway

The Discord Gateway API (v10) is fully implemented. The gateway client can connect, heartbeat, reconnect, resume, receive events, and send commands.

3.2 REST

The Discord REST API (v10) is fully implemented.

3.3 Voice

The Discord Voice API is not implemented. If you'd like to contribute to the library, this would be an excellent start.

4. Installation

Remora.Discord's primary distribution format is via nuget - get it there!

If you wish to use or develop the library further, you will need to compile it from source.

git clone git@github.com:Remora/Remora.Discord.git
cd Remora.Discord
dotnet build
dotnet pack -c Release

5. Usage

Up-to-date documentation for the API, as well as a quickstart guide, is available online at the repository pages.

Each package has its own README with more detailed information regarding its purpose and use. If you want to know more about each one of these, please refer to the list below. It's roughly organized in order of importance to end users, but feel free to explore.

If you want to get started quickly, please refer to the Samples for community-created example bots.

5.1 Versioning

A note on versioning - Remora.Discord uses SEMVER 2.0.0, which, in short, means

Given a version number MAJOR.MINOR.PATCH, increment the:

MAJOR version when you make incompatible API changes,
MINOR version when you add functionality in a backwards compatible manner, and
PATCH version when you make backwards compatible bug fixes.

Due to the rapidly- and often-changing nature of Discord's API, this means that changes to the MAJOR component of the version in components of the library may change almost every new release. Typically, new functionality in Discord's API means that new fields are added, types of fields change, or parameters sent to endpoints change.

Generally, these changes only affect the API and API.Abstractions packages - these will often increment their MAJOR versions. Dependant packages - such as Gateway or Rest - will update together with these packages, but unless their public API changes as a result, it will be considered a PATCH upgrade.

The consequences of this is that you may see source-level breakages when upgrading from one minor version to the next. While undesirable, it is an effect of Discord's uneven and inaccurate update cycle. Because of the way C# handles dependencies, however, it's unlikely that this would affect anything outside of normal development - as such, it's been deemed an acceptable degradation.

5.2 Releases

Remora.Discord does not follow a set release cycle, and releases new versions on a rolling basis as new features of the Discord API are implemented or documented.

As a bot developer, you should check in every now and then to see what's changed - changelogs are released along with tags here on Github, as well as in the individual package descriptions.

Whenever a new set of packages are released, the commit the releases were built from is tagged with the year and an incremental release number - for example, 2021.1.

5.2.1 Bleeding Edge Builds

Whenever a new push to master is made, a new set of packages based on the latest commit will be published to GitHub Packages.

The URL of the NuGet source is https://nuget.pkg.github.com/Remora/index.json. As the NuGet source requires authentication, follow GitHub's instructions: here

7. Licensing

Remora.Discord is released under the Lesser GNU Public License, version 3.0 or later.

The code samples (both under the Samples directory and any snippets in documentation, manuals, or other educational material) is licensed under the MIT license.

8. Contributing

See Contributing.

Thanks

Icon by Twemoji, licensed under CC-BY 4.0.

Remora / Remora.Discord

readme