Discord bot Server - nicho92/MtgDesktopCompanion GitHub Wiki

DiscordBotServer is the MTG Companion server plugin that exposes card lookup and price-movement features through a Discord bot. It uses JDA (Java Discord API) to connect to Discord, registers slash commands, answers interactions with Discord embeds, and records query metadata in the technical service manager for monitoring.

Create your discord bot

Go to Online Help

Where it fits

  • Plugin type: server plugin, declared as org.magic.servers.impl.DiscordBotServer in the default server list.
  • Runtime name: Discord.
  • Primary class: src/main/java/org/magic/servers/impl/DiscordBotServer.java.
  • Admin endpoint: /admin/discord on JSONHttpServer, which combines live Discord connection details with recorded bot queries.
  • Admin UI: the admin Discord page calls /admin/discord and renders guild and message tables.

Startup flow

  1. MTG Companion loads enabled server plugins from the application configuration.
  2. If the Discord server plugin is enabled and AUTOSTART is true, the server manager can start it automatically.
  3. start() builds a JDA client with the Discord bot token stored in the plugin authenticator under TOKEN.
  4. The JDA client installs a listener for:
    • ReadyEvent, used to log that the bot is connected.
    • SlashCommandInteractionEvent, routed to command handling.
    • CommandAutoCompleteInteractionEvent, routed to autocomplete handling.
  5. If ACTIVITY_TYPE and ACTIVITY are configured, the bot presence is updated.
  6. initCommands() registers the bot slash commands with Discord.
  7. Pagination support is activated through the JDA paginator helper used for multi-card search results.

Registered slash commands

Command Required options Optional options Purpose
/card cardname setname, price Searches cards by name, optionally filters by set, and returns card details. If price is true, the response includes the best available regular and foil prices from enabled price providers.
/format formatname none Shows the largest upward and downward daily price movements for a Magic format.
/set setname none Shows the largest upward and downward daily price movements for a set.
/help none none Sends a short usage summary for the supported commands.

All commands are registered as Discord slash commands in initCommands().

Autocomplete behavior

Discord autocomplete is handled before command execution:

  • cardname autocomplete starts only after the typed value reaches AUTOCOMPLETE_START characters. It searches the enabled MTGCardsProvider, keeps distinct names, and returns up to 25 choices.
  • setname autocomplete filters set codes/names. When a card name is already provided, it narrows suggestions to editions of that card; otherwise it uses all editions from the enabled card provider.
  • formatname autocomplete filters values from MTGFormat.FORMATS.

Discord limits autocomplete replies, so the implementation caps choices at 25.

Command handling details

/card

The /card command:

  1. Stores a human-readable query string in a MessageInfo audit object.
  2. Defers the Discord reply, because card provider and price provider calls can take time.
  3. Resolves the optional set filter through the enabled MTGCardsProvider.
  4. Searches matching cards by name.
  5. Builds one embed per matching card with:
    • card name and mana cost,
    • color-derived embed color,
    • type line,
    • oracle text,
    • set,
    • reserved-list status,
    • extra card metadata when present,
    • collection names when SHOW_COLLECTIONS is enabled,
    • image or thumbnail from the enabled MTGPictureProvider,
    • optional prices from all enabled MTGPricesProvider implementations,
    • optional external link built from EXTERNAL_LINK plus the card Scryfall ID.
  6. Sends the first embed and enables pagination when multiple cards match.

/format

The /format command asks the enabled dashboard plugin for price shakers in the selected format. It sorts the result twice: once for the biggest upward daily percentage changes and once for the biggest downward daily percentage changes. Each side is limited by CARD_SHAKE_LIMIT, and the combined result is returned in an embed.

/set

The /set command resolves the selected set through the enabled card provider, then asks the enabled dashboard plugin for that edition's price shakers. It uses the same upward/downward daily movement display and CARD_SHAKE_LIMIT behavior as /format.

/help

The /help command sends a plain text explanation of /card, /format, and /set.

Configuration

DiscordBotServer defines these plugin properties:

See Discord plugin documentation

Monitoring and admin data

Every slash command creates a MessageInfo audit record with the Discord user, channel, guild, query text, timing, and any accumulated price-provider errors. The record is stored through AbstractTechnicalServiceManager after command handling.

The JSON admin server exposes /admin/discord, returning:

  • server: live bot details from DiscordBotServer.toJsonDetails(), including guilds, bot user, and presence data when connected.
  • queries: recorded Discord MessageInfo entries from the technical service manager.

The admin UI's Discord page consumes that endpoint to display bot status, guild information, and message/query history.

Dependencies on other MTG Companion plugins

DiscordBotServer is an integration layer. It delegates most MTG-specific work to enabled plugins:

  • MTGCardsProvider for card search, set lookup, and edition listing.
  • MTGPictureProvider for card image URLs.
  • MTGPricesProvider implementations for optional price fields on /card.
  • MTGDao for optional collection lookup when SHOW_COLLECTIONS is enabled.
  • MTGDashBoard for card-shaker data used by /format and /set.

Because of those dependencies, command quality depends on the configured providers and whether they are enabled, reachable, and indexed.

Stopping and health

  • stop() shuts down the JDA client, sets the Discord presence offline, and logs the stop.
  • isAlive() returns true only when the JDA status is CONNECTED.
  • getVersion() reports the JDA library version used by the plugin.

Troubleshooting checklist

  • Verify the Discord server plugin is enabled in the server configuration.
  • Add a valid Discord bot token to the plugin authenticator under TOKEN.
  • Ensure the bot has been invited to the target Discord guild with permissions to use slash commands and send embeds.
  • Check that card, picture, dashboard, DAO, and price providers are enabled as needed for the commands you want to use.
  • Use the admin Discord page or /admin/discord endpoint to confirm connection status, guild visibility, and recorded query errors.
  • If autocomplete seems inactive, check AUTOCOMPLETE_START and remember that Discord will not request card-name suggestions until the configured character threshold is reached.