Jet Set Willy  As manufacturer (probably) intended
Hi and thanks for your interest in my little project,

For those who dont know what Ive been up to, my goal was to take a regular copy of the popular 1980s 8-bit computer game Jet Set Willy  and  look for and eliminate, as far as possible, every known bug, anomaly and unintended quirk.

Having said that, I also wanted to make any modifications look as invisible as possible or if the bugs have a visual impact then to simply correct them to make the game play as was originally intended without any unnecessary enhancements, the idea being to make the game as close to as the author intended it to run as possible. 

Of course it's never going to be precisely as intended as there is missing information which will probably never be found but my aim is to get as near to the mark as possible.

Some may question as to what on earth I am doing messing around with a computer game that was created some 33 years ago especially when all the bugs that prevented the game from being playable had long since been resolved. 

I dont really have a standard answer but aside from just giving myself something to do in my spare time I think I speak for many when I say that JSW, like many other games made for the computers of the day were the games of our youth, it was one of best selling games of 1984, those days where you needed a mortgage to buy a PC, the Xbox one was a twinkle in Bill Gatess eye and Sony hadnt quite got round to making the PlayStation yet so we had to make do with the technology of the day which was basically a computer with no hard disk, rubber keys, 48K of memory (unless your budget stretched to a Commodore 64 or a BBC etc..) and having to wait 3 minutes for a game to load from a cassette which, if youre lucky worked after a couple of dozen attempts and adjusting the volume, and tone controls etc .. (sigh) the good ol'days (????)

Maybe in another 33 years time there will be someone out there doing a disassembly of Call of Duty or GTA5 and trying to iron out the many bugs that exist in these games .. but somehow I doubt it, small and primitive as it may seem by todays standards JSW is unique in the way it demonstrates the way in which programmers made games back then
 
Before I go on I would like to express sincere thanks to everyone who helped out; most of the modifications were made with the assistance and guidance of those mentioned below and without their help its fair to say many of the modifications would not have been possible or at the very least would have taken considerably longer, please see the Acknowledgements section for full details.

Thanks to the availability of room and sprite editing software there are over 100 versions and variations of JSW with an interesting variety of rooms and sprites, most all have one thing in common though they use the original engine, the core coding that controls the animation, room layout and of course feature the item collection mission...


Its well documented that when originally produced the Jet Set Willy could not be completed and exploring certain rooms was made dificult if not impossible due to four main issues which I have listed below along with the solutions that I have implemented:

Firstly let's start with...

The Attic
Probably the most famous and destructive bug of them all; Willy enters the room and well nothing seems to happen at first, theres a slight flicker in one corner of the room but thats about it. However, when leaving the room things take a rather sinister turn, certain rooms begin to look a bit strange, most notably guardians start to disappear, more drastically Willy loses all his lives at once without any apparent reason when entering other rooms. Even after restarting the game the bug remains in place and only gets worse the more you try to play; the kitchens become a no-go area and the MegaTree complex is also beyond the realms of navigation. The bug stays in the game permanently and youre left with no choice but to reset the computer and load the game again from scratch. Way back when it was discovered there were numerous rumours speculating as to the reasoning for its existence, some would say that the author, Matthew Smith, deliberately put it there or left it there to add an additional challenge; as there were no items to collect in this room in theory it would not be necessary to visit it but it soon became clear to those trying to complete the game without visiting the attic that it was not actually possible, there are many rooms designed for Willy to pass through one way so once he has collected his item he cannot trace his steps back. Other rumours suggested that it was caused by the seemly complex looking breakdancing technicoloured centipede like guardian which, perhaps was too complex for the computer to handle or perhaps just badly coded.
 
Eventually it was discovered that it was caused merely by an incorrect piece of code that governed the presence of an arrow that should have appeared across the top half of the screen which was easily corrected, I have not made any other modifications to this room.

The second of the four issues lie in The First Landing

