 _________  ____  ____  _  ___  Original by Neil Raine
(  _   _  )(  ) )(  ) )(_)(  _) Updated by Martin    ___
( ) ( ) ( )( O  )( O  ) _ ( )_             Bazley   ( __)
(_)_(_)_(_)(__)_)(__) )(_)(___)_  ___  ___  ________(_  )
(  _   _  )( )( )(____)( )__(  _)(   )(   )(  _   _  )( )
( ) ( ) ( )( )( )( ___)(    ) )  ( O )( O )( ) ( ) ( )( )
(_) (_) (_)(____)(___ )(_)(_)_)  (___)(___)(_) (_)_(_)( )
               (______)                            (____)

This text is best viewed at a wrapwidth of 77 columns.
For interactive contents, do a 'List of Found' search for '==='.

StrongED$WrapWidth = 77

_____________________________________________________________________________

=== 1 == Introduction ==

I know nothing at all about the history of the original Magic Mushrooms game
- just that I loved playing it.  Unfortunately, due to the nature of the
program, doing so required a BBC, something increasingly hard to come by.

Not that my writing this program had much to do with an unsatisfied craving
- after all, the original game is available for download from
stairwaytohell.com, and I have a working copy of BeebIt - but it was a nice
little project and it's kept me happy for the past two weeks or so.

_____________________________________________________________________________

=== 2 == Playing the game ==

=== 2.1 == Starting up ==

When you double-click on the !MagicMush icon, an icon will appear on the icon
bar.  It will stay there until you choose 'Quit' from its menu.

If you don't have TimPlayer installed, you will see a warning message.  You
can still play the game, but it will be completely silent.  You can download
TimPlayer from <http://www.riscos-digitalcd.net/>.

To play the game, click Select on this icon (or on 'Play game' from the
menu).

Of the other options on the menu, 'Help...' will display this help file,
'Editor...' will open the editor windows for you to design your own levels
(see section 3), and 'Music' and 'Sound' can be clicked to toggle whether
the game starts up with music playing and sound effects enabled respectively.

=== 2.2 == Movement ==

Well, it's a platform game.  Hopefully movement should be obvious.  These are
the keys you will need:

Z       Left
X       Right
Return  Jump
P       Pause/unpause
M       Toggle music
S       Toggle sound effects
Escape  Quit

The initial state (enabled or disabled) of music and sound effects can be
chosen from the application's icon bar menu.  Note that if TimPlayer is not
installed, neither option will have any effect.

=== 2.3 == Special blocks ==

Watch out for the following blocks (and inhabitants):

CONVEYORS will shift you left, right, up or down.  You can't escape from the
vertical ones.
ICE will cause you to skid, making it impossible to turn round or stop moving
until you reach the end.
MUSHROOMS can be picked up.  You would be well advised to do so, because
you're not allowed to leave the level until you've got them all.
GOALS take you to the next level, if all mushrooms have been collected.
SHAKING BLOCKS will jiggle you about.
99 BLOCKS will reset your time limit.  Yes, there's a time limit.
TRAMPOLINES cause you to jump higher.  Watch out - they can cause you to jump
higher than you can survive falling.
CRACKED BLOCKS disappear when walked over.
MONSTERS can move about and will kill on contact, but fortunately are
extremely stupid.

=== 2.4 == The object of the game ==

Basically, collect all the mushrooms on each level, walk over a goal and
don't die.  You can die by running out of time, running over a
monster, falling too far or falling off the bottom of the level.  Currently
the most you can survive falling is three and a half blocks - the extra half
block is to making shaking blocks slightly less fatal.

_____________________________________________________________________________

=== 3 == Custom levels ==

=== 3.1 == Level sets ==

The default level set used by the game is in the 'Levels' subdirectory inside
the application directory (hold down Shift and double-click on the !MagicMush
icon).  This illustrates the basic structure of a level set.

Each level is a data file, with a special leafname - no more or less than
three characters, with each character being a number.  For example, '001',
'002', '156' and '999' are valid level names, but '3', '1024' and 'MyLevel'
are not.  Any levels which have appropriate names are played through in
numerical order (note that the numbers don't necessarily have to be
consecutive).

There should also be at least one sprite file in the directory - this may be
called anything.

