Jet Set Mini

==============================================
Jet Set Mini

by Ian Rushforth & Andy Ford |

(jswmm.co.uk)

with music by Richard Hallas
==============================================

‘Jet Set Mini’ is a redesign of Matthew Smith’s classic ZX Spectrum 48K game ‘Jet Set Willy’. It can be played on a real Spectrum, on the Sinclair ZX Spectrum Vega/Vega+ or on a computer, game console or another device using a ZX Spectrum emulator.

In ‘Jet Set Mini’, Willy’s original mansion has been somewhat reduced in scale. But size isn’t everything! Much of the code which was freed up by paring back the layout has been recycled, in order to insert a whole host of special effects into the game!

Many of these changes are implemented via tools known in the trade as ‘Patch Vectors’, which are called up on a room-specific basis. There are also a number of generic modifications and enhancements to the game engine. However, the essence of this 8-bit, 48K game will be very familiar to connoisseurs of ‘Jet Set Willy’. We hope you enjoy it!

Contents

I. Acknowledgements and thanks

II. Instructions

III. Game history

IV. Technical novelties

V. Bug fixes

VI. The legal bit

VII. Closing remarks

———————————————————————-

I. Acknowledgements and thanks

The authors would like to express their gratitude to:

– Matthew Smith, creator of the original ‘Jet Set Willy’ and ‘Manic Miner’.