In this room there is an item (honest). Youd be forgiven for not spotting it. Its actually invisible and cant be collected anyway because its actual location turns out to be between the pillar and the flashing cross, well out of reach of Willys grasp. There were various patches developed to resolve this issue which included making a path off the staircase that led to the item. However, the official Software Projects patch was to relocate this object to The Hall, it was still invisible but can at least be collected thereby adding to Willys required item count. I have used this patch but I have now made it visible by borrowing an item from the West Wing Roof

Thirdly

The Banyan Tree
In the right hand side of this room Willy should be able to exit the top of the screen to A Bit of Tree but he cant. Theres a block that looks out of place and is blocking his path. It turns out that this cell should be the same as the ones surrounding it which Willy can walk or jump through. The official Software Projects patch is to change the cell so that it matches the ones surrounding it. Once again I have used this patch but, purely for aesthetic purposes added an additional cell but other than this I have left the room largely unchanged 

And the fourth issue which lies in the Conservatory Roof
This is one room that I had to make some significant changes to. There are four items to collect, each one being closely guarded by a static guardian. However one of them can only be completed by sacrificing a life and another cannot be collected at all, this is because the gap between the static guardian and the edge of the screen is only wide enough to accommodate the item and Willy needs a bit more room than this to avoid contact with the guardian. This means he hits the static guardian before collecting the item losing a life and so never manages to collect it. The official patch was to simply remove this guardian but I have chosen not to use it. The guardian graphics and items are cleverly designed to give the appearance of the guardian holding them and Willy would need to snatch them from their hands so in my opinion, leaving a gap where the guardian used to be and the item seemingly floating in mid air just doesnt look right, in particular this is the only room where Willy has to lose a life to collect one of the items and I believe that it not what he intended. I have chosen to re-position the four guardians so that all of the items can be collected without any life loss. I have also made further modifications to this room which I will describe later in this document

It turns out that Software Projects were not aware (as far as we know) that these bugs existed and it was only when they announced a competition to see who can be the first to correctly answer the question How many items does Willy need to collect to complete the game? were they to be made aware of the issues. 
The competition winners were two people who had hacked the game, studied the code and discovered that it could not be completed without making some modifications to the code in these areas.

With these four modifications in place it was made possible to complete the game. But I wanted to go further, for there were many more bugs and oddities which were not so widely known or at least not so frequently talked about:

The 'shy' item in The Swimming pool 
Upon entry to this room you would hear the sound effect that tells you that an item has been collected and Willys item count does indeed increment by one but the item is never seen. As far as I am aware, no official fix was created for this as at the time as it didn't really affect the ability to complete the game. However, most would say that since the author went to the trouble of creating an item to be collected here then surely he must have intended for it to be seen. Changing the colour of the rope to blue allows the item to be seen and thus collectable

All Along The (top of the) Watch Tower
Of course it's common knowledge that in this room Willy can exit the top of the room which means he ends up in The Off Licence. .. perhaps he was thinking that there was some kinda way outta here... but alas that wasnt supposed to happen and by lowering the conveyor at the top of the screen Willy is free to jump along it to his hearts content should he feel the need to do so

Rescue Esmerelda 
Here Willy was able to jump out of the top of the room by climbing up into the conveyor but he would end up in Ballroom East. There seems no reason as to why the author would intentionally create such an illogical exit and when he does reappear here he is halfway embedded in the floor, and so it is assumed that it is another bug caused by having the conveyor set one row too high. There were a few options available and in one version of JSW called the 2015 Bugfixed Version a ceiling was placed in this area to prevent Willy escaping in this way, in another version The Nightmare Edition Willy can freely exit the room here and ends up in The Belfry as featured in JSW2. In the end I chose to make a minimal alteration by simply lowering the conveyor by one row so the exit is now out of reach.

Conservatory Roof Refurbishment 
Having resolved the problem with the uncollectible item here there are a couple of other things about this room which, to me at least, seems to be looking somewhat underdeveloped. Two other main issues are, as I mentioned earlier, Willy has to make a kamikaze jump into the item on the far left but in doing so makes an unavoidable collision with the static guardian. I believe that this was not entirely part of the authors game plan, it seems a little too coincidental to me that this is the only room where Willy has to lose a life in order to collect an item. I have made some hopefully subtle changes to the room to enable Willy to collect the item safely without removing too much challenge from the room. 
In addition to this, there is a plain white block in this room. When first playing this game I thought this would kill Willy on contact but it turned out to be merely a conveyor. I believe that the author intended to develop it but due to time constraints never got round to it. I have replaced the plain white slab with a more in keeping looking conveyor graphic

