serenity

Serenity uses Cargo features to manage dependencies and functionality. You can disable default features to reduce binary size or RAM usage (e.g., disabling cache).

Default features include:

• builder, cache, chrono, client, framework, gateway, http, model, standard_framework, utils, rustls_backend.

Commonly used features:

• cache: Stores guilds, channels, and users to avoid REST requests. Disable if RAM is limited.
• collector: Allows awaiting specific events (messages, reactions) with configurable criteria.
• voice: Enables voice plugin registration. Use Songbird for actual voice connections.
• simd_json: Enables SIMD accelerated JSON parsing.
• unstable_discord_api: Enables features of the Discord API that do not have a stable interface.
• full: Enables all parts of the codebase.

[dependencies.serenity]
default-features = false
features = ["builder", "chrono", "client", "gateway", "http", "model", "utils", "rustls_backend"]
version = "0.12"

Use BucketBuilder to define how commands are rate limited within the StandardFramework. You can specify the scope of the limit (Global, User, Guild, Channel, or Category), the delay between invocations, the number of allowed invocations within a specific time span, and custom actions when a limit is exceeded.

Key Configuration Methods:

• new_global(), new_user(), new_guild(), new_channel(), new_category(): Sets the scope of the rate limit.
• delay(secs: u64): Sets the minimum duration between command invocations.
• time_span(secs: u64): Sets the window of time for the limit to apply.
• limit(n: u32): Sets the maximum number of allowed invocations within the time_span.
• await_ratelimits(amount: u32): If greater than 0, the command invocation will be delayed amount times instead of being cancelled. This is required to trigger delay_action.
• delay_action(action: DelayHook): Provides a callback function to execute when a user's command is delayed (e.g., sending a custom warning message). This automatically sets await_ratelimits to at least 1.
• check(check: Check): Adds a middleware function to verify if the command invocation is eligible for the bucket.

let framework = StandardFramework::new()
    .bucket("example_bucket", BucketBuilder::default()
        .delay_action(|ctx, msg| {
            Box::pin(example_overuse_response(ctx, msg))
        })
        .delay(10) // 10 second delay
        .await_ratelimits(1) // Allow 1 delay action to trigger
    )
    .await
    .group(&GENERAL_GROUP);

Use HttpBuilder to customize the underlying HTTP client. This is useful if you need to use a proxy or disable the internal rate limiter (e.g., when delegating rate limiting to a proxy like twilight-http-proxy).

Key configuration methods:

• new(token): Creates a new builder. The token is automatically prefixed with "Bot " if not already present.
• proxy(proxy_url): Sets a proxy URL (e.g., http://127.0.0.1:3000).
• ratelimiter_disabled(bool): Disables the internal rate limiter. Use this with proxy to delegate rate limiting to an external service.
• application_id(id): Sets the application ID for interaction-related requests.
• client(reqwest_client): Provides a custom reqwest::Client.
• build(): Finalizes the configuration and returns an Http instance.

# use serenity::http::HttpBuilder;
# fn run() {
let http =
    HttpBuilder::new("token").proxy("http://127.0.0.1:3000").ratelimiter_disabled(true).build();
# }

To create a basic bot, implement the EventHandler trait to respond to events (like message) and use Client::builder to initialize the client with your bot token and required GatewayIntents. Use client.start() to begin listening for events.

use std::env;

use serenity::async_trait;
use serenity::model::channel::Message;
use serenity::prelude::*;

struct Handler;

#[async_trait]
impl EventHandler for Handler {
    async fn message(&self, ctx: Context, msg: Message) {
        if msg.content == "!ping" {
            if let Err(why) = msg.channel_id.say(&ctx.http, "Pong!").await {
                println!("Error sending message: {why:?}");
            }
        }
    }
}

#[tokio::main]
async fn main() {
    // Login with a bot token from the environment
    let token = env::var("DISCORD_TOKEN").expect("Expected a token in the environment");
    // Set gateway intents, which decides what events the bot will be notified about
    let intents = GatewayIntents::GUILD_MESSAGES
        | GatewayIntents::DIRECT_MESSAGES
        | GatewayIntents::MESSAGE_CONTENT;

    // Create a new instance of the Client, logging in as a bot.
    let mut client =
        Client::builder(&token, intents).event_handler(Handler).await.expect("Err creating client");

    // Start listening for events by starting a single shard
    if let Err(why) = client.start().await {
        println!("Client error: {why:?}");
    }
}