Final project: chessboard puzzle game

README.md

@@ -1,3 +1,44 @@
-# cs50p
+# Chessboard puzzle game
+#### Video Demo:  <URL HERE>
+#### Background information
+This script implements a puzzle game described
+[here](http://datagenetics.com/blog/december12014/index.html).
+I heard about it thanks to 3blue1brown and Stand-up Maths who played
+it and explained it [here](https://youtu.be/as7Gkm7Y7h4).
 
-CS50P: CS50's Introduction to Programming with Python
+#### Overview of the puzzle:
+- Two players are faced with a challenge by a judge.
+- The judge will show player 1 (P1) a square chessboard covered in coins.
+    Each coin will be put heads or tails by the judge at their will.
+- The judge will show player 1 a tile of the chessboard where a key will
+    be hidden. Player 1 must then flip one and only one coin and then leave
+    the room without communicating with Player 2.
+- Player 2 is then shown the chessboard (as modified by the single flip made
+    by Player 1) and must guess the correct tile where the key is hidden.
+- Player 1 and 2 can agree upon a strategy before starting, but the judge
+    will know what they said and can act accordingly when choosing the coin
+    disposition on the chessboard.
+- No tricks: the players can not communicate after Player 1 is told where the
+    key is; each coin may be only H or T, its orientation is meaningless, and
+    it cannot be put in other states (e.g. on its side).
+
+#### Description
+The script generates three pdf files: Problem, Key and Solution.
+- `Key.pdf` shows the initial 8x8 grid, filled with random heads (H) or tails
+    (T), with an orange coin where the invisible key is hidden.
+    This is how the grid looks like when the judge shows it to Player 1
+    asking them to flip one and only one coin.
+- `Problem.pdf` shows the same grid with just one coin flipped by Player 1.
+    This is how the grid looks like when the judge shows it to Player 2 after
+    Player 1 has flipped one coin.
+- `Solution.pdf` shows the same grid, with an orange coin and a purple coin.
+    The orange one is where the key is hidden, the purple-background coin
+    is the one to flip to communicate where the key is.
+
+##### How to play
+- Show player 1 the `Key.pdf`: a grid with one key hidden.
+- Ask player 1 to flip one and only one coin. They should choose the
+    purple-background coin in `Solution.pdf`, thus producing the same grid
+    shown in `Problem.pdf`.
+- Show Player 2 `Problem.pdf` and ask them to identify where the key is.
+    They should point to the orange coin in `Key.pdf` and `Solution.pdf`.