The Nightmare blob in the room 
Another odd looking graphic that turned out to be a conveyor is in The Nightmare Room. Originally it has the appearance of a garish green and blue flashing blob which looks like its worth avoiding. Making some modifications to the code has now given it a more respectable appearance. 
Elsewhere in this room it appears that the ramp leading to the left hand exit looks a bit untidy, this is because theres a small amount of game corruption here. 

Second helpings 
Whilst taking a stroll to The Beach Wily encounters an item in the sand. When he collects it the item count increases by 2 meaning that he seems to have collected 2 items at once here. I have removed the additional item and placed it elsewhere in the game under another graphic.

Blue haze?
Everyone who has played JSW will have noticed that when Willy enters certain Blue rooms some of the guardians have an odd looking pale aurora around them. Arguably this wasnt intended. I have corrected this now, there were a few different fixes available here, on Richard Dymonds website skoolkit.ca there are a list of POKEs that you can enter to turn off the bright attribute of the guardians thereby eliminating the glow around them. However I chose to implement a different fix as it meant that the guardians could keep their intended attribute values

Saw subject 
A comparatively minor issue where Willy visits the Cuckoos Nest is the saw which seems to traverse the room without turning around. I have made the necessary corrections and it now faces the correct way.

The elephant in the room 
When Willy is walking into a room with limited height, in particular, approaching a gap which is only half his height it is possible for him to continue walking through it up to a point, trouble is, when he has to turn round and go back he cant, he becomes embedded in the cells and the game has to be restarted, this issue is encountered when negotiating the elephant in Dr Jones Will Never Believe This. I have now corrected this issue so he cannot get into any such spaces but this in turn caused a problem in another room

The Forgotten Abbey
Having resolved the aforementioned issue it made the item in the Forgotten Abbey inaccessible as originally, Willy needs to briefly and ever so slightly jump through the corner of an earth cell. Looking at the layout of the room I managed to resolve the issue by changing the platform on which he stands to access the item.

Crazy Conveyors 
The conveyor graphics in the Tool Shed, West of Kitchen, The Wine Cellar and the Nightmare Room are all corrupt and they dont look as they should. Using the available patches I have corrected them and now they look much better

Even crazier clock 
Willys mission of course is to collect all the items in and around his mansion by no later than 12 midnight, only there was a problem with that, the in-game clock shown at the bottom of the screen hasnt been functioning quite as it should and come midday am is still showing and doesnt change to pm until 1 in the afternoon. Furthermore at the stroke of midnight, when the game is supposed to end the pm stays in place and the game continues to run until 1 in the morning. This took some doing but a fix was eventually found and the clock is now a little healthier

More than enough time? 
Sticking with the clock issue for the moment, to actually fail his mission and not be able to collect all his items in time the player would have to be playing for a very long time. Even though the game clock runs two thirds quicker than real time (about 23 seconds to one minute) this would mean you would have to have taken 8 hours to try and complete the game assuming that Willy has not lost all of his lives by then. With this in mind I decided to make the clock a little more challenging and it now runs at twice the speed but hopefully not so fast that it would pose too much of a challenge to the player

Unintended exits
The Roof and The Beach both feature ropes that Willy is not supposed to be able to reach the top of as there is no room above these rooms. The author did make put a block in the way preventing Willy reaching the top of the rope. However, when the rope has swung to the far left or right Willy can, if he times it right, make a jump out of the top of the screen. When he does this he reappears in the bottom of the same screen. A fix was found to lower the limit at which point Willy is stopped from climbing

