Advanced MM/JSW Trainer (C) BROADSOFT 2006
======================= [v0.1.0 - please do not spread the beta-revisions]

For the Sinclair ZX Spectrum 128K

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

<x This document is a draft which contains comments. x>

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

Quirky features are the magic of MM/JSW for me, and yet their deliberate exploitation has proved to be off-putting when MM/JSW games are introduced to the wider Spectrum community.

What the scene needs, IMO, is a game to demonstrate quirky features in their minimal forms, to train the lay player in the more arcane aspects of game-mechanics. That is the goal of Advanced MM/JSW Trainer.

--------
The Game
--------

Advanced MM/JSW Trainer is a redefinition of the rooms, items, guardians and graphics in Matthew Smith's classic Manic Miner and Jet Set Willy, which I acknowledge as being the copyright of Bug-Byte (1983) and Software Projects (1984) respectively.

The main game is based on John Elliott's JSW64 {Hacklevel 12; Variant V}, and there are 48K JSW and MM annexes to cover those features which are not applicable to JSW64.

Advanced MM/JSW Trainer is written for JSW players who wish to learn all the ins and outs of the game-engine - the so-called quirky features that I deliberately exploit in my MM/JSW games.

My goal is to make this game as self-explanatory as possible; however, my Quirky Features document may prove to be a useful reference:
http://geocities.com/andrewbroad/spectrum/willy/features.html

And a blow-by-blow description of each room can be found in:
* ROOMS_JSW64.TXT: the JSW64 main game;
<x * ROOMS_JSW48.TXT: the 48K JSW annex; x>
<x * ROOMS_MM48.TXT: the 48K MM annex. x>

I have tried to be fair by keeping infinite-death scenarios to a minimum. You shouldn't encounter infinite death unless you do something really stupid, such as jumping into an unfamiliar room when you should be walking into it.

<x I have thoroughly play-tested the final revision, and I certify that it /is/ possible to complete. x>

You can consider yourself to have passed Advanced MM/JSW Trainer if you finish the game by saving and loading snapshots on an emulator. Infinite lives are provided as an option in the BASIC loader. If you cheat by using any other POKEs, or by using WRITETYPER, you should consider yourself disqualified. ;-)

-----------------
Design-Principles
-----------------

The game shall be divided into various categories, with a cluster of rooms for each category, and a teleporter to each category from the start-room ("Main menu" [0]).

All room-connections shall be two-way, and will probably all be teleporters (except for the inter-room features), and the teleporters in each room shall be close together. This is to allow the selective user to navigate as quickly as possible from the start-room to the room (s)he wants.

Each teleporter shall not be invisible, but shall be marked with a thing-like-a-portal-sprite (technically four cells, two switch-guardians, or two stationary guardians with a harmless-guardian patch-vector) that shall give a visual clue to its destination (e.g. a picture of an Earth-cell for the Earth-cells trainer).

The teleporters shall be coloured as follows:
* bright yellow: unvisited
* dull cyan: visited
<x bright magenta: leads to rooms which have been edited since the previous revision (beta-releases only) x>

When entering a room, the room-setup patch-vector recolours the teleporter that led to it dull cyan (see TECHNICA.TXT).

Cell-graphics shall be the same in every room, and the game will also serve as a source of screenshots for my Quirky Features page:
http://geocities.com/andrewbroad/spectrum/willy/features.html

The cells' PAPER-colours shall alternate between black and blue in a chessboard-pattern throughout the whole game, to facilitate counting the number of Air-cells. Rather than having twice the number of cell-classes per room, I have written a patch to achieve this (see TECHNICA.TXT), applicable to JSW64, JSW48, MM48 and hopefully even JSW II. The user is given the option to enable or disable this patch in the BASIC loader, along with infinite lives.

For each feature that does /not/ apply to all game-engines, the room for that feature shall display an indicator (implemented as a stationary guardian, probably a switch) for each game-engine to which it /does/ apply. Each such indicator shall be one of the following: 
* MM: applicable to the Manic Miner game-engine; 
* JSW48: applicable to the original, unpatched 48K Jet Set Willy game-engine; 
* JSW128: applicable to the highest hacklevel of the JSW128 game-engine; 
* JSW64: applicable to the highest hacklevel of the JSW64 game-engines (any of the six variants); 
* JSW: applicable to all the Jet Set Willy game-engines (JSW48, JSW128 and JSW64). 

A game-engine indicator (or the lack of one) does /not/ mean that the room would convert perfectly to (all) the game-engine(s) specified - only that the essential features of the room are applicable to those game-engine(s).

JSW II is not covered by the above indicators, because its game-mechanics are radically different. Thus the lack of an indicator, or the JSW indicator, does /not/ mean that a feature is applicable to JSW II.

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

To play Advanced MM/JSW Trainer, 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 load-command).

Advanced MM/JSW Trainer consists of the following TAP-files:
* JSW64.TAP: the JSW64 main game;
* JSW48.TAP: the 48K JSW annex;
* MM48.TAP: the 48K MM annex.

Please note that JSW64.TAP has to load the last file on the tape /after/ the options-screen in the BASIC loader, so it's no use saving a snapshot on the options-screen (as you can in all my non-JSW64 games). I had to do this because the last file (the title-screen tune) has to be loaded into video-RAM.

