Expanded yield system / auto-pass options

[MostCromulent]

---

Summary

Inspired by recent discussion on the Forge Discord, this PR adds an expanded yield system to reduce click fatigue in multiplayer games and speed up play. Changes are extensively documented in Documentation. Fully backwards compatible with current functionality: the feature is disabled by default and must be explicitly enabled in preferences.

Problem

In multiplayer Magic games (3+ players), the current priority system requires excessive clicking:

• Dozens of priority passes every turn in a 4-player game.
• Players must manually pass priority even when they have no possible actions.
• This creates click fatigue and slows down gameplay significantly (particularly if players are inattentive and don't immediately respond to prompts).

Solution

Expanded yield options that give players more flexibility to control yield timing and conditions. The aim is to help players spend less time responding to unnecessary priority prompts and let them get to their desired phase of action quicker:

Particularly helpful for that one friend who won't pay attention to priority prompts in Commander.

• Yield Options Panel: Dockable panel with extended yield buttons and visual feedback (blue=ready, red=active)
• Six Yield Modes: Next Phase, Before Combat, End Step, End Turn, Your Next Turn, Stack Clears
• Smart Suggestions: Prompts to auto-yield when player cannot respond (no mana, no actions, can't respond to stack). Configurable through checkbox options in game taskbar menu.
• Configurable Interrupts: Automatically cancels yield when attacked, targeted, mass removal cast, etc. Interrupt conditions are highly configurable through checkbox options in game taskbar menu.
• F-Key Hotkeys: F1-F6 for yield modes, ESC to cancel.

Key Design Decisions

• GUI-layer only: No changes to game engine or network protocol (Edit: though see comments below about network implementation to avoid desync).
• Feature-gated: Default OFF, requires explicit enable + restart
• Backward compatible: Existing Ctrl+E behavior unchanged when feature disabled

Testing

Changes have been tested in local play (thanks to PotionSTAT for testing and feedback). As changes are purely on the GUI layer and do not involve network logic, there is no reason to think testing would not replicate in network use cases. (Edit: see comments about network play below).

---

Code authored by Claude Code (Opus 4.5) under human direction and review.

[MostCromulent]

Testing by PotionSTAT has revealed an issue with network play integration not realised before PR.

YieldController was using gameView.getGame() which returns an unsynchronized dummy object for network clients. Have refactored to use network-safe GameView properties and added StackItemView.getApiType() for mass removal detection. Will also check implications for smart prompts.

[MostCromulent]

Re: Network Code Changes

While the yield system was designed to avoid network protocol changes, in testing discovered that smart suggestions in InputPassPriority had a network compatibility issue requiring new TrackableProperties. This is because the logic was checking the Game object on the server which doesn't exist on network clients.

The solution: Add two TrackableProperties (HasAvailableActions, WillLoseManaAtEndOfPhase) to PlayerView. These piggyback on existing GameView serialization—no protocol changes required. The host calculates these values and they're automatically included when GameView is sent to clients.

The yield system remains client-local; this ensures the data for yield suggestions is synchronized, while yield decisions stay independent per client.

The alternative to making these network changes would have been implementing a more basic heuristic for the yield prompts which would have been a worse and experience for the player.

Edit: Claude AI's explanation for why server needs to know client yield mode state

The server needs to track the client's yield mode to detect end conditions because the client doesn't have access to the same context as the server, which has the authoritative game state and can reliably detect when yield end conditions are met across all players.

When client activates a yield mode it uses notifyYieldModeChanged to notify the server. The server then monitors game state and checks yield end conditions in YieldController.java. When end condition is met the server calls clearYieldMode() which triggers syncYieldModeToClient() to notify the client.

Both server and client stay in sync about yield state. If only the client tracked it, multiplayer edge cases could cause the client to yield too long or not long enough.

[tool4ever]

I still need to investigate this, seems rather hacky

• but if it's needed it should reuse lookupPlayerViewById

[MostCromulent]

I'll address the duplicate function issue now, and can come back to this if you find a better approach.

[autumnmyst]

1. HasAvailableActions only updates when APINA is on, but the yield suggestions need that value updated even when not autopassing
2. I'm noticing that when turning autopass OFF -> ON it passes once even if the player has actions, much like if the player pressed "Ok." Is this the desired behavior? It seems it could lead to frustration if they only meant to turn the toggle on for later.

[MostCromulent]

2. I'm noticing that when turning autopass OFF -> ON it passes once even if the player has actions, much like if the player pressed "Ok." Is this the desired behavior? It seems it could lead to frustration if they only meant to turn the toggle on for later.

This is intentional, but I'm open-minded on whether it's best UI design.

Basic idea is that if user is activating auto-pass on their priority it indicates they want to yield. This is same reason activating always-yes or always-no on a stack trigger doesn't just silently toggle the preference, it also applies it and passes priority at the same time.

The alternative has its downsides too. If you activate auto-pass after already receiving priority it can't recalculate APINA (or at least when I looked into this it would have resulted in some very messy code which wasn't worth it) - so you have situation where you activate auto-pass, you may have no actions available, but it just sits there leaving you with priority. That's probably even more confusing.

[mermerico]

I love this PR but I found the settings a bit confusing. Here was my effort to reorganize. Let me know what you think and I can upload a patchset.

[autumnmyst]

@mermerico my concern here is that “intelligent” and “advanced” aren’t mutually exclusive. Often times you will sit with autopass on but then might draw an instant you don’t intend to play immediately, and will then use the yield options to pass forward to a certain point (while having interrupts to stop that yielding), all the while keeping autopass on. For legacy behavior everything is behind a flag in preferences and, if using this system, I wonder how necessary having a legacy setting is since you would just flip the flag (end turn + auto yields still work like how they do in current forge regardless)

[autumnmyst]

The right-click yields are really cool. Just a couple suggestions:

1. Have some way to yield just the stack (the suggestions are good, but won't appear if you can respond). Maybe right-clicking the current phase with a non-empty stack could just yield that stack and nothing else, but right clicking current phase with empty stack yields everything until that phase comes around again (like it does currently)?
   [A really advanced version of this could let you right click a spell/ability on the stack, and yield to specifically that spell/ability, but you would need to deal with those objects getting deleted/manipulated which could get messy, so unless it's trivial probably save for later PR.]

2. Have a checkbox at the bottom of yield interrupts for "Autopass respects interrupts" (unchecked by default). From playing a few games, I'm noticing it's exceedingly rare that I want to actually hold prio when I have no actions (honestly I haven't found a single reason to do so against the computer, since there's no point in bluffing counterspells etc.). I'm finding that interrupts are mainly used for stopping the fast-forward, since I might have an instant I want to cast only in case of an interrupt. However, if I don't have anything, autopass respecting interrupts means it stops me on all my interrupts even if I couldn't do anything about it. I'm suggesting leaving this unchecked by default since (from my experience) the only reason to hold when you have nothing is: 1. if things are playing out too quickly to follow (in which case you could also just turn off autopass / turn on resolve delay) 2. To bluff a counterspell in multiplayer. Both of these I'd consider extenuating enough circumstances to warrant opening the menu and checking the box.

[MostCromulent]

The right-click yields are really cool. Just a couple suggestions:

@autumnmyst both implemented. 👍

[autumnmyst]

I found and fixed a small bug as well as moving interrupts to being event-driven. I figured since I'd already implemented a fix I would just make a PR into your branch: MostCromulent#18

[tool4ever]

I don't understand why the legality check was removed
this seems wrong

[tool4ever]

what about the old auto pass cancel:
do we feel it's now more desired to keep passing even if we had to declare attackers...?

[MostCromulent]

No I think you're right: once the interrupt fires we want to cancel the yield. If the user has APINA enabled then it can take care of things from there.

[MostCromulent]

Closing this PR - replaced by #10606.