serenity 0.2.0

A Rust library for the Discord API.
serenity-0.2.0 doesn't have any documentation.

ci-badge crate-badge license-badge docs-badge contribs-badge dapi-badge

serenity

serenity logo

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 Events, 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:

#[macro_use] extern crate serenity;

use serenity::client::Client;
use std::env;

fn main() {
    // Login with a bot token from the environment
    let mut client = Client::login_bot(&env::var("DISCORD_TOKEN").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

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

Installation

Add the following to your Cargo.toml file:

[dependencies]
serenity = "0.2"

and to the top of your main.rs:

#[macro_use] extern crate serenity;

Serenity only supports the latest Stable, Beta, and Nightly.

Features

Features can be enabled or disabled by configuring the library through Cargo.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:

  • 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;
  • 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)

Related Projects