discordrb Documentation

To add discordrb to your project using Bundler, add the following line to your Gemfile:

gem 'discordrb'

Then, run bundle install in your terminal. To run a script (e.g., ping.rb) within the Bundler context, use:

bundle exec ruby ping.rb

You can install the gem directly without Bundler using the following commands depending on your operating system:

Linux / macOS

gem install discordrb

Windows Note: Ensure you have the Ruby DevKit installed (e.g., via RubyInstaller).

gem install discordrb --platform=ruby

If your bot requires voice functionality, you must install the following system dependencies:

1. libsodium
2. libopus: A compiled libopus distribution available in your system's PATH.
3. FFmpeg: Must be installed and available in your PATH.

The Discordrb::Commands system supports command chaining, allowing multiple commands to be executed in sequence.

• Chaining: Commands can be linked together (e.g., !cmd1 !cmd2). A command must have chain_usable: true (which is the default) to be part of a chain.
• Subchains: You can nest commands using subchain delimiters (configured in the bot attributes). This allows for complex, nested command structures.
• Execution: The CommandChain class handles the parsing of delimiters, quotes, and escape characters to ensure arguments are passed correctly between commands in the chain.

You can implement rate limiting for specific commands using the bucket and rate_limit_message attributes. If a bucket is provided, the bot checks if the user is rate-limited for that bucket before executing the command block.

• bucket: A unique identifier for the rate-limiting bucket.
• rate_limit_message: The message sent to the user when rate-limited. You can use the %time% placeholder to inject the remaining time until the next request is allowed.

Discordrb::Commands::Command.new(:spammy, 
  bucket: :spam_check, 
  rate_limit_message: "Slow down! Wait %time% seconds."
) do |event|
  # ...
end

Discord Intents are used to declare which events your bot wishes to receive from the Discord Gateway. You can use the Discordrb::INTENTS hash to select specific intents.

Commonly used constants include:

• Discordrb::ALL_INTENTS: All available intents.
• Discordrb::UNPRIVILEGED_INTENTS: All intents except for server_members and server_presences (which require privileged access in the Discord Developer Portal).
• Discordrb::NO_INTENTS: No intents (0).

# Example of using specific intents
intents = Discordrb::INTENTS[:server_messages] | Discordrb::INTENTS[:server_members]

Discordrb monkey-patches Integer and String to provide a resolve_id method. This allows for consistent ID handling across different types.

• Integer#resolve_id: Returns itself.
• String#resolve_id: Returns the integer representation of the string.

"12345".resolve_id # => 12345
12345.resolve_id     # => 12345

The Discordrb::Webhook class allows you to interact with webhooks on a server channel. You can retrieve its name, channel, server, avatar, and type. If it is an Incoming Webhook, you can access its token.

Key attributes:

• name: The webhook name.
• channel: The Channel the webhook is connected to.
• server: The Server the webhook is connected to.
• token: The webhook's token (only available for Incoming Webhooks).
• avatar: The webhook's avatar ID.
• type: The webhook type (1 for Incoming, 2 for Channel Follower).
• owner: The Member, User, or nil object of the creator. Returns nil if the webhook was requested using a token.

The :prefix attribute determines what triggers a command chain. It supports three modes:

1. String: A literal prefix. If the prefix is !, a command test is triggered by !test. Note that it is literal; if you want a space, the prefix must be ! .
2. Array of Strings: Any string in the array can act as a prefix.
3. Proc: A callable object that receives a Discordrb::Message and returns either the raw command chain string or nil if the message should be ignored. This allows for dynamic prefixes based on server context or other logic.

# Example of a dynamic prefix using a Proc
bot = Discordrb::Commands::CommandBot.new(
  token: 'TOKEN',
  prefix: ->(message) {
    # Only allow commands in a specific server
    message.guild.id == 12345 ? '!' : nil
  }
)

The Discordrb::Events.matches_all method is used to determine if an event's attributes satisfy a set of criteria. It supports several formats for the attributes parameter:

1. nil: Always returns true.
2. Single attribute (not negated): Matches if the attribute equals the to_check value (via the provided block).
3. Single attribute (negated): Matches if the attribute does not equal the to_check value (using not!(object)).
4. Array of attributes: Matches if any element in the array matches the to_check value (OR logic).

Note: It does not support an array of negated attributes. The comparison logic is driven by a block that receives the attribute (a) and the value to check (e).

To create a basic bot, require discordrb, initialize a Discordrb::Bot with your bot token, define event handlers (such as bot.message), and call bot.run to start the connection.

require 'discordrb'

bot = Discordrb::Bot.new token: '<token here>'

bot.message(with_text: 'Ping!') do |event|
  event.respond 'Pong!'
end

bot.run