JET SET WILLY CONSTRUCTION KIT 1.0 (C) BROADSOFT 2003
==================================

For the Sinclair ZX Spectrum 128K

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


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

Jet Set Willy Construction Kit is an editor for Jet Set Willy (JSW was written
by Matthew Smith, Copyright Software Projects 1984 - owned by Jester Interactive
since 2001) which I wrote myself, and use to write all my JSW games (except Jet
Set Dizzy and Jet Set Willy: Manic Miner, which were written using JSW CK's
predecessor, the slow and incomplete Jet Set Willy Screen Editor which could
literally only edit *rooms* (i.e. 49152-65535)).

The reason I wrote JSW CK, despite the existence of other JSW-editors on the
Internet, is that I did all my MM/JSW development on a real Spectrum +2 rather
than on an emulator (until it broke in April 2003), and the challenge of writing
my own editor was much more appealing than the tedium of typing an editor from
the Internet into my real Spectrum. It also means that as the author of JSW CK,
it's easy for me to modify it or extend it. I started work on JSW CK in summer
1997, and it was essentially complete by spring 1999, when it was solid enough
to complete my JSW games We Pretty and Jet Set Willy: The Lord of the Rings. JSW
CK is written predominately in BASIC, but has several machine-code routines to
perform expensive operations such as screen-drawing and look-ups in the blink of
an eye.

From playing briefly with the other Spectrum-based JSW-editors (of which the
best two seem to be JetSet Editor and JSW Editor MkII), it seems that JSW CK has
the advantages of a better user-interface - it has more shortcuts, and you never
have to go through a sequence of inputs all over again if you want to change one
thing. Above all, the way it handles guardian-classes and guardian-instances is
superb - you can either access the guardian-class table via the guardian-
instances in rooms, or browse the guardian-class table and look up all instances
of a guardian-class across all rooms.

JSW CK also has capabilities that other JSW-editors do not appear to have - for
example, you can edit the length of a rope, and you can specify the vertical
position of a horizontal guardian in pixels, not just characters.

I would appreciate feedback from anyone who is more familiar with the other
JSW-editors and has something to add about the relative advantages and
disadvantages of JSW CK, or indeed any other suggestions as to how I could
improve or extend JSW CK.

Many thanks to Richard Hallas for rescuing JSW CK 0.0 from tape and converting
it to emulator format for me!


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

To use Jet Set Willy Construction Kit, 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 128
BASIC). You also have to open the TAP file in the emulator (either before or
after issuing the loading instruction).

JSW CK is a 128K program, which uses the silicon disc. Therefore, your emulator
must support 128K mode.

Even though it's a 128K program, JSW CK is too large even for the silicon disk,
so I had to split it into two parts, each with its corresponding TAP file:
1. The Room Editor and Item Editor (JSW-CK-1.TAP);
2. The Guardian Editor and 16x16 Graphic Editor (JSW-CK-2.TAP).

Both TAP files come with the original JSW appended for convenience; for the
record, the following POKEs have been applied to "Bytes: JSW1":
34480,195 }
34481,202 } bypass colour-code routine (JP 34762)
34482,135 }
42183,11: official Software Projects poke to move item from "First Landing" to
"The Hall"
56876,4:  official Software Projects poke to fix "The Banyan Tree"
59901,82: official Software Projects poke to fix the faulty arrow in "The Attic"
60231,0:  official Software Projects poke to fix "Conservatory Roof"


User-Guide
----------

See USER.TXT for the user-guide.


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), my Manic Miner Room Format, Richard Hallas's music
document, a list of some of the quirky features in MM/JSW which I use in my
games, and links to other MM/JSW websites.

* http://www.geocities.com/andrewbroad/spectrum/download/
My download page. Currently contains my other games, my Manic Miner Screen
Editor, 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
----------------

Jet Set Willy Construction Kit 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
(2003). This document should be included with all copies of the program.
Modifications are discouraged but not forbidden, and you should state
specifically what you have modified. So it's okay by me if you want to extend
JSW CK to be a JSW128 editor, or to cover Geoff Mode or whatever - although I
may do so myself in the future and supersede your version! ;-)

