33e32da2dfd2aa570d5ea23a121105cbe50d7f6a
[pyrisk.git] / README
1 PyRisk
2 ======
3
4 This is a Python engine and interface for building games similar to
5 the 1957 La ConquĂȘte du Monde by Albert Lamorisse (of "Le Ballon rouge
6 / The Red Balloon" fame).  The game is perhaps better known as Risk,
7 and is produced by Parker Brothers (now a division of Hasbro).
8
9 Benefits over other open source implementations:
10
11   * simple, extensible implementation
12   * play-by-email
13
14
15 Getting PyRisk
16 ==============
17
18 PyRisk is available as a Git repository::
19
20     $ git clone git://tremily.us/git/pyrisk.git
21
22 The most recent commit is also available as a gzipped tarball at::
23
24     http://git.tremily.us/?p=pyrisk.git;a=snapshot;h=HEAD;sf=tgz
25
26 Once you get the source, installation is via Docutils::
27
28     pyrisk$ python setup.py build
29     pyrisk$ python setup.py install
30
31
32 Getting started
33 ===============
34
35 To setup play-by-email, you'll have to have some method to redirect
36 appropriate messages into a named pipe.  With procmail, that will
37 look something like::
38
39     :0
40     * ^Subject:.*\[PyRisk.*
41     {
42       :0 wc
43       /path/to/named/pipe
44     
45       :0
46       | /bin/echo -e '\000' >> /path/to/named/pipe
47     }
48
49 The echo command appends a NULL byte to the FIFO, which (I think), helps
50 the read() in _get_msg break at the appropriate point.
51
52 Once you have the procmail rule setup, just add your EmailPlayers to
53 your game and go::
54
55     from pyrisk.base import generate_earth, Player, Engine
56     from pyrisk.player.email import IncomingEmailDispatcher, \
57         OutgoingEmailDispatcher, EmailPlayer
58     from pyrisk.graphics import WorldRenderer
59     world = generate_earth()
60     ied = IncomingEmailDispatcher(fifo_path='/tmp/pyrisk.in')
61     oed = OutgoingEmailDispatcher(return_address='server@example.com')
62     wr = WorldRenderer()
63     players = [EmailPlayer('Alice', 'alice@big.edu', ied, oed, wr),
64                EmailPlayer('Bob', 'bob@fish.net', ied, oed, wr),
65                Player('Charlie')]
66     e = Engine(world, players)
67     e.run()
68     ied.close()