twilight

[![codecov badge][]][codecov link] [![discord badge][]][discord link] [![github badge][]][github link] [![license badge][]][license link] ![rust badge]

![project logo][logo]

twilight is a powerful, flexible, and scalable ecosystem of Rust libraries for the Discord API.

The ecosystem of first-class crates includes [twilight-cache-inmemory], [twilight-gateway], [twilight-http], [twilight-model], and more. These are explained in detail below.

The main twilight crate is purely an advertisement crate: it has no functionality. Please use the individual crates listed below instead!

Installation

Twilight supports a MSRV of Rust 1.89. We do not consider changes to the MSRV semver-incompatible, therefore it may change in minor or patch releases.

We recommend that most users start out with these crates:

• [twilight-cache-inmemory][crates:cache-inmemory]
• [twilight-gateway][crates:gateway]
• [twilight-http][crates:http]
• [twilight-model][crates:model]

Core Crates

These are essential crates that most users will use together for a full development experience. You may not need all of these - such as [twilight-cache-inmemory] - but they are often used together to accomplish most of what you need.

[twilight-model]

Models defining structures, enums, and bitflags for the entirety of the Discord API. It is split into a number of sub-modules, such as gateway for containing the WebSocket gateway types, guild for containing types owned by guilds (servers), voice containing the types used by the Voice WebSocket API, and more.

These are all in a single crate so that you can use gateway models without depending on [twilight-gateway]. One use case is if you write your own WebSocket gateway implementation.

[twilight-cache-inmemory]

In-process-memory based cache over objects received from the gateway. It's responsible for holding and managing information about things like guilds, channels, role information, voice states, and any other events that come from Discord.

[twilight-gateway]

Implementation of Discord's sharding gateway sessions. This is responsible for receiving stateful events in real-time from Discord and sending some stateful information.

[twilight-http]

HTTP client supporting all of the Discord REST API. It is based on hyper. It meets Discord's ratelimiting requirements and supports proxying.

[twilight-standby]

Event processor that allows for tasks to wait for an event to come in. This is useful, for example, when you have a reaction menu and want to wait for a specific reaction on it to come in.

Additional Crates

These are crates that are officially supported by Twilight, but aren't considered core crates due to being vendor-specific or non-essential for most users.

[twilight-lavalink]

Client for [Lavalink] as part of the twilight ecosystem.

It includes support for managing multiple nodes, a player manager for conveniently using players to send events and retrieve information for each guild, and an HTTP module for creating requests using the [http] crate and providing models to deserialize their responses.

[twilight-mention]

Create display formatters for various model types that format mentions. For example, it can create formatters for mentioning a channel or emoji, or pinging a role or user.

[twilight-util]

Utility crate that adds utilities to the twilight ecosystem that do not fit in any other crate. Currently, it contains:

• A trait to make extracting data from Discord identifiers (Snowflakes)

• A calculator to calculate the permissions of a member in a guild or

[twilight-gateway-queue]

A trait and some implementations that are used by the gateway to ratelimit identify calls. Developers should prefer to use the re-exports of these crates through the gateway.

Quick Start

Twilight provides a [template] to help you get started quickly.

• Install [cargo-generate]: cargo install cargo-generate
• Create a bot based upon the template: cargo generate twilight-rs/template

License

All first-party crates are licensed under [ISC][LICENSE.md].

The twilight logo was created by [Fezhoof] and is licensed under the terms of [CC BY-SA 4.0].

[CC BY-SA 4.0]: https://creativecommons.org/licenses/by-sa/4.0/ [Fezhoof]: https://linktr.ee/fezhoof [LICENSE.md]: https://github.com/twilight-rs/twilight/blob/main/LICENSE.md [Lavalink]: https://github.com/freyacodes/Lavalink [http]: https://crates.io/crates/http [cargo-generate]: https://github.com/cargo-generate/cargo-generate [crates:cache-inmemory]: https://crates.io/crates/twilight-cache-inmemory [crates:gateway]: https://crates.io/crates/twilight-gateway [crates:http]: https://crates.io/crates/twilight-http [crates:model]: https://crates.io/crates/twilight-model [codecov badge]: https://img.shields.io/codecov/c/gh/twilight-rs/twilight?logo=codecov&style=for-the-badge&token=E9ERLJL0L2 [codecov link]: https://app.codecov.io/gh/twilight-rs/twilight/ [discord badge]: https://img.shields.io/discord/745809834183753828?color=%237289DA&label=discord%20server&logo=discord&style=for-the-badge [discord link]: https://discord.gg/7jj8n7D [github badge]: https://img.shields.io/badge/github-twilight-6f42c1.svg?style=for-the-badge&logo=github [github link]: https://github.com/twilight-rs/twilight [license badge]: https://img.shields.io/badge/license-ISC-blue.svg?style=for-the-badge&logo=pastebin [license link]: https://github.com/twilight-rs/twilight/blob/main/LICENSE.md [logo]: https://raw.githubusercontent.com/twilight-rs/twilight/main/logo.png [rust badge]: https://img.shields.io/badge/rust-1.79+-93450a.svg?style=for-the-badge&logo=rust [template]: https://github.com/twilight-rs/template [twilight-cache-inmemory]: https://twilight.rs/chapter1crates/section4cache_inmemory.html [twilight-gateway-queue]: https://twilight.rs/chapter1crates/section7firstparty/section5gatewayqueue.html [twilight-gateway]: https://twilight.rs/chapter1crates/section3gateway.html [twilight-http]: https://twilight.rs/chapter1crates/section2http.html [twilight-lavalink]: https://twilight.rs/chapter1crates/section7firstparty/section3_lavalink.html [twilight-mention]: https://twilight.rs/chapter1crates/section7firstparty/section2_mention.html [twilight-model]: https://twilight.rs/chapter1crates/section1model.html [twilight-standby]: https://twilight.rs/chapter1crates/section6standby.html [twilight-util]: https://twilight.rs/chapter1crates/section7firstparty/section4_util.html