Inserting patch vectors in JSW48 games

[jetsetdanny]

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:

 

https://web.archive.org/web/20031012234840/http://www.cix.co.uk/~morven/jsw/

 

https://web.archive.org/web/20030818082654/http://www.cix.co.uk/~morven/jsw/geoffmode.html

 

https://web.archive.org/web/20030701143111/http://www.cix.co.uk/~morven/jsw/geoff_dis.html

 

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 April 10, 2016 by jetsetdanny

[IRF]

It might be worth pointing out that the value '80' in 'EE 80' refers to 'Page #80' of the code, which represents the 'Room Definition Buffer' (to which each room's definition bytes - including Offsets #EE and #EF which define the destination address of the current room's Patch Vector - are copied upon entry to a room, via the routine at #8912). i.e. in the example you gave, the values of #C0EE and #C0EF are copied to #80EE and #80EF when Willy enters The Off Licence, so when the Patch Vector points HL at the values stored in #80EE, it is picking up the address specified at #C0EE-EF (this is then refreshed each time Willy enters a new room).

 

Also, I think that each room has a 2-byte chunk AND a 3-byte chunk of unused code in it, so could you have up to two patch vectors per room?

Edited July 5, 2016 by IRF

[jetsetdanny]

Perhaps. I am not aware that it has been tried before. I guess the main patch vector would have to be modified, or there would have to be two CALL instructions in the main loop to call two separate main patch vectors, each of which would work just like the one in Geoff Eddy's games.

 

Which are the unused bytes in the room data apart from ED, EE and EF?

[IRF]

Perhaps. I am not aware that it has been tried before. I guess the main patch vector would have to be modified, or there would have to be two CALL instructions in the main loop to call two separate main patch vectors, each of which would work just like the one in Geoff Eddy's games.

 

Which are the unused bytes in the room data apart from ED, EE and EF?

 

DF and E0.  I haven't checked that this is the case in every single room though.

Edited March 13, 2016 by IRF

[jetsetdanny]

They may be unused, indeed. There are question marks next to them in Arsen Torbarina's document.

[SkoolKid]

DF and E0.  I haven't checked that this is the case in every single room though.

Bytes DF and E0 are definitely unused in every room. At least in the original JSW.

[jetsetdanny]

Thanks for confirming this, Richard!  :)

[IRF]

If inserting two patch vectors per room isn't implemented, as discussed above, then other possible uses for the extra two spare bytes at addresses nnDF and nnE0 in each room could include:

 

All the single byte variables (and a couple of two-byte variables) from #85CB to #85E4 could be shifted into some of these unused addresses within the room data (and the routines which initialise, check and update them amended accordingly), thus freeing up a solid 26-byte chunk.

 

Or you could insert a 'secret' text message across the 128 bytes (64x2) at addresses DF and E0 in each room, which - if the player discovers it buried within the code and puts the whole message together - gives a hint as to how to solve a particularly tricky aspect of the game?!

 

Does anyone have other suggestions, in the pursuit of using up every last byte? :ph34r:

Edited March 14, 2016 by IRF

[jetsetdanny]

You could use these two bytes to determine some room-specific elements. In "Willy's New Mansion" Special Edition, for example, nnED is used to set the in-game tune by room and the nnEE and nnEF are used for patch vectors. If I wanted to add another element set by room using a special routine, e.g. which character Willy should be playing as in any given room, I could use one (or both, depending on the situation) of these additional spare bytes. Something to be kept in mind for the future...

[jetsetdanny]

And one more reflection about inserting two "main" patch vectors. While probably possible technically (why not?), I think it simply wouldn't make much sense. A patch vector is a subroutine, a chunk of code, which does something special in the room, and the two bytes in the room data point to where the patch vector for this particular room should be activated from (where it starts). The patch vector may include various elements, including calls to other subroutines. So, once you have been able to call a patch vector, you can make it perform all the tricks you want for this room. So you don't need a second patch vector.

 

Having said that, perhaps with two patch vectors you could save some space. You need 3 additional bytes in the main loop and 5 additional bytes for the second "main" patch vector, that's 8 extra bytes altogether, not much. And then, if you have a patch vector for room A, and a patch vector for room B, and you want to apply both of them in room C, you could do it without sacrificing any more bytes, by calling them both, I think (thinking aloud, kind of). Perhaps it's not such a bad idea, after all...