Card Stories - Beta1.0 Specifications

= Overview =

The game includes a deck of cards.


 * A player (who we will call the author) creates a new game.
 * He chooses a card,
 * picks a word or a sentence to describe it,
 * offers players to play the session
 * the participant players choose a card in their own deck that matches the author's sentence
 * Once enough players have chosen the card, the author displays all chosen cards, and the players try to figure out which one is the author's
 * The author wins if at least one of his friends gesses right, but not all of them do. Then the winners are the author and the friends who guessed right.

If the author loses, all the other players win.

= Creation of a game =

The author creates a new game, through the 'new game' button, on the application welcome screen which looks like that:



The author picks a card in his deck, a sentence and notices friends: 



After each step completed, the 'ok' button lets the author start the next step.

If necessary, this step can be broken into different screens, on screen for each of the three steps.

The author can chose among a set of 20 cards that are randomly selected from the overall deck.

Publication with Facebook Share
Instead of using the traditional application API to publish to the user's wall, we would use Facebook Share.

http://www.facebook.com/share/

After "Choose a sentence" / before "Invite friends":




 * John Doe is the author name
 * "My great sentence" is the sentence the author has chosen
 * The link sends to cardstories.farsides.com (the page that contains the meta-data used by the Facebook sharer) and redirects players to apps.facebook.com when they click on it to ensure they play from within Facebook (they join the game).


 * the post appears on the friend's wall but anyone can click on the link and play the game.
 * A game is limited to 6 players (including the author). It should be stated on the noticing screen.
 * The Facebook share screen is shown in an Iframe, not in a browser pop-up

= Playing the game =

'''Each participant takes his turn by picking a card that is, according to him, the closest to the sentence. '''

The player has two ways of reaching the game :

1) follow the link on a wall where it has been posted, he then goes directly to the screen where he picks a card. Everyone can do that.

2) If the player is one of the friends who received a message on his wall, he can go to the application and follow these steps :



The player then picks his card :



Each player receives a deck of 7 cards.

Two players cannot have a card in common (given that a session is limited to 6 players including the author, this gives us a minimum of 36 cards to have in the overall deck).

Once all the author decides so (see below), the participants vote for the game 

The participants can either vote by following the link on a notification they receive or follow these steps :



The player then votes :



Once the player has voted, he still has access to the previous page, but he can't do anything, and he can't see the votes of the other players until they have been published by the author (on his management screen, he sees 'voted - waiting for author to publish the results').

'''During this process, the organizer can monitor the status of the game. He can reach the corresponding screen the following way :'''



The next screen can have two status, depending on the step of the game (step 1 = pick cards, step 2 = vote) :




 * Step 1 :
 * In our example, the player 3 received a message but did not play yet. The player 4 saw the message on the wall of someone else and chose to participate.
 * When the author feels that enough players have picked a card, he pushes the vote button to move to step 2. For those players who received a message on their wall but did not play, the game disappears from the list on the game management screen ('current games').
 * Step 2 :
 * The author can wait for all players to vote before moving on to the next step. But if a player takes too much time to vote, he can also use the 'force end' button to finish the game.

'''Once all players have voted, the author can see the results and publish them. To reach the results screen, he can either follow the link on the notification he will receive or follow these steps:'''



After "Publish the results" / before displaying the results:




 * The image displayed is the card that the author had selected
 * The link sends to cardstories.farsides.com (the page that contains the meta-data used by the Facebook sharer), but doesn't redirect to apps.facebook.com - it allows everyone to see the results of the game without adding the application. Clicking on "Create your own game" sends to apps.facebook.com though - requiring the user to add the application and then letting him create a new game.
 * The Facebook share screen is shown in an Iframe, not in a browser pop-up.

On the screen that shows the cards (the one which is created once the author publishes the results), there is a button 'create another game' available for all visitors.

Rules for win/lose
the author wins if at least one of his friends gesses right, but not all of them do. Then the winners are the author and the friends who guessed right.

If the author loses, all the other players win.

