From 7a8a7ab16a562c015cc90071df63028658206d60 Mon Sep 17 00:00:00 2001 From: Sebastian Lohff Date: Sun, 8 Dec 2013 00:52:47 +0100 Subject: [PATCH] Documentation --- Readme.md | 90 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 90 insertions(+) create mode 100644 Readme.md diff --git a/Readme.md b/Readme.md new file mode 100644 index 0000000..234abfb --- /dev/null +++ b/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. +