Read Me

			       Seaweed
		     Economic Experiment Designer

Create simple economic games

    * two players
    * symmetric actions
    * one decision per screen

Draw screen like Powerpoint
Define payoff matrices
Specify a number of rounds

... and your game is ready to be played by randomly paired people on
the internet

			      -=-=-=-=-

Seaweed started as Lydia B. Chilton's master thesis project at MIT,
<http://groups.csail.mit.edu/uid/projects/seaweed/ChiltonThesis-Seaweed-19May2009.pdf>.
It was written in PHP (5.2.13 on cweed.org; 5.3 developers) using the
web application framework CodeIgniter-1.7.2, all of whose files are
included in source-control.  The meat of the Seaweed implementation is
in system/application where there are directories corresponding to the
Model-View-Controller paradigm:

  models
  views
  controllers

Dr. Joseph Lawrance at MIT developed Seaweed to use Adobe Flex 3.4.0 AIR
1.5.2 SDK.  <http://groups.csail.mit.edu/uid/seaweed/release-0.3> is a
live server.  The (read-only) sources are available from

  https://svn.csail.mit.edu/uid/projects/cWeed/
  username: anon
  pwd: anon

There are 4 directories at top level, listed here with their most
recent revision, author, and revision date:

	directory	 rev.	author	   revision date
	=========	 ====	======	   =============
  GameEngineAsymmetric	r2829 | paigep	 | 2009-12-09
  Seaweed1.0		r1742 | jyuan	 | 2009-03-10
  Seaweed2.0		r3000 | lawrance | 2010-06-02
  SeaweedAsymmetric	r2828 | paigep	 | 2009-12-09

The current work started from Seaweed2.0 in May 2011.

The directory structure for the "Flex"ed application is not contained
within system/application as for CodeIgniter, but in peers of
"system":

  /home/jaffer/cWeed/Seaweed2.0:
  drwxr-xr-x  6 jaffer users  4096 2011-05-25 13:32 DataOutput
  drwxr-xr-x  6 jaffer users  4096 2011-05-25 13:32 Deploy
  drwxr-xr-x 10 jaffer users  4096 2011-05-25 13:32 Designer
  drwxr-xr-x  8 jaffer users  4096 2011-05-25 13:32 GameChooser
  drwxr-xr-x  9 jaffer users  4096 2011-05-25 13:32 GameEngine
  drwxr-xr-x  5 jaffer users  4096 2011-05-25 13:32 Global
  drwxr-xr-x  6 jaffer users  4096 2011-05-25 13:32 Login
  drwxr-xr-x  4 jaffer users  4096 2011-05-25 13:32 PlaySideBySide
  drwxr-xr-x 10 jaffer users  4096 2011-05-25 13:32 Viewer

The correspondence between these directories and the CodeIgniter
organization is made in "system/application/config/routes.php":

  $route['Deploy/src/php/getGameJSON.php'] = "game/load";
  $route['Designer/backend/php/getDB.php'] = "game/load";
  $route['Viewer/backend/php/getDB.php'] = "game/load";
  $route['Designer/backend/php/saveGame.php'] = "game/save";
  $route['GameChooser/backend/php/chooseGame.php'] = "game/index";
  $route['GameChooser/backend/php/cloneGameLoader.php'] = "game/copy";
  $route['GameChooser/backend/php/deleteGame.php'] = "game/delete";
  $route['GameChooser/backend/php/newBlankGameLoader.php'] = "game/newGame";
  $route['GameChooser/flex/GameChooser.html'] = "game/chooser";

The "Login" modules appears to be incomplete and unused.

			      -=-=-=-=-

The source code for this Seaweed project (from Seaweed2.0) is stored
in Subversion hosted by SourceForge.  The SourceForge project website
is <http://sourceforge.net/projects/c-weed/> and
<https://sourceforge.net/projects/c-weed/> for developers.  The
registered developers are:

  jaffer	Aubrey Jaffer
  shaharr	Shahar Ronen

To checkout the development tree into a new directory "c-weed", do:

  svn co https://c-weed.svn.sourceforge.net/svnroot/c-weed c-weed

"Ant" is used to build and deploy three versions of Seaweed:
"dev", "developer", and "release".

These are the targets supported by the top-level "build.xml":

	build-dev	deploy-dev
	build-developer	deploy
	build-release	deploy-release
	clean
	docs

Notice that deploy-developer is instead deploy.  "ant" with no
arguments is the same as "ant deploy".

