DefRoom - Jet Set Willy Room Editor
                   ===================================
                          J.G.Harston, 1984-2003
                               jgh@mdfs.net
                    mdfs.net/Software/JSW/Editors/JGH

                The program is Copyright (C) J.G.Harston,
                       but may be freely distributed

DefRoom allows you to edit room definitions for Jet Set Willy, including the
extra rooms available with the 7-bit room patch. These instructons describe
the Spectrum version. The BBC version is functionally the same.


                               MAIN MENU
                               =========

On running DefRoom the main menu is displayed listing the available main
commands. At any point if DefRoom stops with an error, it can be rerun to
return directly to the main menu.

L: Load a file, S: Save a file
------------------------------
This allows you to load and save parts of the Jet Set Willy data. You will
be prompted with what to save: Code, Rooms, Sprites, Objects or Guardian
data. You then are prompted for the filename.

Code: loads and saves data from anywhere in memory. You are prompted for the
data start address and, when saving, the length.

Rooms: loads and saves room data. You are prompted for the room number and,
when saving, the number of rooms. Rooms are numbered from 0 to 127 with
rooms 0-63 in memory at 49152-65535 (&C000-&FFFF) and rooms 64-127 in memory
at 32768-49151 (&8000-&BFFF). Only rooms 87, 91, 94, 95, 103, 104, 105 and
106 are available in the lower 16K.

As rooms are in memory in blocks of 64, you cannot load or save a single
block of rooms starting at room<64 and continuing past room>63.

Sprites: loads and saves sprite data. You are prompted for the sprite number
to start and, when saving, the number of sprites. Sprites are numbered from
0 to 295 with sprites in memory at 39680-49151 (&9B00-&BFFF). Sprites 128 to
295 are the main sprites. The only low-numbered sprites available are the
Foot, Barrel, Maria and Willy in sprites 10-23 and the toilet in sprites
88-91.

Objects: loads and saves the object table at 41983-42495 (&A3FF-&A5FF).

Guardian: data loads and saves the Guardian data. You are prompted for the
guardian number and, when saving, the number of guardians. Guardians are
numbered from 0 to 126 and occupy memory at 40960-41975 (&A000-&A3F7).

If no start is given when loading, then the data is loaded to whereever it
was saved from. If no filename is given, or no start or length when saving,
then the load or save is aborted, and the program returns to the main menu.

If the second character of the filename is ':', then the first character
specifies what device to use, either 'T' for tape, '1'-'8' for microdrive 1
to 8 or 'S' for serial link. Otherwise, the default device is used.

All: loads the files with the names: Sprites0, Sprites128, Objects, Rooms,
Room087, Room091, Room094, Room095 and Room103+.

D: Drive
--------
This allows you to select the default drive for loading and saving files.
Enter '1' to '8' for microdrives 1 to 8, 'T' for tape or 'S' for serial
link. When the program starts this is set to the drive just loaded from.

C: Catalogue
------------
This catalogues the current device as selected with D from the main menu.
When cataloging from tape, pressing ENTER will stop the listing.

R: Room editor
--------------
This enters the room editor.

G: Guardian/Sprite Editor
-------------------------
This loads the Sprite editor "DefSprite" from the currently selected device.

X: Exit to Menu Program
-----------------------
This loads a menu program called "run" from the currently selected device.




                              ROOM EDITOR
                              ===========

When the room editor is selected, you are prompted for a room number, and
then that room is displayed and it can be edited. Pressing 'M' will return
you to the main menu.

Below the displayed room and name are the four rooms the current room
connects to and their names. The next line shows the current room number and
the room blocks: Air, Wall, Floor, Nasty, Slope, Conveyor and Object, along
with the border colour. The number of objects in the current room is shown
as a proportion of the total number of objects.

The cursor keys and the Kempston joystick will move around the screen.

When the cursor is on the name line, the room name can be edited.
Symbol-Shift always gives the single character on each key without having to
go into extended mode. Symbol-Shift-I (AT) gives the copyright symbol.

Moving the cursor down to the room exit lines allows you to change the room
exits. Moving down to the bottom line allows you to change the border
colour. Moving further down will return the cursor to the top of the screen.

1 to 4 selects a room block, Air, Wall, Floor or Nasty, as indicated by the
arrow on the status line.

0/space/fire places the current room block in the room.

R: Selects another room.
G: Edit the room's guardian list. You should ensure the guardian list ends
   with 255,0. This also allows you to edit the extra, normally unused, data.
C: Edit the room's conveyor and slope settings.
E: Edit a room block. The cursor keys move around the 8x8 grid. 0 or fire
   flips the pixel between set and unset. Pressing A lets you set the
   attribute, and pressing ENTER returns you to the room editor.
O: Places an object at the cursor position.
D: Deletes object at the cursor position. This can be a bit slow as it
   searches through the entire object table to find the object under the
   cursor.
H: Displays help screen. Press any key to return to the room editor.
M: Returns to the main menu.


Future improvements
===================
Should display the room's sprites. Might get around to rewriting the whole
program in machine code. Still some INPUT commands that don't access the
external keyboard.


Technical notes
===============
There is insufficient memory to hold the Jet Set Willy program code, as
RAMTOP is set at 38655 (&96FF). The Jet Set Willy code can be split up into
code and data by doing the following:
  CLEAR 32767
  LOAD "jsw1" CODE
  SAVE "CODE" CODE 33280,6400
  SAVE "DATA" CODE 38656,26880
or the appropriate microdrive commands. "DATA" can then be loaded by
DefRoom.

DefRoom will load and save with the Discovery and the DISCiPLE as they use
standard microdrive commands.

When loading seperate parts, code must be loaded first, before any tune
data, and Sprites files must be loaded before any guardian data, the objects
data and rooms number 64+. The recommended loading order is:
  CODE     Tunes     Sprites     Guardian data     Objects     Rooms


Version History
===============
These instructions were written in 2003, so I'm a bit hazy on the exact
development history!

1.25 20-Feb-2007 Some minor tweeks and bugfixes. Drive defaults to Serial if
                 program loaded from Serial port. Updated run menu program.
1.24 06-Nov-2003 Added the 'X' option from the main menu, and allowed
                 editing of the extra room data unused by the standard JSW48
                 engine. Fixed unsuppressed key repeat in the file menu.
1.23 12-Jan-2003 Corrected the Help screen to reflect reality, corrected a
                 microdrive bug that incorrectly allowed LOAD "", wrote
                 these instructions.
1.21 Spring 1989 File routines rewritten to allow more flexible saving as
                 seperate parts instead of all 64 rooms in one block. d:name
                 decoding rewritten to be tidier and more generic.
1.20 Winter 1986 Added 7-bit room number capability.
1.12 xx-xxx-1985 d:name filename support added.
1.11 xx-xxx-1985 Implemented serial drive option to access remote computer.
1.10 xx-xxx-1985 Added microdrive and external keyboard support.
1.00 xx-xxx-1984 Original version. No object add/remove, no microdrive
                 support, no guardian list editing.