Phases in MTG Forge

Magic’s phases are simple to understand but complicated to program (much like combat and other parts of Magic.) MTG Forge implements the phases as a huge array since the phases always progress in the same order. In order to makes progressing to the next phase as simple as possible, the array also includes each place that a user can "stop and play a card" which is called priority.

Let me show you a part of the array and then explain it in more detail.

String phaseArray[][] = 
{
  {"Human", "Human", "Untap"},

  {"Human", "Human", "Upkeep"},
  {"Human", "Computer", "Upkeep"},

  {"Human", "Human", "Draw"},
  {"Human", "Computer", "Draw"},

  {"Human", "Human", "Main1"},
  {"Human", "Computer", "Main1"},
}

This is a two-dimensional array that holds whose turn is it (active player), the player who has priority and the name of the phase. The line

{"Human", "Computer", "Upkeep"}

means that the active player is the human and the computer currently has priority during the Upkeep.

This array is part of the Phase object. The most important methods of Phase is getPhase(), getActivePlayer(), getPriorityPlayer(), and nextPhase(). From the example above, getActivePlayer() would return "Human" and getPriorityPlayer() would return "Computer". nextPhase() is used throughout the program to advance to the next phase. Progressing from one phase to the next is very easy, all you have to do is to increment the array index. If there are no attacking creatures those phases are skipped by calling nextPhase().

The Phase object works well but MTG Forge’s phase problem seems to be in the code that observes Phase. I love the observer pattern and use it throughout MTG Forge but sometimes it causes me trouble if I have too many observers that also change the object that they are observing.

For example objects A, B, C are observing Z and when B is notified of a change from Z it modifies Z. (B only modifies Z once every 24 hours so there isn't an infinite loop.) If Z changes, A, B, C are called twice, once when Z was first changed and then later when B changes Z. And to further complicate the issue, A and C may be called before B changed Z or after. I’ve tried to make this example as simple as possible but it is still hard to understand. Basically the problem is that when Z changes, A,B,C are each called twice, once for the initial change of Z and then again when B changes Z.

The problem is when you have multiple observers and one of the observers changes the object that it is observing, then the other observers don't work correctly. If you know of a solution for this, please let me know.

I’ve come up with a solution that I call an "ordered observer". From the example above when Z changes, the observers would be notified in this order A, B, A, B, C instead of A, B, C, A, B, C thus reducing the number of times that C is called. You can download the full Java code here.

p.s.
You can also read more about programming Magic's phases here. What other topics would you like to read about?

class OrderedObserver
{
private boolean shouldContinue;

void updateObservers()
{
 shouldContinue = true;
 notifyObservers();
 shouldContinue = false;
}

//if updateObservers() is called while looping through all observers
//the loop stops and then starts over
void notifyObservers()
{
  OrderedObserver ob;
  for(int i = 0; i < list.size(); i++)
  {
    ob = (OrderedObserver) list.get(i);
    if(shouldContinue)
      ob.notify(this);
  }
}//notifyObservers()

}//end class

Magic’s phases (some of these are technically steps)
Untap
Upkeep
Draw
1st Main
Begin Combat
Declare Attackers
After Declare Attackers
Declare Blockers
After Declare Blockers
Combat Damage
End of Combat
2nd Main
End of Turn
Cleanup