The helpful (?) bug 
One of the (arguably unhelpful) quirks of JSW is that if Willy, for example drops out of a room and has no safe platform to land on in the room below he loses a life but rather than putting Willy back to his previous position his starting position is at the beginning of the room he entered (or fell into) so this means that he will continue falling to his death until all of his lives are gone. However, when making his way up to Under the Roof from A Bit Of Tree Willy cannot fall out of this room for if he does he loses a life but is then placed back onto the platform he was standing on preventing him from losing all of his remaining lives. Rather than removing this bug I thought about putting it in other areas of the game where it might prove useful, Entrance to Hades for example. However this was to prove beyond the scope of my coding knowledge and decided instead to just remove the bug. Even though removing it serves no purpose other than to make the game harder but a bugs a bug and it had to go

Code entry screen
Upon loading the game the player is taken to a code entry screen where one enters a code from the supplied card to enable the game to run, if you look carefully at the coloured squares you will see that some of them are brighter than others as the Bright attribute has not been set for the 3rd and 4th square, a fix has been found for this.

Listen very carefully  I shall play this only once
When starting the game Willy goes about his business to the tune of If I were a Rich Man. Youd be forgiven for not noticing it at first but the 'beep' is not actually played.  All of the notes in the in-game tune consist of at least 2 beeps.. Most people have probably figured out by now that the Sinclair ZX Spectrum cannot beep and process code at the same time so the tune consists of lots of little beeps allowing processing to take place between each beep. Those with a keen ear would notice that the very first beep is not played until it loops round again. 

The Master Bedroom
When Willy enters this room Maria will show him the door as he climbs the ramp to the upper mezzanine, however, she also does this when he jumps in the air.  Some say this is a bug or at least some sort of anomaly. Whether this was a bug or not is not entirely clear but I can see the logic in this and i feel that it enhances the game without making it look too obvious.

There are a number of other little tweaks I have been able to implement to the game:
The long established interface 1 issue for example, way back when we were loading games into computers using cassettes the more privileged among us possessed the Interface 1 peripheral, but this caused a problem when using it with JSW as it locked up the game whenever you tried to pause it, a fix was found to resolve this which I have put in just for the hell of it. 

Also when pausing the game the conveyor in To The Kitchen / Main Stairway starts flashing and the earth cells in Nomen Luni which are normally flashing seem to stop when the game is paused. A fix was found for this which I have put into the game. 

Untidy Willy
During gameplay as Willy goes about his travels his appearance can get a little ..err.. scruffy..
This is particularly noticeable for example where he is in a non-black backgrounded room and / or making a jump or moving up or down a ramp Willy can often be seen to be flickering black or half of his body is briefly left behind. A rather clever piece of code was developed for this and now Willy's animation is vastly improved


Willys last movements
A comparatively minor issue, when starting the game for the first time after loading Willy is in the bath facing the tap and the toilet, during gameplay his animation sequence is one of three positions as he walks and jumps. When starting the game again he returns to the bathroom but the direction he was facing and his last animation held before the previous game ended is remembered so in some cases he would start the game facing away from the tap. Not exactly a big deal but nonetheless it needed tidying up so with some help I put a fix in place for this.

No more lazy Willy
Ive made another modification which, for the most part probably wont be noticed by the player during normal gameplay. This modifications is mainly for the benefit of anyone wishing to see the game in an editor or if they are using cheat POKEs that, for example, enable Willy to jump out of the top of the screen. What I have done is remove all exits that teleport Willy to The Off Licence and instead Willy appears at the opposite end of the same room so now the only way Willy can get to the Off Licence is to make his way on foot (okay yes you can still use the WRITETYPER Easter egg)



Replacing the 'lost' rooms
(spoilers follow)

Another part of my project was to look into the issue of the missing rooms. For those who dont know, Matthew Smith originally designed JSW with the intention of creating sixty-four rooms but the end product only contained sixty. This was because during game development the graphic data containing four of the rooms became corrupted. Due to time constraints he was not able to rebuild the rooms in time for the game to be released.
In an effort to provide some sort of idea as to what it might have been like to play the game with all of the rooms in place I have created four rooms and placed them in the corrupted memory area where the original rooms would have been. 
What the authors original room designs were like no one really knows but he has dropped a few hints as to where they might have been located. With this in mind I created The Bunker which can be accessed to the right of the Tree Root under Under the Megatree (which I nearly called it) enter the room carefully!
In an interview with Matthew Smith he commented on the rooms that got deleted and dropped a hint that suggested that they would have been in the MegaTree complex. So I placed the other three rooms here. Navigate Willy to the Tree Top and head left to Out on a Limb and left again (careful how you enter this room) Willy finds himself in Special Branch. On the other hand (or branch if you will..) head right of the Tree Top and Willy finds himself on One Flew Over The Cuckoos Nest (you might need to dim the screen a little), not quite as mad or entertaining as the film but you get the idea. And of course what is a tree without a treehouse? and how does one get to it? Climb the rope of course

