source: trunk/README @ 30

Last change on this file since 30 was 30, checked in by jtv, 13 years ago

New file

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