Add card info tooltips with keyword explanations and related cards

[MostCromulent]

Summary

Adds Arena-style card info popups to desktop UI including selected card, related cards (tokens created, spellbooks etc), and keyword explanations. Includes menu options to enable/disable each section and scale card image size. Addresses #9705.

(I can imagine some people choosing to use this instead of default card view/card details panels).

Features

• Adds a hoverable card info popup that appears when mousing over cards during a match, showing the card image, keyword ability and keyword action explanations with reminder text, and related card images (tokens, spellbook, meld pairs) grouped by category
• Related cards supports 'creates, 'transforms into', 'other face', 'meld', 'flips into', 'specialises into', 'partner', and 'spellbook'.
• Keyword actions are defined in a new KeywordAction enum (forge-game) covering all 67 entries from MTG comprehensive rules section 701, making them reusable across modules in future
• Popup is constrained to the Forge window bounds, enforces single-instance display, and includes user preferences for image size and enable/disable toggle under Game menu

New files

• forge-game/.../keyword/KeywordAction.java — enum of all MTG keyword actions with reminder text
• forge-gui-desktop/.../view/arcane/CardInfoPopup.java — popup window with pill-panel styling
• forge-gui-desktop/.../match/menus/CardInfoPopupMenu.java — Game menu submenu for popup settings

Note

Original feature request in #9705 also wanted to include flavour text for alchemy cards. This is not currently included in Forge card data so cannot be easily extracted. I have not included in this PR as I don't think significant extra diff to achieve this is worth the benefit.

---

🤖 Generated with Claude Code

[dracontes]

Some notes testing this out for a bit:

• There's a clear overlap with being able to roll the mouse wheel up on hovering over a card to show an enlarged view of the card image. In fact these two ways to getting a detailed view of the card image do conflict a fair bit.
  I do agree the additional information in question is useful to have closer at hand.
  Though, personally, much because I think it's best if we don't hew too close to Arena, my preference would be for the additional information to be added to the wheel roll overlay instead. As it is something people should already use, it dovetails nicely.
  Or, at least, the wheel roll overlay should have this additional information as well and users should be able to choose between or against the two options.

• In any case there's some issues with margins and not particularly informative text for some abilities, and for some reason the generated images for associated cards (namely spellbooks) are just the boilerplate blank frame one.

[MostCromulent]

Understand what you say about avoiding too much similarity.

I'm happy to re-work this to integrate with the scroll-up card zoom view if that's the consensus, though that perhaps makes the functionality less obvious to the kind of less experienced users who the tooltips and related cards are most useful for?

(Also personally I basically never use the scroll-up function, hence why I missed the conflict when zoomed in. I should at least be able to sort that out.)

Will look into the other issues. The image downloader for the related cards box was at least working for me earlier today.

[dracontes]

I'm happy to re-work this to integrate with the scroll-up card zoom view if that's the consensus, though that perhaps makes the functionality less obvious to the kind of less experienced users who the tooltips and related cards are most useful for?

Well, the existing functionality is similar, in broad strokes, to how things work on the Android version: there swiping tapping brings up (and dismisses) the card detail, which can then be swiped between two display formats.

Will look into the other issues. The image downloader for the related cards box was at least working for me earlier today.

Just to be clear: I don't download images for Forge. I find the built-in card renderer/image generator sufficient for my usage. The problem is that those related cards aren't rendering as expected.

A few more notes:

• The tooltip popup flickers something fierce if you hover the cursor on the name bar of a tapped card. It happens even after moving the cursor well into the card's footprint, where you'd expect the cursor to "lock in" as it were.
• A few more issues with displayed text:

• Also seems like the issue with the margins of the bounding box for the text is at least intermittent. Seems like it fixed itself on my side. ETA: Or not, see below,

• Also also, seems like the popup isn't all that consistent picking up on granted abilities: Mary Jane in the screenshot above has flying and intimidate.

[Hanmac]

in theory, SpellAbilityEffect represents KeywordActions
maybe they can be used too 🤔

for KeywordInterfaces, checkout KeywordInterface#getTitle too (see TypeCycling)

[MostCromulent]

@dracontes, I'll test this more extensively tomorrow but latest commits should hopefully address many of the issues you had above including card rendering and initial implementation of seperate preference toggles to enable/disable showing related cards/keyword tips in the card zoom view.

Still working on getting it to more accurately pick up granted abilities/solve a few layout problems.

[Jetz72]

Ideally we could identify KeywordActions by inspecting the card's abilities and their parameters rather than the Oracle text. But I'm not sure how well that works with everything. Something like Scry might be a straightforward spot check for a ScryEffect or a ReplaceScry, but I think there are some that are implemented purely through card script.

[MostCromulent]

Ideally we could identify KeywordActions by inspecting the card's abilities and their parameters rather than the Oracle text. But I'm not sure how well that works with everything. Something like Scry might be a straightforward spot check for a ScryEffect or a ReplaceScry, but I think there are some that are implemented purely through card script.

