From bc2b47a6cac0c704d7a4b2d1f9fa0d3b969ad683 Mon Sep 17 00:00:00 2001 From: Ray Greenwell Date: Sat, 22 Dec 2007 01:23:40 +0000 Subject: [PATCH] Comment tweaks. git-svn-id: svn+ssh://src.earth.threerings.net/vilya/trunk@536 c613c5cb-e716-0410-b11b-feb51c14d237 --- src/as/com/threerings/ezgame/AbstractControl.as | 10 +++++----- .../com/threerings/ezgame/AbstractGameControl.as | 9 +++++---- src/as/com/threerings/ezgame/EZBagsSubControl.as | 14 +++++++++++--- src/as/com/threerings/ezgame/EZEvent.as | 3 --- src/as/com/threerings/ezgame/EZGameControl.as | 4 +++- src/as/com/threerings/ezgame/EZGameSubControl.as | 9 ++++++--- src/as/com/threerings/ezgame/EZLocalSubControl.as | 5 +++-- src/as/com/threerings/ezgame/EZNetSubControl.as | 14 +++++++++----- src/as/com/threerings/ezgame/EZPlayerSubControl.as | 3 ++- .../com/threerings/ezgame/EZSeatingSubControl.as | 5 +++-- .../com/threerings/ezgame/EZServicesSubControl.as | 10 ++++++---- .../com/threerings/ezgame/MessageReceivedEvent.as | 3 +++ 12 files changed, 56 insertions(+), 33 deletions(-) diff --git a/src/as/com/threerings/ezgame/AbstractControl.as b/src/as/com/threerings/ezgame/AbstractControl.as index 72b7fcfe..a9433a43 100644 --- a/src/as/com/threerings/ezgame/AbstractControl.as +++ b/src/as/com/threerings/ezgame/AbstractControl.as @@ -27,7 +27,7 @@ import flash.events.Event; import flash.events.EventDispatcher; /** - * The abstract base class for EZ controls. + * The abstract base class for Game controls and subcontrols. */ public class AbstractControl extends EventDispatcher { @@ -39,7 +39,7 @@ public class AbstractControl extends EventDispatcher } /** - * Are we connected and running inside the EZGame environment, or has someone just + * Are we connected and running inside the game environment, or has someone just * loaded up our SWF by itself? */ public function isConnected () :Boolean @@ -55,9 +55,9 @@ public class AbstractControl extends EventDispatcher * * Example: * _ctrl.doBatch(function () :void { - * _ctrl.set("board", new Array()); - * _ctrl.set("scores", new Array()); - * _ctrl.set("captures", 0); + * _ctrl.net.set("board", new Array()); + * _ctrl.net.set("scores", new Array()); + * _ctrl.net.set("captures", 0); * }); */ public function doBatch (fn :Function) :void diff --git a/src/as/com/threerings/ezgame/AbstractGameControl.as b/src/as/com/threerings/ezgame/AbstractGameControl.as index d93abe99..85ec3bbf 100644 --- a/src/as/com/threerings/ezgame/AbstractGameControl.as +++ b/src/as/com/threerings/ezgame/AbstractGameControl.as @@ -41,19 +41,20 @@ import flash.geom.Point; [Event(name="unload", type="flash.events.Event")] /** - * The single point of control for each client in your multiplayer EZGame. + * Abstract base class for GameControl implementations. */ public class AbstractGameControl extends AbstractControl { /** - * 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 AbstractGameControl (disp :DisplayObject, autoReady :Boolean) { + if (disp == null || Object(this).constructor == AbstractGameControl) { + throw new IllegalOperationError("Abstract"); + } + createSubControls(); var event :DynEvent = new DynEvent(); diff --git a/src/as/com/threerings/ezgame/EZBagsSubControl.as b/src/as/com/threerings/ezgame/EZBagsSubControl.as index b89ef6a6..a81e04d3 100644 --- a/src/as/com/threerings/ezgame/EZBagsSubControl.as +++ b/src/as/com/threerings/ezgame/EZBagsSubControl.as @@ -22,7 +22,15 @@ package com.threerings.ezgame { /** - * Contains 'bags' game services. + * Contains 'bags' game services. Do not instantiate this class yourself, access it + * via GameControl.services.bags. + * + * Bags are secret collections containing non-unique elements that are stored on the server. + * They can be used to implement game features where clients can't be trusted to not + * sniff their network. + * + * For example you could create a bag called "dice" and fill it with [ 1, 2, 3, 4, 5, 6 ]. + * Now you can roll the die with _ctrl.services.bags.pick("dice", 1, "diceProperty"); */ public class EZBagsSubControl extends AbstractSubControl { @@ -41,7 +49,7 @@ public class EZBagsSubControl extends AbstractSubControl } /** - * Add to an existing bag. If it doesn't exist, it will + * Add values to an existing bag. If it doesn't exist, it will * be created. */ public function addTo (bagName :String, values :Array) :void @@ -50,7 +58,7 @@ public class EZBagsSubControl extends AbstractSubControl } /** - * Merge the specified bag into the other bag. + * Merge all values from the specified bag into the other bag. * The source bag will be destroyed. The elements from * the source bag will be shuffled and appended to the end * of the destination bag. diff --git a/src/as/com/threerings/ezgame/EZEvent.as b/src/as/com/threerings/ezgame/EZEvent.as index 90880a26..36a0d18d 100644 --- a/src/as/com/threerings/ezgame/EZEvent.as +++ b/src/as/com/threerings/ezgame/EZEvent.as @@ -23,9 +23,6 @@ package com.threerings.ezgame { import flash.events.Event; -// TODO: there may not be much point in using the standard flash event -// architecture. I'm about thiiiiiiis close to not. -// public /*abstract*/ class EZEvent extends Event { /** diff --git a/src/as/com/threerings/ezgame/EZGameControl.as b/src/as/com/threerings/ezgame/EZGameControl.as index 2bb67c77..4f1361d8 100644 --- a/src/as/com/threerings/ezgame/EZGameControl.as +++ b/src/as/com/threerings/ezgame/EZGameControl.as @@ -26,7 +26,9 @@ import flash.display.DisplayObject; /** * The single point of control for each client in your multiplayer EZGame. * - * TODO: lots of documentation. + * Usage: Usually, in your top-level movieclip/sprite: + * _ctrl = new EZGameControl(this); + * */ public class EZGameControl extends AbstractGameControl { diff --git a/src/as/com/threerings/ezgame/EZGameSubControl.as b/src/as/com/threerings/ezgame/EZGameSubControl.as index af9bebf8..1b4d616d 100644 --- a/src/as/com/threerings/ezgame/EZGameSubControl.as +++ b/src/as/com/threerings/ezgame/EZGameSubControl.as @@ -85,7 +85,8 @@ package com.threerings.ezgame { [Event(name="UserChat", type="com.threerings.ezgame.UserChatEvent")] /** - * Access game-specific controls. + * Access game-specific controls. Do not instantiate this class yourself. + * Access it via GameControl.game. */ public class EZGameSubControl extends AbstractSubControl { @@ -107,6 +108,8 @@ public class EZGameSubControl extends AbstractSubControl /** * Get any game-specific configurations that were set up in the lobby. + * + * @return an Object containing config names mapping to their values. */ public function getConfig () :Object { @@ -133,7 +136,7 @@ public class EZGameSubControl extends AbstractSubControl } /** - * Returns the player ids of all occupants in the game room. + * Returns the player ids of all occupants in the game room: players and watchers. */ public function getOccupantIds () :Array /* of playerId */ { @@ -143,7 +146,7 @@ public class EZGameSubControl extends AbstractSubControl /** * Get the display name of the specified occupant. Two players may have the same name: always * use playerId to purposes of identification and comparison. The name is for display - * only. Will be null is the specified playerId is not in the game. + * only. Will be null is the specified playerId is not present. */ public function getOccupantName (playerId :int) :String { diff --git a/src/as/com/threerings/ezgame/EZLocalSubControl.as b/src/as/com/threerings/ezgame/EZLocalSubControl.as index f2bbaec3..3b29d202 100644 --- a/src/as/com/threerings/ezgame/EZLocalSubControl.as +++ b/src/as/com/threerings/ezgame/EZLocalSubControl.as @@ -48,7 +48,8 @@ import flash.events.KeyboardEvent; import flash.geom.Point; /** - * Access local properties of the game. + * Access local properties of the game. Do not instantiate this class yourself, + * access it via GameControl.local. */ public class EZLocalSubControl extends AbstractSubControl { @@ -100,7 +101,7 @@ public class EZLocalSubControl extends AbstractSubControl } /** - * Display a feedback system chat message for the local player only, no other players + * Display a feedback chat message for the local player only, no other players * or observers will see it. */ public function feedback (msg :String) :void diff --git a/src/as/com/threerings/ezgame/EZNetSubControl.as b/src/as/com/threerings/ezgame/EZNetSubControl.as index 43ab5ea6..738febef 100644 --- a/src/as/com/threerings/ezgame/EZNetSubControl.as +++ b/src/as/com/threerings/ezgame/EZNetSubControl.as @@ -36,7 +36,10 @@ package com.threerings.ezgame { [Event(name="msgReceived", type="com.threerings.ezgame.MessageReceivedEvent")] /** - * Provides access to 'net' game services. + * Provides access to 'net' game services. Do not instantiate this class yourself, + * access it via GameControl.net. + * + * The 'net' subcontrol is used to communicate shared state between game clients. */ public class EZNetSubControl extends AbstractSubControl { @@ -46,7 +49,7 @@ public class EZNetSubControl extends AbstractSubControl } /** - * Get a property from data. + * Get a property value. */ public function get (propName :String, index :int = -1) :Object { @@ -88,15 +91,16 @@ public class EZNetSubControl extends AbstractSubControl /** * Set a property that will be distributed, but only if it's equal to the specified test value. * - *