Earlier I touched upon the subject of the game ending at midnight, even with the fix in place all that happens is that the game aborts and the player is taken back to the title screen so there is no game-over sequence, no foot, no barrel and no Willy .. something of an anti-climax if its something that the player had been waiting for. In The Nightmare Edition this was added in with a couple of extras thrown in. Taking inspiration from this I decided to follow suit and include a similar but slightly simplified sequence, largely due to my lack of coding knowledge but also because I didnt want anything elaborate so as to remain in keeping with the original version.

In the original, the 2015 Bugfixed version and TNE the game over sequence is kept the same where Willy makes his traditional mad dash for the lav having made his way to bed, in my version I have also kept this sequence in place, however I have added a little extra sequence: As soon as he has launched himself into the great white abyss the clock speeds up until midnight comes then, before going back to the title screen willy gets his revenge on Maria, I wont spoil it any more than that. 





-	-	-	-	-	-	-	-	-	


Acknowledgements
Credits, kudos and copious thanks to the following people and sources

Firstly, there are two other enhanced versions of JSW which keep the original room layout which I have referred to in enabling me to make all the above changes
In 2015 the JSWMM community created the 2015 Bugfixed version, playing this game gave me inspiration to create my own version having seen all of the improvements that had already been made in this version, one such example was the lowering of the conveyor in The Watch Tower to prevent the unintended teleport to the Off Licence
Later on The Nightmare Edition was created. Although still featuring the original JSW game engine this game had been extensively reworked featuring lots of new rooms, new graphics and new puzzles and is as challenging as it is addictive without being too offputting for those determined enough to have a go at completing it.
Looking at both of these versions enabled me to gain more of an understanding as to how the game engine functioned and helped weed out the little bugs that were present in the original version

Thanks to Richard Skoolkid Dymond and his excellent disassembly of JSW which shows in intricate detail the inner workings of the game which can be found on his websites: http://skoolkit.ca/disassemblies/jet_set_willy/index.html and http://skoolkid.github.io/jetsetwilly/index.html for those who prefer to work in hexadecimal. 
These websites also contain not only a list of most of the various bugs and quirks found in JSW but also the patches required to correct many of them.
The ones I have used from his websites include:
Revealing the shy object in the Swimming pool
Removing the helpful bug in Under The Roof
Correcting the orientation of the saw guardian in The Cuckoos Nest
Lowering the maximum height Willy can climb up the rope in The Beach and On the Roof
Theres also a whole bunch of trivia and other interesting facts which I have used in my enhancements and to vastly improve my knowledge of assembly language. 

Thanks to The JSWMM community http://jswmm.co.uk namely:
Ian IRF Rushforth who found a few more bugs, provided a whole load of tips and hints and also plenty of corrections including :-
The coding which provides the corrections to the clock and enables it to change to pm at 12 noon and am at 12 midnight and also ends the game at this point instead of 1am, the coding that corrects the flashing conveyor and non-flashing graphics in To The Kitchen Main Stairway and Nomen Luni respectively, developed the patch which prevents Willy from walking leftwards through head-height earth cells, provided the patch to eliminate the blue glow around the guardians in the non-black backgrounded rooms, provided the fix that retained Willys default starting position so that he is always facing the tap regardless of he was doing or which way he was facing in previous game sessions and also the alteration that enables that first note to be played when starting the game
The coding required to correct Marias hand gesture timing was supplied courtesy of Stuart Brady who, along with Ian Rushforth also helped in making the corrections to the ramp in The Nightmare Room

