Repository files navigation

This is a fork ofserenity-rs/serenity that has tweaks for making custom clients andprobably violates Discord TOS.

If you want to make a bot, use the upstream version.

This repo is not stable and is often rebased onto upstream.

Serenity is a Rust library for the Discord API.

View theexamples on how to make and structure a bot.

Serenity supports bot login via the use ofClient::new.

You may also check your tokens prior to login via the use ofvalidate_token.

Once logged in, you may add handlers to your client to dispatchEvents,by implementing the handlers in a trait, such asEventHandler::message.This will cause your handler to be called when aEvent::MessageCreate isreceived. Each handler is given aContext, giving information about theevent. See theclient's module-level documentation.

TheShard is transparently handled by the library, removingunnecessary complexity. Sharded connections are automatically handled foryou. See thegateway's documentation for more information.

ACache is also provided for you. This will be updated automatically foryou as data is received from the Discord API via events. When calling amethod on aContext, the cache will first be searched for relevant datato avoid unnecessary HTTP requests to the Discord API. For more information,see thecache's module-level documentation.

Note that - although this documentation will try to be as up-to-date andaccurate as possible - Discord hostsofficial documentation. Ifyou need to be sure that some information piece is accurate, refer to theirdocs.

A basic ping-pong bot looks like:

use serenity::client::Client;use serenity::model::channel::Message;use serenity::prelude::{EventHandler,Context};use serenity::framework::standard::{StandardFramework,CommandResult,    macros::{        command,        group}};group!({    name:"general",    options:{},    commands:[ping],});use std::env;structHandler;implEventHandlerforHandler{}fnmain(){// Login with a bot token from the environmentletmut client =Client::new(&env::var("DISCORD_TOKEN").expect("token"),Handler).expect("Error creating client");    client.with_framework(StandardFramework::new().configure(|c| c.prefix("~"))// set the bot's prefix to "~".group(&GENERAL_GROUP));// start listening for events by starting a single shardifletErr(why) = client.start(){println!("An error occurred while running the client: {:?}", why);}}#[command]fnping(ctx:&mutContext,msg:&Message) ->CommandResult{    msg.reply(ctx,"Pong!")?;Ok(())}

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

Add the following to yourCargo.toml file:

[dependencies]serenity ="0.7"

Serenity supports a minimum of Rust 1.35.

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

[dependencies.serenity]default-features =falsefeatures = ["pick","your","feature","names","here"]version ="0.7"

The default features are:builder,cache,client,framework,gateway,http,model,standard_framework,utils, andrustls_backend.

The following is a full list of features:

• builder: The builders used in conjunction with models' methods.
• cache: The cache will store information about guilds, channels, users, andother data, to avoid performing REST requests. If you are low on RAM, do notenable this.
• client: A manager for shards and event handlers, abstracting away thework of handling shard events and updating the cache, if enabled.
• framework: Enables the framework, which is a utility to allow simplecommand parsing, before/after command execution, prefix setting, and more.
• gateway: A Shard, used as a higher-level interface for communicating withthe Discord gateway over a WebSocket client.
• http: Functions providing a wrapper over Discord's REST API at a lowenough level that optional parameters can be provided at will via a JsonMap.
• model: Method implementations for models, acting as helper methods overthe HTTP functions.
• standard_framework: A standard, default implementation of the Framework
• utils: Utility functions for common use cases by users.
• voice: Enables compilation of voice support, so that voice channels can beconnected to and audio can be sent/received.
• default_native_tls: Default features but usingnative_tls_backendinstead ofrustls_backend.

Serenity offers two TLS-backends,rustls_backend by default, you need to pickone if you do not use the default features:

• rustls_backend: Uses Rustls for all platforms, a pure RustTLS implementation.
• native_tls_backend: Uses SChannel on Windows, Secure Transport on macOS,and OpenSSL on other platforms.

If you want all of the default features except forcache for example, you canlist all but that:

[dependencies.serenity]default-features =falsefeatures = ["builder","client","framework","gateway","http","model","standard_framework","utils","rustls_backend",]version ="0.7"

If you use thenative_tls_backend and you are not developing on macOS or Windows, you will need:

• openssl

If you want to usevoice, Serenity will attempt to build these for you:

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

In case the automated building fails, you may report it to us, but installing should fix it.

Voice + ffmpeg:

• ffmpeg (Arch:extra/ffmpeg)

Voice + youtube-dl:

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

• Discord.net
• JDA
• disco
• discordrb
• discord.js
• discord.py