[−][src]Crate 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-command-parser
, 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 requires the latest stable Rust version.
We recommend that most users start out with these crates added to your
Cargo.toml
's [dependencies]
section:
twilight-cache-inmemory = "0.1"
twilight-gateway = "0.1"
twilight-http = "0.1"
twilight-model = "0.1"
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-command-parser
- 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-command-parser
Helpful crate for parsing commands out of messages received over the gateway. It finds messages commanding your bot and parses the arguments out.
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-embed-builder
Utility crate for creating and validating message embeds, to be used when creating or updating messages.
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.
Examples
use std::{env, error::Error}; use tokio::stream::StreamExt; use twilight_cache_inmemory::{EventType, InMemoryCache}; use twilight_gateway::{cluster::{Cluster, ShardScheme}, Event}; use twilight_http::Client as HttpClient; use twilight_model::gateway::Intents; #[tokio::main] async fn main() -> Result<(), Box<dyn Error + Send + Sync>> { let token = env::var("DISCORD_TOKEN")?; // This is the default scheme. It will automatically create as many // shards as is suggested by Discord. let scheme = ShardScheme::Auto; let cluster = Cluster::builder(&token) .shard_scheme(scheme) // Use intents to only receive guild message events. .intents(Intents::GUILD_MESSAGES) .build() .await?; // Start up the cluster. let cluster_spawn = cluster.clone(); // Start all shards in the cluster in the background. tokio::spawn(async move { cluster_spawn.up().await; }); // HTTP is separate from the gateway, so create a new client. let http = HttpClient::new(&token); // Since we only care about new messages, make the cache only // cache new messages. let cache = InMemoryCache::builder() .event_types( EventType::MESSAGE_CREATE | EventType::MESSAGE_DELETE | EventType::MESSAGE_DELETE_BULK | EventType::MESSAGE_UPDATE, ) .build(); let mut events = cluster.events(); // Process each event as they come in. while let Some((shard_id, event)) = events.next().await { // Update the cache with the event. cache.update(&event); tokio::spawn(handle_event(shard_id, event, http.clone())); } Ok(()) } async fn handle_event( shard_id: u64, event: Event, http: HttpClient, ) -> Result<(), Box<dyn Error + Send + Sync>> { match event { Event::MessageCreate(msg) if msg.content == "!ping" => { http.create_message(msg.channel_id).content("Pong!")?.await?; } Event::ShardConnected(_) => { println!("Connected on shard {}", shard_id); } // Other events here... _ => {} } Ok(()) }
Note about tracing
When using the tracing
crate you won't, by default, see logs from any
libraries that use the log
crate. You can add that back by using the
tracing-log
crate and initializing it like this:
tracing_log::LogTracer::init()?;
License
All first-party crates are licensed under ISC