@Jetz72, I've asked the AI to assess the feasability of this for each of the KeywordActions. Here's the response:

Direct ApiType match (34):
Scry, Surveil, Mill, Fight, Goad, Investigate, Explore, Connive, Discover, Cloak, Manifest Dread, Amass, Learn,
Incubate, Ring Tempts You, Venture, Vote, Clash, Detain, Regenerate, Manifest, Meld, Set In Motion, Abandon,
Proliferate, Planeswalk, Open an Attraction, Assemble, Villainous Choice, Time Travel, Endure, Airbend, Earthbend,
Blight

K: keyword definition — no SpellAbility to inspect (3):

• Monstrosity → K:Monstrosity:4:5 B G (keyword definition, not an effect)
• Adapt → K:Adapt:1:2 G U (same pattern)
• Exert → K:Exert (keyword, triggers are separate)

Ambiguous ApiType — overloaded or flag-dependent (4):

• Transform → SetState (also used for flip cards, MDFCs)
• Convert → SetState (same as Transform)
• Populate → CopyPermanent with Populate$ True flag
• Bolster → PutCounter with Bolster$ True flag

No ApiType exists (8):
Behold, Fateseal, Roll to Visit, Collect Evidence, Suspect, Forage, Harness, Waterbend

Indistinguishable from generic effects (1):

• Support → PutCounter with specific targeting (no flag — identical to any "put +1/+1 counters on target creatures"
  ability)

Totals: 34 detectable via effects, 16 still need Oracle text fallback. Plus CardView doesn't expose ability data
today — all 50 would require plumbing game-layer data into the view layer.

That means there would still need to be a hybrid approach with Oracle text fallback rather than a clean replacement. There's also an architectural question since the detection currently runs against CardStateView (which only exposes strings) rather than the game Card object — threading ability data to the view layer would be a larger change.

Given the text approach seems to work, I'd lean toward keeping it as-is for this PR and potentially revisiting if we build richer ability metadata into CardView in the future. But happy to refactor if you feel the hybrid approach is worth it now.

[Jetz72]

Well, 34 out of 50 (not counting the 17 trivial ones) isn't too bad of a start. Digging into it a bit more -

