Initial revision of cocktail multiplayer networked gaming platform. (Far

from complete.)


git-svn-id: svn+ssh://src.earth.threerings.net/narya/trunk@2 542714f4-19e9-0310-aa3c-eee0fc999fb1

docs/design.txt

@@ -0,0 +1,55 @@
+Cocktail Mk3 -*- outline -*-
+
+* What is it?
+Cocktail is a platform on which multiplayer networked games may be
+developed. The platform is (extremely) loosely based around the idea of a
+cocktail party. For the most part, this just gives us a useful context
+from which to choose names. The basic service of the Cocktail platform is
+a simple information sharing mechanism based on the concept of distributed
+objects. This layer is called "Cher" for reasons outlined in the Cher
+design notes.
+
+A distributed object has a set of subscribers. Whenever a modification is
+made to that object, all of that object's subscribers are notified. This
+has the beneficial effect of providing a framework in which to conceive a
+distributed application based on who needs to know what. If information
+need be shared among a set of clients, a distributed object can be created
+to represent that information and those clients would subscribe. Then
+modifications to that object (as well as simple notifications) can be
+easily delivered to those clients and those clients only.
+
+As one discovers after further use of the system, the distributed object
+concept turns out to be a useful one for other reasons when designing
+distributed applications (a subset of which are multiplayer networked
+games). The distributed objects fit nicely as the model in the model,
+view, controller pattern as well as into other useful patterns.
+
+The primary value of the design is to bring the level of abstraction up
+from network connections and packets, to objects and events.
+
+** Getting the party started
+Atop the distributed object layer, we further develop the concept of the
+cocktail party. Parties tend to take place in rooms and be attended by
+groups of people. This is the essence of the next layer of the system: a
+framework for providing rooms, with occupants and mechanisms for the
+people to move between those rooms. Within the rooms, we provide some
+useful basic services like the ability to chat among the occupants of the
+room, as well as some non-room-specific facilities like person to person
+messaging from anywhere in the system and a location directory.
+
+Not all games developed with the platform will want to use the room
+concept, therefore we attempt at this layer and in all subsequent layers
+to decouple our services as much as possible. This allows a game with
+special needs or for whom our half-baked analogies don't apply, to
+leverage some of the useful services without having to bend their design
+in uncomfortable ways or hack up some additional interface to the services
+we provide.
+
+** Let's play
+From here, we branch off into all sorts of interesting directions based on
+the different kinds of games that are implemented with the system. We
+provide matchmaking lobbies, an extension of the room concept to the game
+room, on top of which is provided a framework for managing generic
+turn-based games, and various other useful services. Again the philosophy
+is to provide consistently designed, but decoupled services that can be
+used within and along side whatever design works best for your game.

docs/presents/design.txt

@@ -0,0 +1,38 @@
+Cher Mk3 Design -*- outline -*-
+
+* Why Cher?
+The basic function of this layer is to allow the sharing (Cher-ing) of
+information among different nodes in the network. Plus, I don't think Cher
+has ever had a software system named after her and it's high time. Imagine
+Cher as the social lubricant that allows the party goers to communicate.
+
+* Client components
+
+** DObjectManager
+Manages object proxies; converts value change requests into events,
+forwards them via the iomgr; dispatches events on incoming queue; reaps
+proxies when last subscriber goes away
+
+** UI (AWT/Swing)
+Standard AWT/Swing UI
+
+** UI (Controller)?
+Provides a paradigm of controllers and commands; code can post commands
+back to the controller queue for later execution; UI elements structured
+to automatically generate commands; will probably opt not to use this in
+favor of Swing's built-in paradigms
+
+** I/O Manager
+*** Reader
+Reads incoming data from the socket; decodes messages; posts events to
+domgr queue; notifies object subscription penders (this should be done
+asychronously)
+
+*** Writer
+Encodes object subscription and event forwarding requests; writes them to
+the outgoing socket
+
+** Client object
+Informs exo-client about connection state changes; provides interface to
+connection + authentication (logon) and disconnection (logoff); provides
+access to omgr and client dobj

docs/presents/notes.txt

@@ -0,0 +1,94 @@
+Cher Mk3 Notes -*- outline -*-
+
+* Server components:
+  + Connection manager 
+  + Client manager
+  + Event dispatch thread (DObjectManager)
+  + Server side services?
+  + Room/Game managers
+  + Info repository for shared info?
+
+* Client components:
+  + Network client (auth + DObject services)
+  + Applet shell
+  + Panel management
+  + Components: chatbox, occupant info, turn indicator?
+  + Room/Game panels, controllers, etc.
+
+* Client detail:
+  + Supply credentials (username, password)
+  + Establishes, maintains connection: 
+    login (connect), logout (disconnect)
+  + Creates, manages client-side DObjectManager
+
+* Events in the client will be dispatched on the AWT thread
+- Provide pluggable "event dispatcher" on the client
+- Allow extension of Event as DispatchableEvent so that event objects
+  themselves can extend Runnable and be popped right into
+  SwingUtil.invokeLater().
+
+* Client perform all network ops on own thread, will call back to main
+  code through Observer interface to notify of state changes in the
+  authentication process/connectedness:
+
+  public interface ClientObserver
+  {
+      public void didConnect ();
+      public void connectionFailed ();
+      public void didLogon ();
+      public void logonFailed ();
+      public void didDisconnect ();
+      public void didLogoff ();
+  }
+
+* Three Rings Client flowlist:
+
+  Instantiate client
+  Obtain auth info
+  Obtain room info
+  Authenticate
+
+* Distributed objects are defined like a class with a set of public data
+  members which is then converted into an actual class with get/set
+  methods for each member.
+
+  public dclass GameObject
+  {
+      public int[] players;
+      public String description;
+  }
+
+  becomes
+
+  public class GameObject extends DObject
+  {
+       public void setPlayers (int[] players);
+       public void setPlayersAt (int index, int value);
+       public int[] getPlayers ();
+       public int getPlayersAt (int index);
+
+       public void setDescription (String description);
+       public String getDescription ();
+  }
+
+* Classes:
+
+  DObjectManager
+  DObject
+  DEvent
+  DTransaction
+  Subscriber
+
+* Events:
+
+  ATTRIBUTE_CHANGED
+  ATTRIBUTES_CHANGED
+  ATTRIBUTES_CHANGED_SPLIT
+  ELEMENT_CHANGED
+  OBJECT_DESTROYED
+
+  ELEMENT_ADDED
+  ELEMENT_REMOVED
+
+  OID_ADDED
+  OID_REMOVED