Allow a game to delay its start until all of its players are actually ready

rather than assuming that as soon as they construct the EZGameControl, they're
ready to play. That's not totally unreasonable, but with this new explicit
mechanism, games can also "rematch" (or just replay if it's single player) by
having all clients call playerReady() again after the game has ended.


git-svn-id: svn+ssh://src.earth.threerings.net/vilya/trunk@328 c613c5cb-e716-0410-b11b-feb51c14d237

src/as/com/threerings/ezgame/EZGameControl.as

@@ -107,7 +107,6 @@ import flash.display.DisplayObject;
  */
 [Event(name="UserChat", type="com.threerings.ezgame.UserChatEvent")]
 
-
 /**
  * The single point of control for each client in your multiplayer EZGame.
  *
@@ -117,12 +116,17 @@ public class EZGameControl extends BaseControl
 {
     /**
      * Create an EZGameControl object using some display object currently on the hierarchy.
+     *
+     * @param disp the display object that is the game's UI.
+     * @param autoReady if true, the game will automatically be started when initialization is
+     * complete, if false, the game will not start until all clients call {@link #playerReady}.
      */
-    public function EZGameControl (disp :DisplayObject)
+    public function EZGameControl (disp :DisplayObject, autoReady :Boolean)
     {
         var event :DynEvent = new DynEvent();
         event.userProps = new Object();
         populateProperties(event.userProps);
+        event.userProps["autoReady_v1"] = autoReady;
         disp.root.loaderInfo.sharedEvents.dispatchEvent(event);
         if ("ezProps" in event) {
             setEZProps(event.ezProps);
@@ -363,6 +367,16 @@ public class EZGameControl extends BaseControl
         }
     }
 
+    /**
+     * If the game was not configured to auto-start, all clients must call this function to let the
+     * server know that they are ready, at which point the game will be started. Once a game is
+     * over, all clients can call this function again to start a new game.
+     */
+    public function playerReady () :void
+    {
+        callEZCode("playerReady_v1");
+    }
+
     /**
      * Requests a set of random letters from the dictionary service.  The letters will arrive in a
      * separate message with the specified key, as an array of strings.

src/as/com/threerings/ezgame/client/EZGameController.as

@@ -56,7 +56,18 @@ public class EZGameController extends GameController
      * This is called by the GameControlBackend once it has initialized and made contact with
      * usercode.
      */
-    public function userCodeIsConnected () :void
+    public function userCodeIsConnected (autoReady :Boolean) :void
+    {
+        if (autoReady) {
+            playerIsReady();
+        }
+    }
+
+    /**
+     * Called by the GameControlBackend when the game is ready to start. If the game has ended,
+     * this can be called by all clients to start the game anew.
+     */
+    public function playerIsReady () :void
     {
         playerReady();
     }

src/as/com/threerings/ezgame/client/GameControlBackend.as

@@ -141,15 +141,13 @@ public class GameControlBackend
         populateProperties(evt.ezProps);
 
         // ok, we're now hooked-up with the game code
-        _ctrl.userCodeIsConnected();
+        _ctrl.userCodeIsConnected(evt.userProps["autoReady_v1"]);
     }
 
     protected function setUserCodeProperties (o :Object) :void
     {
         // here we would handle adapting old functions to a new version
-
         _ezDispatcher = (o["dispatchEvent_v1"] as Function);
-
         _userFuncs = o;
     }
 
@@ -187,6 +185,7 @@ public class GameControlBackend
         o["gameConfig"] = gameConfig;
 
         // functions
+        o["playerReady_v1"] = playerReady_v1;
         o["setProperty_v1"] = setProperty_v1;
         o["testAndSetProperty_v1"] = testAndSetProperty_v1;
         o["mergeCollection_v1"] = mergeCollection_v1;
@@ -224,13 +223,20 @@ public class GameControlBackend
     }
 
     /**
-     * Set a property.
+     * Called by the client code when it is ready for the game to be started.
+     */
+    public function playerReady_v1 () :void
+    {
+        _ctrl.playerIsReady();
+    }
+
+    /**
+     * Sets a property.
      *
-     * Note: immediate defaults to true, even though immediate=false is
+     * Note: immediate defaults to true, even though immediate=false is the general case. We are
-     * the general case. We are providing some backwards compatibility
+     * providing some backwards compatibility to old versions of setProperty_v1() that assumed
-     * to old versions of setProperty_v1() that assumed immediate and did
+     * immediate and did not pass a 4th value.  All callers should now specify that value
-     * not pass a 4th value.
+     * explicitly.
-     * All callers should now specify that value explicitely.
      */
     public function setProperty_v1 (
         propName :String, value :Object, index :int, immediate :Boolean = true) :void