I would love you to use JSW CK to write your own games, which is one of the main
reasons I'm releasing it, of course! :-) Please state in the games' accompanying
documentation that you used Broadsoft's Jet Set Willy Construction Kit (version
1.0) - credit where due will be greatly appreciated. I also give my permission
to convert JSW CK to other computers, or otherwise reuse parts of the design or
code of JSW CK (some of the machine-code routines are very `reuseful',
especially for other MM/JSW utilities).

Please let me know if you do use JSW CK in writing a game, or if you extend the
editor in any way, 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!


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

21st August 2000: Release of Jet Set Willy Construction Kit version 0.0 (public
beta version) on the Internet. "Program: ROOMS" in JSW-CK-1.TAP got corrupted in
the tape-transfer, leaving the main room-editor unusable. I have since (as of
version 1.0) typed it into emulator-format by hand (courtesy of Martijn van der
Heide's BAS2TAP utility - http://www.worldofspectrum.org/utilities.html).

30th November 2002: JSW CK 0.0 reissued with PC-sympathetic newlines, updated
Internet section and copyright notice, and various other changes to the
documentation. The TAP files were completely unchanged.

29th July 2003: Release of JSW CK 1.0:
+ "Program: ROOMS" in JSW-CK-1.TAP is now present and correct.
+ All references to the help-pages in Part II have been removed. These were
never implemented due to lack of silicon-disk space - use the user-guide
instead!
+ Part II Room Browser now tolerates invalid ramps.
+ When you change an arrow's direction, its start-column x is automatically
changed so that the arrow appears on the screen in the same time-frame as the
other direction (287-x mod 256).
+ Invalid arrows are now allowed with a warning!
+ The original JSW is appended to both JSW-CK-1.TAP and JSW-CK-2.TAP.

If you release your own version of JSW CK, 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.0M or something - do not call it
version 2.0, 1.1 or 1.0.1, 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: Minor enhancements:

* Changing the border-colour will only alter the 3 least significant bits of
Offset 222, to respect things like Geoff Mode which use the other bits (JSW CK
0.0 simply pokes the new border colour into Offset 222). Similar considerations
may apply to guardian-class definitions, although the required changes are more
complicated and won't be made until a possible major new version to support
Geoff Mode in the future.

* A couple of cosmetic bugs in the Guardian-Class Editor will be fixed - the
PAPER bug when you edit the colour of a guardian in a non-black room,
bidirectional horizontal guardians walking properly on the guardian-class
screen, and the correct sprite-frame appearing in the guardian-class path
editor.

* There is a bug in the Item Editor: sometimes when you move an item, a space
appears behind it when there's actually something there - but this bug may be
too expensive to fix if it would require keeping track of what's underneath
every item (all 256 items could be in one room, and even at the same character
location, so it would need a 256x256 buffer to keep track!).

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

* `0' to input the length of a ramp/conveyor.

* Changing a guardian-instance's position in the Guardian-Instance List using
CAPS-SHIFT & `8' for down, CAPS-SHIFT & `9' for up.

* Copying a room to another room, or exchanging two rooms, with the option of
copying or moving the items in those rooms.

* Saving/loading an individual room (with the option of saving the items in that
room), guardian-class, sprite page or single 16x16 sprite. (Tape only, due to
the problem of running out of silicon disk space.)

* Basic support for John Elliott's JSW128 and for Geoff Mode:
- loading/saving a 16K room file;
- supporting room numbers 64-255;
- different guardian-class tables in JSW128 (Offset 223);
- superjump on/off in JSW128 (MSB of Offset 222);
- editing the player sprite page (Offset 237) - used by JSW128, Geoff Mode and
JSW:LOTR;
- bidirectional/unidirectional player sprites in Geoff Mode (the 2 most
significant bits of Offset 222);
- lives-counter in Geoff Mode (Offset 223);
- patch-vector in Geoff Mode (just the address (Offsets 238/239) - JSW CK will
not attempt to be an assembler! ;-) ).

* Detect the Block-Graphics Bug.


Future work: Major additional functionality:

* Editing the general setup (start-room, Willy's start-position, position and
colour of Maria and the toilet, colour of foot and barrel on Game Over screen,
cheat modes, &c.).

* The new guardian-types in Geoff Mode (fast horizontal guardians, wraparound
guardians, &c.). Currently, JSW CK falls over if you try to edit the guardians
of a Geoff Mode game. ;-(

* Editing the title-screen colour-attributes (and the four 8x8 graphics used on
the title screen), the title-screen scrolly, the score-bar colour-attributes and
the score-bar text.

* 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! ;-) ).
