Back in 1999-2002 Geoff Eddy released four games which used a modified JSW48 game engine (by JSW48 I refer to the original game engine of "JSW", as distinct from the game engines later developed by John Elliott, known as JSW128 and JSW64). The game engine of the first three games ("J4 (The Fourth Remix)", "Willy the Hacker" and "Willy Takes a Trip") came to be known as Geoff Mode 1, and the game engine of the fourth game ("ZX Willy the Bug Slayer") as Geoff Mode 2.
One of the characteristic features of these game engines is that they use the so-called patch vectors.
As Geoff himself explained over a decade ago:
"Two bytes within the room data specify the location of a subroutine which is called every tick, after Willy and all the guardians, items and arrows have been displayed but before the room data is finally copied to the screen. This subroutine, which may be different for each room, is known as the 'patch vector', for now-forgotten reasons."
Geoff's website has sadly been offline for a while, but it can still be accessed on the Wayback Machine, e.g. at:
The above pages basically give all the information one needs to apply patch vectors. I used them in recent months while working on the Special Edition of my 2004 game "Willy's New Mansion" (to be released on 10 May, if all goes well). There were some things I had to understand before applying the patch vectors, however, and so now that I have been through it, I would like to share the information a little more "manual-style" than Geoff did in his notes, so that anyone interested can apply these changes in their own projects.
First of all, what I call "the main patch vector" (which Geoff simply calls "the patch vector", but they are all patch vectors, so I think it's good to distinguish this one from all the other, room-speficic ones) has to be called from the main game loop. Geoff does it at #89F5-#89F7. I'm not sure if it has to necessarily be in this very spot, but I have just followed what Geoff did and placed it there and it works fine.
So at #89F5 you have to insert the following code:
CD x y
CD is the CALL instruction, and x y are the two parts of the address where your "main patch vector" will be, in reversed order.
So, for example, if you place the main patch vector at #8141, the CALL instruction at #89F5 has to be:
CD 41 81
Now, in order to be able to insert the call instruction at #89F5, you need to have three bytes of unused space there. These are easy to achieve in a non-modified JSW48 game, because there is code which is unused at #8A0B - #8A25.
So my suggestion is to (for example):
- Move the code at #89F5-#8A0A three bytes down to #89F8-#8A0D (this frees up #89F5-#89F7).
- Insert "CD 41 81" at #89F5-#89F7.
- NOP out (set to zeroes) the addresses #8A0E-#8A25.
In this case, the main patch vector is set to be at #8141. This address is the beginning of unused space which extends until #81FF in an unmodified JSW48 game.
The main patch vector is 5 bytes long and it is the following code:
2A EE 80 E9 C9
So you need to insert this code at #8141-#8145. It could be inserted somewhere else where free space is, of course; in such case the CALL command at #89F5-#89F7 would have to be adjusted accordingly (to show the correct address).
Now, as quoted before, the main patch vector uses two bytes within the room data of each room to specify the location of a subroutine which will be called to achieve some special effects. These bytes are always at #nnEE and #nnEF in the room data. So, for example, they would be at #C0EE and #C0EF in "The Off Licence" in the original "JSW".
Incidentally, the preceding byte within the room data (at #nnED, so for example at #C0ED in "The Off Licence") is also unused by an unmodified game engine. It can be used for other purposes. Andrew Broad used it to determine Willy's character in each room in his game "Jet Set Willy: The Lord of the Rings". It has also been used to determine the in-game tune in each room in "Jet Set Willy: The Nightmare Edition" and in the soon-to-be-released Special Edition of "Willy New Mansion".
Now, after applying the instruction to call the main patch vector and the main patch vector itself, the value of the addresses #nnEE and #nnEF in *every* room has to be modified adequately, i.e. it has to hold the address of the patch vector meant for this room or - if no patch vector is meant for this room - it *has* to point to the address where the C9 (RET) instruction is in the main patch vector.
So in the example we are discussing, in every room where no patch vector is to be applied, the value of #nnEE and #nnEF *has* to be 45 81 - because the instruction C9 at the end of the main patch vector is at 8145. Otherwise the game will crash upon entering a room where this has not been set properly.
In the rooms where specific patch vectors are to be applied, the value of #nnEE and #nnEF should point to the addresses where these patch vectors start. So, for example, using the free space extending between #8141 and #81FF, we we could insert a patch vector which will do something special in "The Off Licence". We could place this patch vector right after the main patch vector, starting at #8146. So the value of the addresses #C0EE and #C0EF would have to be, respectively, 46 and 81, to point to the address 8146 where the patch vector for this room begins.
[EDIT: Additional info added following Ian's advice]: Every patch vector should end with a RET (C9) instruction, so that after executing it the program jumps back to the main loop. It has to happen at the very end of the patch vector, of course: some patch vector themselves call subroutines with CALL instructions within them; others may comprise several chunks of code with JP instructions in-between them. The important thing is that at the end of everything a patch vector is supposed to do there must be a return to the main loop or else the program will (most probably) crash.
This is all concerning the general rules of how to apply patch vectors. Now, what can be achieved using them, can be seen in Geoff Eddy's games. It will also be very apparent in the Special Edition of "Willy's New Mansion", where the majority of the rooms (62 out of 66) will have specific patch vectors, both copied from Geoff's games (and modified in some cases) and of my own design . In fact, I believe the Special Edition of "Willy's New Mansion" will be the most-patch-vector-intense game ever released (among the ones using the JSW48 game engine, at least).
I hope this is helpful. If you have any questions, I will try to answer them to the best of my knowledge .
Edited by jetsetdanny, 10 April 2016 - 04:21 PM.