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
• Feature-gated: Default OFF, requires explicit enable + restart
• Network independent: Each client manages its own yield state locally
• 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.

---

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

[Jetz72]

This file shouldn't be added to the main repo.

[tool4ever]

it's good for following the AI reasoning process at this stage

but yea when it gets finalized for merge some of the content should land in docs/ for end users (Wiki)
and non trivial code aspects would be fine as Javadoc only

[MostCromulent]

Have committed draft wiki documentation for review.

[tool4ever]

seems appropriate to me

[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.

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.

[tool4ever]

I was actually considering a way where the feature doesn't need its own checkbox but the changes in this class alone make that impossible:
this costs way too much performance and certainly should only be performed when it's actually needed

[MostCromulent]

Do you have a preferred way of dealing with this? I raised with the AI coder and its suggested response was:

Option 1: Change to only compute hasAvailableActions() if the smart prompts are enabled by the user; or

Option 2: Adopt a less accurate heuristic with lower performance cost:

Remove:                                                      
  1. hasAvailableActions() method from Player.java             
  2. updateAvailableActionsForView() method from Player.java   
  3. The TrackableProperty from PlayerView.java                
  4. The call in PhaseHandler.passPriority()                   
                                                               
  Replace with: Simpler heuristics using existing View data    
  (like shouldShowNoManaPrompt already does):                  
                                                               
  private boolean shouldShowStackYieldPrompt() {               
      // ... existing null/stack checks ...                    
                                                               
      // Simple heuristic: no mana = can't respond to stack    
      return !hasManaAvailable(pv);                            
  }                                                            
                                                               
  private boolean shouldShowNoActionsPrompt() {                
      // ... existing null/turn checks ...                     
                                                               
      // Simple heuristic: empty hand + no mana = nothing to do
      FCollectionView<CardView> hand = pv.getHand();           
      boolean emptyHand = (hand == null || hand.isEmpty());    
      return emptyHand || !hasManaAvailable(pv);               
  }                                                            
                                                               
  Trade-offs:                                                  
  - Pro: Zero performance cost - uses already-synced View      
  properties                                                   
  - Pro: No new TrackableProperties needed                     
  - Con: Less accurate - misses free spells, 0-cost abilities, 
  etc.                                                         
  - Con: Won't detect "has cards but can't afford any of them"

[MostCromulent]

When you say "the feature doesn't have its own checkbox" do you mean expanded yields are just integrated by default rather than being an experimental option in the Preferences menu?

[tool4ever]

the code should probably also be moved to the View classes to keep the engine clean

[tool4ever]

When you say "the feature doesn't have its own checkbox" do you mean expanded yields are just integrated by default rather than being an experimental option in the Preferences menu?

yea that's what I meant but I feel like this is turning more into a power user feature anyway and it might be better for the new user experience having the GUI less crowded at first
this also relates to how it intersects with the existing system, but I'll make a separate comment on that later

based on that Option 1 probably makes more sense, if the heuristics are broadened it might also degrade usefulness too much imo

thanks

[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.

[tool4ever]

I don't mind a few more shortcuts but right now F1 is already hardcoded to Help so this doesn't even work
while some more flexibility in the system might be nice, considering this PR size already it shouldn't be done here

[tool4ever]

given that this feature access is desktop only right now you should also check for mobile GUI
otherwise I'd imagine this will still get enabled and cause some confusion (e.g. for users who switch between them to play adventure)
if you want to support both better leave it for a follow-up, I don't think I'd survive the code growth from that alone... 😅