Please note that, unlike in the standard set() function, the property will not be + *

Please note that, unlike in the setImmediate() function, the property will not be * updated right away, but will require a request to the server and a response back. For this * reason, there may be a considerable delay between calling testAndSet, and seeing the result * of the update. * *

The operation is 'atomic', in the sense that testing and setting take place during the * same server event. In comparison, a separate 'get' followed by a 'set' operation would - * involve two events with two network round-trips, and no guarantee that the value won't - * change between the events. + * first read the current value as seen on your client and then send a request to overwrite + * any value with a new value. By the time the 'set' reaches the server the old value + * may no longer be valid. Since that's sketchy, we have this method. */ public function testAndSet ( propName :String, newValue :Object, testValue :Object, index :int = -1) :void diff --git a/src/as/com/threerings/ezgame/EZPlayerSubControl.as b/src/as/com/threerings/ezgame/EZPlayerSubControl.as index 48074d6d..855b73cb 100644 --- a/src/as/com/threerings/ezgame/EZPlayerSubControl.as +++ b/src/as/com/threerings/ezgame/EZPlayerSubControl.as @@ -22,7 +22,8 @@ package com.threerings.ezgame { /** - * Provides access to 'player' game services. + * Provides access to 'player' game services. Do not instantiate this class directly, + * instead access it via GameControl.player. */ public class EZPlayerSubControl extends AbstractSubControl { diff --git a/src/as/com/threerings/ezgame/EZSeatingSubControl.as b/src/as/com/threerings/ezgame/EZSeatingSubControl.as index e480b3a5..62808537 100644 --- a/src/as/com/threerings/ezgame/EZSeatingSubControl.as +++ b/src/as/com/threerings/ezgame/EZSeatingSubControl.as @@ -23,7 +23,8 @@ package com.threerings.ezgame { /** - * Access seating information for a seated game. + * Access seating information for a seated game. Do not instantiate this class directly, + * access it via GameControl.game.seating. */ // TODO: methods for allowing a player to pick a seat in SEATED_CONTINUOUS games. public class EZSeatingSubControl extends AbstractSubControl @@ -61,7 +62,7 @@ public class EZSeatingSubControl extends AbstractSubControl } /** - * Get the names of the seated players, omitting any watchers. + * Get the names of the seated players, in the order of their seated position. */ public function getPlayerNames () :Array /* of String */ { diff --git a/src/as/com/threerings/ezgame/EZServicesSubControl.as b/src/as/com/threerings/ezgame/EZServicesSubControl.as index a60064ab..b4a84cc2 100644 --- a/src/as/com/threerings/ezgame/EZServicesSubControl.as +++ b/src/as/com/threerings/ezgame/EZServicesSubControl.as @@ -22,7 +22,8 @@ package com.threerings.ezgame { /** - * Provides access to 'services' game services. + * Provides access to 'services' game services. Do not instantiate this class yourself, + * access it via GameControl.services. */ public class EZServicesSubControl extends AbstractSubControl { @@ -79,9 +80,10 @@ public class EZServicesSubControl extends AbstractSubControl } /** - * Start the ticker with the specified name. The ticker will deliver messages to all connected - * clients at the specified delay. The value of each message is a single integer, - * starting with 0 and increasing by 1 with each messsage. + * Start the ticker with the specified name. The ticker will deliver messages + * (resulting in a MessageReceivedEvent being dispatched on the 'net' control) + * to all connected clients, at the specified delay. The value of each message is + * a single integer, starting with 0 and increasing by 1 with each messsage. */ public function startTicker (tickerName :String, msOfDelay :int) :void { diff --git a/src/as/com/threerings/ezgame/MessageReceivedEvent.as b/src/as/com/threerings/ezgame/MessageReceivedEvent.as index b55e5870..19f0de4e 100644 --- a/src/as/com/threerings/ezgame/MessageReceivedEvent.as +++ b/src/as/com/threerings/ezgame/MessageReceivedEvent.as @@ -23,6 +23,9 @@ package com.threerings.ezgame { import flash.events.Event; +/** + * Dispatched on the 'net' subcontrol when a message is sent by any client. + */ public class MessageReceivedEvent extends EZEvent { /** The type of all MessageReceivedEvents. */