Documentation stuff

git-svn-id: svn://cook.msm.cam.ac.uk:745/thrust3d/thrust3d@242 84d2e878-0bd5-11dd-ad15-13eda11d74c5

1 files changed, 52 insertions, 22 deletions

diff --git a/README b/README
index 35995f8..dd37cf7 100644
--- a/README
+++ b/README
@@ -6,20 +6,35 @@ Post-apocalyptic Jet Set Willy, set in a 3D nuclear power station.
 Aim
 ===
 
-Fly around the highly radioactive remains of the Mars nuclear power station and collect the coloured flashing radiactive
-debris.  Don't crash into any walls or other objects or your craft will explode.  Land only on the glowing energy
-platforms.
+In the year 2084, humanity's first nuclear power station on Mars suffered a total meltdown.  Radioactive debris were
+spilt across almost a thousand square kilometres of Martian land.  The reactor building itself stayed structurally
+intact, but was filled with radioactive particles spewed out by the core.  Your job is to pilot a small
+remote-controlled decontamination vehicle around the power station complex, collecting all of the radioactive particles.
+
+Unfortunately the lander craft suffers from almost comically low fuel efficiency, and its fuel cells become depleted
+after only a few hundred metres of flying.  Your craft's electrostatic shielding system is powered from the same energy
+source, and will draw a larger current when necessary to deflect radiation away from its sensitive electronics.  Hitting
+any stationary object in flight will put a huge momentary strain on the batteries and take a sizable chunk out of your
+fuel reserve.
+
+Luckily for you, there are a great many energy platforms distributed around the building to recharge the service robots
+which inhabited the area.  Your vehicle can land on these platforms to recharge, and they are the only objects which it
+is safe to come into contact with.
 
 Background
 ==========
 
+You may remember Jet Set Willy from many years ago.  It was a 2D platform game in which you guided a little character
+around a huge maze of different rooms, dodging obstacles and finding secret passages while collecting little flashing
+debris from all over the game's abstract world.
+
 In the mid 90s, I played a game from a magazine cover disk (Archimedes World I think, but I really can't remember)
 called "Lander".  No, not the demo version of Zarch, this was a completely different game where you piloted a small 2D
 spaceship round a vast world collecting glowing radioactive debris from over a hundred separate rooms.  The spaceship
 part was just like the many Lunar Lander variants you have probably played, but the exploration of a vast world appealed
 to me for the same reasons that I enjoyed Jet Set Willy many years before.  In Lander, just like in Jet Set Willy. the
 game would theoretically end when all the debris had been collected.  In practice, this was virtually impossible due to
-the shear size and complexity of the game.  The attraction of the game was not in winning it, but in being able to
+the sheer size and complexity of the game.  The attraction of the game was not in winning it, but in being able to
 explore a seemingly never-ending world of pure imagination.
 
 In creating Thrust3D I wanted to recreate that feeling of exploration and imagination, but using the capabilities of
@@ -32,37 +47,52 @@ Installation
 
 For installation details, see the 'INSTALL' file.  Basically it's just the usual ./configure / make / sudo make install.
 
+3D Graphics Acceleration
+========================
+
 You will almost certainly need working 3D acceleration (direct rendering) and a vaguely modern graphics card to play
 Thrust3D smoothly.  To see if you have this, run 'glxinfo' in a terminal and see if it says 'direct rendering: yes' or
 not.  If not, you most likely need to install 3D drivers for your graphics card.  Linux drivers for NVIDIA and ATI cards
 come from the respective manufacturers' websites.  For Intel cards, look up the Linux DRI project.  Drivers might be
 included in your distribution.
 
-Thrust3D runs at full speed, but only just, on my ATI Mobility Radeon X600 card.  This is the primary development
-system.  It also works fine on my NVIDIA Quadro FX540.  Both of these are 'entry-level' cards with fairly comparable
-specifications.  If you have something beefier, great - it'll probably munch this for breakfast.  If not, you can still
-play - you might just need to disable a few features (if that doesn't happen automatically): see the output from
-'thrust3d --help' for details of things you can disable.  You should also try turning the resolution down (for example,
-'thrust3d --resolution 640').
+Thrust3D runs at full speed, but only just (about 18 frames per second), on my ATI Mobility Radeon X600 card.  This is
+the primary development system.  It also works fine on my NVIDIA Quadro FX540.  Both of these are 'entry-level' cards
+with fairly comparable specifications.  If you have something beefier, great - it'll probably munch this for breakfast.
+If you have a lower spec card, you can still play:  If Thrust3D detects that a certain OpenGL feature isn't available,
+it should disable its use and fall back gracefully.  You may need to turn the resolution down (for example, by starting
+the game from a command prompt with 'thrust3d --resolution 640') to get smooth play from a low-end card.   You might
+also need to disable certain OpenGL features manually if the card advertises things which it technically supports but
+whose implementation causes trouble: see the output from 'thrust3d --help' for details of things you can disable and
+experiment until it works.
 
 Music
 =====
 
 You can put some suitable background music as an Ogg/Vorbis file at $PREFIX/share/thrust3d/sounds/music.ogg ('$PREFIX'
-is probably '/usr/local' unless you've done something different).  'Radioactivity' by Kraftwerk is particularly
-appropriate. Obviously I can't distribute a copy of that material with the game, so you'll have to obtain your own copy.
+is probably '/usr/local' unless you've done something different when you typed ./configure.  If you don't know what
+this means, don't worry).  'Radioactivity' by Kraftwerk is particularly appropriate. Obviously I can't distribute a copy
+of that material with the game, so you'll have to obtain your own copy.
 
 Controls
 ========
 
-	Space       - thrust (upwards)
-	  or: Mouse button 1 (usually the left button)
-	Left arrow  - turn left
-	Right arrow - turn right
-	Up arrow    - thrust forwards
-	Down arrow  - thrust backwards
-	Mouse       - change viewing angle (press 'r' to reset to default)
-	
-	'w'         - enter wireframe mode (this is not useful)
-	'e'         - exit wireframe mode
+	Space          - thrust upwards
+	Left arrow     - turn left
+	Right arrow    - turn right
+	Up arrow       - thrust forwards
+	Down arrow     - thrust backwards
+	Mouse          - change viewing angle (press 'r' to reset to default)
+	Mouse button 1 - thrust upwards
+	'w'            - enter wireframe mode (this is not useful)
+	'e'            - exit wireframe mode
+
+"Mouse button 1" is usually the left mouse button, unless you're left-handed like me.  Controlling the view direction
+and vertical thrust with the left hand while controlling the lateral motion on the keyboard with the right hand works
+very nicely with a left-handed trackball setup like mine.
+
+Feedback?
+=========
+
+I'm keen to hear what you think of this game.  Email me on taw27@srcf.ucam.org.