= Other notes =


 * managing games: on the current games screen,
 * there are two possible roles : player and author
 * if player, the possible status are : Pick a card !, Vote !, card picked - waiting for others, voted - waiting for author to publish
 * if author, the possible status are : Pending - check the status, Done - announce the results
 * When the results are announced, the game moves to the 'finished' tab and the status is replaced by win/lose with a link to see the cards


 * On the player's profile, there is, to begin with, 1) the number of games played as author and as player, 2) and for each, the number of games won (and %), 3) and the overall number of games played/won/% of success


 * Email notifications :
 * new game,
 * turn,
 * automated reminders when players don't play
 * publication of results...


 * Information that need to be retrieved from the players facebook account and stored in our database :
 * email,
 * name,
 * sex,
 * birthday
 * location,
 * likes,
 * list of friends,
 * and all basic/public profile information


 * There is a unique URL for each game, accessible publicly. It displays all the information that all the players know at any moment during or after the game, as soon as the author selected his card &amp; sentence. (It opens the possibility to add non-FB sharing features more easily later on)


 * Add a one-click action buttons to bookmark and Like the application, in a preeminent place on every single page (and make it disappear when players do the action)


 * In-game comments: on each of the screen showing a game step (ie all screens exccept the welcome screen and the list of games), add the Facebook comments below the existing screen. It should use one Unique id for each different game. http://developers.facebook.com/docs/reference/plugins/comments

= Requirements =

General

 * Follow the Facebook guidelines and advices found on http://developers.facebook.com/
 * Use the Graph API (http://developers.facebook.com/docs/api)
 * When you install the application on Facebook yourself, it must remain in sandbox/developer mode and not be publicly accessible.
 * You must provide an document describing the installation steps within the first week of development, and keep it up to date until the work is accepted.
 * The design for the application will be communicated during development. It must be identical to the pixel to the design contained in the documents.
 * Must be implemented in object-oriented model and must not use global variables. All SQL requests must be made through data objects.
 * Produced or modified code must be fully documented, using all tags available in phpDocumentor. Make the generated documentation easy to read, thorough, and keep in mind that it should be easily understandable by other developers without prior knowledge of the code.
 * The following browsers must be supported: IE 8.0, 7.0, 6.0; Firefox 3.0, 2.0-2.x, 1.5; Safari; Chrome; Opera
 * Have complete copyrights to all work produced. All deliverables and third-party libraries must be compatible with the GNU AGPLv3, under which the software will be released.

Commits

 * Developments must be split into small and isolated commits to a bazaar repository on Launchpad, with a meaningful and thorough commit message. Make one entry for each unique change within a function or file - no "Updated missions" with 2000 lines of modified code in a single commit. Keep it simple, think about people who will read the diffs of the commits you make.
 * When you fix a bug or add a new feature, isolate the fix in a single commit (or several if it's a big change), include the bug id in the commit message, and provide a link to the revision in the bug report or the feature ticket.
 * Push commits to your branch progressively during development - never stay more than a day without commiting and pushing. It helps other developers and those who want to follow your progress to be up to date on your latest work. It also helps to review your code progressively, instead of having a large chunk to read when the release is ready.
 * Make sure you have merged your repository with the trunk line and resolved any conflicts before pushing changes to Launchpad.

Tests

 * A set of unit tests covering 100% of the code written or modified for the job. There is no need to cover the code that already existed and that was not modified.
 * A single command without argument must run all the unit tests, report the total percentage of coverage and list all the lines of code that are not covered.
 * Implement a verbose mode for running the tests so identifying which unit test fails and why is straightforward.
 * All javascript functions, if any, must be tested using http://siliconforks.com/jscoverage/ and reach 100% coverage. All code must be encapsulated in functions. All javascript functions must be defined in .js files.
 * Create Windmill tests for all new features and make sure all the existing Windmill tests keep working.
 * The tests must be implemented using the same techniques as the pre-existing tests of the software being modified. It is not acceptable to create a new test environment.

Language &amp; metrics

 * The game interface can be translated in mutliple languages through .po files, and the game automatically selects the appropriate language based on the headers sent by the browser
 * All server pages/URLs and user actions are tagged using Open Web Analytics
 * All player actions are logged in a table in the database, along with all the relevant contextual information: date/time, username, action, result, game id, etc.

= Solo Mode = Card_Stories_-_Solo_Mode

= Adding Depth of Play = Card_Stories_-_Adding_Depth_of_Play