Serenity is a Rust library for the Discord API.
View the [examples] on how to make and structure a bot.
Serenity supports both bot and user login via the use of [Client::login_bot]
and [Client::login_user].
You may also check your tokens prior to login via the use of
[validate_token].
Once logged in, you may add handlers to your client to dispatch [Event]s,
such as [Client::on_message]. This will cause your handler to be called
when a [Event::MessageCreate] is received. Each handler is given a
[Context], giving information about the event. See the
[client's module-level documentation].
The [Shard] is transparently handled by the library, removing
unnecessary complexity. Sharded connections are automatically handled for
you. See the gateway's documentation for more information.
A [Cache] is also provided for you. This will be updated automatically for
you as data is received from the Discord API via events. When calling a
method on a [Context], the cache will first be searched for relevant data
to avoid unnecessary HTTP requests to the Discord API. For more information,
see the cache's module-level documentation.
Note that - although this documentation will try to be as up-to-date and accurate as possible - Discord hosts official documentation. If you need to be sure that some information piece is accurate, refer to their docs.
A basic ping-pong bot looks like:
```rust,no-run
use serenity::client::Client; use std::env;
fn main() { // Login with a bot token from the environment let mut client = Client::loginbot(&env::var("DISCORDTOKEN").expect("token")); client.with_framework(|f| f .configure(|c| c.prefix("~")) // set the bot's prefix to "~" .on("ping", ping));
// start listening for events by starting a single shard
let _ = client.start();
}
command!(ping(_context, message) { let _ = message.reply("Pong!"); }); ```
Full examples, detailing and explaining usage of the basic functionality of the
library, can be found in the [examples] directory.
Add the following to your Cargo.toml file:
toml
[dependencies]
serenity = "0.2"
and to the top of your main.rs:
```rs
```
Serenity only supports the latest Stable, Beta, and Nightly.
Features can be enabled or disabled by configuring the library through Cargo.toml:
toml
[dependencies.serenity]
git = "https://github.com/zeyla/serenity.git"
default-features = false
features = ["pick", "your", "feature", "names", "here"]
The following is a full list of features:
Serenity requires the following dependencies:
The following dependencies all require the voice feature to be enabled in your Cargo.toml:
community/libsodium)extra/opus)Voice+ffmpeg:
extra/ffmpeg)Voice+youtube-dl:
community/youtube-dl)