Dr. Andrew Broad
Sinclair ZX Spectrum
Manic Miner/Jet Set Willy
Manic Miner Room-Format

This document was last updated on 1st April 2004 - changes since previous version (15th March 2003):


Welcome to my Manic Miner Room-Format! I figured all this out for myself by eyeballing the data and experimenting. That was back in 1992, before I had access to the Internet, therefore I had no idea that other people have also written Manic Miner editors and unofficial sequels! But as far as I know, this is the only technical specification for Manic Miner on the Internet, and none of the existing editors - except my own Manic Miner Screen Editor which has now been released - appear to have all this knowledge built into them! Everything you ever wanted to know about the room-format is here, plus I impart lots of tips on creating special effects as well as pointing out the pitfalls to avoid!

I did this for Jet Set Willy as well, but Arsen Torbarina had already put a JSW Tech Page on his JSW Ultimate Fan Page, so there goes my novel contribution! ;-( Unfortunately his website is now gone, so I most probably will write up my JSW Room-Format at some point in the future. In the meantime, this document is worth reading because many of the tips mentioned here apply to JSW too! Serious JSW-hackers may also be interested in John Elliott's disassembly of the Jet Set Willy engine and his Jet Set Willy II Room-Format.

It is very encouraging to see the inventive uses to which the information in this document is being put. I envisaged that people would use it to hack directly into the Manic Miner code or even to write their own editors (Stuart Brady is writing a Manic Miner level-editor for Linux), but it is also proving useful for other tasks such as converting Manic Miner to run on other computers (e.g. Garry Lancaster's Manic Miner `88), or mechanical transformations (e.g. Philip Bee is working on laterally inverting (`mirroring') the Manic Miner rooms, and I'm planning to write programs to map between Manic Miner and Jet Set Willy in the future).

I assume the reader has a basic grounding in data-representation and computer-architecture, a good working knowledge of the Sinclair ZX Spectrum, and some experience of playing Manic Miner. If not, then take a degree in Computer Science at the University of Manchester, get yourself a Spectrum-emulator, and download Manic Miner from World Of Spectrum for it! And do check out my fabulous games!!

Copyright Notice

Copyright in text of this document rests with the Author (Andrew Broad). I'm a very reasonable person when it comes to my own copyright: I don't mind you putting a copy on your own website (my website won't be here forever in any case :-(), but if you do, please have the decency to let me know if possible.

If you do publish a copy elsewhere, you may edit the HTML as long as you leave the actual text alone (some introductory text by the host at the top of the document is acceptable, but please leave the rest as it is). You must acknowledge me as the author. You should periodically check the original location of this document (http://www.geocities.com/andrewbroad/spectrum/willy/mm_format.html) to see if it has been updated.

Known `mirror sites' for this document (please let me know of any others):

The Technical Stuff

Manic Miner's rooms are stored in memory addresses 45056 to 65535, so although the complete game is stored from 32768 to 65535, there is no need to edit 32768 to 45055 to redesign the caverns! Appendix E contains the odds and sods that I have discovered about addresses 32768 to 45055 (specifically, I have found out about the graphics for Miner Willy, the in-game tune, the title-screen/Room 19 picture, colour-attributes for title-screen and for the bottom eight rows below the playing-area; the title-screen scrolly and other pieces of text).

Each room r is represented as a 1024-byte contiguous block of memory, starting at address 45056 + 1024*r {0 <= r <= 19}, where Room 0 is the first room ("Central Cavern" in the original Manic Miner) and Room 19 is the last room ("The Final Barrier" in the original Manic Miner).

Each byte of room-data is offset from the start address of the room by i bytes {0 <= i <= 1023}, so the datum at Offset i in Room r is held at address 45056 + 1024*r + i.


The rest of this document specifies the data represented at the various offsets within a room:

Offsets 0 to 511: Screen-Layout

The blocks on the screen are represented as a sequence of 16 rows, each of which consists of 32 characters, one byte per character.

Each character is the colour-attribute of the block at that position on the screen (see Appendix A for a specification of colour-attributes). These colour-attributes correspond to the ones defined for the block-graphics, and care must be taken that they agree, because an attribute in the screen-layout which does not map to any block-graphic in this way will be interpreted as an undefined blob on the screen! (such blobs usually behave like regular floor, but don't count on it!). Room 2 of Craig Rothwell's Manic Miner 7 ("The Menagerie") has such undefined blobs in it - that room has /nine/ different colour-attributes in its screen-layout!

Note that it's possible to design a room so that Willy can go off the edge of the screen, though this can never happen in the original Manic Miner caverns. When this happens, he appears on the other side of the screen. Manic Miner 2 uses this trick heavily, but there are bugs associated with it as Manic Miner wasn't really designed to allow this. The manoeuvre is juddery (basically, if Willy goes off the right of the screen, he goes down one character-row; if Willy goes of the left of the screen, he goes up one character-row), and if it's off the top or bottom of the screen, it corrupts memory so that:

So if you want to let Willy jump off the top of the screen or fall off the bottom, as happens on several occasions in Manic Miner 2 and Manic Miner 4, you should base your game on the Bug-Byte version of Manic Miner.

Title-Screen Graphics in Room 19

Room 19 ("The Final Barrier" in the original Manic Miner) has the title-screen picture on the first eight character-rows of the screen (the picture showing the sunny lake, the house and the car). The picture overrides the pixel patterns for any blocks which occur at the corresponding positions in Room 19.

The picture's colour-attributes are stored in the screen-layout for Room 19, which means they can be edited by editing the room, which changes the colours both on Room 19 and on the title-screen, as I do in all my Manic Miner games.

The picture itself (i.e. the pixels but not the colour-attributes) is stored separately from the room-data (in addresses 40960 to 43007 - see Appendix E). This means that the picture still gets displayed on edited versions of Room 19, independently of the colour-attributes defined there. This has implications for the collision detection algorithm for guardians, which is pixel-based (so avoid having guardians in the top half of the screen unless you are sure that their `on' pixels won't touch any of the picture's `on' pixels). It does not affect the behaviour of the blocks as far as Willy is concerned, because that behaviour is attribute-based.

Offsets 512 to 543: Room-Name

A room-name is represented in exactly 32 bytes, one byte per character, where Offset 512 is the leftmost character and Offset 543 is the rightmost character.

The characters are encoded in the well-known ASCII text format, which I'm sure needs no introduction to serious readers of this document! I would merely recommend that you stick to ASCII characters 32 through 127, using spaces (32) to pad out the name, as codes outwith this range are likely to be interpreted in strange ways! Ignacio Pérez Gil used control characters for the Spanish accents etc. in the room-names of Manic Miner 5: Los Peligros del LSD.

Offsets 544 to 615: Block-Graphics

Each room has eight block-graphics (each of which is represented in nine bytes): The nine bytes for each block graphic are used as follows:

The colour-attributes defined here must agree with the ones in the screen-layout, as this is how the block at each character-position is specified, so when you change an attribute here, remember to replace all occurrences of that attribute in the screen-layout! Beware the case where you're changing to an attribute that already occurs on the screen (because you will lose the distinction between the two block-types), and the case where you're changing from a multiply-defined attribute (because, since there's no distinction on the screen-layout, it will replace all blocks of that attribute - it is better to decide whether to replace each occurrence of the block by hand, rather than replacing all blocks automatically and indiscriminately).

In general, two block-graphics should not have the same colour-attribute, because it makes an occurrence of that attribute in the screen-layout ambiguous. However, you could try using this technique for special effects such as crumbling conveyors (as in Room 10 of Manic Miner: The Hobbit, "On the Doorstep").

If a block-type is not required on a screen, I suggest zeroising the 8x8 pixel pattern and using 255 for the colour-attribute as the neatest solution (some rooms in the original Manic Miner use a colour-attribute of 0 for this purpose, but I don't like that because it often clashes with the Background attribute).

The Block-Graphics Bug

There is a horrid bug in the Manic Miner game-engine which can cause one block graphic in a room to corrupt another (typically so that its 8x8 pixel pattern resembles the first block graphic when it is displayed on the screen). You can often fix it by changing the colour-attribute of one or the other graphic if you encounter it. The bug can also be due to pixel patterns, however (e.g. if you laterally invert the pixel pattern for Wall in Room 0 ("Central Cavern") of the original Manic Miner, it corrupts Nasty 1's pixel pattern!)

Matthew Wilson has now explained the exact cause of the block-graphics bug to me. The Manic Miner game-engine looks up each block from the screen-layout (Offsets 0 to 511) in the block-graphics section (Offsets 544 to 615), and uses the next eight bytes as the pixel pattern to display. However, it interprets the first occurrence of the block byte in Offsets 544 to 615 as the colour-attribute, even if it isn't one of Offsets 544, 553, 562, 571, 580, 589, 598 or 607. So the block-graphics bug occurs if the colour-attribute value happens to occur in the pixel pattern data before its proper occurrence as a colour-attribute, and the following eight bytes are used as the pixel pattern (which explains why it resembles one of the pixel patterns for the room but looks as if it has been shifted vertically).

There's a similar bug in the Jet Set Willy game-engine, though not identical - try writing "West of Kitchen" or "The Wine Cellar" (Rooms 24 and 49 respectively in the original Jet Set Willy) in Manic Miner, and you'll see that Manic Miner will corrupt some block-graphics that Jet Set Willy does not! (you'll also notice that you can't jump onto the ledges on the left-hand side of "The Wine Cellar" in Manic Miner, whereas in Jet Set Willy, you can).

Note on Collision Detection for Guardians

Manic Miner's collision detection algorithm for guardians is pixel-based, which means that you lose a life if a guardian touches Willy, another guardian or the pixels in a block on the screen. That's why the 8x8 pixel pattern for Background tends to be left blank, but it only need be if a guardian would touch any pixels in it which are turned on! Equally, you can safely have a guardian walk through a block of any type, provided it would not touch any pixels. I exploited all these peculiarities in "Dotty" (Room 14 of Manic Miner 4). The first three rooms of Craig Rothwell's Manic Miner 7 are also excellent examples of this.

Note that it does not count as a collision if a guardian touches the portal or an item (though if the guardian is white, it'll collect the item for you! (see Room 12 of Manic Miner: The Hobbit, "Not at Home")), and it does not matter what the Kong Beast touches as it falls to its death in Rooms 7 and 11 ("Miner Willy meets the Kong Beast" and "Return of the Alien Kong Beast" in the original Manic Miner)!

Crumbling Floor

The 8x8 pixel pattern for Crumbling Floor (Offsets 563 to 570) should respect Manic Miner's algorithm for detecting that the floor has crumbled completely: each time Miner Willy steps on a block of crumbling floor, it shifts the 8x8 pixel pattern of that particular block down one pixel, with the bottom row of pixels falling off the bottom of the character and a blank row of pixels being fed in at the top. If the bottom row of pixels is blank after that shift, it infers that the occurrence has crumbled completely and replaces the colour-attribute at that character-position with that of the Background graphic. Therefore, you should probably avoid having a blank row of pixels in the middle of the 8x8 pixel pattern for Crumbling Floor, because Manic Miner will infer prematurely that it has crumbled completely, leaving a `ghost' (the pixels in rows above the blank line but the colour-attribute of Background; you can see the `ghost' in white ink when Willy touches it) at that character-position. See Room 0 of Manic Miner 7 ("The Money -O- Meter") for a very clever exploitation of this feature, and Room 0 of Manic Miner: The Buddha of Suburbia ("The Terminator") for a not so clever example! (originally unintended as I didn't understand it back in 1992, but when I revamped the game for an Internet release in 1998, I liked it so I left it in! :-))

Manic Miner's crumbling algorithm can be exploited to create proper fast-crumbling floors, where there are a number of blank rows of pixels at the top of the 8x8 pixel pattern, depending on how rapidly you want it to fall away. Examples of this are "A Hole in the Ocean" (Room 13 in Manic Miner 4), and several rooms in Manic Miner: The Buddha of Suburbia and Manic Miner: The Hobbit.


Note that the specification of the conveyor's direction and position of animation are decoupled from the Conveyor blocks in the screen-layout (unlike in Jet Set Willy). What this means basically is that you can have as many conveyors as you like in a room, but they all have to go in the same direction, and at most one `row' of Conveyor blocks can be animated (although all the rooms in the original Manic Miner happen to have at most one conveyor, to which the conveyor-animation is applied). But the animation need not be applied to a conveyor - observe the animated floor in "Amoebatrons' Revenge" (Room 17 in the original Manic Miner)! Room 4 in Manic Miner: The Buddha of Suburbia ("Zane Zane Zane - Ouvre le Chien!") illustrates this point very well - any blocks under the conveyor-animation have their top row of pixels rotated in the direction of the conveyor and their third row down of pixels rotated in the opposite direction, so this should be taken into account when designing the 8x8 pixel pattern for Conveyor (or whatever the conveyor-animation is to be applied to).

Switches (Rooms 7 and 11)

The Spare graphic (Offsets 607 to 615) is usually used as an alternate Floor, but in Rooms 7 and 11 ("Miner Willy meets the Kong Beast" and "Return of the Alien Kong Beast" in the original Manic Miner), it has a special role:

N.B. The above coordinates are all hardwired into the game-engine. You cannot, by simply editing the room-data, change the positions of the switches (such that they will still work), the blocks that get turned to background, the Kong Beast or the altered path of the second horizontal guardian.

For the switch to work correctly, leave the bottom three rows in the 8x8 pixel pattern for Spare intact, as Manic Miner tries to detect this pattern and laterally invert it when Willy flicks the switch. Note that the switch's colour-attribute does not affect this effect.

John Elliott's Manic Miner Patch allows a Kong Beast in any room, as specified by Offset 627.

Solar Rays (Room 18)

In Room 18 ("Solar Power Generator" in the original Manic Miner), the solar rays can be absorbed by Wall blocks or deflected by guardians. They start from the top of the screen from column 23, and go down until they are deflected or absorbed, so the best way to disable this feature is to have a Wall block at (0,23). Bugs will occur if you let a ray go off the screen without being absorbed.

Changing the colour-attribute of Background from its original green ink on green paper can result in harmless rays, as in Room 18 of Manic Miner: The Hobbit ("The Last Stage").

John Elliott's Manic Miner Patch allows solar rays in any room, as specified by Offset 627.

Offsets 616 to 622: Miner Willy's Start-Position

Some of Offsets 616 to 622 are only meaningful in terms of the way they are used at runtime - when you're actually playing the game, they are copied to the runtime work area and updated there (see Appendix F).

Offsets 623 to 626: Conveyor: Direction and Position of Animation

Technically, the animation of the conveyor is decoupled from the actual Conveyor blocks (for further discussion of this issue, see the subsection on Conveyors in the Block-Graphics section). If you are a lay hacker who just likes to have one conveyor in each room and animate that, then whenever it says "conveyor-animation" below, just read "conveyor".

Offset 627: Border-Colour / John Elliott's MM Patch

Offset 627 represents the colour of the room's border (0=black, 1=blue, 2=red, 3=magenta, 4=green, 5=cyan, 6=yellow, 7=white).

John Elliott's Manic Miner Patch interprets Offset 627 as follows (see Appendix D):


Offsets 628 to 654: Items

Each room can have 0, 1, 2, 3, 4 or 5 items. Perhaps you call them `keys' or `objects', but not all the items actually look like keys (the item-graphic is defined separately), and in my world view, everything's an object! :-)

Offsets 655 to 691: Portal

Offsets 692 to 699: Item-Graphic

The item's 8x8 graphic (see Appendix B) is held in Offsets 692 to 699. Note that there is no colour-attribute associated with this - colour-attributes are associated with the individual instances of the item (up to five of which are stored in Offsets 629 to 653).

Offsets 700 to 701: Air

The amount of air you have in a room is held in Offsets 700 and 701:

Offsets 702 to 732: Horizontal Guardians

Each room can have 0, 1, 2, 3 or 4 horizontal guardians. All rooms can have these. Unlike in Jet Set Willy, all horizontal guardians in a room have to have the same graphic (guardian-graphics are defined separately within the room-data).

Up to four horizontal guardians can be stored in Offsets 702 to 729 (each represented by seven bytes):

If there are fewer than four horizontal guardians in the room, the sequence is terminated with 255 in the byte after the last horizontal guardian (i.e. 702, 709, 716 or 723), and all bytes after that one up to and including Offset 729 are padded out with 0. So if you delete a guardian, remember to shunt the ones after it down a place, and pad out as necessary!

The seven bytes of each horizontal guardian are used as follows:

Offsets 733 to 760: Vertical Guardians (only for rooms which have them)

Only the following rooms can have vertical guardians:

The alleged vertical guardian in Room 4 ("Eugene's Lair" in the original Manic Miner) is a special case (see the Special Graphics section) - it is not a guardian in the sense of this section!

John Elliott's Manic Miner Patch allows any room to have vertical guardians (or a Eugene), as specified by Offset 627.

For rooms which don't have vertical guardians, Offsets 733, 734 and 735 are set at 0 (and so are Offsets 736 to 760, except for Rooms 0, 1, 2 and 4 which have special graphics).

Each room for which vertical guardians are enabled (whether because of the room-number, or by using MM Patch) can have 0, 1, 2, 3 or 4 vertical guardians. Unlike in Jet Set Willy, all vertical guardians in a room have to have the same graphic (guardian-graphics are defined separately within the room-data).

Up to four vertical guardians can be stored in Offsets 733 to 760 (each represented by seven bytes):

If there are fewer than four vertical guardians in the room, the sequence is terminated with 255 in the byte after the last horizontal guardian (i.e. 733, 740, 747 or 754), and all bytes after that one up to and including Offset 760 are padded out with 0. So if you delete a guardian, remember to shunt the ones after it down a place, and pad out as necessary!

The seven bytes of each vertical guardian are used as follows:


Vertical guardians have unorthodox semantics in Room 13 ("Skylab Landing Bay" in the original Manic Miner). Instead of going up and down, they come down from the top of the screen and explode at the bottom of their path! The way this is implemented is that after a vertical guardian has exploded, it starts again at the top of the screen, shifted horizontally 8 characters to the right (under modulo-32 to give screen wraparound). Thus, in the original version, there are three vertical guardians in this screen, giving the illusion of twelve!

You can edit the vertical guardians in Room 13 like any other vertical guardians, but you must bear in mind the special conditions stated above. You have to make sure the vertical guardians do not clash or straddle the screen under modulo-8 (i.e. avoid having a vertical guardian in columns 7 & 8, or 15 & 16, or 23 & 24, as this would cause them to straddle the vertical borders of the screen).

I have experienced a lot of trouble with Skylabs crashing into the floors they explode on and killing you, when you try to change their paths or speed! The best way I know to cure such a problematic Skylab is to change the number of pixels (the three least significant bits of the third byte) below the starting position to some number between 0 and 7 and to set the number of pixels below the top position (the three least significant bits of the sixth byte) to that same value. This requires at most eight experiments before you cure the problem (unless of course the guardian is faulty for other reasons! ;-)).

The graphics for these guardians are also unorthodox (see the section on Guardian-Graphics).

John Elliott's Manic Miner Patch allows Skylabs in any room, as specified by Offset 627.

Offsets 736 to 767: Special Graphic (Rooms 0, 1, 2 and 4)

Rooms 0, 1, 2 and 4 have a special 16x16 graphic (see Appendix C) associated with them, which is held in Offsets 736 to 767. On all other screens, Offsets 761 to 767 are zeroised (Offsets 736 to 760 are also zeroised on screens which don't have vertical guardians).

John Elliott's Manic Miner Patch allows any room to have a Eugene, as specified by Offset 627.

Offsets 768 to 1023: Guardian-Graphics

Eight 16x16 sprites (see Appendix C) for the guardians are held in Offsets 768 to 1023:

Exactly which sprites are used for what varies from room to room. In particular, some rooms are allowed to have bidirectional graphics for the horizontal guardians, while others are not, because some of the sprites are used for other purposes (mainly vertical guardian-graphics).

The rooms which have bidirectional graphics for horizontal guardians are: The sprites are used in the following different ways, depending on which number room it is:

John Elliott's Manic Miner Patch allows any room to have vertical guardians, Skylabs or a Kong Beast, as specified by Offset 627 - which therefore determines whether horizontal guardians have unidirectional or bidirectional sprites.

Appendix A: Colour-Attributes

A colour-attribute is represented as an 8-bit word in the following format (see Appendix D):

Appendix B: 8x8 Graphics

An 8x8 graphic is represented as a sequence of eight contiguous bytes, where the first byte is the top row of pixels and the eighth byte is the bottom row of pixels.

Within each row, each of the eight bits represents a pixel, where the most significant bit is the leftmost pixel and the least significant bit is the rightmost pixel.

If a bit is set to 0 then the corresponding pixel is `off', whereas if the bit is set to 1, the corresponding pixel is `on'.

In other words, it's exactly how normal people would visualise it! :-)

Appendix C: 16x16 Graphics

A 16x16 graphic is represented as a sequence of 32 contiguous bytes. Start with your understanding of 8x8 graphics (see Appendix B), where a byte represents a row of pixels. In a 16x16 graphic, the bytes (numbered 0 through 31), are aligned as follows:
00 01
02 03
04 05
06 07
08 09
10 11
12 13
14 15
16 17
18 19
20 21
22 23
24 25
26 27
28 29
30 31

In other words, go left to right and then top to bottom through the whole of the graphic. Don't think of it as 2x2 characters or you'll get your head in a tangle! ;-)

Stuart Brady suggests that it might be better to think of a 16x16 graphic as a sequence of sixteen 16-bit words, each representing a row of pixels. Take your pick! :-)

Appendix D: Word-Formats

For data which is best understood at the level of bits, I have adopted a generic template in which I depict the byte(s) in binary to show how each bit is used.

Bits which are always 0 or always 1 are depicted as `0' or `1', while bits which vary are depicted as letters. Where several bytes fulfil the same functional role, they are shown side-by-side, with the offset above, e.g.

   621      620
This depicts that the bytes at Offsets 620 and 621 form a 16-bit word (which happens to partially represent Willy's start-position in a Manic Miner room), where the seven most significant bits at Offset 621 are fixed (so it's always 92 or 93 in denary, depending on whether the least significant bit is 0 or 1), and there are variables:

In this example, which is typical of many in Manic Miner and Jet Set Willy, these data represent the position of a 16x16 sprite as the number of characters down from the top of the screen (YYYY) and the number of characters to the right of the left border of the screen (XXXXX) - or, if you prefer, the row and column of the top-left 8x8 character of the 16x16 graphic.

Appendix E: Addresses 32768 to 45055

Though this document is primarily concerned with the upper 20K of Manic Miner (addresses 45056 to 65535, where the room-data are stored), I have discovered various useful bits and pieces about the lower 12K (addresses 32768 to 45055), which are the subject of this appendix.

Appendix F: Runtime Buffers

The emphasis of this document has been on the anatomy of a Manic Miner file rather than the dynamic aspects of the room format at runtime. However, while Garry Lancaster was working on a Z88 conversion of Manic Miner, he discovered some details of how the game engine copies the room-data to buffers at runtime and updates these data during play, and he was kind enough to share this information with me. I'll let his own words tell the story...

"The first thing to understand is the way Manic Miner uses the level data. When a new level is entered, the first 512 bytes are copied into an area I call the "background attribute buffer". These are then used to generate the "background screen buffer" - basically everything except the items, guardians and Willy himself.

"The other 512 bytes are copied to a work area and are used throughout play, with the positions being updated in the copy. This explains why several of the locations appear to be unused, as they only get initialised during play.

"Secondly, the positions of various things on the screen often appear twice in odd formats within the level data. This is because the program sometimes needs an attribute address and sometimes a graphic address; if both are needed, only three bytes are required since the low byte of an attribute address is the same as that of a graphic address. To add to the confusion, some positions are given within the "background" buffers mentioned above, and others are given within the "secondary" graphics/attribute buffers.

"To make sense of this, you need to understand how the screen is displayed. At the start of a new level, the background buffers are generated (as discussed earlier) and these stay the same except for conveyors and certain special features in the Kong screens. Every move, the background buffers are copied to the secondary buffers, where guardians, items and Willy are added (checking for collisions). Finally the secondary buffers are copied to the screen.

"Anyway, the various positions in the level data correspond like this:
0111Y000 : background graphics buffer (for conveyors only)
0110Y000 : secondary graphics buffer
0101110Y : secondary attributes buffer"

I have since discovered that the bit pattern for the background graphics buffer should be 0111Yyyy, where yyy is the number of pixels below the specified character row. So the vertical position of a conveyor-animation can be given in pixels, not just characters. The bit pattern for the secondary graphics buffer should similarly be 0110Yyyy in principle, which would allow you to specify the vertical positions of items, portals and horizontal guardians in pixels. However, there are bugs associated with this, so it's not recommended (the Manic Miner game engine doesn't cover the three character rows that such a graphic would straddle with the colour-attribute, and there seem to be other bugs too which cause nasty corruptions).

Email me