If you need any other functionality that Twilight provides, you can just add
that dependency in.
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.
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.
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.
Implementation of Discord's sharding gateway sessions. This is responsible
for receiving stateful events in real-time from Discord and sending some
stateful information.
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.
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.
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.
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.
Examples
The following example is a template for bootstrapping a new bot using
Twilight's HTTP and gateway clients with its in-memory cache. In order to
run this, replace the contents of a new project's main.rs file with the
following. Be sure to set the DISCORD_TOKEN environment variable to your
bot's token. You must also depend on futures, tokio,
twilight-cache-inmemory, twilight-gateway, twilight-http, and
twilight-model in your Cargo.toml.
use std::{env, error::Error, sync::Arc};use twilight_cache_inmemory::{InMemoryCache,ResourceType};use twilight_gateway::{Event,Shard,ShardId};use twilight_http::ClientasHttpClient;use twilight_model::gateway::Intents;#[tokio::main]asyncfnmain() -> anyhow::Result<()>{// Initialize the tracing subscriber.
tracing_subscriber::fmt::init();let token = env::var("DISCORD_TOKEN")?;// Use intents to only receive guild message events.letmut shard = Shard::new(ShardId::ONE,
token.clone(),Intents::GUILD_MESSAGES | Intents::MESSAGE_CONTENT,);// HTTP is separate from the gateway, so create a new client.let http = Arc::new(HttpClient::new(token));// Since we only care about new messages, make the cache only// cache new messages.let cache = InMemoryCache::builder().resource_types(ResourceType::MESSAGE).build();// Process each event as they come in.loop{let event = match shard.next_event().await{Ok(event) => event,Err(source) => {
tracing::warn!(?source, "error receiving event");if source.is_fatal(){break;}continue;}};// Update the cache with the event.
cache.update(&event);
tokio::spawn(handle_event(event,Arc::clone(&http)));}Ok(())}asyncfnhandle_event(event:Event,http:Arc<HttpClient>,) -> Result<(),Box<dynError + Send + Sync>>{match event {Event::MessageCreate(msg)if msg.content == "!ping" => {
http.create_message(msg.channel_id).content("Pong!")?
.await?;}// Other events here...
_ => {}}Ok(())}
twilight-rs/twilight
twilight
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.67.
We recommend that most users start out with these crates:
twilight-cache-inmemory
twilight-gateway
twilight-http
twilight-model
If you need any other functionality that Twilight provides, you can just add that dependency in.
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 ontwilight-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:
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.
Examples
The following example is a template for bootstrapping a new bot using Twilight's HTTP and gateway clients with its in-memory cache. In order to run this, replace the contents of a new project's
main.rs
file with the following. Be sure to set theDISCORD_TOKEN
environment variable to your bot's token. You must also depend onfutures
,tokio
,twilight-cache-inmemory
,twilight-gateway
,twilight-http
, andtwilight-model
in yourCargo.toml
.License
All first-party crates are licensed under ISC