Breadcrumb Trail Documentation

Overview

A breadcrumb trail is a list of secret words. When a player says one of them in a monitored channel, the bot records the find, can DM the player a message, and tells the moderators in the game log. A player who finds every word completes the trail, which can send a completion DM and add or remove Discord roles. Use it for hidden objectives, scavenger hunts, or unlocking a secret shop.

Four moderator commands manage the trail, and a web page manages everything else:

• /addbreadcrumb - Add a word to the trail
• /removebreadcrumb - Remove a word from the trail
• /breadcrumbprogress - Show every player's progress
• /managebreadcrumbs - Get a private link to the management page

Moderator only: all four commands require the server's configured moderator role.

Two-server setups: the trail is stored once per game, under the chat server. The commands work the same from the chat server or the role server, and channels on both servers can be monitored.

/addbreadcrumb Command

Add a word or phrase to the trail. Only works while a game is active.

Arguments

┌──────────┬────────┬──────────┬──────────────────────────────────────────────────────────┐
│ Argument │ Type   │ Required │ Description                                              │
├──────────┼────────┼──────────┼──────────────────────────────────────────────────────────┤
│ word     │ String │ Yes      │ The word or phrase to watch for                          │
│ message  │ String │ No       │ DM sent to the player when they say this word            │
└──────────┴────────┴──────────┴──────────────────────────────────────────────────────────┘

Without message, the breadcrumb is silent: the find is still recorded and logged, but the player is not told. Adding a word that is already on the trail is refused.

Examples

/addbreadcrumb word:moonlight message:You feel a chill. The old mill is worth a second look.
/addbreadcrumb word:old mill

/removebreadcrumb Command

Remove a word from the trail. All player progress for that word is removed too.

/removebreadcrumb word:moonlight

/breadcrumbprogress Command

Post a private 🍞 Breadcrumb Trail Progress embed. It lists the trail (each word with its DM message, if any) and then one line per player: Name — 2/5 followed by the words they have found, with 🏆 Completed the trail! for players who finished. Players in the game are listed first; anyone else who has found a word is added after them. Long lists continue in extra embeds.

/breadcrumbprogress

/managebreadcrumbs Command

Reply with a private link to the breadcrumb management page. The link is personal; do not share it.

The page has these sections:

• Breadcrumb Settings — the two trail rules (below) and the optional trail completion DM.
• Monitored Channels — which channels (or whole categories) on the chat server and, if different, the role server the bot listens in. Nothing is detected until at least one channel is monitored.
• Breadcrumb Words — add, edit and remove words and their DM messages, the same data as /addbreadcrumb and /removebreadcrumb.
• Trail Completions — who has completed the trail, the maximum number of players who receive the completion DM and roles (0 = unlimited), and a reset.
• Completion Roles — roles to add and roles to remove on each server when a player completes the trail.

Trail rules

• Require in order — a word only counts if the previous word on the list has already been found by that player. Said out of order, it does nothing.
• Require single message — the trail is only completed by one message that contains every word. Off (the default), finding all the words across any number of messages completes it.

How Detection Works

• The bot watches messages in the monitored channels. Monitoring a category covers every text channel in it, and monitoring a channel covers its threads.
• Messages from bots and from moderators are ignored, and so is a message that is nothing but a URL.
• Matching is case-insensitive on whole words, so moonlight matches Moonlight! but not moonlights.
• Each word counts once per player. The first time a player says it, the bot records the find with a link to the message, sends the word's DM message (if any), and posts 🍞 Name said "word" — jump to message in the game log channel. If the DM cannot be delivered (DMs disabled), the log line says so.
• When a player has found every word (see the trail rules above), the bot records the completion and posts 🏆 Name completed the entire breadcrumb trail! in the game log. If the completion cap has not been reached, the player also gets the completion DM and the configured roles are added and removed on each server.
• Completions past the cap are still recorded and logged; those players just do not receive the DM or roles.

Tips

• Add the words before you open the monitored channels to players, so early messages are not missed. Words added later only match messages sent after they were added.
• Use a silent breadcrumb (no message) when the players should not know they have found something.
• Pair the trail with the shop: tag or role the completing players and put a hidden shop behind that tag. See the Shop moderator guide.
• /breadcrumbprogress is private, so it is safe to run in any channel.