Michael Bayne
2890c16224
that we needed to be able to tell if one game ended and another one had started so we introduced GameObject.roundId which was a value that was incremented every time the game started. Thus if you had a timer that expired and you wanted to make sure that somehow the game hadn't ended and then been started anew while you were away, you could save the roundId and check it when you woke up. That was all fine and good, except for the poor choice of variable name. Then we came to implement Whirled and wanted to provide an abstraction of "rounds" which were subunits into which a single game is divided. We had this lovely variable already lying around called roundId and we succumbed to the temptation to overload its meaning and have games that use round increment the round id multiple times during a game which preserves the monotonically increasing nature of roundId as expected by the Parlor code and seemed to do no harm. Then we discovered a pesky wrinkle, which is that GameManager sets GameObject.roundId in gameWillStart() and then goes on to set GameObject.state after that. We were naturally listening for roundId to change and triggering a call to roundDidStart() at that time, but this resulted in a strange sequencing of callback methods that went: roundDidStart(), gameDidStart(), roundDidEnd(), roundDidStart(), ..., roundDidEnd(), gameDidEnd(). The premature roundDidStart() was irksome, and I looked into what would be needed to remedy it. It turned out that a lot of code on the server-side of things depended on the Parlor semantics of roundId and wanted roundId to be set to the current round's value in gameWillStart() and similarly in gameDidStart(). However, there's no gameWillStart() on the client and it didn't appear to me that anyone much cared about roundId in gameDidStart(), so I opted for some hackery in the name of expedience that preserved the server-side semantics but changed the client to see ROUND_ID change after STATE changed. As you might expect given the verbosity of this explanation, that turned out to be a new bad idea stacked on the previous bad idea of reusing roundId which was stacked on the bad choice of name for roundId. It turns out some puzzles in Yohoho did expect roundId to be already set in gameDidStart() which was no longer the case and the inevitable digital mayhem ensued. The time has come to undo the various bad decisions and replace them with new decisions that we hope aren't bad. Those decisions are: - rename roundId in GameObject to sessionId and restore its original semantics which are that it represents a monotonically increasing integer that is incremented (and published to the client) in gameWillStart() and thus represents the current game session from the very first to the very last; - add WhirledGameObject.roundId for handling rounds in Whirled games and give it the semantics we desire which are for it to be set to 1 in gameDidStart() and then incremented only when a new round is started, and reset to 1 when a new game is started (this change is in another commit). This will temporarily break some builds as I need to go rename some things in Yohoho and then I need to look at Bang! Howdy which if I recall correctly also naughtily uses roundId for nefarious ulterior purposes and needs also to be cured of its wayward habits. git-svn-id: svn+ssh://src.earth.threerings.net/vilya/trunk@611 c613c5cb-e716-0410-b11b-feb51c14d237
The Vilya library
-----------------
The Vilya library provides various facilities for making networked multiplayer
games. It's various packages include:
* whirled - builds on the crowd framework and defines a scene graph with
portals to move between scenes and provides hooks for distributing and
updating scene data (for example isometric rendering information) over
the network
* parlor - builds upon the crowd framework to create the notion of a
game with players and provides tools for making turn based games
* puzzle - builds on the parlor and media frameworks to provide tools
for implementing puzzle games in a networked environment
* micasa - builds on the parlor framework to provide lobbies and
matchmaking for multiplayer games
Documentation is somewhat sparse at the moment, but inspection of the code in
the tests/ directory shows examples of use of many features of the library.
Building
--------
Building the library is very simple. First ensure that the necessary third
party jar files are available in the lib/ directory. See lib/README for a list
of the necessary third party jar files and how to get them.
The library is built using Ant, a modern build tool written in and for Java. If
you aren't already using Ant for other projects, it can be found here:
http://ant.apache.org/
Invoke ant with any of the following targets:
all: builds the distribution files and javadoc documentation
compile: builds only the class files (dist/classes)
javadoc: builds only the javadoc documentation (dist/docs)
dist: builds the distribution jar files (dist/*.jar)
Distribution
------------
The Vilya library is released under the LGPL. The most recent version of the
library is available here:
http://www.threerings.net/code/vilya/
Contribution
------------
Contributions to Vilya are welcome. Read-only access to the subversion
repository is available at:
svn://code.threerings.net/vilya/trunk
Patches can be mailed to Michael Bayne <mdb@threerings.net>.
Contact Information
-------------------
Vilya is actively developed by the scurvy dogs at Three Rings Design, Inc.
Contact Michael Bayne <mdb@threerings.net> with questions, comments and other
wordly endeavors.
$Id$