• As it points out, Forge treats Monstrosity and Adapt as keyword abilities (which it probably shouldn't but not a huge issue). If we were to refactor these we'd probably just skip them in the keyword action search and let the ability keyword write the description.
• Populate and Bolster would have to be done by inspecting parameters on their respective methods. Roll to Visit Your Attractions is done as an action via an optional parameter on RollDice.
• Suspect and Harness would have to be detected via the Attributes$ parameter on AlterAttribute
• Fateseal and Support seem indistinguishable. If we went this route, we'd probably resolve this by adding marker parameters to the cards that use these keyword actions. Currently a total of 21, across both keywords.
• Transform and Convert would be indistinguishable purely from the ability scripts. We could introduce marker parameters to separate out the 15 convert cards, but I'm not sure it'd even be worth it. As far as I can tell, these actions are exactly the same thing, rules-wise. I don't think non-transforming MDFCs use SetState.
• Feels a bit strange that Flip isn't considered a keyword action. It'd be set apart by the Mode$ parameter.
• Exert's API is CostExert. It evidently wasn't looking at cost APIs, which is why it also missed Behold, Collect Evidence, Forage, and Waterbend. Scry and Mill can also occur as costs.
• On a similar note, it'd also need to inspect Trigger and Replacement APIs. Plenty of these actions like Scry have effects which either trigger when you do them or modify them via REs.

I think we could get away without a hybrid approach, but it'd still be a pretty huge overhaul to what you currently have. Each keyword would need one or more cues to check against an ability, trigger, or replacement effect, for their API, parameters, sub-abilities, and any associated costs. Instead of threading ability data to the view layer we'd probably just compute the keyword action list on the game layer. Possibly within the abilities/triggers/REs themselves before compiling them in the Card[State]View class to hand off to the UI...

On second thought, if we ever wanted tooltips to work outside of a game we'd have to do it even earlier, with less tools. Possibly while as part of the CardFace/CardRules? And then we'd need to either link those keyword abilities to their ability string or generate them a second time while in-game so that we can handle cases when they're moved between cards....

...I think it's probably fine for now. I don't think the current implementation will usually be an issue as long as the card name isn't included in the text matching.

[Hanmac]

I will do some cleanup with Landwalk and Affinity later that day

[MostCromulent]

It occurs to me there may be situations where you want different overlays between the two (i.e. you want to see the PT overlay in the tooltip but you don't need the name because the tooltip is already readable)

Having now tested this more thoroughly, I definitely think users will want granular control of the overlays between cards on field vs hover tooltips. Have consolidated this into a shared dialog menu:

[MostCromulent]

@Jetz72 if you're still comfortable with the KeywordActions detection working based the oracle text (at least for time being), I've tested this and it seems to be functioning properly and ready for review. (With as many cards as MTG has I expect there will be edge cases where certain syntax still trips it up, but I haven't encountered any glaring errors in latest testing).

One outstanding design question is what should the default preference for this be? I think the keyword tooltips in particular are very useful , but they don't make a heap of sense without the card popup next to them - so I lean to enabling both by default but this isn't a super strong view. If it's all off by default I think there's a risk it just gets missed in the menu settings.

[dracontes]

Good show so far 👍

A few more comments after a bit more testing.

• Getting the same hover tooltip flickering happening on the game log for a similar reason as on the battlefield: the tooltip is displayed by hovering anywhere on a particular log message (area highlighted in red on the screenshot), but the tooltip's card image is linked to the footprint of the card image on the log message. Maybe here the card image should render outside of the log's footprint entirely just for clarity, like it does for the stack.

• I appreciate that you did enough to disentangle the zoom-in and tooltip. I do think that having the zoom-in deal with the full display of large spellbooks exclusively is a smart solution. Still, I do feel the checkboxes should be available for users to disable all of it at their convenience, if not for any other reason. Even agreeing that these features should be set by default to the configuration you find most useful, so people are at least aware of them, I have had to field questions on Discord regarding disabling the overlays for instance.

• Cards like Garth One-Eye should display a similar information box as cards with spellbooks

• I feel like "the Ring tempts you" should show the respective emblem though seeing as there's no script for it might be a tall order to have it display for me (unless the card image already does).

• I think if there's "Mill 2" there should be "Mill 1."

• Issues with information text display for sundry abilities:
  ‣ Craft is a bit messy

‣ I would expect "Amass [creature type] [N]"

‣ A bit confused/confusing with equip abilities of a different character

[MostCromulent]

@dracontes thanks for feedback, this is very helpful and I will investigate.

[MostCromulent]

I appreciate that you did enough to disentangle the zoom-in and tooltip. I do think that having the zoom-in deal with the full display of large spellbooks exclusively is a smart solution. Still, I do feel the checkboxes should be available for users to disable all of it at their convenience

I think we have that here - unless there was different enable/disable functionality you wanted?

[MostCromulent]

@dracontes all of the issues above should now be fixed.

Game log overlap - now renders outside of the log entirely.

Garth One-Eye / Cards naming other cards

The Ring Tempts You - took some slightly ugly Ring-related hard coding within the tooltip file, but have got this working. Have also got it to track your current ring level in the header and tooltip.

Mill

Craft

Amass

Equip

[Hanmac]

Devotion is a bit tricky

because the gods have "Devotion for X and Y",
where Hybrid Mana only counts once, not twice

would be best if you check for SVar X = contains Devotion like this:

forge/forge-gui/res/cardsfolder/i/iroas_god_of_victory.txt

Line 7 in 682bb19

SVar:X:Count$DevotionDual.Red.White

[dracontes]

I think we have that here - unless there was different enable/disable functionality you wanted?

I apologize: I somehow must have convinced myself during the testing I did for my 2026-02-21 review of that version of the PR there was a checkbox implemented to disable the zoom-in view altogether, either from the Game dropdown menu or on Preferences. Just fired up that version of this PR and I can't find it.

Still, I would like that to be available for the reasons I stated. if it isn't too much trouble to implement.

[MostCromulent]

Devotion is a bit tricky [...] would be best if you check for SVar X = contains Devotion like this:

@Hanmac have re-worked this on latest commits, seems to be working well.

checkbox implemented to disable the zoom-in view altogether, either from the Game dropdown menu or on Preferences.

@dracontes have re-worked master enable/disable hotkeys and preferences similar to CTRL-O for overlays.

[dracontes]

have re-worked master enable/disable hotkeys and preferences similar to CTRL-O for overlays.

I'm sorry, I should have been clearer: what I am asking for is a checkbox to disable the image itself showing up when you scroll up when hovering a card. Could certainly be that checkbox you set up is what's reworked to do that.

Ran down the discussion, verifying relevant items. Here are some salient enough issues. The rest were addressed well enough.

• Like for other, similar instances, if there's "monstrosity 5" there should be "monstrosity X".

• Likewise for collect evidence.

• I'm pretty sure the underlined text isn't true: the keyword actions transform and convert are interchangeable.

• Some confusion with trample and trample over planeswalkers

• Seems like the layout here could be a bit more compact

• ETA: The text for waterbend is a bit off, making it sound more like convoke than it actually is.

[MostCromulent]

what I am asking for is a checkbox to disable the image itself showing up when you scroll up when hovering a card.

I think the CTRL-I shortcut should do what you're looking for: completely disable the tooltip functionality in zoom view. Disabling the "Enable Card Information Tooltips in Zoom View" preference will do the same thing.

Here are some salient enough issues. The rest were addressed well enough.

These should now be fixed.