+================================+
| JET SET WILLY CONSTRUCTION KIT |
|          Version 1.0           |
|       (C) BROADSOFT 2003       |
|                                |
|           USER-GUIDE           |
+================================+

Jet Set Willy Construction Kit (JSW CK) is split into two 128K programs due to lack of memory (silicon disk space), which have to be loaded separately:

* Part I allows you to edit all aspects of rooms (except guardian-instances), and to edit the item table.

* Part II allows you to edit guardians (both guardian-instances in rooms, and guardian-classes), and 16x16 graphics.

If you should break into the program at any time, use LOAD !"0" to recover and return to the main menu. If you get a "File already exists" error, try ERASE !"scr" followed by LOAD !"0".


PART I: THE ROOM EDITOR AND THE ITEM EDITOR
===========================================

A high-level view of the architecture of JSW CK Part I is:

   +-----------+    +-------------+
-->| Main Menu |<-->| Room Editor |
   +-----------+    +-------------+
         ^                 ^
         |                 |
         |                 V
         |          +-------------+
         \--------->| Item Editor |
                    +-------------+

The main menu for Part I has five options:
	1: Room Editor (see Section I.1)
	2: Item Editor (see Section I.2)
	3: Load Game - do this before anything else, even when you're starting work on a new game! ;-)
	4: Save Game - do this regularly, as in every half-hour! ;-)
	5: Play Game - it is impossible to return from this without resetting the Spectrum, so save the game first! ;-)


I.1 The Room Editor
-------------------

The Room Editor is reached by pressing `1' on the main menu, which prompts you to enter the number of the room to visit (0 to 63). The Room Editor can also be reached via the Item Editor (Section I.2).

To exit the Room Editor and return to the main menu, press `q'.

Press `h' for help (an online list of keys).

In the Room Editor, use the following keys to navigate around the rooms:
	CAPS-SHIFT & 6: visit room to the left
	CAPS-SHIFT & 7: visit room to the right
	CAPS-SHIFT & 8: visit room below
	CAPS-SHIFT & 9: visit room above
	j: input a room number to visit (0-63)
	n: visit next room number
	b: visit previous room number
	p: return to the room previously visited
	l: show list of room-titles, which you can scroll through and select a room to visit

To clear a room, press `x'. Then press either `w' to clear the whole room (i.e. set all 256 bytes of the room to 0), or `0', `1', `2', `3' to clear just the screen-layout (i.e. replace all Floor, Wall and Nasty blocks with either Background (`0'), Floor (`1'), Wall (`2') or Nasty (`3'), but don't touch anything else). I usually just clear the screen-layout rather than the whole room, not least because zeroising the guardian-instance list means that the blank room contains eight instances of Guardian-Class 0!

Use the following keys to set the connections (room exits):
	SYMBOL-SHIFT & 6: specify room to the left
	SYMBOL-SHIFT & 7: specify room to the right
	SYMBOL-SHIFT & 8: specify room below
	SYMBOL-SHIFT & 9: specify room above

Room-numbers should be in the range 0 to 63. However, JSW CK does accept room-numbers up to 255, to facilitate editing JSW128 room-files. In 48K JSW, a room-number r in the range 64-255 means that when the player takes that exit, (s)he appears in Room (r mod 64), but any items in that room do not appear and cannot be collected. This quirky feature can be used to suppress items when entering rooms from certain directions, as first exploited in Goodnite Luddite (Broadsoft, 2002).

Tip: Whenever you set a connection, it's best to go to that room immediately and set the inverse connection back to the room you're working on, unless this is not what you want (JSW CK does not impose geographical coherence). Not setting inverse connections immediately makes it harder to iron out the geography later, and you might forget to set a connection.

Use the following keys to edit the screen-layout:
	6: move cursor left
	7: move cursor right
	8: move cursor down
	9: move cursor up
	0: put a Background block
	1: put a Floor block
	2: put a Wall block
	3: put a Nasty block
	CAPS-SHIFT & 0: put Background and move in last direction moved
	CAPS-SHIFT & 1: put Floor and move in last direction moved
	CAPS-SHIFT & 2: put Wall and move in last direction moved
	CAPS-SHIFT & 3: put Nasty and move in last direction moved

Press `4' to edit the ramp (see Section I.1.2) and `5' to edit the conveyor - each room has (at most) one ramp and (at most) one conveyor.

Press ENTER to edit the room-title. You can either type in the whole string at once by pressing `s' (if less than 32 characters, it will be padded out with spaces on the right; if more than 32 characters, it will be truncated - a phenomenon known as Procrustean assignment), or edit it a character at a time by pressing `c' (`6' and `7' move the cursor left and right respectively). Press Enter to return to editing the screen-layout.

Press SPACE to change the border colour for the room. This sets the border to the next colour in the cycle: black, blue, red, magenta, green, cyan, yellow, white.

Use the following keys to enter the 8x8 Graphics Editor (see Section I.1.1) and edit the block-graphics and the item graphic for the room:
	SYMBOL-SHIFT & 0: edit Background graphic
	SYMBOL-SHIFT & 1: edit Floor graphic
	SYMBOL-SHIFT & 2: edit Wall graphic
	SYMBOL-SHIFT & 3: edit Nasty graphic
	SYMBOL-SHIFT & 4: edit Ramp graphic
	SYMBOL-SHIFT & 5: edit Conveyor graphic
	SYMBOL-SHIFT & i: edit Item graphic

Press `i' to enter the Item Editor and edit the items in this room (see Section I.2).

