Discord Embeds & Views
Relevant source files
The following files were used as context for generating this wiki page:
Discord Embeds and Views provide the primary interface for rich, interactive communication between Red and its users. Embeds allow the bot to send structured data with titles, descriptions, and fields, while Views leverage Discord's interaction components like buttons and select menus to create dynamic UI elements.
The bot uses these components across various modules, including the help system, general utility commands, and audio playback. Configuration settings allow server administrators and users to toggle embed usage and choose between different interaction styles, such as traditional reactions or modern component-based menus.
Sources: redbot/core/commands/help.py, redbot/core/core_commands.py:1085-1100
Interaction Components and Views
Interactions in Red are primarily handled through the discord.ui.View class and its derivatives. These views manage the state and logic for buttons and select menus attached to messages.
SimpleMenu and Navigation
The SimpleMenu class implements a paginated navigation system. It supports navigation via buttons or select menus based on the bot's configuration.
The diagram above shows the logic flow within a SimpleMenu instance when navigating between content pages.
SimpleMenuhandles a list of pages which can be either strings ordiscord.Embedobjects.- It includes controls for "First", "Previous", "Stop", "Next", and "Last".
- The
use_select_menuattribute determines if a dropdown is added for direct page jumps.
Sources: redbot/core/utils/views.py:11-131, redbot/core/commands/help.py:618-630
Specialized Views
Red employs specific views for administrative tasks and configuration:
- SetApiView: Provides a specialized interface for configuring API tokens, including a button that triggers a modal for secure input.
- ConfirmView: A standard utility for "Yes/No" or "Confirm/Cancel" interactions.
Sources: redbot/core/utils/views.py:134-210, redbot/core/core_commands.py:1800-1805
Embed System and Configuration
Embeds are used to present detailed information like server statistics, command help, and dictionary definitions.
Hierarchy of Embed Settings
The bot evaluates whether to use embeds based on a specific priority order. The system checks settings until it finds an explicit True or False.
| Priority | Scope | Description |
|---|---|---|
| 1 | Channel | Overrides set for specific text/voice channels. |
| 2 | Server Command | Command-specific overrides within a guild. |
| 3 | Server | Global toggle for an entire guild. |
| 4 | Global Command | Global command-specific default. |
| 5 | Global | The final fallback setting for the entire bot instance. |
Sources: redbot/core/core_commands.py:1085-1103
Embed Formatting Logic
The bot includes logic to group and paginate embeds to stay within Discord's character limits. For example, the help system groups fields into batches to prevent exceeding the 5500-character total limit or 1024-character field limit.
Sources: redbot/core/commands/help.py:385-440
Feature Implementation Examples
Help System Menus
The help command uses HelpMenuSetting to determine the interaction style.
| Setting | Value | Description |
|---|---|---|
disabled | 0 | Sends pages as separate messages. |
reactions | 1 | Uses legacy emoji reactions for navigation. |
buttons | 2 | Uses modern button components. |
select | 3 | Uses buttons and a select menu. |
selectonly | 4 | Uses only a select menu for navigation. |
Sources: redbot/core/commands/help.py:59-66, redbot/core/core_commands.py:2285-2315
General Cog Embeds
The General cog utilizes embeds for commands like serverinfo and urban. The serverinfo command dynamically builds an embed with fields for member counts, channel counts, and guild features.
# Simplified snippet of serverinfo embed creation
data = discord.Embed(description=created_at, colour=await ctx.embed_colour())
data.add_field(name=_("Users online"), value=f"{online}/{total_users}")
data.add_field(name=_("Roles"), value=humanize_number(len(guild.roles)))
Sources: redbot/cogs/general/general.py:236-258
Audio Utility Formatting
The Audio module uses a send_embed_msg helper to ensure consistent embed styling. It automatically retrieves the configured embed color and applies timestamps and footers.
Sources: redbot/cogs/audio/core/utilities/miscellaneous.py:58-100
Configuration Commands
Administrators manage embeds and views through the following command groups:
[p]embedset: Toggles embed usage across various scopes (user, channel, server, global).[p]helpset usemenus: Selects the interaction type for the help command.[p]helpset pagecharlimit: Adjusts the maximum characters allowed per help embed page.
Sources: redbot/core/core_commands.py:1105-1350, redbot/core/core_commands.py:2280-2320
Summary
The Discord Embeds & Views system provides a flexible, tiered configuration that allows Red to adapt to different server preferences. By utilizing specialized navigation classes like SimpleMenu and hierarchical settings, the bot maintains high readability and interactive capability while respecting Discord's API constraints.