Documentation

Readme.md

@@ -0,0 +1,90 @@
+Seopardy
+========
+What this is
+------------
+Seopardy is an implementation of the game "Jeopardy" and a
+reimplementation/clone of the software "beopardy", mostly known for being
+used in the Chaos Communication Congress Hacker-Jeopardy.
+
+
+Installation & Requirements
+---------------------------
+To run this software you need:
+
+ * python (python2)
+ * python-pyside
+ * python-pyside.phonon (for music)
+ * python-yaml / PyYAML
+ * python-serial / pyserial
+
+To play a game I recommend:
+
+ * a question file
+ * music!
+    * start song (played while naming players)
+    * question song (played while question is displayed)
+    * end song (played while victory window is shown)
+ * a configuration file - just copy seopardy.conf.dist to seopardy.conf
+ * buttons for player input
+
+
+The Question File
+-----------------
+A question file is a yaml-file defining all sections and questions used in the
+game. For an example look into `questions/template.q`. It can contain an arbitrary
+number of sections, though five are generally recommended. Each section has exactly
+five questions. A question can have the following keys:
+
+ - Name (to remind you of the question number)
+ - Question (text/image/... displayed on screen)
+ - Answer (to remind you of the answer, not used in the program)
+ - Type (type of question)
+ - Double-Jeopardy (if the question is a Double-Jeopardy, default false)
+
+Four *Types* of question are supported:
+
+ - Text: The text is normally displayed on screen
+ - Code: The code is displayed with a monospace font, tabs are replaced with
+         four spaces
+ - Image: The Question key is a path to an image, which is displayed on screen
+ - Music: The Question key is a path to a music file, which is played
+
+
+Gamestate
+---------
+To prevent you from losing the current gamestate in case of a crash,
+seopardy saves its interal state as a yaml file after each question.
+You can specify a directory where the gamestates are stored in the config
+file and load a state with the --gamestate parameter.
+
+
+Player Input
+------------
+To get the input from a button (aka "the outside world") into the game,
+two classes are available:
+
+*Fifo* creates a fifo in your local filesystem, first argument being the
+path to where the fifo should be created. To emit a button press you can
+simply write an ASCII-number into the fifo, corresponding to the player
+which pressed a button. All other characters are ignored.
+
+*Serial* reads from a serial device using pyserial. Parameters are path to the
+device, baudrate (default 9600), parity (default N) and stop-bits (default 1).
+As with the fifo, an ASCII-number for the player which pressed a button is
+expected. All other characters are ignored.
+
+Writing an own class for player input should be fairly easy. Within its own
+thread the class can do whatever it wants (including blocking I/O). When it
+wants to signal a button was pressed it just needs to emit a ButtonEvent.
+
+
+Known Bugs
+----------
+
+ * The focus order and focus setting for the question-answer-editing and the
+   double-jeopardy window is somewhat broken.
+ * The input threads are currently not shut down correctly, leaving some ugly
+   output on the console when exiting the game.
+ * Stylesheets for buttons/labels could be more centrally managed and more
+   consistent.
+