The other keys are:
	r: redraw screen (you'll want to do this when it gets cluttered up with ramps, conveyors and items! ;-) )
	CAPS-SHIFT & SYMBOL-SHIFT: turn the chequered grid on/off


I.1.1 The 8x8 Graphics Editor
-----------------------------

The 8x8 Graphics Editor is entered from the Room Editor (see above). It is used to edit the pixel-patterns and colour-attributes of a room's block-graphics, and the pixel-pattern of a room's item graphic (in my book, an item graphic is not a block-graphic - just Background, Floor, Wall, Nasty, Ramp and Conveyor).

To exit the 8x8 Graphics Editor and return to the Room Editor, press `q'.

Press `h' for help (an online list of keys).

As in the Room Editor, use the following keys to select an 8x8 graphic to edit:
	SYMBOL-SHIFT & 0: edit Background graphic
	SYMBOL-SHIFT & 1: edit Floor graphic
	SYMBOL-SHIFT & 2: edit Wall graphic
	SYMBOL-SHIFT & 3: edit Nasty graphic
	SYMBOL-SHIFT & 4: edit Ramp graphic
	SYMBOL-SHIFT & 5: edit Conveyor graphic
	SYMBOL-SHIFT & i: edit Item graphic

Further keys for selecting an 8x8 graphic to edit:
	SYMBOL-SHIFT & 6: edit previous block-graphic in room (not including the item graphic)
	SYMBOL-SHIFT & 7: edit next block-graphic in room (not including the item graphic)
	SYMBOL-SHIFT & 8: edit the corresponding graphic in the previous room
	SYMBOL-SHIFT & 9: edit the corresponding graphic in the next room
	j: input a room number (0-63) and edit the corresponding graphic in that room
	SPACE: go back to the room in which you entered the 8x8 Graphics Editor
	ENTER: go back to editing the graphic for which you entered the 8x8 Graphics Editor

Basic keys for editing the pixel-pattern of an 8x8 graphic:
	6: move cursor left
	7: move cursor right
	8: move cursor down
	9: move cursor up
	0: toggle pixel
	1: pixel on
	2: pixel off
	CAPS-SHIFT & 0: toggle pixel and move in last direction moved
	CAPS-SHIFT & 1: pixel on and move in last direction moved
	CAPS-SHIFT & 2: pixel off and move in last direction moved

Keys for more advanced pixel-pattern editing:
	3: all pixels in grid on
	4: all pixels in grid off - recommended for unused block-types
	5: toggle all pixels in grid
	CAPS-SHIFT & 5: laterally invert grid
	CAPS-SHIFT & 6: rotate grid left
	CAPS-SHIFT & 7: rotate grid right
	CAPS-SHIFT & 8: rotate grid down
	CAPS-SHIFT & 9: rotate grid up

Keys for editing the colour-attribute of an 8x8 graphic (not applicable to the item graphic):
	i: change ink-colour (0=black, 1=blue, 2=red, 3=magenta, 4=green, 5=cyan, 6=yellow, 7=white)
	p: change paper-colour
	b: bright on/off
	f: flash on/off
	CAPS-SHIFT & 3: set colour-attribute to 255 (white ink, white paper, bright on, flash on) - recommended for unused block-types
	CAPS-SHIFT & 4: set colour-attribute to 0 (black ink, black paper, bright off, flash off)

If you give two block-types the same colour-attribute then their effects will be combined, e.g. giving Ramp the same colour-attribute as Floor makes all floor blocks behave as ramps (as in "Out on a limb"); giving Conveyor the same colour-attribute as Ramp makes the ramp behave as a Conveyor (as in "The Chapel") and vice versa (as in "Let There Be Light!" in JSW Ivy).

There is a bug which corrupts pixel-patterns, which I call the Block Graphics Bug. The JSW game-engine looks up the pixel-pattern of a block by its colour-attribute, but it looks at the pixel-pattern bytes as well as the colour-attribute bytes! So if the target colour-attribute byte happens to occur in the pixel-pattern of any /previous/ block-type, JSW will take the next eight bytes as the pixel-pattern.

Last but not least:
	c: copy 8x8 graphic to clipboard
	v: paste 8x8 graphic from clipboard
The 8x8 clipboard is a buffer for the purpose of moving 8x8 graphics around. It holds the pixel-pattern and colour-attribute for one 8x8 graphic. Since item graphics do not have a colour-attribute, if an item graphic is copied into the clipboard, it flags the fact that it doesn't have a colour-attribute, and pasting it into a block-graphic leaves that block-graphic's colour-attribute unchanged. If a block-graphic is pasted into an item graphic, the colour-attribute is ignored.


I.1.2 The Ramp Editor
---------------------

The Ramp Editor is entered by pressing `4' in the Room Editor (see Section I.1).

To exit the Ramp Editor and return to the Room Editor, press `4' again.

Each room has one ramp, which has a length of zero-or-more characters. The base of the ramp is the bottom character, and it either slopes up to the left or to the right. A ramp may extend beyond the left or right edge of the screen (in which case it wraps around to the other side), but may not extend beyond the top of the screen.

Use the following keys to edit the ramp:
	6: move base of ramp left
	7: move base of ramp right
	8: move base of ramp down
	9: move base of ramp up
	1: shorten the ramp by one character
	2: lengthen the ramp by one character
	3: toggle direction of ramp


I.1.3 The Conveyor Editor
-------------------------

The Conveyor Editor is entered by pressing `5' in the Room Editor (see Section I.1).

To exit the Conveyor Editor and return to the Room Editor, press `5' again.

Each room has one conveyor, which has a length of zero-or-more characters (unlike in Manic Miner, where having a zero-length conveyor-animation causes a bug). The base of the conveyor is the leftmost character (regardless of the direction). A conveyor may extend beyond the left or right edge of the screen (in which case it wraps around to the other side).

Use the following keys to edit the conveyor:
	6: move base of conveyor left
	7: move base of conveyor right
	8: move base of conveyor down
	9: move base of conveyor up
	1: shorten the conveyor by one character
	2: lengthen the conveyor by one character
	3: change direction of conveyor (left, right, off, or sticky)


I.2 The Item Editor
-------------------

There are two ways to reach the Item Editor:

* Press `i' in the Room Editor. This takes you into the Item Editor to edit the items in the current room.

* Press `2' on the main menu, which prompts you to enter the number of the item to edit (1 to n, where n is the number of items - a Jet Set Willy game must have at least one item, and at most 256).

Either way, you enter the Item Editor in a particular room.

When you want to exit the Item Editor, press `q' if you want to go (back) to the main menu, or `r' if you want to go (back) to the Room Editor.

Press `h' for help (an online list of keys).

When you enter the Item Editor, it draws all the items in the current room, and puts the cursor over the first item in the room. If there are no items in the room then there is no cursor, in which case none of the keys - except `q', `r', `h', `5' and ENTER - have any effect.

Keys for selecting an item to edit:
	2: select next item in the room
	1: select previous item in the room
	4: select next item in the item table
	3: select previous item in the item table
	5: input an item number (in the item table) to edit

Keys for editing the selected item (i.e. the one under the cursor):
	6: move item left
	7: move item right
	8: move item down
	9: move item up

Keys for moving the selected item to another room (caveat: it's not often that you want to move an existing item to another room, and the following keys should not be confused with their counterparts in the Room Editor, which just move *you*):
	CAPS-SHIFT & 6: move item to room to the left
	CAPS-SHIFT & 7: move item to room to the right
	CAPS-SHIFT & 8: move item to room below
	CAPS-SHIFT & 9: move item to room above
	j: input a room number to move item to (0-63)
	n: move item to next room number
	b: move item to previous room number

Press DELETE (CAPS-SHIFT & `0') to remove the selected item. The items after it in the item table will be shunted down to fill the gap, causing their item numbers to decrease by one.

Press ENTER to add a new item. The item will be inserted in the item table at a position you get to specify (usually, you will just want to insert it at the end of the table (i.e. at n+1, where n is the number of items that exist before the new one is inserted), but JSW CK gives perfectionists the flexibility to insert it wherever we will - a desirable thing to be able to control sometimes). Any existing items at or after the specified insertion position will be shunted up to make way for the new item, causing their item numbers to increase by one.

The colour-attribute of an item is not specified, but the ink-colour flashes in the following cycle: magenta, green, cyan, yellow (paper, bright and flash are as the room's Background colour-attribute). Unlike in Manic Miner (which specifies the colour of each item on the zeroth time-frame), the relative ink-colours of the items in a room are determined by their order in the item table: the first item in a room is one step in the ink-colour cycle behind the second, and so on.


PART II: THE GUARDIAN EDITOR AND THE 16X16 GRAPHICS EDITOR
==========================================================

To understand JSW CK's Guardian Editor, you must first understand that Jet Set Willy decouples the representation of guardians into guardian-classes and guardian-instances (my terminology):

* A /guardian-class/ is a partial specification of a guardian (including guardian-type it is - a horizontal guardian, a vertical guardian, a rope, or an arrow). Guardian-classes are stored in the Guardian-Class Table (at addresses 40960-41983, for those of you who are knowledgeable about guardians but are unfamiliar with my terminology).

* A /guardian-instance/ is a particular instance of a guardian-class in a particular room (each room can have up to eight guardian-instances, as held in the room's Guardian-Instance List). A guardian-instance completes the information from its guardian-class. A particular guardian-class can have many guardian-instances, even in the same room.

The information needed to enact a guardian-instance (i.e. its path, graphics, colour, &c.) is held partly in the guardian-instance itself, and partly in its guardian-class. Since one guardian-class can have many guardian-instances, and the class data is the same for each instance of that class, using guardian-classes economically is an important skill to have - you can only have 127 guardian-classes, so if you profligately create a new guardian-class for every guardian-instance, you'll be restricted to an average of two guardian-instances per room!

With respect to the relationship between guardian-classes and guardian-instances, JSW CK is carefully designed to be as usable as possible without losing any of the flexibility you need for guardian-class economy. The key concept in the design of the Guardian Editor is >focus<:

* A /focus/ is a (room, guardian-instance) pair, one or both of which can be null in the current state:
	- If both are null (if the room is null, then obviously the guardian-instance must also be null, since guardian-instances are contained in rooms), then you can browse and edit guardian-class data, except the path of the guardian, because that is specified partly in the guardian-class, and partly in the particular guardian-instances of that class.
	- If both are non-null, then you can fully edit the guardian-class data and the guardian-instance data - in particular, you can edit the path of the guardian with respect to the particular guardian-instance in the current focus (JSW CK makes you edit the instance path data separately from the class path data, in order that you understand when you're altering the class data - which affects all guardian-instances of that class - and when you're altering the instance data, which only affects that specific guardian-instance).

* There are two ways to set a focus in JSW CK:
	- by selecting a guardian-instance from a room's Guardian-Instance List in the Room Browser;
	- by selecting an instance of a guardian-class, from a list that the Guardian-Class Editor generates (by looking up all instances of that class across all rooms).

A high-level view of the architecture of JSW CK Part II is:

   +--------------+       +------------------------+
   | Room Browser |<----->| Guardian-Instance List |
   +--------------+       +------------------------+
         ^                             ^
         |                             |
         |                             V
         |         +-------------------------------+
         |         | Guardian-Instance Path Editor |
         |         +-------------------------------+
         |                             ^
         |                             |
         V                             V
   +-----------+           +-----------------------+
-->| Main Menu |<--------->| Guardian-Class Editor |
   +-----------+           +-----------------------+
            ^                 |
            |                 |
            V                 V
         +-----------------------+
         | 16x16 Graphics Editor |
         +-----------------------+

The main menu for Part II has six options:
	1: Room Browser (see Section II.1)
	2: Guardian-Class Editor (see Section II.2)
	3: 16x16 Graphics Editor (see Section II.3)
	4: Load Game - do this before anything else, even when you're starting work on a new game! ;-)
	5: Save Game - do this regularly, as in every half-hour! ;-)
	6: Play Game - it is impossible to return from this without resetting the Spectrum, so save the game first! ;-)


II.1 The Room Browser
---------------------

The Room Browser is an adaptation of the Room Editor from Part I, which allows you to navigate the rooms, but not to edit anything except the Guardian-Instance List (unfortunately I ran out of silicon disk space, forcing me to split JSW CK into two parts - I made the best compromise I could, okay?). The Room Browser is reached by pressing `1' on the main menu, which prompts you to enter the number of the room to visit (0 to 63). The Room Browser can also be reached via the Guardian-Instance Path Editor.

To exit the Room Browser and return to the main menu, press `q'.

In the Room Browser, use the following keys to navigate around the rooms:
	CAPS-SHIFT & 6: visit room to the left
	CAPS-SHIFT & 7: visit room to the right
	CAPS-SHIFT & 8: visit room below
	CAPS-SHIFT & 9: visit room above
	j: input a room number to visit (0-63)
	n: visit next room number
	b: visit previous room number
	p: return to the room previously visited
	l: show list of room-titles, which you can scroll through and select a room to visit

Press `g' to go to the room's Guardian-Instance List, described in the following subsection.


II.1.1 The Guardian-Instance List
---------------------------------

The Guardian-Instance List is a list of the guardian-instances in a particular room, so the focus is the room but no particular guardian-instance. It is reached either from the Room Browser (by pressing `g'), or from the Guardian-Instance Path Editor (by pressing `i').

To go (back) to the Room Browser, press `r'.

The Guardian-Instance List is displayed, and if there are more than zero guardian-instances in the room, you can scroll through them (press `8' for down, `9' for up). If there are fewer than eight guardian-instances in the room, then there's a gap after the last one which you can put the cursor over.

Press `0' to enter the Guardian-Instance Path Editor (see Section II.2.1), setting the selected guardian-instance as the focus. Obviously this only works if there are more than zero guardian-instances in the list and you have selected one of them (rather than the gap) by putting the cursor over it.

Press DELETE (CAPS-SHIFT & `0') to remove the selected guardian-instance.

Press ENTER to insert a new guardian-instance at the current position in the list. If the cursor is over the gap, it will be inserted at the end of the list, otherwise the guardian-instances at and after the selected position will be shunted up so that it can be inserted there.

The order of guardian-instances can be important in some circumstances, as this affects collision-detection (see the Collision-Detection document on my website). In short, the guardian-instances should be ordered as follows:
1. HORIZONTAL/VERTICAL GUARDIANS
2. ROPE
3. ARROWS

When you create a guardian-instance by editing the Guardian-Instance List directly in this way, you need to know what number guardian-class to create an instance of. When you need to control the order, this entails browsing the Guardian-Class Editor (Section II.2) to find or create the appropriate guardian-class, and returning to the Guardian-Instance List to insert it.

You can also create a guardian-instance directly from the Guardian-Class Editor (Section II.2), but you cannot control the order that way - it is simply inserted at the end of the Guardian-Instance List.


II.2 The Guardian-Class Editor
------------------------------

The Guardian-Class Editor is at the heart of JSW CK Part II. It can be entered directly from the main menu (by pressing `2'), or from the Room Browser (via the Guardian-Instance List and the Guardian-Instance Path Editor):

* When entering from the main menu, you will be prompted for the number of the guardian-class to visit. The focus will be null.

* When entering from the Guardian-Instance Editor, the focus will be the current room and the selected guardian-instance from that room. The guardian-class will, of course, be that of the selected guardian-instance.

Press `q' to return to the main menu.

Use the following keys to navigate around the Guardian-Class Table:
	n: visit next guardian-class
	b: visit previous guardian-class
	j: input a guardian-class to visit
Leaving a guardian-class by pressing one of these keys resets the focus to null.

When you visit a guardian-class, some information will be displayed on the screen, including the current focus, and what /type/ of guardian (horizontal guardian, vertical guardian, rope or arrow) it is. A guardian-class may also be cleared (i.e. currently unused).

When you visit a cleared guardian-class, you can unclear it (i.e. initialise it for use) by pressing ENTER. This prompts you to select what guardian-type it shall be (horizontal guardian, vertical guardian, rope or arrow). Once a guardian-class in uncleared, you cannot change its guardian-type - you have to clear it before you can do that.

The following keys only apply to uncleared guardian-classes.

To clear a guardian-class, press DELETE (CAPS-SHIFT & `0'). You are not allowed to do this if any guardian-instances of this class still exist - you'll have to delete those before you can clear the class (a sensible constraint imposed by JSW CK, not by Jet Set Willy itself).

Use the following keys to edit the guardian-class:
	a: edit animation (though this is only partially specified by the guardian-class) (see Section II.2.3)
	I (CAPS-SHIFT & i): change ink-colour (0=black, 1=blue, 2=red, 3=magenta, 4=green, 5=cyan, 6=yellow, 7=white)
	B (CAPS-SHIFT & b): bright on/off
N.B. A guardian-class does not specify paper-colour and flash - they are inherited from whatever the guardian is printed over (usually background). The above three keys only apply to horizontal and vertical guardians, since you cannot customise the animation or colour of ropes and arrows (ropes inherit their entire colour-attribute from whatever they're printed over, and arrows always have white ink).

Press `s' to enter the 16x16 Graphics Editor (Section II.3) to select a sprite-page for this guardian-class if it's a horizontal or vertical guardian, or to enter the Arrow Sprite Editor (Section II.2.4) if it's an arrow.

Press ENTER to create an instance of this guardian-class. You need to know the number of the room to put it in; the alternative way of creating a guardian-instance is to go to the Guardian-Instance List (Section II.1.1) and insert it. This operation sets the newly-created guardian-instance as the current focus.

Creating a guardian-instance in this way simply inserts it at the end of the room's Guardian-Instance List. Please note that it will sometimes be important to control the order of the Guardian-Instance List, and you should then remember the guardian-class number and create a new instance directly in the Guardian-Instance List (see Section II.1.1).

You can also change the focus explicitly by pressing `f', which brings up a list of all instances of this guardian-class across all rooms (which JSW CK looks up on the spot using a nifty machine code routine :-) ), which you can scroll through and select a guardian-instance to focus on. You can also delete guardian-instances directly from this list, which is handy.

When, and only when, the focus is set to a particular guardian-instance, two more functions are available:
	i: enter the Guardian-Instance Path Editor (Section II.2.1) and edit the instance part of this guardian's path;
	c: enter the Guardian-Class Path Editor (Section II.2.2) and edit the class part of this guardian's path.

The reason you have to set a focus, even to edit the class part of the path, is so that it can display the guardian on the screen, since its position is specified partly in the guardian-class and partly in the guardian-instance.


II.2.1 The Guardian-Instance Path Editor
----------------------------------------

The Guardian-Instance Path Editor is for editing those aspects of a guardian which are stored in the guardian-instance rather than the guardian-class. The Guardian-Instance Path Editor can be entered from two directions:

* from the Guardian-Instance List (Section II.1.1) of a room, by pressing `0' when a guardian-instance is selected;

* from the Guardian-Class Editor (Section II.2), by pressing `i' when a specific guardian-instance is set as focus.

To go (back) to the Guardian-Class Editor, press `0'.
To go (back) to the Guardian-Instance List, press `i'.

The Guardian-Instance Path Editor displays the guardian on the screen, in its starting position (if it's an arrow and starts off the screen, you will not be able to see it).

If it's a HORIZONTAL GUARDIAN, a VERTICAL GUARDIAN or a ROPE, you can edit its (start) column using the following keys:
	6: move (start) column left one character
	7: move (start) column right one character

If it's an ARROW, you can edit its row using the following keys:
	6: move row down one character
	7: move row up one character
	CAPS-SHIFT & 6: move row down one pixel
	CAPS-SHIFT & 7: move row up one pixel

Normally arrows, which are three pixels tall, should not straddle vertical character-boundaries. However, invalid arrows are a really cool quirky feature to have, so JSW CK now allows the shaft of an arrow to be at pixel-position 0 or 7. It merely flashes up an "INVALID" warning.
* A pixel-position of 0 causes a row of colour-attributes to be drawn 8 character-rows below the shaft of the arrow. The colour-attributes are the byte of the arrow-sprite (Section II.2.4). Pairs of invalid arrows can thus be used to create moving platforms or holes!
* A pixel-position of 7 causes the arrow-sprite to be drawn 8 character-rows below the shaft of the arrow, in the background ink-colour.


II.2.2 The Guardian-Class Path Editor
----------------------------------------

The Guardian-Class Path Editor is for editing those aspects of a guardian which are stored in the guardian-class rather than the guardian-instance. The Guardian-Class Path Editor can be entered from the Guardian-Class Editor (Section II.2), by pressing `c' when a specific guardian-instance is set as focus.

To go (back) to the Guardian-Class Editor, press `0'.

The Guardian-Instance Path Editor displays the guardian on the screen, in its starting position (if it's an arrow and starts off the screen, you will not be able to see it).


If it's a HORIZONTAL GUARDIAN, the keys are:
	8: move row down one character
	9: move row up one character
	CAPS-SHIFT & 8: move row down one pixel (yes, really!)
	CAPS-SHIFT & 9: move row up one pixel
	6: set initial direction to left
	7: set initial direction to right
	l: edit left boundary:
		6: move left boundary left one character
		7: move left boundary right one character
		0: set left boundary and return
	r: edit right boundary:
		6: move right boundary left one character
		7: move right boundary right one character
		0: set right boundary and return

Note that a horizontal guardian always starts on its leftmost sprite, regardless of whether it goes left or right initially (unlike in Manic Miner, where a horizontal guardian starts on its rightmost sprite if it goes left initially). So if it goes left initially, it will move left one step in the zeroth time-frame (i.e. the one before the screen is first drawn), and thus appear to start one character to the left of its starting column. So it's safe to place an initially-left-moving horizontal guardian so that the right half of it is in a wall, for example.

Note also that a horizontal guardian's start position does not have to be between its left and right boundaries, so you can give it a grand entrance! :-)


If it's a VERTICAL GUARDIAN, the keys are:
	8: move start row down one character
	9: move start row up one character
	CAPS-SHIFT & 8: move start row down one pixel
	CAPS-SHIFT & 9: move start row up one pixel
	t: edit top boundary:
		8: move top boundary down one character
		9: move top boundary up one character
		CAPS-SHIFT & 8: move top boundary down one pixel
		CAPS-SHIFT & 9: move top boundary up one pixel
		0: set top boundary and return
	b: edit bottom boundary:
		8: move bottom boundary down one character
		9: move bottom boundary up one character
		CAPS-SHIFT & 8: move bottom boundary down one pixel
		CAPS-SHIFT & 9: move bottom boundary up one pixel
		0: set bottom boundary and return
	v: edit velocity

The velocity (speed and direction) of a vertical guardian is the number of pixels it moves in each time-frame, and its initial direction. The velocity v is in the range {-64 <= v <= +63}. I haven't seen a vertical guardian with velocity of magnitude greater than 8 pixels/time-frame in any MM/JSW game other than my own :-)
* If v is negative, the guardian goes up initially.
* If v is positive, the guardian goes down initially.
* If v is zero, the guardian is stationary.

The length of a vertical guardian's path (from its initial column to its top/bottom boundary, and between its top and bottom boundaries) should be a multiple of its velocity, otherwise it can go beyond its boundaries (usually with disastrous consequences). Unless you're trying to pull off a special trick such as having a vertical guardian move so fast that it gives the illusion of two guardians, as I did in We Pretty's "S WAN SREF LEC TI NGELE P H ANTS" - it took me many attempts to get that to work! :-)

Note that a vertical guardian's start position *does* have to be between its top and bottom boundaries!


If it's a ROPE, the keys are:
	6: set initial direction to left
	7: set initial direction to right
	8: increase length by one dot
	9: decrease length by one dot

A dot is printed every three vertical pixels, starting at the top pixel-row of the screen. The standard length is 33 dots.


If it's an ARROW, the keys are:
	6: set direction to left
	7: set direction to right
	5: move start-column left one character
	8: move start-column right one character
	CAPS-SHIFT & 5: move start-column left 32 characters
	CAPS-SHIFT & 8: move start-column right 32 characters

The start-column of an arrow (its column in the zeroth time-frame) is in the range 0 to 255 inclusive (0 to 31 on-screen, 32 to 255 off-screen).

When changing the direction of an arrow, JSW CK automatically adjusts the start-column using the formula (287-x mod 256), so that the arrow will appear on the screen in the same time-frame as it did in the other direction.


II.2.3 The Animation Editor
---------------------------

The Animation Editor is used to control how horizontal and vertical guardians animate, i.e. the cycle of sprites (from the guardian's sprite-page) that is displayed. It is entered from the Guardian-Class Editor (Section II.2) by pressing `a' when the current guardian-class is a horizontal or vertical guardian.

Press `a' to return to the Guardian-Class Editor.

A horizontal or vertical guardian has a sprite-page associated with it, containing eight 16x16 sprites (sprite numbers 0 to 7). For a vertical guardian, the sprite number to be drawn cycles continuously from 0 to 7; for a horizontal guardian, the sprite number cycles from 3 to 0 when it's moving left, and from 4 to 7 when it's moving right.

A vertical guardian-class has an animation-speed bit, which you can toggle between fast (increment the sprite number every time-frame) and slow (increment the sprite number every two time-frames) by pressing `s'.

Now, unlike in Manic Miner, at each step in the cycle the sprite number to be drawn is modified by applying a three-bit animation mask (the sprite number is, of course, a three-bit number also) to restrict which sprites are actually drawn. The animation mask is edited using the following keys:
	b: toggle most significant bit of animation mask
         (for horizontal guardians, whether the animation is bidirectional)
	c: toggle middle bit of animation mask
	d: toggle least significant bit of animation mask

Furthermore, each guardian >instance< has a start-sprite (from 0 to 7), which further restricts which sprites are drawn. You can change the start-sprite by pressing SPACE (only when a guardian-instance is in focus).

The sprite number to be drawn at each step of the cycle is actually:
	((n AND a) OR s)
where n is the current sprite number in the cycle
      AND is the bitwise-AND operator
      a is the animation mask
      OR is the bitwise-OR operator
      s is the start-sprite
So `start-sprite' is a bit of a misnomer, which can lead to horrible, jerky animation if misused (and I'm not talking about JSW Ivy ;-) ). The following illustrates proper use of the animation mask and the start-sprite:

* The animation mask is typically used to specify whether the whole of the sprite-page is to be used, or only half, or a quarter, or even an eighth (i.e. just one sprite)!

* The start-sprite is then used to specify which half/quarter/eighth is to be used (for a specific guardian-instance).

So for full animation, use an animation mask of 111 and a start-sprite of 0.

JSW CK demonstrates on-screen how the guardian will be animated, which helps to understand how the animation mask and the start-sprite work. However, it is only able to show the animation properly if the focus is set to a guardian-instance - otherwise it shows full animation.


II.2.4 The Arrow Sprite Editor
------------------------------

The Arrow Sprite Editor is entered from the Guardian-Class Editor (Section II.2), by pressing `s' when the current guardian-class is an arrow. It is used to edit the arrow's 8x3 pixel-pattern.

To exit the Arrow Sprite Editor and return to the Guardian-Class Editor, press `q'.

The arrow sprite is displayed as an 8x3 pixel grid, but the middle row is hard-wired to be 11111111, and the bottom row is hard-wired to be the same as the top row. So it's effectively a one-dimensional graphics editor.

Basic keys for editing the arrow sprite:
	6: move cursor left
	7: move cursor right
	0: toggle pixel
	1: pixel on
	2: pixel off
	CAPS-SHIFT & 0: toggle pixel and move in last direction moved
	CAPS-SHIFT & 1: pixel on and move in last direction moved
	CAPS-SHIFT & 2: pixel off and move in last direction moved

Keys for more advanced arrow-sprite editing:
	3: all pixels on
	4: all pixels off
	5: toggle all pixels
	CAPS-SHIFT & 5: laterally invert grid
	CAPS-SHIFT & 6: rotate grid left
	CAPS-SHIFT & 7: rotate grid right


II.3 The 16x16 Graphics Editor
------------------------------

The 16x16 Graphics Editor actually consists of two components:

* The Sprite-Page Editor (Section II.3.1) is an outer layer for navigating sprite-pages, performing special operations (shifting and reversing for horizontal guardians) on a sprite-page, and selecting a sprite-page for a guardian-class.

* The 16x16 Sprite Editor (Section II.3.2) is an inner layer for editing a particular sprite within a sprite-page. It's analogous to the 8x8 Graphics Editor (Section I.1.1), although without colour-attributes (which are held in guardian-classes).


II.3.1 The Sprite-Page Editor
-----------------------------

The Sprite-Page Editor is entered either from the Part II main menu (option `3'), or by pressing `s' in the Guardian-Class Editor (Section II.2) when the current guardian-class is a horizontal or vertical guardian:

* When entering from the Guardian-Class Editor, the sprite-page is that of the current guardian-class. You can select another sprite-page for that guardian-class by moving to another sprite-page and pressing ENTER, which sets the current guardian-class's sprite-page to the current sprite-page and returns to the Guardian-Class Editor.

* When entering from the main menu, you are prompted for the sprite-page to visit, from 0 to 255 inclusive. The address space of sprite-page n is (256*n) to (256*n + 31). Any such 256-byte block in memory can be used as a sprite-page, but obviously you shouldn't edit the graphics in the sprite-page if its address space is used for something else. JSW CK advises you when it's not safe to edit a particular sprite-page, but does not prevent you from doing so - you can actually `edit' a room without loading Part I by editing the corresponding sprite-page! :-)

Press `q' to exit the Sprite-Page Editor and return to the main menu.

A sprite-page contains eight 16x16 sprites (sprite numbers 0 to 7). All 16x16 graphics in Jet Set Willy are stored in sprite-pages, so how the sprites in a sprite-page are interpreted depends on where they're referred to from, although it's worth noting that horizontal guardians use Sprites 0 to 3 for the left-facing sprites, and Sprites 4 to 7 for the right-facing sprites. However, for Willy (Sprite-Page 157) it's the other way round (except in Geoff Mode and JSW:LOTR, where the sprite-page for each room is specified in Offset 237 of the room data).

Use the following keys to navigate around the sprite-pages:
	n: visit next sprite-page
	b: visit previous sprite-page
	j: input a sprite-page to visit

If you have entered the Sprite-Page Editor from the Guardian-Class Editor, pressing ENTER selects the current sprite-page for the current guardian-class, and returns to the Guardian-Class Editor (Section II.2).

Use keys `0' to `7' to select a sprite within the sprite-page to edit in the 16x16 Sprite Editor (see Section II.3.2).

JSW CK provides two special operations to speed up the editing of horizontal guardian graphics:

* Horizontal guardian shifting (press `8'). You select a sprite, and every sprite to the left of it in that half of the sprite-page is shifted two/four/six pixels to the left, and every sprite to the right of it in that half of the sprite-page is shifted two/four/six pixels to the right.

* Horizontal guardian reversing (press `9'). You select one half of the sprite-page (by selecting a sprite within that half), and it copies the four sprites from that half to the other half, laterally inverted.


II.3.2 The 16x16 Sprite Editor
------------------------------

The 16x16 Sprite Editor is used to edit the 16x16 graphics themselves. It is entered from the Sprite-Page Editor.

To exit the 16x16 Sprite Editor and return to the Sprite-Page Editor, press `q'.

Use the following keys to select a different 16x16 sprite (within the sprite-page) to edit:
	SYMBOL-SHIFT & 0: edit Sprite 0
	SYMBOL-SHIFT & 1: edit Sprite 1
	SYMBOL-SHIFT & 2: edit Sprite 2
	SYMBOL-SHIFT & 3: edit Sprite 3
	SYMBOL-SHIFT & 4: edit Sprite 4
	SYMBOL-SHIFT & 5: edit Sprite 5
	SYMBOL-SHIFT & 6: edit Sprite 6
	SYMBOL-SHIFT & 7: edit Sprite 7

Further keys for selecting a 16x16 graphic to edit:
	SYMBOL-SHIFT & 8: edit the corresponding sprite in the previous sprite-page
	SYMBOL-SHIFT & 9: edit the corresponding sprite in the next sprite-page
	j: input a sprite-page (0-255) and edit the corresponding sprite in that sprite-page
	SPACE: go back to the sprite-page in which you entered the 16x16 Sprite Editor
	ENTER: go back to editing the sprite for which you entered the 16x16 Sprite Editor

Basic keys for editing the pixel-pattern of an 16x16 graphic:
	6: move cursor left
	7: move cursor right
	8: move cursor down
	9: move cursor up
	0: toggle pixel
	1: pixel on
	2: pixel off
	CAPS-SHIFT & 0: toggle pixel and move in last direction moved
	CAPS-SHIFT & 1: pixel on and move in last direction moved
	CAPS-SHIFT & 2: pixel off and move in last direction moved

Keys for more advanced pixel-pattern editing:
	3: all pixels in grid on
	4: all pixels in grid off
	5: toggle all pixels in grid
	CAPS-SHIFT & 5: laterally invert grid
	CAPS-SHIFT & 6: rotate grid left
	CAPS-SHIFT & 7: rotate grid right
	CAPS-SHIFT & 8: rotate grid down
	CAPS-SHIFT & 9: rotate grid up

Last but not least:
	c: copy 16x16 graphic to clipboard
	v: paste 16x16 graphic from clipboard
The 16x16 clipboard is a buffer for the purpose of moving 16x16 graphics around. It holds the pixel-pattern for one 16x16 graphic.

JSW CK advises you when a sprite-page is not safe to edit, but does not prevent you from doing so unless it is actually in ROM (sprite-pages 0-63), in which case it gives you read-only access to the sprite-page.
