Card Commands

Summary

The application command /card is used to query Marvel Champions cards. The wrapper syntaxes {{terms}} and <<terms>> can be used as shorthands for the aforementioned application command. If more than one result is found for the terms that are queried, a select menu will appear to allow the user to choose their intended card result. If a single result is found or after a selection is made, that card result will be returned with a variety of buttons that can be used to interact with the card result. After the interaction timeout is reached, these buttons will be removed and the card result will remain static within the channel in which it was queried.

Semantics

Cerebro utilizes the following terminology for card commands:

• author — The creator of a given piece of unofficial content.
• classification — Conventionally used to refer to a card's aspect affiliation — Aggression, Basic, Justice, Leadership, or Protection — but can also include a card's status as a Hero card or an Encounter card.
• name — Used interchangeably to refer to the Name (title) or Subname (subtitle) of a card.
• official — Any card that has been officially printed by Fantasy Flight Games (FFG).
• origin — A card's status as either official or unofficial.
• text — Refers to the rules text printed in a card's textbox. This does not include a card's Traits, which are treated separately.
• unofficial — Any card that has been created by a member of the Marvel Champions community with no affiliation to FFG.

Querying

There is one primary application command that allows users to query for card results:

• /card origin:[official|unofficial|all] [classification] [cost] [name] [resource] [text] [traits] [type]

When executed, this command will query the database for official cards, unofficial cards, or both — depending on the provided origin value — that comply with the provided filters. A query must have at least one of the optional filters, but there is no limit to how many can be used in conjunction with one another. Those filters are as follows:

• author:@username — Queries only for cards that are authored by the specified user. It's important to note that Official cards do not possess an Author value and will thus be excluded from all queries possessing this filter.
• classification:[aggression|aspect|basic|encounter|hero|justice|leadership|protection|player] — Queries only for cards that are affiliated with the specified aspect if aggression, basic, justice, leadership, or protection is chosen. aspect queries only for non-hero player cards, hero queries only for non-aspect player cards, and player queries only for all player cards, hero and aspect alike. encounter, inversely, queries only for non-player cards.
• cost:[[user input]] — Queries only for cards that have the specified cost. It's important to note that Encounter cards do not possess a Cost value and will thus be excluded from all queries possessing this filter.
• name:[[user input]] — Queries only for cards with a matching name.
• resource:[energy|mental|physical|wild|none] — Queries only for cards whose printed resources contain the specified resource type. It's important to note that Encounter cards do not possess a Resource value and will thus be excluded from all queries possessing this filter.
• text:[[user input]] — Queries only for cards with matching text.
• traits:[[user input]] — Queries only for cards whose traits contain all specified traits. The input for this filter can be a single trait — like Spy — or a comma-delimited list of traits — like Aerial, Avenger. It's important to note that when multiple traits are supplied to the query, it will search for cards that possess all of the provided traits, not just some of them.
• type:[ally|alter-ego|attachment|environment|event|hero|main scheme|minion|obligation|resource|side scheme|support|treachery|upgrade|villain] — Queries only for cards of the specified type.

Multiple filters in conjunction with one another possess an AND relationship rather than an OR relationship; the query /card origin:all classification:aggression type:ally will return only Allies affiliated with the Aggression aspect.

If a single matching card is found, that card result will be returned immediately. If more than one matching card is found, the user will be presented with a select menu that will allow them to choose the card result that they intended to retrieve. After a select menu is displayed, there is a 45-second timeout before it vanishes and a card result can no longer be retrieved.

When a card result is returned — either as a result of a single match to the provided query or because a selection was made from the select menu — it will look similar to the image below.

* There is a known issue wherein making a selection from the menu will sometimes result in a failed interaction. If this happens, merely re-select the desired result until the interaction succeeds.

Wrapper Syntax

