serenity.rs

Serenity is an ergonomic and high-level 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.

Example Bot

A basic ping-pong bot looks like:

```rust,no-run extern crate serenity;

use serenity::client::{Client, Context}; use serenity::model::Message; 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();

}

fn ping(_context: &Context, message: &Message, _args: Vec) { let _ = message.reply("Pong!"); } ```

Full Examples

Full examples, detailing and explaining usage of the basic functionality of the library, can be found in the [examples] directory.

Features

Features can be enabled or disabled by configuring the library through Cargo.toml:

toml [dependencies.serenity] git = "https://github.com/zeyla/serenity.rs.git" default-features = false features = ["pick", "your", "feature", "names", "here"]

The following is a full list of features:

• cache: The cache will store information about guilds, channels, users, and other data, to avoid performing REST requests. If you are low on RAM, do not enable this;
• framework: Enables the framework, which is a utility to allow simple command parsing, before/after command execution, prefix setting, and more;
• methods: Enables compilation of extra methods on struct implementations, such as Message::delete(), Message::reply(), Guild::edit(), and more. Without this enabled, requests will need to go through the [Context] or [rest] module, which are slightly less efficient from a development standpoint, and do not automatically perform permission checking;
• voice: Enables compilation of voice support, so that voice channels can be connected to and audio can be sent/received.

Dependencies

Serenity requires the following dependencies:

• openssl

Voice

The following dependencies all require the voice feature to be enabled in your Cargo.toml:

• libsodium (Arch: community/libsodium)
• opus (Arch: extra/opus)

Voice+ffmpeg:

• ffmpeg (Arch: extra/ffmpeg)

Voice+youtube-dl:

• youtube-dl (Arch: community/youtube-dl)