DOCSEARCHbyAlgolia
Submit Docs

poise

repository·current·Indexed 21 days ago

https://github.com/serenity-rs/poise

An opinionated Discord bot framework for serenity (v0.6.2) that simplifies bot creation with automated argument parsing, unified command handling for slash and text commands, and built-in support for message edit tracking. It provides procedural macros like #[poise::command] and #[derive(ChoiceParameter)] to define command behavior, metadata, and selectable options.

Tokens
16.9K
Snippets
45
Records
73
Agent score
74%

What's inside poise

  1. Overview of Poise features

    current

    Poise is an opinionated Discord bot framework designed to simplify command handling and interaction. Key features include:

    • Slash commands: Define slash commands using a single Rust function signature.
    • Flexible argument parsing: Command parameters are automatically parsed from normal Rust types.
    • Text commands: Commands are agnostic, supporting both legacy text-based commands and modern slash commands.
    • Edit tracking: Automatically updates bot responses when a user edits their message.

  2. Explore Poise usage patterns via examples

    current

    Poise provides several example categories to demonstrate its capabilities:

    • Basic Structure: Demonstrates FrameworkOptions, creating and accessing the user-defined data struct, implementing a help command, defining commands, and sending responses.
    • Feature Showcase: A 'kitchen sink' demonstration of most Poise features, where each file focuses on a specific feature using one or more example commands.
    • Fluent Localization: Shows how to implement localization for large-scale bots using the Fluent localization framework.
    • Invocation Data: Demonstrates how Context.invocation_data flows through the different stages of a command invocation.
    • Manual Dispatch: Shows how to bypass poise::Framework to manually invoke Poise's event dispatch functions (intended for special use cases).
    • Quickstart: A minimal, runnable example used for basic verification and testing.

  3. Configure environment variables for Poise

    current

    To run Poise examples or applications, you must provide your Discord application token via the following environment variable:

    • DISCORD_TOKEN: your application's token

    Note that Application ID and owner ID are not required to be set manually, as poise requests them from Discord automatically during startup.

    export DISCORD_TOKEN=your_token_here

  4. How to learn and use Poise

    current

    To get started with Poise, you should consult the following resources:

    1. API Documentation: The primary source for technical details and method signatures.
    2. Examples: The examples/ directory in the repository contains practical implementations. Specifically, check examples/feature_showcase to see the full range of Poise's capabilities.
    3. Development Versions: If you are using a development version directly from Git, refer to the current or next branch documentation instead of the stable docs.

    For community support, you can join the Serenity support server.

  6. Define Context Menu Commands

    current

    Context menu commands (User/Member/Channel context menus) are specialized commands that operate on a single target.

    Constraint: A context menu command must have exactly one parameter. The type of this parameter determines what the context menu acts upon (e.g., a User or a Message). The framework uses the ContextMenuParameter trait to convert the interaction value into the type required by your function.

  7. How application replies and followups work

    current

    When using send_application_reply (or send_reply in an application context), Poise manages the lifecycle of the interaction response:

    1. Initial Response: If no response has been sent yet, it sends an initial interaction response.
    2. Followups: If an initial response has already been sent, it automatically sends a followup instead.
    3. Autocomplete: If the interaction type is Autocomplete, the function performs a no-op and returns an Autocomplete handle.

    This ensures that your command can respond to the user even if the initial interaction window has expired or if you are performing multi-step operations.

  8. Use discard_spare_arguments in prefix commands

    current
    When defining a prefix command, you can configure it to discard any extra arguments provided by the user that are not explicitly captured by your parameters. If discard_spare_arguments is set to true, the macro automatically appends a #[rest] (Option<String>) parameter to the internal parsing logic to consume any leftover text.

  9. Configure Gateway Intents for Poise

    current

    To receive specific events from Discord, you must set gateway intents. For Poise to support prefix commands, you must include the MESSAGE_CONTENT intent.

    A common setup is to use non_privileged() intents combined with MESSAGE_CONTENT using the bitwise OR operator.

    serenity::GatewayIntents::non_privileged() | serenity::GatewayIntents::MESSAGE_CONTENT

  10. How user data works in Poise

    current

    Poise allows you to maintain a global state (user data) that is accessible to all commands and interactions.

    1. Initialization: You provide a setup closure during framework construction. This closure is invoked automatically as soon as the bot receives the Ready event from Discord.
    2. Data Availability: Because the setup runs after the Ready event, you can use the serenity::Context and serenity::Ready data (like the bot's user ID or connected guilds) to initialize your state.
    3. Accessing Data: You can retrieve this data asynchronously using framework.user_data().await. This method will block (via polling) until the Ready event has been processed and the data is initialized, ensuring you never access uninitialized state in your commands.
    // Example setup closure signature
let setup = |ctx: &serenity::Context, ready: &serenity::Ready, framework: &Framework<MyData, MyError>| {
    Box::pin(async move {
        // Initialize your custom data type
        Ok(MyData { /* ... */ })
    })
};

  11. Manage Framework Owners and Permissions

    current

    Poise provides built-in support for managing bot owners to bypass certain checks.

    • owners: A HashSet<serenity::UserId> containing the IDs of users allowed to use owners_only commands.
    • initialize_owners: If true (default), Poise automatically populates the owners set using the application info from Discord.
    • initialized_team_roles: When initialize_owners is true, you can specify which serenity::TeamMemberRoles should be treated as owners. If set to None (default), only users with the Developer and Admin roles are initialized as owners.
    • skip_checks_for_owners: If true, any command issued by an ID in the owners set will skip all command checks.

  12. Use `poise::serenity_prelude` for easier imports

    current

    Poise re-exports most items from the serenity crate via poise::serenity_prelude. This allows you to use shorter paths for common Discord types like Member, UserId, or GatewayIntents.

    use poise::serenity_prelude as serenity;

// Now you can use serenity::Member, serenity::UserId, etc.