– Dr Andrew Broad, for his laterally-inverted version of ‘Jet Set Willy’, titled ‘ylliW teS teJ’, which formed the starting point for the development of ‘Jet Set Mini’. Thanks also to Andrew for his published technical documents (http://www.oocities.org/andrewbroad/spectrum/willy/), for his advice during the early stages of development of ‘Jet Set Mini’, and for establishing and managing the Manic Miner & Jet Set Willy Yahoo! Group (https://groups.yahoo.com/neo/groups/manicminerandjetsetwilly/info).

– John Elliott, for his excellent JSW Editor (JSWED, http://www.seasip.info/Jsw/jswed.html), which was the main tool used to create the game, and for JSWED’s accompanying documentation. John’s ‘Adjacent Ropes’ patch has also been implemented, as well as a laterally-inverted version of a patch suggested by John to ensure that Willy’s facing direction and frame of animation are reset at the start of each game.

– Richard Hallas, for scoring the ‘Radetzky March’ (originally composed by Johann Strauss Sr.); the introduction to the March is used as the title screen tune, and the main part of the March is used as the in-game tune. An earlier, shorter version of the ‘Radetzky March’ was scored by Richard for Philip Bee’s game ‘Jet Set Willy Ivy’. Richard’s document ‘A Miner Triad’ (http://hallas.net/Software/music.htm) is an invaluable guide to creating music for JSW/Manic Miner games. His input to ‘Jet Set Mini’ marks Richard’s return to the JSW/MM scene after a hiatus of almost twenty years!

– Richard Dymond (‘SkoolKid’), for his complete Jet Set Willy and Manic Miner disassemblies (http://skoolkid.github.io/jetsetwilly/ and http://skoolkid.github.io/manicminer/), which were absolutely instrumental to the implementation of numerous code modifications and optimisations in ‘Jet Set Mini’.

– Geoff Eddy, for his Patch Vectors, many of which have been used in ‘Jet Set Mini’ in modified form. Geoff’s detailed disassemblies of his Patch Vectors, and his comprehensive documentation of the ‘Geoff Mode’ game engine, were also extremely useful when adapting patches for our purposes. Archived versions of these webpages are accessible via the Wayback Machine:
(https://web.archive.org/web/20080511161939/http://www.cix.co.uk/~morven/jsw/patches.html),
(https://web.archive.org/web/20030818082654/http://www.cix.co.uk:80/~morven/jsw/geoffmode.html).

– Daniel Gromann, for creating some of the Patch Vectors in the game; specifically the colour-changing guardians in the rooms ‘The Mansion Security Guard’ and ‘Ground Floor Landing’, and the ‘Easter egg’ message in ‘First Landing’. Daniel and Ian Rushforth also co-created the ‘Swooshing Arrows’ and ‘Shimmering Arrows’, earlier incarnations of which appeared in the Special Edition of Daniel’s excellent game ‘Willy’s New Mansion’, and which now shoot through the Ballroom screens in ‘Jet Set Mini’. Daniel carried out extensive playtesting of ‘Jet Set Mini’ at various stages of the game’s development, and his JSW Central website (www.jswcentral.org) is a rich source of information on JSW & MM games.

– Stuart Brady, for his Cell-Graphics Bug Fix, and for his helpful explanation of the way that the various ‘screen buffers’ work in the JSW game engine (primary and secondary buffers, for both the display and attribute files). A deep insight into how the screen buffers operate was essential when devising many of the Patch Vector effects in ‘Jet Set Mini’.

– Steve Marsden and David Cooke, for a number of sprites from their game ‘Technician Ted’. The character font used in ‘Jet Set Mini’ was also sourced from ‘Technician Ted’.

– Peter Harrap, for a couple of sprites from his game ‘Wanted: Monty Mole’.

– Alex Cornhill (‘Sendy’), for unwittingly inspiring ideas for new block types, in messages posted on the Manic Miner & Jet Set Willy Yahoo! Group more than a decade ago!

– ‘Norman Sword’, for his work on fixing the ‘Jagged Finger’ and ‘Delayed Attribute’ flaws in the original JSW game engine.

– Jonathan Graham Harston, for his ‘Full Z80 Opcode List Including Undocumented Opcodes’ (http://www.z80.info/z80oplist.txt), for his ‘Jet Set Willy’ related documentation (http://mdfs.net/Software/JSW/) and for his elegant Pause Bug Fix.

– James Moxham, for his ‘ZINT Z80 Interpreter’ (http://www.z80.info/z80code.htm), which is a highly informative introduction to the Z80 instruction set that was frequently referred to during the development of ‘Jet Set Mini’.

– The authors of Binary Hex Converter (http://www.binaryhexconverter.com/), which was the standard tool used to convert values back and forth between the decimal, binary and hexadecimal systems. The Bitwise Calculator at http://www.miniwebtool.com/bitwise-calculator/ was also a useful tool.

– The ZX Spin team, for their ZX Spin (http://www.zophar.net/sinclair/zx-spin.html), which was used by Daniel Gromann in playtesting.

– Jan Bobrowski, for his Qaop/JS HTML5 ZX Spectrum emulator, which was used by Ian Rushforth in playtesting.

– Günter Woigk, for his zxsp version 0.8.pre27 (ZX Spectrum emulator for macOS: http://zxsp.blogspot.co.uk), which was used by Richard Hallas to create the music in ‘Jet Set Mini’. Richard also used Z80Em (an emulator for RISC OS: http://www.borcherds.co.uk/murklesoft/riscos/Z80em.html) and FUSE (Free UNIX Spectrum Emulator: http://fuse-emulator.sourceforge.net/) during the process of transferring the music file.

– Claus Jahn, for his ZX-Modules (http://www.zx-modules.de), particularly ZX-Blockeditor which was used by Andy Ford during the creation of the loading and title screens.

– Ian Rushforth would like to give special thanks to Andy Ford, for his extreme patience towards the end of the development of ‘Jet Set Mini’, particularly for the process of repeatedly adding the BASIC loader to the final game file (following the creation by Ian of several ‘Final Final’ builds!).

———————————————————————-

II. Instructions

The object of the game is to guide Willy and collect all of the flashing items scattered around his mansion, avoiding the moving and unmoving guardians and the stationary nasties which may kill you (as will falling from an excessive height). With all the items collected, the player needs to go to ‘The Master Bedroom’ where Maria will no longer be blocking access to Willy’s bed. This has to be done before the in-game clock reaches midnight, or before Willy runs out of lives. An extra life will be granted for every ten items collected.

Use O-Left, P-Right (or a combination of keys from the top row of letters) and SPACE or any of the letters from the bottom row to jump.
A-G pauses the game; any other key unpauses it.
H-ENTER/RETURN toggle the music ON/OFF.
Pressing SHIFT+SPACE together at the same time abandons the current game.

There are also a couple of locations where a novel key combination has been introduced via a Patch Vector, to free Willy from a ‘sticky’ situation if he gets stuck on a conveyor. Press the X, O and R keys simultaneously to activate this.

‘Jet Set Mini’ has been fully playtested and it is possible to complete the game, before an in-game time of 8:15 am, without losing a single life.

———————————————————————-

III. Game history

‘Jet Set Mini’ started off at the end of January 2016 as a simple ‘builder’ base file for an article which Andy Ford was writing at jswmm.co.uk, on how to add a Speedlock loader to a JSW (or Manic Miner) 48K game file. Thus the first incarnation only featured 12 rooms, and was initially intended as ‘space filler’ for the tape file (to be replaced by the builder’s own data), rather than a stand-alone game in itself.

However, after a bit of tinkering about in the Contributor Lounge of jswmm.co.uk, the ‘Jet Set Mini’ project started to take on a life of its own. It now features 36 rooms, 100 items to collect, and hordes of guardians (many of which are taken from the original ‘Jet Set Willy’, some of which are ‘borrowed’ from the game ‘Technician Ted’, and a couple of brand new eight-legged sprites have been created by Ian Rushforth). There are also numerous visual, audio, static and dynamic special effects scattered throughout the game.

The eventual release of ‘Jet Set Mini’ in July 2017 means that the project has had the gestation period of an elephant! (An unbelievable pink one, perhaps?) Much of the delay was down to a combination of Richard Hallas’ expressed desire to complete his earlier score of the ‘Radetzky March’, with his extremely busy work schedule. Whilst awaiting Richard’s contribution, “The Devil found work for idle hands” and Ian Rushforth devised an abundance of special effects that ended up in the game. So as well as eventually supplying the musical score, Richard’s involvement inadvertently gave rise to a considerable enhancement of the project! (Richard apologises for creating the long delay, but is pleased that something positive came out of it!)

———————————————————————-

IV. Technical novelties

Amongst the innovations in ‘Jet Set Mini’ are some novel sound effects, screen flash sequences, printed messages/features, brand new block types, and guardians which change attributes or follow unusual trajectories. These have been tailored to suit the rooms in which they take place, in order to enhance the atmosphere of Matthew Smith’s classic game, and increase the challenge level without making the game TOO difficult to complete (we hope?).

Many of the game’s special effects are implemented on a room-by-room basis, via tools known as Patch Vectors – there are two basic variants of these: ‘Room Setup Patch Vectors’ (implemented once each time Willy enters a room, or when he is ‘respawned’ within the room after losing a life), and ‘Main Loop Patch Vectors’ (implemented repeatedly during each ‘tick’ of the game, i.e. every time that the main loop of the program is executed whilst Willy is in a particular room).

‘Jet Set Mini’ is probably one of the most Patch Vector-intensive JSW games published to date. However, there are also many room-specific special effects that do not rely on Patch Vectors, but which exploit existing ‘quirky features’ of the JSW 48K game engine (such as combined block types, ‘invalid arrows’ and ‘invalid ramps’). This is true of everything that occurs within the West Wall triptych of rooms, for example. (If you know what’s going on with the Barrels in ‘Halfway up…’, then “Answers on a postcard please?”!)

There is also an ‘invalid rope’ (whereby the x-coordinate of the top segment of the rope lies outside the usual range of 0-31) present somewhere in the layout. To the best of the authors’ knowledge, this is a new and innovative feature for a published JSW game. (N.B. To allow Willy to examine this feature more closely, you could try using POKE 59471, 15 or POKE 41372, 27 [leave the room in question and re-enter, if entering a POKE dynamically] – but surely that would be ‘Cheating?’…)

As previously mentioned under ‘Instructions’, there is a brand new X-O-R keypress combination in ‘Jet Set Mini’ which can occasionally be used to free Willy from a ‘sticky’ situation. XOR stands for ‘eXchange On-off / Reverse’. This particular Patch Vector edits the conveyor definition in the current room buffer – reversing the polarity of a standard ‘left-right’ conveyor, or toggling the status of a ‘sticky’ conveyor between on and off. The same logic gate is applied in both cases to implement this (can you guess which one?).

Other ‘global’ changes to the game engine have been introduced. For instance, a standard JSW 48K in-game tune comprises 64 notes (requiring 64 bytes of data), but in ‘Jet Set Mini’ this has been extended to 256 notes (allowing Richard Hallas to score an extended ‘Radetzky March’). Another novelty is that the INK colour of the room name printed on the status bar is now determined on a room-by-room basis, to complement the border colour settings. Various tweaks have been made to original JSW features, such as the scrolling message effect on the title screen, and items that cycle through eight INK colours rather than four (an optimised variant of a ‘Geoff Mode’ feature).

Of course, one of the most notable changes is the fact that the entire layout is laterally-inverted, based as it is on the mirrored JSW game ‘ylliW teS teJ’ from Andrew Broad’s ‘Party Willy’ box-set. However, with regard to the guardians in ‘ylliW teS teJ’, only arrows and vertical guardians were perfectly laterally-inverted. In ‘Jet Set Mini’, true lateral inversion (i.e. both spatial and temporal) has also been achieved for horizontal guardians and for ropes.

In some rooms, formations of guardians of the same type have been made to animate out-of-sync with each other, thanks to some low-level bit-fiddling, e.g. the various leg segments of the Attic Centipede (or is it now a Millipede?), which as a result displays a more ‘naturalistic’ crawling motion. ‘Jet Set Mini’ is also the first JSW48 game to feature 128 distinct ‘Guardian Classes’ (#00-#7F; Class #7F previously being out of bounds because of technical limitations which have now been overcome).

There are many more additional features implemented that haven’t been listed here – to find out more, you’ll just have to play ‘Jet Set Mini’ for yourself and see them in action! (Or in some cases, hear them – you’ll miss a few tricks if you play on mute!)

———————————————————————-

V. Bug fixes

A number of bugs that were present in the original JSW game engine have been fixed in ‘Jet Set Mini’, including:

– The Cell-Graphics Bug. The effects of this can be seen in the original ‘Jet Set Willy’, where it affects the conveyors in several rooms (e.g. ‘Tool Shed’). During the process of drawing the current room, a cell’s bitmap can become corrupted if that cell’s colour-attribute byte matches with a graphic-data byte which precedes it in the room data. The fix for this bug means that all the original JSW graphics in ‘Jet Set Mini’ are rendered as Matthew Smith intended – except of course that they are laterally-inverted! – and any new cell graphics that have been created are immune from the effects of the bug.

– The ‘Adjacent Ropes’ Bug. In the original game engine, a rope’s data ‘spilt over’ beyond the eight bytes that are normally allocated to each entity in the ‘guardian buffer’. Therefore any guardian (or another rope), which immediately followed on after a rope in a room’s list of guardians, could be corrupted by the preceding rope. The ‘Adjacent Ropes’ patch prevents this ‘spillover’ of a rope’s data from occurring, so that guardians (or another rope) can safely be placed immediately after a rope in a room’s guardian list, without corruption.

– The Pause Bug. An error in the original main loop meant that the program would ‘freeze up’ if the game was paused and unpaused whilst certain hardware was attached to the Spectrum. Some patches for this bug have been known to cause even more problems than they fix. The fix used in ‘Jet Set Mini’ does not have any such side effects.

– The Missed Note Bug. In the original ‘Jet Set Willy’, the very first note is missed out at the start of the first rendition of the in-game tune, each time a new game is commenced. This happens because, during each pass through the game’s main loop, the variable which acts as an index of the progress of the tune is incremented before a note is selected to be played. By initialising the value of the ‘Music Note Index’ to a value of 255 (#FF in hexadecimal) at the start of each game, instead of to zero, the missing note has been restored.

– The ‘Jagged Finger’/’Delayed Attributes’ imperfections. These flaws are caused by the fact that the copying of the display and attribute buffers, to the display and attribute files, can instantaneously fall ‘out of sync’ with the physical updating of the screen’s ‘raster’ scan lines. As a result, moving sprites can momentarily break up and flicker, and can partially (or, in the case of arrows, entirely) be rendered in the wrong colour attribute for a brief but perceptible moment. By changing the sequence in which elements of the display and attribute buffers are copied across, these effects can be greatly reduced or eliminated.

– The four ‘classic’ bugs in the original JSW game data (including the infamous ‘Attic Bug’). In all four cases, the fixes implemented in ‘Jet Set Mini’ are rather different from the solutions that were provided by Software Projects in their officially-released POKES. (Those four ‘official’ POKES were derived from the hackers who first wrote in to the publishers to say that they had used them to complete ‘Jet Set Willy’, and so cannot really be considered as ‘canon’.)

– A couple of less-infamous bugs in the original JSW game data have also been fixed. There was a ‘self-collecting item’ in ‘Swimming Pool’, which was automatically collected as soon as Willy entered the room, because the background INK setting of the room was set to white (items are collected if the room cell in which they are located contains white INK – normally signifying that Willy has touched them). After editing the background INK colour for the room, the ‘auto-collection’ no longer occurs (although when you see the positioning of the item within the Pool in ‘Jet Set Mini’, you might wish that it did get auto-collected!). There was also a ‘double item’ in ‘The Beach’ in the original game (i.e. two items located at the same coordinates within the room), which have been separated out in ‘Jet Set Mini’. (In fact, if this had not been done, then one would have ‘auto-collected’ the other, as a consequence of the implementation of items that cycle through eight INK colours, including white!)

– Great care has been taken to reduce the potential for ‘Infinite Death Scenarios’ (i.e. where Willy meets an unavoidable fatality upon entry to a room, which then occurs repeatedly until all his lives have expired) – especially when such a scenario could not easily be foreseen by a careful player, or would otherwise be considered unfair. Similarly, an attempt has been made to avoid situations where Willy might get ‘stuck’ (with no means of escape, not even by sacrificing a life; thus forcing the player to abandon the current game). In some cases, avoiding such scenarios has entailed inserting ‘invisible Fire cells’ at the top or bottom of rooms, to prevent Willy from jumping or falling from one room to the next, where to do so would otherwise bring the game to a premature end. (So if you encounter a sudden and unexpected – but singular – fatality, consider that it might be as a result of the authors ‘being cruel to be kind’!)

All the preceding entries concern attempts to eliminate bugs or flaws from ‘Jet Set Mini’. Conversely, a new bug was unintentionally introduced during the development of the game (relating to an erroneous re-entry point into the program’s main loop). This was discovered during playtesting, when it was found to be the root cause of a spectacular new ‘quirky manoeuvre’. Since this accidental glitch turned out to be so impressive (if you discover it whilst bouncing around the mansion, we hope you’ll agree!), and because it is harmless enough (in fact, it can actually be helpful to Willy in certain circumstances), it was decided to leave this bug in situ!

On the wider subject of ‘quirky manoeuvres’ that are permitted by the JSW game mechanics, this is one of the more contentious aspects of JSW games. Whether they arise from ‘bugs’ in the code, or are considered ‘interesting quirky features’ to be exploited, can become a matter of heated debate! Some players relish the ability to perform manoeuvres that are seemingly in defiance of ‘Willy’s Laws of Physics’; whereas others find them rather off-putting, particularly if a game is designed so that it cannot be completed without advance knowledge of such tricks.

‘Jet Set Mini’ attempts to strike a balance in this regard. Bug fixes that are available, which would preclude the use of quirky moves, have not been implemented in the game (why spoil the fun for those who wish to use them?). Consequently, there are a number of places in the layout where the player may find shortcuts by utilising a few quirky manoeuvres (including several brand new ones!). However, it is quite possible to complete the game without relying on these ‘oddities’!

———————————————————————-

VI. The legal bit

‘Jet Set Mini’ is freeware, and all of its innovative elements may freely be reused in other projects. If you do so, please acknowledge their authorship.

———————————————————————-

VII. Closing remarks

We hope you enjoy playing ‘Jet Set Mini’ as much as we did writing it! Please also check out its sister project, ‘Jet Set Mixup’, released on the same day.

If you have any queries, comments or general feedback, please contact us on the email address below, or come and visit our Jet Set Willy & Manic Miner Community at jswmm.co.uk to join in with Willy-based discussions!

Ian Rushforth & Andy Ford, 21st July 2017
projects@jswmm.co.uk