The command described above can be executed using wrapper syntax. A query for official cards by name can be accomplished by wrapping the query terms in two sets of curly brackets — i.e. {{terms}} — and a query for unofficial cards by name can be accomplished by wrapping the query terms in two sets of angle brackets — i.e. <<terms>>. By default, Cerebro evaluates all messages posted within channels in which it has visibility for instances of this wrapper syntax — meaning that the wrapper syntax can be used conversationally. An example of this would be I just finished playing a game with {{Ms. Marvel}} and it was a lot of fun! — a message that would be evaluated to execute the command /card origin:official name:Ms. Marvel.

Cerebro is designed to evaluate all instances of the wrapper syntax it discovers. This means that multiple queries can be made within a single message. An example of this would be {{Spider-Man}}'s hero deck is great. I'm convinced that {{Backflip}} is the best card in the game! — a message that would be evaluated to execute two commands: /card origin:official name:Spider-Man and /card origin:official name:Backflip. When multiple wrapper queries are made, the querying user will be prompted to return the results either separately or together.

If the querying user chooses to return the results separately, conventional querying logic will apply and each query will result in either a single card's output or a select menu to choose the intended card, all at once in the corresponding channel. If the querying user chooses to return the results together, a subroutine will be initiated in which each query will be executed, one at a time, and if multiple results are found, a select menu will appear. In this subroutine, select menus will be devoid of the Browse Results button, since the underlying logic is composing a stitched image.

Spoilers and Incomplete Data

Cerebro's database is updated regularly to possess as much content as possible. That data is sometimes pulled from pre-release news articles, leaks from early-access, and other sources that are not the physical cards themselves. When a card is queried that contains spoiled or incomplete data, its result contents will be wrapped with spoiler tags to prevent the loss of immersion for other users who might not want to have the surprise ruined for them until they're able to physically get their hands on those cards.

Buttons

Card results feature buttons that can be used to interact with them in various ways. After a card result is returned, there is a 30-second timeout before the buttons vanish and the result becomes static. If any buttons are clicked, this timeout resets. Certain buttons will be present based on the features that a given card possesses, but regardless of the card's features, its result will always possess two buttons by default: Toggle Art and Clear Buttons. If a button is clicked by a user other than the user who initially queried for the result, they will not impact the result and will instead receive an ephemeral response indicating that they cannot interact with other users' queries.

Browse Results

This button will appear when a query returns multiple results and a select menu is presented for the selection of a particular result. Clicking it will transition the user into a browsing state where all of the queried results can be navigated.

Cancel Selection

This button will appear when a query returns multiple results and a select menu is presented for the selection of a particular result. Clicking it will cancel the selection, circumventing the interaction timeout and clearing the select menu.

Change Art

This button will appear only if a card possesses various art styles. Clicking it will cycle the result link and its associated thumbnail or attachment through the various art styles that the card possesses. The status of the art and rules toggles will not change.

Clear Buttons

This button will always be present on card results. Clicking it will bypass the timeout period and force all of the buttons to vanish, leaving the result static. If the user was browsing through a collection of cards at the time that this button was clicked, the most recent card they were viewing will be the result that persists once all of the buttons have vanished.

Flip Card

