source: trunk/README

Last change on this file was 45, checked in by jtv, 11 years ago

Updated email addresses, URLs.

File size: 6.6 KB
Line 
1libmines - http://pqxx.org/development/mines/
2
3Welcome to libmines, a reusable library for building Minesweeper games.
4
5Introduction
6------------
7
8This package is for programmers who want to write their own version of the
9famous little puzzle game.  (If you think you know the game from soup to nuts
10and it's boring, do read on).  Building libmines requires a somewhat Unix-like
11system and the GNU version of "make"--it may be installed on your system as
12"gmake".
13
14Everybody's got their own version of Minesweeper.  All of them are essentially
15the same, with different user interfaces--often just so they can use different
16user-interface toolkits.
17
18Mostly these versions are "good enough."  But the way we programmers like to do
19things, once everyone agrees what something should do at its core, we call it
20"well-understood" and separate the core from the parts that everyone wants to do
21differently.  That's what libmines is: it provides the heart of the game, the
22"game logic," with some room for variation, so you can build your own new user
23interface without having to write the actual puzzle part all over again.  Of
24course libmines is Free Software (or Open Source, as some prefer to say) so feel
25free to change it and give it to your friends.  Better yet, once you know what
26you want changed in the library to suit your own project, share your wishes and
27changes with the author so everyone can benefit!
28
29Doing things this way makes the programming easier for everyone.  It also makes
30for cleaner code.  It's a great way to learn programming, from making one's
31first steps with a programming language to practicing one's software-engineering
32skills.  And perhaps most of all, it makes it easy to do really new stuff with
33the game!
34
35A very basic text-based command line client is included, which is meant mostly
36for testing.  But there's also a simple CGI program: set up your web server to
37provide access to it, and you can play the game in your browser through the
38Internet.  An example is running on pqxx.org--see the main development page.
39
40Those sample user interfaces aren't great, so here's your chance.  Perhaps you
41can be the one to write a much better one.  Or be the first to build an online
42multiplayer version.  Or figure out new ways to present the playing field.  If
43you want to do it all in 3D, well, we can talk.
44
45
46Boring!
47-------
48
49Your average Minesweeper gets boring fairly quickly.  You may even think of it
50as mindless--one visitor found the project page by searching the Internet for
51"Minesweeper and other mindless games."  Well, with libmines, it doesn't have to
52be.
53
54Most Minesweeper games work like this: you click on a mineless square to reveal
55it.  The square will then show the number of mines neighbouring it.  If there
56are no nearby mines, all surrounding squares will also be revealed, and if some
57of those also show zeroes, their neighbours will be revealed and so on.  Then
58you go on to the next obviously mineless square, until the game finally becomes
59harder.  A large portion of the mistakes come from accidentally clicking in the
60wrong place, clicking with the wrong mouse button, or simply boredom and
61drifting attention.  Yes, the game becomes mindless pretty quickly that way.
62
63That's why libmines goes a little further.  You can specify various levels of
64intelligence.  Level zero doesn't "auto-reveal" anything at all, just what you
65click on.  Level one does it for squares that aren't near mines, like the other
66versions of the game.  Level two is smarter: it will also reveal squares that
67are near mines, as long as all those mines have already been accounted for.  And
68conversely, it also recognizes the situation where all remaining neighbours of a
69field must be mines.  What remains are the interesting situations where you need
70to do some actual thinking.  This way, the game is over much sooner--or you can
71play much bigger fields with more mines.  You can do the thinking, and leave the
72dumb work to the library.
73
74Another way to make things interesting again is to vary the rules a bit.  You
75can show squares outside the actual playing fields, so the player can see what
76squares are safe to click on as starting points.  That eliminates the silly
77guessing at the beginning of the game, as you look for a usable starting point.
78You can let the user mark possible mines with flags, as most versions of the
79game do, or you can make it a fatal mistake to get this wrong, or you can do a
80bit of both.  Players can have multiple lives if you want.  If you would like to
81do really exotic things like add or remove mines during the game, or make them
82move around, they may not be possible yet but we can add them.
83
84
85Writing your own
86----------------
87
88The native language for libmines is C++.  If that is the language you want to
89write your game in, that's easy.  If it's not, there is also an API in C that,
90with a few small exceptions, supports all of the native features.  Most if not
91all other programming languages offer ways to call C functions, so this should
92be enough to support user interfaces in just about any language out there.
93
94Saving games is also possible, of course.  The file format consists of a few
95lines describing the playing field, followed by a compact base64-encoded binary
96representation of the field itself (two bits per square: "is mined" and "has
97been revealed").  The data is written to a memory buffer provided by you; if you
98want to add data of your own, you can write that to file before or after the
99buffer's contents.
100
101The saved-game feature was designed for performance.  That may seem silly: how
102often do you want to save a game, and how long can it take?  We could have made
103things slower and more flexible, but doing that yourself shouldn't be hard.  The
104fast, compact format lets you go to other extremes: the included web user
105interface saves every game to a file after every move, and reloads it every time
106the field is displayed.  That will scale to enormous playing fields and huge
107numbers of simultaneous games.  Future versions could optimize it even further
108by storing games in shared memory.  Or someone might want to write a version for
109mobile phones or other small devices, and keep game state in a tiny bit of
110non-volatile memory.
111
112To start using libmines in C++, take a look at the source files with names
113ending in ".hxx".  These headers define the C++ API.  The C interface is defined
114in a header called c_abi.h.
115
116For more easily readable documentation on how to use libmines in your own
117program, see the documentation in the "doc" directory.  If you would like to
118have this documentation generated in other formats such as LaTeX, ensure that
119the documentation extractor "doxygen" is installed on your system; edit the
120configuration file doc/Doxyfile accordingly, then run "make".
121
Note: See TracBrowser for help on using the repository browser.