"dev.properties" and "release.properties" are included in Subversion
sources (at top level).  These files specify the URL, file-locations,
and database parameters for a Seaweed deployment.  They assume
file-system access to the web-site directory.  While this works for
running a local webserver on a developer's machine, I have
deploy-release build the website in
/home/jaffer/public_html/seaweed/release-0.3/, then upload it to the
live website using:

  lftp -c 'open cweed.org; mirror -R \
	  /home/jaffer/public_html/seaweed/release-0.3 \
	  public_html/cweed.org/release-0.3'

Because other developers are unlikely to have my particular
file-system organization, they should copy "dev.properties" to
"developer.properties" and customize it for their system; then use

  ant build-developer
  ant deploy

or just "ant" for local development.

The first time that and Ant build is attempted, Ant downloads
.flex/flex_sdk_3.4.zip and unpacks it into a newly created .flex
directory.

In order to run "ant docs" on Linux, one must do:

  chmod +x .flex/bin/* .flex/asdoc/templates/*.linux

Thereafter, "ant docs" builds documentation of the Flex classes:

  docs:
  drwxr-xr-x  7 jaffer users 4096 2011-06-08 19:15 Designer
  drwxr-xr-x  4 jaffer users 4096 2011-06-08 19:15 GameChooser
  drwxr-xr-x  4 jaffer users 4096 2011-06-08 19:15 GameEngine
  drwxr-xr-x  3 jaffer users 4096 2011-06-08 19:15 Login

			      -=-=-=-=-

"GameEngine/src/GameEngine.mxml", which includes "GameEngine.as", gets
compiled into "build/GameEngine/flex/GameEngine.swf".  It sets up four
"mx:HTTPService" objects which issue HTTP-Post requests:

  '/php/checkPartners.php'+params.nocache
  '/php/getNextScreen.php'+params.nocache
  '/php/registerPlayer.php'+params.nocache
  '/php/setUpComputerPlayers.php'+params.nocache

params.nocache contains the session identifier.

		     GameEngine/src/GameEngine.as

load() is called only from the mx:Application attribute
applicationComplete="load()".  It is responsible for the "Mechanical
Turk Preview mode", which currently puts up text screen: "Play a short
game and earn some cents!"

HTTPService calls are made by invoking the <id>.send() where <id> is
the value of the id field of a mx:HTTPService record in
"GameEngine.mxml".

load() calls register.send() if this is not a preview screen.

The "register" mx:HTTPService has attribute result="registered(event)"
registered() retrieves the object JSON.decode(event.result as String).
    if (result.registered) nextScreen.send();
    else register.send();

handleScreen() is the major piece of "GameEngine.as".  It is called
with the event object by both the nextScreen and checkPartners
mx:HTTPServices in "GameEngine.mxml".  It "send"s services
checkPartners.send() [two places] and setUpComputerPlayers.send().

handleScreen() calls helper functions makeWaitingScreen,
makeTimeoutScreen, or makeScreen.

makeScreen() is called only from handleScreen().
makeScreen() adds makeTimeoutScreen() to
	     screenTimer.addEventListener("timerComplete",...)

load() calls makeWaitingScreen() for "Mechanical Turk Preview mode".

getNextScreen() is called only from makeScreen()
		b.addEventListener(MouseEvent.CLICK,...).
getNextScreen() "send"s nextScreen.send(params);

			       Sequence

load() is called initially.  If this a Turk-Preview then:

  makeWaitingScreen("Play a short game and earn some cents!", NaN)
 
and nothing else happens.  Otherwise register.send() which invokes
GameEngine/php/registerPlayer.php with the results directed to
registered(event).

registered(result) calls nextScreen.send() if result.registered,
otherwise loops by calling register.send().

nextScreen loads GameEngine/php/getNextScreen.php.  In a transaction,
getNextScreen.php calls findNextNode(), then processNode() to get the
$widgets, which it returns to (Flash) handleScreen.

findNextNode() checks if the $nodeID and $nodeType from _SESSION are
empty; if so, it returns an array of `id` and `type` from the
`firstNodeId` and `firstNodeType` fields for this game.

			     Result Logs

Times in the getResults logs from cweed.org (hosted by x10hosting.com)
are one hour behind EDT; so it is either EST or CDT.  x10hosting.com's
mailing address is in Tilton NH; so I guess it is EST.

Logging starts when a partner is found.  Errors are not logged.
Complete games end with "finalScreen".  There are 3 ways a game fails
to complete:

 * a player takes longer than 1 minute to click a button;

 * the game lasts longer than 5 minutes (MTurk's limit); or

 * Seaweed hangs waiting for data which failed to be written into the
   database.

X10Hosting's free server seems to be so heavily loaded that I have had
a MTurk game terminated because it lasted over 5 minutes.


			    Paying Bonuses

<http://cweed.org/release-0.3/GameEngine/php/payBonuses.php>