This button will appear only if a card possesses multiple faces or variations (as dictated by the card's pack identifier ending in an alphabetical character such as 01001A). Clicking it will cycle the result to the opposite face or next variation in the list. All aspects of the result will change to portray the newly selected card. The status of the art toggle will not change, but the rules toggle will always be disabled.

Previous [Element] and Next [Element]

This button will appear only if a card belongs to a group or if the user is actively browsing a collection of cards. Clicking either will navigate the user to the appropriate card in the group or collection. All aspects of the result will change to portray the newly selected card. The status of the art toggle will not change, but the rules toggle will always be disabled.

Show All

This button will appear only when a query is made that retrieves multiple cards. Clicking it will result in a single message with one or more image attachments containing all of the query results stitched together. This subroutine bypasses all other response logic — meaning there won't be any buttons on the message with which to interact with the results.

Toggle Art

This button will always be present on card results. Clicking it will invert the state of the art toggle — from disabled to enabled and vice versa. While the art toggle is enabled, all textual content from the result will be purged and only the card image will be shown. The rules toggle will always be disabled.

Toggle Rules

This button will appear only if a card's textbox possesses any keywords or scheme icons. Clicking it will invert the state of the rules toggle — from disabled to enabled and vice versa. While the rules toggle is enabled, the contents of the result will be replaced with a list comprised of the name and description of each keyword or scheme icon present in the card's textbox — effectively replacing the reminder text that has been scrubbed from every card. The art toggle will always be disabled.

Unveil Secretly

This button will appear only if a card has been marked as spoiled or incomplete. Clicking it will spawn a separate ephemeral message that only the user who clicked it can see. This newly-created message will be free of spoiler tags — meaning all of its contents will be visible without the need to click each spoiler tag individually. The status of the art and rules toggles will not change. This is the only button that can be clicked by users other than the user who initially queried for the result (as it doesn't impact the original message).

Matching Hierarchy

The matching of card names consists of anywhere from one to four separate passes through the database with the number of passes being dictated by the presence of matches at each step. Each pass is comprised of three different checks. This means that up to 12 points of verification can be made for a single query. Regardless of how many matches are found in the database, however, Cerebro will prioritize results that match with the queried terms before returning non-matching results. A search for Venom might match Venom, Venom Blast, and Venom's Pistol on the database side, but Cerebro will filter out the latter two results because the former is the only one that matches the query exactly.

Types of Checks

Within each pass, there are three different checks that are performed. For the following checks, consider the initial query Star-Lord's Helmet.

1. Normalized — Any accented characters in the query or the database are converted to plain alphanumeric characters and then the entire string is converted to lowercase. All other special characters are left intact. The example above remains star-lord's helmet.
2. Tokenized — Any character in the normalized strings that isn't a letter, a number, a hyphen, or whitespace is removed and the text is broken down at hyphens and whitespaces to create a series of tokens that can be compared. The example above becomes star, lords, and helmet.
3. Stripped — Any character in the normalized strings that isn't a letter or a number is removed — including whitespace — leaving one big, smooshed-together jumble of letters and numbers. The example above becomes starlordshelmet.

Database Passes

The first pass will always be made. If any matches are found, they'll be returned and the calls to the database cease there. If no matches are found, however, a second pass will be made, and so on. If no matches are found by the conclusion of the fourth pass, Cerebro concedes defeat and returns an error message.

1. Exact Matches — The first pass seeks to find any row in the database in which all of the queried terms are found exactly as searched. This pass is generally sufficient so long as the query contains all alphanumeric elements of the card name in the order in which they appear. For example, Spider-Man will match any card named Spider-Man, but not Spider-Woman.
2. Token Matches — The second pass seeks to find any row in the database in which some of the queried terms are found exactly as searched. If at least one of the provided tokens matches, the row will be returned. For example, Captain Americ will match Captain America, Captain America's Helmet, Captain America's Shield, and Captain Marvel.
3. Partial Matches — The third pass seeks to find any row in the database in which all of the queried terms are found partially as searched. This means that the entire query must be found, but the match doesn't have to be an entire token. For example, Clap will match Thunderclap.
4. Fuzzy Matches — The fourth and final pass seeks to find any row in the database in which all of the queried terms are found fuzzily as searched. Fuzzy matching is not an exact science, but simply put, a fuzzy match entails the modification of one or more characters to wind up at the desired result. The more characters that need to be modified to get to the desired result, the lower the fuzzy match rating. For example, Captain Marbel will fuzzy match to Captain Marvel because it only requires one character modification.

Wildcards

Cerebro's filtering of exact matches can be circumvented with the use of a wildcard character — or asterisk (*). If Cerebro detects a wildcard character in a query, it skips over the first and second passes entirely and jumps straight to the third pass in an attempt to make partial matches. In this way, Venom* will match Venom, Venom Blast, and Venom's Pistol and because none of those results possess an asterisk and therefore do not match the query exactly, Cerebro will return all of them in a select menu. Wildcards can be a powerful tool if used correctly!