----------------
Acknowledgements
----------------

* Matthew Smith, for writing the original Jet Set Willy, and in particular for deciding on an unencrypted, perspicuous room-format! ;-)

* This game was written using John Elliott's JSWED (v2.3.1), and playtested using Ramsoft's RealSpectrum v0.97.23.

* John Elliott again, for the JSW64 family of game-engines, and also for his invaluable disassemblies of MM and JSW, and his description of the JSW128/64 music-format.

* My fellow MM/JSW authors, for general inspiration, and some specific tricks (sometimes unintended on their part, but deliberately exploited by me! ;-) ).

* Richard Hallas's document "A Miner Triad" was an invaluable aid to redefining the music (I wrote the tunes in 48K format, then used my own program SPECSAISIE JSWtoJSW128Tunes to convert them to 128K).

* The in-game tune is "Popcorn" by Gershon Kingsley.

--------
Internet
--------

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

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

* http://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://geocities.com/andrewbroad/spectrum/download/
My download page. Currently contains my other games, my Manic Miner Screen Editor, 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 (with options for receiving and sending messages by email), Files and Photos (i.e. screenshots) sections which members can upload to, Links and 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 this 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 week. 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!

The World Of Spectrum forums [http://www.worldofspectrum.org/forums/] are worth browsing through on a regular basis, particularly the Games forum (this is something I do on a weekly basis).

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

<x This is a beta-revision of Advanced MM/JSW Trainer, so please do not redistribute it until it reaches v1.0.0. x>

<x The following paragraph will come into effect when v1.0.0 is released:
	Advanced MM/JSW Trainer 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 (2006). 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. x>

I don't mind you reusing some of the rooms, graphics, &c. in your own games, or converting the game to another computer (e.g. for JSW-PC). However, the accompanying documentation must state that the reused material is the copyright of Broadsoft - failure to do so may be construed as plagiarism. I would like the documentation to be quite specific about this, e.g. "Graphic X in Room Y was taken from Advanced MM/JSW Trainer", or whatever.

Please let me know if you do rerelease Advanced MM/JSW Trainer or reuse bits of it - it's not that I'd be likely to object, I'd just be very interested to know what follows from my releasing it!

----------------
Revision-History
----------------
Beta-releases
-------------

v0.0.0 (16th April 2006): JSW64, JSW48 and MM48 variants created, with chequered cell-grid patch applied. No new rooms.

v0.0.1 (21st April 2006): New rooms "Main menu" [0] and "Master Bedroom" [1] (see ROOMS_JSW64.TXT). New patches for JSW64 main game: "Chequered cell-grid + reset cells' FLASH-bits" and "No custom font for JSW64" (see TECHNICA.TXT).

v0.0.2 (24th April 2006): New room "Water-cells and basic jumping" [2] (see ROOMS_JSW64.TXT). "Print room-number" patch added and applied to JSW64, JSW48 and MM48 variants. Teleporter-list relocated to #A003 (JSW64 only) to allow up to 255 teleporters. "Harmless guardians" POKE applied to JSW64 and JSW48 variants. Default room-setup patch-vector (JSW64 only) added. See TECHNICA.TXT for details.

v0.0.3 (27th April 2006): New room "Traps to avoid" [3]; modified bottom-left of "Water-cells and basic jumping" [2] (see ROOMS_JSW64.TXT). Edited scrollies in JSW64, JSW48 and MM48 variants. Edited "Items collected" message to give number of items in the game, in JSW64 and JSW48 variants.

v0.0.4 (1st May 2006): New rooms "Earth-cells: Snagging your head" [4] and "Jumping into Earth-cells" [5] (see ROOMS_JSW64.TXT). Game-engine indicators introduced (Sprites #B360-B3FF) and added to Rooms [1] and [4]. Introduced colour-code for teleporters (see Design-Principles) and written room-setup patch-vectors to recolour visited teleporters (see TECHNICA.TXT).

v0.0.5 (6th May 2006): Finished the Earth-cells cluster with new rooms "Jumping left thru' overhead ECs" [6], "Walking left thru' head-high ECs" [7] and "Columns of alternate Earth-cells" [8] (see ROOMS_JSW64.TXT). Added in-game tune "Popcorn" to MM48, JSW48 and JSW64 variants. Updated Acknowledgements.

v0.0.6 (10th May 2006): New rooms "Fire-cells" [9], "Fire-cells: Pitfalls to avoid" [10] and "Fire-cells: Landing in adj cells" [11]; renamed [3] "Water-cells: Pitfalls to avoid" (see ROOMS_JSW64.TXT).

v0.0.7 (13th May 2006): New room "Trap-cells (harmless Fire-cells)" [12] (see ROOMS_JSW64.TXT).

v0.0.8 (18th May 2006): New room "Basic conveyor-mechanics" [13] (see ROOMS_JSW64.TXT).

v0.0.9 (20th May 2006): New room "Stopping on conveyors" [14] (see ROOMS_JSW64.TXT). Harmful-guardians POKE applied on a room-by-room basis (see TECHNICA.TXT).

v0.1.0 (22nd May 2006): New room "Sticky conveyors" [15]; placed an additional conveyor at the bottom-left of "Basic conveyor-mechanics" [13] (see ROOMS_JSW64.TXT).
