Jet Set WillyHome -> Jet Set Willy 128 -> JSW64 room formats
| Format | Block types | Guardians per room | Rooms | Free bytes in room record |
|---|---|---|---|---|
| V | 8 | 13 | 128 | 64 |
| W | 13 * | 8 | 128 | 0 |
| X | 8 | 13 (75) | 64 | 606 |
| Y | 13 * | 8 (63) | 64 | 512 |
| Z | 256 ** | 8 (31) | 64 | 256 |
| [ | 16 | 4 (63) | 64 | 512 |
Free bytes in a room are available to the designer. They can be used for custom graphics or patch vector code; or for additional guardians (this is the meaning of the figures in brackets in the 'guardians per room' table).
[*] Formats W, Y and [ use a 4-bit room map, so they can all specify 16 block types. But W and X don't have enough memory to store patterns and attributes for all 16.
[**] Although this format supports 256 block types, only 13 of them are 'real'. All the others just behave like differently- coloured water.
In Manic Miner, JSW48 and JSW128, the meaning of cells is fixed - the first cell is air, the second is water, and so on. In JSW64, this is controlled by the game itself. In the V and X variants, the cell types are set up by room; so one room could have three types of 'fire' cell and no conveyors, while another could have one fire, and two conveyors (one going each way). In the other four variants, the cell type is set up globally.
Cell types are:
00-68 Up to 13 guardian instances for the room, terminated with 0FFh. 69-6D Behaviour of the 8 cell types. First byte low nibble = behaviour of first cell First byte high nibble = behaviour of second cell 2nd byte low nibble = behaviour of third cell etc. 6E-B5 Attributes and bitmap for 8 cell types
Cell types are:
00-40 Up to 8 guardian instances for the room, terminated with 0FFh. 41-B5 Attributes and bitmap for 13 cell types
00-20 Up to 4 guardian instances for the room, terminated with 0FFh. 21-25 Reserved. 26-B5 Attributes and bitmap for 16 cell types
B6-D5 The room name, ASCII.
D6 Conveyor animation, and the Final Barrier flags.
Bits 5,6,7: Source of bottom half of room image
Bits 2,3,4: Source of top half of room image
0: No image (normal room)
1: Title screen, top half
2: Title screen, bottom half
3: Screen buffer 1 (bank 7 at E2FFh)
4: Screen buffer 2 (bank 7 at EBFFh)
5,6,7: Reserved.
Bits 0,1: Conveyor direction. If set to 2 or 3, then all conveyors
in the room become deactivated or sticky respectively.
D7-D8 Conveyor animation position
D9 Conveyor animation length
DA-DB Address of the guardian instance table used by this room.
Normally 8000h, but if a larger guardian instance table is needed
it will be the address of that table, either in the room record or
elsewhere in memory. The original guardian table will then be
available for your own purposes.
DC Solar Power beam entry point. Low 5 bits are X-coordinate; high 3
bits are Y-coordinate (solar power must start in the top 8 lines).
DD Attribute of the solar beam. If this is zero, the room has no solar
power. Note that unlike in Manic Miner, the solar beam does not
require a green background. If you want a harmless solar beam, you'll
have to set the room not to limit air supply.
DE Bits 0-2: Border
Bits 3-5: Willy's colour
Bit 6: Rigor Mortis. If set, guardians are stationary until all
objects in the room have been collected.
Bit 7: Superjump.
DF Air supply, major value. See Andrew Broad's Manic Miner room format
for full details of this field.
E0 Air supply, minor value. Must be a multiple of 4, or 0xFF if the
room does not have a limited air supply.
E1 Item bitmap
E9-EC Exits
ED Willy's sprite page. If less than 80h, uses the standard Willy.
EE-EF The address of the 16x16 graphic to use for the portal. Set to 0 if
this room does not have a portal.
F0-F1 Position of portal attribute (based at 5C00h).
F2-F3 Position of portal bitmap (based at 6000h).
F4 Portal attribute. If it is flashing the portal can be entered
even if there are still items to be collected.
F5 Portal destination room number.
F6-F7 Portal destination: Position of Willy attributes (based at 5C00h).
F8 Portal destination: Willy's new Y-coordinate (based at 6000h).
F9-FA 'Portal' patch vector
FB-FC 'Room setup' patch vector
FD-FE 'Main loop' patch vector
FF Room flags:
Bit 0 set if, when Willy dies, he loses the items he collected in
the current room.
Bit 1 set if escalators go down rather than up.
Bit 2 set to make all ramps in the room into escalators.
Bit 3 set if Willy can fall any height without losing a life.
Bits 4,5,6 reserved.
Bit 7 set if this is a 'bonus' room (collecting an item gives an
extra life).
100-13F Unused. Available to designer for portal graphic or patch
vector(s).
140-1FF Room layout, 3 bits per cell.
100-1FF Room layout, 4 bits per cell.
100-33F Unused. Available to designer for portal graphic, patch
vector(s), sprites, guardians, or all of the above.
340-3FF Room layout, 3 bits per cell.
100-2FF Unused. Available to designer for portal graphic, patch
vector(s), sprites, guardians, or all of the above.
300-3FF Room layout, 4 bits per cell.
100-1FF Unused. Available to designer for portal graphic, patch
vector(s), sprites or guardians.
200-3FF Room layout, 8 bits per cell. Unknown attributes take
the 'water' graphic.
100-2FF Unused. Available to designer for portal graphic, patch
vector(s), sprites, guardians or all of the above.
300-3FF Room layout, 4 bits per cell.
In these formats, the meaning of each cell is determined globally rather than by room. There is a 16-byte table at F4FFh in bank 7. Each byte defines the meaning of a cell (so byte 0 refers to the first cell in the room definition, byte 1 to the second, and so on).
Cell types are:
After these 16 bytes are the attributes and bitmaps for the three "global" cells -- the ones which are the same in every room.
The cell type table is at F519h and is 16 bytes long. There are no global cell definitions.
The guardians in JSW64 are based on the JSW128 guardians, but with a few added features. A guardian definition is 8 bytes long; I refer to them as GB0-GB7.
The low 4 bits of GB0 give the guardian type. This is one of:
0 - Blank 1 - Horizontal 2 - Vertical 3 - Rope 4 - Arrow 5 - Diagonal 1 6 - Diagonal 2 7 - Vertical, colour-cycling 8 - Extended guardian. Top 4 bits give subtype: 08: Skylab. Behaves like a vertical guardian, except that at the end of its travel it 'crashes' and then reappears 8 columns to the right (wrapping, of course). Other bytes as vertical guardian, except that byte 7 is 'crash' position and byte 6 is 'restart' position. So for an upward skylab, byte 7 must be less than byte 6. 18: Angry Eugene. Other bytes as vertical guardian, except that byte 1 is colour; high bits must be zero. An Angry Eugene goes to the end of his travel and stops dead. 28: Angry Eugene (colour-cycling based on air supply) 38: Angry Eugene (colour-cycling using JSW64 method). 88: Trigger. Byte 0: 88h Bytes 1-2: Address of a flag. When this flag becomes zero, bytes 3-7 are applied to the next guardian in the table; and byte 0 of this guardian is cleared so it doesn't happen again. Byte 3: New byte 0 of next guardian. Bytes 4-7: New bytes 4-7 of next guardian. 98: Switch. Byte 0: 98h. Byte 1: Ink. Byte 2: X-coordinate and frame. The top half of the guardian sprite will be the 'off' switch and the bottom half will be the 'on' switch. Byte 3: Y-coordinate. Byte 4: State. 1=Off 0=On. Byte 5: Sprite page. Byte 6: If it's off and Willy hits it, change state to this. Byte 7: If it's on and Willy hits it, change state to this. A8: Opening wall. Byte 0: A8h. Bytes 1-2: Address of flag (same as for the Trigger). Byte 3: Number of vertical lines this will remove. Byte 4: State. Initialised by JSWED to 1. It will become 0 when all lines are removed. Byte 5: Number of lines removed so far. Initialised by JSWED to 0. Byte 6: X-coordinate of wall to open. Byte 7: Y-coordinate of wall to open. B8: Stopper. Guardians after this one don't move or get drawn. C8: Stopper. Guardians after this one don't move but do get drawn. 9 - Horizontal, colour-cycling A - Vertical B - Reserved C - Reserved D - Diagonal 1, colour-cycling E - Diagonal 2, colour-cycling
Diagonal 1 and 2 are similar; the difference is that if all the other bytes are the same, one goes down when moving left, and the other goes down when moving right.
These guardian types behave like the standard JSW48 horizontal guardian. Diagonal ones use GB4 as their vertical speed.
The top 3 bits of GB7 have these meanings:
Set bit 6 of GB0 to have a stationary rope. The Adjacent Ropes patch is in place, so a rope can be followed by other guardians and it won't corrupt them.
GB1 is the ink colour to use for the arrow. Bits 3-7 of this byte will also be ORed to the screen, so it's best to leave them as 0.
GB3 is the bitmap for the middle line of the arrow.
There are three patch vectors in the room data. In order, these are:
This is called when Willy enters a portal. The Patch Vector Jumpblock (below) provides two possible implementations of this; or you could write your own.
Note that when you return from the Portal vector, the game will assume you have moved to a new room and set things up accordingly. If you want Willy to stay in the same room, return with
POP BC
RET
rather than just RET.
This is called when Willy enters a new room, after the room attributes and bitmap patterns have been generated. This can be used to put custom graphics in a room (like the Final Barrier does in Manic Miner). The default implementation is just to return.
This is called in the main game loop, just after the screen has been drawn and just before Willy moves. It corresponds to the patch vector in 'Geoff Mode' JSW.
The following entry points are provided as helper functions for patches that you write. More may be added later.
The jumpblock is at a fixed location, and this will stay fixed in future JSW64 versions.
869F RET
For rooms without patches, the Room Setup and Main Loop patch vectors should be set to this address.
86A0 JP portal_with_fx_and_air
This is the default portal patch vector. It takes Willy to the location specified in the room's portal settings. The portal special effect occurs (as in Manic Miner); and if the room has a limited air supply, it will be run down to zero with a whining noise (again, as in Manic Miner).
86A3 JP portal_with_fx
As above, but does not do the 'air-running-down' thing.
86A6 JP portal_without_fx
As above, but with no special effects at all (like the JSW128 teleporter).
86A9 JP ptl_fx
This performs the portal special effect only.
86AC JP airend
This performs the air-running-down-to-zero effect.
86AF JP fx_and_air
This performs the portal effect followed by the air-running-down-to-zero effect.
86B2 RST 0
The last entry in the jump block is always RST 0. If more entries are added, they will go at 86AFh and the RST 0 will move to the new end of the jump block.
The following entry points are provided as helper functions for patches that might want to amend the game music system.
The jumpblock is at a fixed location, and this will stay fixed in future JSW64 versions. It may also appear in a later version of JSW128.
FEC0 JP tuneoff
This will stop the in-game tune playing. Returns NZ if the tune was not playing, Z if it was.
FEC3 JP tuneon
This will set the tune going. Note that the tune pointers at 0FE8Eh must have been set to point to the start of the selected tune.
FEC6 JP newtune
Change the in-game tune. Enter with HL pointing to the 6-byte header of the new in-game tune. If no tune is playing, nothing obvious happens; if a tune is playing, it is stopped and the new tune starts.
FEC9 DEFS 6
A copy of the 6-byte header of the last tune selected with NEWTUNE. This is the tune that will be played when the current in-game tune comes to an end (used to make the tune into a continous loop).
John Elliott
30 April 2005