To load a new set of levels, simply drag its directory to the game icon on
the icon bar.

Note that the default level set must never be renamed or otherwise altered in
any way.

=== 3.2 == Designing your own levels ==

If you choose 'Editor...' from the icon bar menu or click Adjust on the icon,
two windows will appear.  The large, and initially blank, one is the level
display, and the smaller one is the toolbox.

Like the game, the editor is fairly self-explanatory.  Select items in the
toolbox by clicking on them, and clicking on the other window will plot the
currently selected tile at the mouse pointer.  Adjust rubs out blocks.  It
works almost exactly like Paint, but with fewer features.

To change the name of the level, type the new name in the writable field at
the top of the toolbox.  Pictures selected in the toolbox will bring up a
display at the bottom telling you what they are.

To save your masterpiece, click Menu over the editor window and go to Save.
This brings up a standard RISC OS save box, from which you can choose a name
for your level (don't forget the three-digits rule, above) and drag it to a
directory of your choice.

To load an existing level, drag the file to any Magic Mushrooms window or
icon.  It will be assumed to be contained in a standard level directory, so
if the graphics set referred to in the level data isn't present in the same
directory, the editor will complain and revert to the default graphics.

When the level is saved, its graphics set will be saved with it, to the same
location (unless another file of the same name as the graphics already exists
- watch out for that).  This doesn't apply if you save to another
application, and equally the editor won't bother searching for graphics
accompanying files dragged in from other applications.

The current levels directory may be opened by clicking on 'Levels...' from
the same menu.

=== 3.3 == Alternative graphics ==

Magic Mushrooms graphics sets, while in sprite file format, have a very
particular structure (detailed in section 4.2).

To load a new graphics set, simply drag the file onto the editor window or
the icon bar icon.  Assuming it's valid, the level currently being edited
will have its graphics set redefined to point to the one just loaded, and the
set just loaded will be what is saved with the level.

Whenever a new level is loaded, its graphics are loaded at the same time.
You will be alerted if they couldn't be found or have become invalid.

There is, of course, only one set (the default set) of graphics supplied.
Why not design your own?

The file '!MagicMush.Levels.MushSpr' must never be renamed or otherwise
altered in any way.

=== 3.4 == Testing ==

If, as is so common, having designed your masterpiece, you want to test it,
there's an easy way to do so.  Click Menu over the editor window and select
'Test'.  The level will be loaded instantly into the main game, skipping the
title screen and exiting when you complete it or lose all your lives.  This
even works without saving the level first.  Nifty, eh?

The game detects whether it was launched for testing purposes by checking for
the existence of a file called 'Test' in the current level directory.  Saving
files under that name is discouraged for this reason.

=== 3.5 == Blank levels ==

The other item on the edit menu is marked 'Clear'.  This will set all of the
blocks in the level to empty space.  The currently loaded graphics set will
be preserved.  Handy when you want to design more than one completely new
level at once.

_____________________________________________________________________________

=== 4 == Technical details ==

=== 4.1 == Level format ==

Offset  Length  Contents
------  ------  -------------------------------------------------------------
0       x       LF-terminated name.
x       y       LF-terminated sprite leafname - graphics set of this level,
                looked for in the current levels directory.
x+y     280     Starting from the top left and working across, one byte per
                block of level data.  Level width is 20 and height is 14.
                The hex value of each byte corresponds to a sprite in the
                sprite file referred to at x.

=== 4.2 == Sprite file format ==

The following sprites are all 40 x 40 pixels at 90 x 90 dpi and 256 colours.
None of them must have masks, except c0.

Name  Purpose
----  -----------------------------------------------------------------------
0     Empty space.
1     Mushroom.  Plotted randomly by game.  Do not attempt to place them
      manually.
11    Right conveyor, frame 1.
12    Frame 2.
13    Frame 3.
14    Frame 4.
21    Left conveyor, frame 1.
22    Frame 2.
23    Frame 3.
24    Frame 4.
30    Starting position.  Never plotted by game - for editor's purposes only.
40    Ice.
50    Normal block.
60    End position.
71    Shaking block, frame 1.
72    Frame 2.
73    Frame 3.
74    Frame 4.
81    '99' block, unused.
82    '99' block, used.  You *could* place these manually if you wanted to -
      but why?
90    Trampoline.
a1    Up conveyor, frame 1.
a2    Frame 2.
a3    Frame 3.
a4    Frame 4.
b1    Down conveyor, frame 1.
b2    Frame 2.
b3    Frame 3.
b4    Frame 4.
c0    Monster.  Note: must have mask.
d0    Normal block.  By default, this sprite represents the left half of a
      block.
e0    Normal block, or right half.
f0    Disappearing block.

The other five sprites are all 40 x 80 with masks.  Note: There is no play3.

Name   Purpose
-----  ----------------------------------------------------------------------
play0  Player going left, frame 1.
play1  Frame 2.
play2  Player standing still.
play4  Player going right, frame 1.
play5  Frame 2.

_____________________________________________________________________________

=== 5 == Version history ==

=== Version 1.00 == 28th January 2009 ==

   First version.

=== Version 1.01 == 11th February 2009 ==

   Fixed nasty bug which wrote to protected areas of memory!
   Many refinements to mode setting - shouldn't flicker any more.
   Changed default value of map handle for consistency.
   Rearranged several sections of the program.
   Increased instrument polyphony from 2 to 4.
   Refined screen bank swapping, the only obvious consequence of which is
    the correct frame now being frozen at the end of a level.
   Added pause facility.
   Fixed end position bug on level 4.
   Added 99 block on level 6, which was previously impossible from some
    start positions.
   Fixed bug in editor discard window.
   Made the editor's loading a bit more robust.
   Remembered to update save menu when loading numbered levels.

=== Version 1.02 == 21st February 2009 ==

   Updated TimPlayer, thus (hopefully) fixing the last remaining
    compatibility issue.
   Improved error handler, which could get into an infinite loop.
   Yet more screen bank improvements (RO4/6 only).
   Various other things I forgot.

=== Version 1.10 == 13th December 2009 ==

   Significant internal reorganisation.  The program now installs itself
    onto the icon bar, and clicking Select on the icon launches the game.
    Clicking Adjust opens the editor windows.
   Added support for external level directories.
   Sprite files are now kept in the level directories which refer to them.
    The 'Sprites' subdirectory has gone.
   Fixed player animation oddities on conveyors.
   Internationalised application.
   Replaced weird editor save function with a conventional save box.
   Added interactive help on the menus.
   Added a 'Save' option to the unsaved level confirmation dialogue box.
   The 'Clear' option no longer resets the graphics set.
   Music and sound effects can now be turned off.  The 'P' key now unpauses
    as well.
   A banner is now displayed to make it more obvious when the game is
    paused.
   The time alert now sounds (fairly) continuously rather than just once at
    ten seconds left.
   Various editor functionalities concerning level names and filenames
    switched around.
   This program is now distributed according to the terms of the GNU General
    Public License, version 3.

=== Version 1.11 == 3rd January 2011 ==

   No longer distributed with (outdated version of) TimPlayer, but looks in
    !System like everyone else does.
   Fixed probably rather horrible bug when desktop screen mode was numeric.

=== Version 1.12 == 19th July 2012 ==

   No longer attempts to change back to the desktop screen mode on exit.
    Not only was it pointless, it was broken.
   Hopefully fixed the long-running glitches with disappearing blocks by
    rewriting the code in a more sensible way.
   Stress-tested all levels by forcing mushrooms to be placed in every spot,
    and altered levels 7 and 10 in light of this.
   Some considerable internal refactoring of the editor.
   Now saves test levels to Scrap instead of its own application directory.
    What the hell was I thinking?
   Removed all ingame occurrences of references to a fixed location for the
    'Test' file.  Bafflingly, not all references to 'Test' were broken in
    this way - there was a defined mechanism for specifying the location,
    which the editor was using and at least some of the game was obeying.
    Again, I can only ask: what the hell was I thinking?
   Sanitised the frankly braindead implementation of the Data Transfer
    Protocol.  As in, it now works at all.
   Greatly increased intelligence about how to load sprite files along with
    levels - including when not to try.
   Editor uses a filled icon background instead of removing the mask from
    the monster sprite.
   Thanks to the above, the sprite data is now not changed after loading,
    which means it can be saved with the level properly instead of the
    ridiculous and unsafe workaround of remembering the location it was
    originally loaded from and attempting to copy it.
   Although it does mean it can't retain the currently loaded graphics set
    when attempting to load a faulty one, so it has to revert to the default
    instead.
   Tightened up restrictions on use of the Menu button.  In particular, you
    can't Menu-drag out of the save box any more!
   Fixed potentially nasty bug where a variable wasn't set up as early as it
    should have been.

=== Version 1.13 == 7th August 2012 ==

   Worked around crashes on RISC OS 3.7 by changing the editor to load its
    sprites into a dynamic area instead of application space.
   Ensure that enough memory for two screen banks is allocated, fixing
    flickering problems on old machines.
   Now works if TimPlayer isn't installed, by disabling all sound.
   Added options to disable sound effects and/or music on startup.
   Toggling whether music or sound effects are playing in-game won't freeze
    the player any more.
   Completely overhauled initialisation of the game, which is now much safer
    and more reliable.
   If the game terminates, the screen and VDU state will be reset, enabling
    the error message to be read - thus reversing an accidental side-effect
    of a change in version 1.12.
   Corrected very wrong limit checking on data blocks.
   Should behave more nicely if there is unsaved data on desktop shutdown.
   Greatly increased speed of loading new graphics sets into the editor.
   Made the editor's level loading slightly more robust.

_____________________________________________________________________________

=== 6 == The boring bits ==

=== 6.1 == Thanks and credits ==

*****************************************************************************
*** This program is dedicated to Neil Raine, author of 'Magic Mushrooms'  ***
*** for the BBC and of parts of RISC OS, who died in a hang glider crash  ***
*** at Ontur aerodrome, Spain, on March 15 2006.                          ***
*****************************************************************************

The game code was written, and the graphics designed, by Martin Bazley.  The
music was remixed by one 'Holger K.' and played with TimPlayer by Andr
Timmermans.  The samples were mostly supplied with Digital Symphony by BASS.
Playtesting and bugfixing was done by Christopher Bazley.  The ResFind
program used to located resources was written by Olaf Krumnow and Herbert
zur Nedden of the German Archimedes Group (GAG).

=== 6.2 == Legal stuff ==

This program is free software: you can redistribute it and/or modify it under
the terms of the GNU General Public License as published by the Free Software
Foundation, either version 3 of the License, or (at your option) any later
version.

This program is distributed in the hope that it will be useful, but WITHOUT
ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
FOR A PARTICULAR PURPOSE.  See the GNU General Public License for more
details.

You should have received a copy of the GNU General Public License along with
this program.  If not, see <http://www.gnu.org/licenses/>.

The application name MagicMush has been officially registered with RISC OS
Open Ltd.

If you're going to review or mirror this program, I'd appreciate knowing
about it!  (Especially if you're going to give it a good review. :-) )

=== 6.3 == Contact ==

My email address may have compliments and (hopefully no) bug reports sent to
it - please exploit this misfeature as far as possible.

 mailto:martin@bazleyfamily.co.uk

Alternatively, if you wish to send letter-bombs or other more substantial
items, my snail mail address is:

 Martin Bazley
 Flat 8
 349 North End Road
 Fulham
 London
 SW6 1NN
 ENGLAND

=== 6.4 == And finally... ==

Do you like talented drawings?  Do you like high-quality photography?  Do you
like regular updates?  Then you'll hate
<http://swirlythingy.deviantart.com/> with a passion, but on the off-chance
you have a particular fascination with what I do in my spare time, do pop
along.

Furthermore, until such time as the dotcom bubble bursts and the fact that
it's never turned a profit catches up with it, you can follow me on Twitter
at <http://twitter.com/swirlythingy> - contains 110% of your RDA of sweary
political rants and dull nerdish musings on computers and comics alike.
Proud not to be an Official Sponsor of the London 2012 Olympic Games!

And should you wish to enjoy more such piffle as this, as well as rather
higher-quality output from other members of the Bazley family, visit
<http://www.starfighter.acornarcade.com/mysite> for RISC OS software (by
everyone), Doom levels (by me and Chris) and digital music (by me).

Thanks for downloading Magic Mushrooms!

_____________________________________________________________________________
Martin Bazley
7th August 2012

=== End