To Norman Sword who, with Ian Rushforth who provided the really useful chunk of code which greatly improves Willys appearance during motion as I mentioned earlier

Daniel jetsetdanny Gromann came up with the Z80 instructions that enable the clock to run at double speed in TNE and has kindly given me permission to use it in my version 
Daniel has also provided me with some useful links to other websites that have proven useful:
http://jswremakes.emuunlim.com/faq.htm or the text version 
http://mdfs.net/Software/JSW/Docs/faq/remakes.htm
also http://pustakalaya.org/wiki/wp/j/Jet_Set_Willy.htm

Thanks to Andy Spider Ford. For providing jswmm.co.uk and also for the detailed instructions in his Speedlock tutorial providing help in making the high-speed loading version and the additional patches to bypass the delay between loading and the start of the game. 
Andy also came up with the idea of using the item from the West Wing Roof, this one was chosen as it was smaller and therefore easier to draw but also it was a mid air item which looked better than other items when placed there and also discovered and corrected the minor oddity with the colour code screen

Thanks to John Elliott and his excellent and easy to use program JSWED 2, a room and graphics editor for JSW which I have used extensively when creating and editing the new rooms and sprites which I used to make the amendments to Rescue Esmerelda. 
JSWED 2 also has a pile of other features to make extensive changes to the game layout including the fix that I mentioned earlier to keep Willys starting position the same at the start of each game regardless of which way he was facing in previous game sessions and also a facility to make sure any room containing a rope always draws the rope last which makes creating and editing rooms much easier. 
Also included in his program is a facility which converts your game to a 128K version where a mind-boggling 256 screens can be created, something I am looking at doing in another project which Ill release some time later

Thanks to Jonathan Needle for creating Spectaculator which has been my main tool for playing, testing, debugging, assembling and re-assembling the game code

Claus John for providing the website http://ww.zx-modules.de where I have been able download a bunch of useful programs for editing the game code and also to assist in creating the high-speed loading version and an in-game loading screen.

Also thanks Gerrard Sweeney and Nick Humphries and their website www.the-tipshop.co.uk where I found a whole load of other info which saved me trawling through dark and scary cupboard for my old computer mags

To my ancient and barely functioning laptop which, in spite of its extremely fragile power supply cord, worn out battery, internal fan screaming like a hairdryer on steroids and flickering screen somehow still soldiers on

And finally to the man who started it all, Matthew Smith, author of Jet Set Willy and Manic Miner, which, without these games I would probably have had more sleep, more hair and possibly a little more sanity (none of which I really miss if i'm honest)


one last thing... 
I have spent as much time as i can afford making this readme as factually correct and easy to understand as possible but there will inevitabally be errors, if you feel the need to tell me where i have gone wrong i tend to frequent the forums at jswmm.co.uk under the username metalmickey, look for my topic and feel free to provide feedback...



*		*		*


Weve come a long way since software houses were struggling to sell computer games for 5.99 in 1983 and battling against piracy created by those on the make by copying their tapes, back then the nearest thing to free software was grabbing a copy of Sinclair Programs and typing out one of their listings but even that was only after paying for the magazine .. and as for loading a commercially produced game, that involved using a cassette tape and player and was notoriously unreliable. 
So if you was to tell a hard-pressed software producer back then that in the future you could store some 10,000 1980s computer games on a chip no bigger than a 5p coin and tape loading errors would never appear again and that millions of people are freely distributing top quality software that they have worked hard on and to only expect thanks and maybe a few quid in voluntary donations in return to cover their expenses they would probably think you have taken one too many pills

But fast forward to the present and here we live in a world where whilst we still have games for sale on high end PCs and games consoles for up to ten times the price that we paid for back then on the flipside of the coin we have millions of volunteers, enthusiasts and hobbyists the world over creating multiple software packages and even entire operating systems and available for free download without even needing to leave your armchair  who knows where we will be in another 30 years .. the mind boggles but as long as there are generous, enthusiastic and cooperative people in the world like those I have been in touch with then the future of computing will surely remain positive

Carry on coding :)

