MANIC MINER SCREEN EDITOR 1.0.1 (C) BROADSOFT 2003
===============================

For the Sinclair ZX Spectrum +2

Written by Andrew Broad
http://www.geocities.com/andrewbroad/


Introduction
------------

The Manic Miner Screen Editor (MMSE) is a program which allows you to redefine
the rooms in Matthew Smith's classic Manic Miner, which I acknowledge as being
the copyright of Bug-Byte (1983) - owned by Jester Interactive since 2001. It is
superior to any of the MM editors hitherto released on the Internet, because it
allows rooms to be edited in ways that were not possible using those, such as
the colour-schemes and the paths of the guardians and probably much more
besides, as is apparent with all MM rewrites written by people other than me up
to this point.

I used MMSE (in its earlier, unreleased incarnations) to create my games Manic
Miner: The Buddha Of Suburbia and Manic Miner 4 on a real Spectrum +2.

A million thanks go to Richard Hallas for rescuing the Spectrum files from audio
cassette and converting them to TAP files, as well as for writing the fabulous
Join The Jet-Set! and Jet-Set Willy In Space :-)


Loading Instructions
--------------------

To use the Manic Miner Screen Editor, you need a Spectrum emulator that is
capable of loading TAP files (I hope I'm right in thinking that the emulators
you all use are capable of loading TAP files, as I don't want to complicate
matters by also releasing snapshot files). To find an emulator for your
particular computer, see the Emulators section of the comp.sys.sinclair FAQ
[http://www.srcf.ucam.org/~pak21/cssfaq/emulator.html].

A TAP file is an encoding of the files on a Spectrum tape (as opposed to a
snapshot file, which is an encoding of the complete state of a Spectrum at the
moment it was created). To load from a TAP file, you have to issue a load-
command to the emulated Spectrum (i.e. select Tape Loader or type LOAD "" (in
48K mode, press J for LOAD and SYMBOL-SHIFT+P for ")). You also have to open the
TAP file in the emulator (either before or after issuing the loading
instruction).


MMSE.TAP
--------

This TAP file contains the Manic Miner Screen Editor itself, which was written
in 128 BASIC on a Spectrum +2 as a series of programs which save themselves onto
and load each other from the silicon disc.

The main idiosyncrasy of MMSE is that it uses files in a 20K format to store
Manic Miner rooms - 20480 bytes, from memory addresses 45056 to 65535. Such a
file containing the original Manic Miner caverns have been appended to this TAP
file. I have written a little utility called MM Loader to help you convert from
and to the standard 32K Manic Miner file format. MM Loader is also included in
this zip archive (see the section "MMLOADER.TAP" below).

When MMSE is loaded, it prompts you to load a 20K room-file. A 20K file of the
original MM rooms follows on MMSE.TAP for convenience.

I have not had time to write a proper user-guide for MMSE, but I have written
the user-interface to be as self-explanatory as possible, so you should get on
okay with it once you understand what redefining a Manic Miner room entails. In
a nutshell, MMSE operates in a screen-layout editor which allows you to place
blocks on the screen, with all the other options accessible from a menu system
which you get into by pressing `9' from here. You can save your work or switch
to editing another room by pressing `0' on the screen-layout editor.

When you place a block on the screen-layout, it is encoded as a colour-
attribute. Colour-attributes are associated with block-types in the block-
graphics section (press `9' on the screen-layout, then select `2' from the
menu). When you change the colour-attribute of a block-type, all occurrences on
the screen-layout are updated accordingly. So if you give a block-type the same
colour-attribute as another block-type, all blocks of that type in the screen-
layout will be merged. MMSE warns you when this would happen, and gives you the
option of not updating the screen-layout, in which case you'll have to sort it
out manually.

Please note that you can have as many conveyor-blocks in the screen-layout as
you want, but the conveyor-animation is controlled separately (press `9' on the
screen-layout, then select `4' from the menu). The conveyor-animation is a row
of characters that are animated, and they don't necessarily have to be conveyor-
blocks.

I suggest downloading my Manic Miner Room-Format from
http://www.geocities.com/andrewbroad/spectrum/willy/mm_format.html, because in
addition to lots of technical details (which you can filter out, because that's
what MMSE takes care of for you), it contains lots of useful tips for designing
rooms, which I would have included in a user-guide if I'd written one!


Known Bugs
----------

I spent a lot of time in 1998 hacking MMSE into a form where it is as user-
friendly as possible to people other than myself, and to eliminate all the bugs
I could, but it is still possible you may have problems...

Because MMSE is a 128K program, this is likely to cause problems with certain
emulators (MacSpectacle 1.8.2 for one) that do not seem to handle this
architecture properly, silicon-disk operations in particular. When I tried to
run MMSE on my emulator, it was not saving the programs to silicon disk
properly, and I got reports such as "b Wrong file type", not to mention that
MMSE runs very slowly on MacSpectacle! But these are faults of the emulator, not
of the program itself, which works fine on a real Spectrum.

An esoteric quirk which I have never been able to get to the bottom of is that
sometimes when you're editing an 8x8 graphics sprite, the program breaks with a
"2 Variable not found" report, even though when I go through all the variables
at the line referred to in the report, they have all been initialised. If this
happens, you should be able to recover by issuing a GO TO 40 (if I remember
rightly) command.

Another bug that occasionally crops up is that the 16x16 graphic editor breaks
with a "C Nonsense in BASIC" report, because MMSE has somehow poked over the
program space and taken out a colon or something! It is also possible for MMSE
to do this to screen-layouts, resulting in an ill-defined blob (typically in the
top row of Room 15), but this bug has never caused me a serious problem in
practice.

The screen-layout editor sometimes used to crash the Spectrum, but this hasn't
happened to me for ages, so it may be that my hacking somehow removed this nasty
bug, I'm not quite sure how! ;-)


MMLOADER.TAP
------------

As mentioned earlier, MMSE insists on using 20K files of Manic Miner rooms,
which are fine for editing but not to play, as it needs the program code which
resides from 32768 to 45055 to do that!

So I have written a little utility called MM Loader that loads in the 12K that
is not stored in MMSE files, followed by a 20K file or a 32K file of your
choice. You can then either play the game, or save a 20K or 32K file, which
gives you a way of converting from one to the other format (32K to 20K for
loading into MMSE, or 20K to 32K to create a stand-alone MM game).

MMSE does not allow you to edit the lower 12K (addresses 32768 to 45055) - that
is beyond its scope - but you could edit this part by other means, save that as
a 32K file, and load a 20K file that you have edited using MMSE on top of that.


Instructions for using MMSE in RealSpec
---------------------------------------

This section, written by Nigel Fishwick (Fishyfish), explains how to use the
Manic Miner Screen Editor under the RealSpec emulator.

> Load RealSpec (obtained from: http://www.ramsoft.bbk.org/)
> 
> Press F7 to choose the correct file, and then load the Manic Miner
> Screen Editor
> 
> If starting afresh, press enter to access the pre-loaded Manic Miner
> data. Select the screen you wish to edit and begin work!
> 
> To load a 'work in progress', type the name of your file (without
> extension) into the editor, then press F7 and select the file from where
> it is stored on your computer. Press enter and then select the room you
> wish to edit.
> 
> To save a 'work in progress', use the options in the editor to save
> progress and type in a filename (without extension). Press Alt & F7 and
> select "Open Tape for Saving". Enter the same filename as used in the
> editor and select "tzx" as the filetype. Press Enter and then press Ctrl
> & F7 to start the virtual tape. Press enter in the editor followed by
> any key to save the file. When asked if you wish to verify, press Ctrl &
> F7 again to stop the tape and then Alt & F7 to close the tape ypu
> opened. Your file is now saved and can be reloaded next time you use the
> editor.
> 
> 
> To test your work, reset the emulator (Alt & F2) and then press F7 to
> select the Manic Miner Loader for loading into the emulator.
> 
> Press 1 to load your saved file, and type in the filename (without
> extension). Then press F7 and select your file from where you saved it.
> Press enter in the Loader tool and then press 5 to play your levels!


Internet
--------

I currently have a website at http://www.geocities.com/andrewbroad/. Some
relevant pages within this website are:

* http://www.geocities.com/andrewbroad/spectrum/
Top-level index of my Spectrum pages.

* http://www.geocities.com/andrewbroad/spectrum/willy/
My Manic Miner/Jet Set Willy pages, including a list of Spectrum MM/JSW games
(which I try to maintain as complete and up-to-date as possible - please inform
me of any I have missed), various other MM/JSW documents, and links to other
MM/JSW websites.

* http://www.geocities.com/andrewbroad/spectrum/download/
My download page. Currently contains my other games, my Jet Set Willy
Construction Kit, and my Java toolkit SPECSAISIE. Also has previews of
forthcoming software (mostly MM/JSW games).

I founded a Yahoo! Group for Manic Miner and Jet Set Willy. Its URL is:-
http://groups.yahoo.com/group/manicminerandjetsetwilly/
It includes a message-board for discussing MM/JSW, picture galleries which
members can upload to, a bookmarks page and a calendar. Anyone can visit the
Group and look around its public areas, but for full privileges you have to join
the Group as a member. This prerequires signing up for a Yahoo! account, which
you can do, free of charge, over the Web. I encourage all members of the MM/JSW
community to join the Group.

I recommend the comp.sys.sinclair USENET newsgroup as a place for discussing
MM/JSW and other Spectrum-related topics. It's worth at least browsing through
the headers each day (says he who has long since lost touch with USENET :-o ).
The newsgroup is archived at http://groups.google.com/ for those who don't have
access to a news-server - in fact, it's worth surfing there even if you do, as
not all news-servers receive all newsgroup postings! http://www.mailandnews.com/
(a free Web-based email-service) also provides access to newsgroups over the
Web.


Copyright Notice
----------------

Manic Miner Screen Editor is, of course, my copyright, but I don't mind you
putting it on your own website or redistributing it otherwise, provided that no
money is charged, and that you acknowledge that it is the copyright of Broadsoft
(1998). This document must be included with all copies of the game.
Modifications are discouraged but not forbidden, and you should state
specifically what you have modified.

Please let me know if you do put MMSE on your website or use it to create a game
- it's not that I'd have any objections, I'd just be very interested to know
what follows from releasing my editor! If you use it to create a game, an
acknowledgement would be nice! :-)


Version History
---------------

23rd April 1998: Initial release of Manic Miner Screen Editor on the Internet.
This version of MMSE shall be retrospectively referred to as 1.0. Though I'd
never heard of her at the time, this was Daniela Hantuchov's 15th birthday! :-)

30th November 2002: Manic Miner Screen Editor reissued with PC-sympathetic
newlines, updated Internet section and copyright notice, and various other
changes to the documentation. The TAP file is completely unchanged.

7th July 2003: Manic Miner Screen Editor 1.0.1 released (seeing as I've just
opened my new website, now seems as good a time as any to slap on a version-
number). The only change to the program is that it no longer allows the user to
specify an air-supply ending in 11111100, as this causes the Spectrum to lock up
when you enter the portal.

If you release your own version of MMSE, please do not increment the version-
number I've given it, but start a separate branch. For example, if your name is
Matthew Smith then you might call it version 1.0.1M or something - do not call
it version 2.0, 1.1 or 1.0.2, because that's what I would call my next version
(depending on whether the changes are major or minor). My versions shall be
considered the definitive ones, and I make no promises to incorporate other
people's changes.


Future work:

* Machine-code routine to draw the screen-layout much faster.

* Improved user-interface - more interactive, rather than inputting a sequence
of values.

* Replacing the graphics-editors with the superior ones from JSW CK.

* Detect the Block-Graphics Bug.

* Filling a whole row or column of background/floor/wall/nasty at once.

* Copying a room to another room, or exchanging two rooms.

* Saving/loading an individual room.

* Support for John Elliott's MM patch:
- preserve the top 5 bits of Offset 627 when changing the border-colour;
- allow user to edit vertical guardians and Skylabs in rooms where the patch
enables them.

* Editing the general setup (scrolly message, title-screen picture, Miner Willy
sprites, &c.).

* Music editor (for the in-game music and the title-screen music). You write the
tunes by pressing a key for each note, which plays that note, and you can also
have it play the whole tune. It will allow variable-length and super-long
combined melodies (see Richard Hallas' music document
[http://www.geocities.com/andrewbroad/spectrum/willy/music.html]). It may also
have extra bells-and-whistles such as reversing the tune (as in "Move On" from
David Bowie's Lodger album, which features "All The Young Dudes" played
backwards), or playing the tune upside-down (as in Mike Oldfield's Tubular
Bells, which features Bach's Toccata played "upside-down", though I'm not sure
exactly how you turn a tune upside down! ;-) ).
