This is a basic guide to understanding and creating patches for the Commander Keen games. It is intended to be a step-by-step guide from simple to complex patch techniques for the novice patcher. It is currently incomplete.
STEP 1: SETTING UP.
First read Ceilick's or my modding tutorial: http://www.shikadi.net/keenwiki/Ceilick ... g_Tutorial This will inform you of basic mod setup as well as get you some rudimentary patches and an idea of how things work. For graphics editing use Keengraph, this will make things easier later on.
Some basic patch utilities can be found in a special zip crated for this tutorial, TutoriTools:
The only other thing you'll need at the moment is a 'hex editor' with which you can view raw Keen code. For preference I use XVI32: http://xvi32.en.softonic.com/ Download and install and that's it!
STEP 2: COPYING PATCHES.
This is the simplest way to get patches, the Keen wiki contains over 4'000 individual example patches all annotated with perfectly comprehensible gibberish. For the most part these can be copy-and-pasted straight into your patch file. The best place to start is the main Patch Index, which lists all the pages with patches on them: http://www.shikadi.net/keenwiki/Category:All_patches
As an example, say we wish to increase the number of lives Keen has in Keen 5 when he starts a new game. We will thus be searching the wiki for 'lives' or 'new game' As it so happens the Patch:Lives page ( http://www.shikadi.net/keenwiki/Patch:Lives ) has a section with the patch we want:
Code: Select all
#Lives Keen has at game start -Keen 5
%patch $5C9B $6F6AW $0003W #3 lives
This can be copied straight from the wiki as-is. It's quite obvious here that the '$0003W' somehow stands for '3 lives'. We don't need to know how just yet, we can change this number to change the number of lives Keen has. helpfully the wiki has most of such changeable numbers color-coded in blue for quick identification.
Using this approach the novice patcher can build an entire mod based on the work of what others have done before. But there are issues; for example, if we give Keen $0010W lives he starts the game not with 10, but with 16 lives, what's going on? Maybe if we look deeper at what we're doing...
STEP 3: TRACKING YOUR CHANGES
By now you should have a patch file full of things you want in your mod or just want to test. But is there any way to track just what's going on? Yes, and it involves the 'hex editor' we downloaded earlier.
First we need to create a 'dump file' for our mod. This is a complete copy of the patched executable as it exists after CKPatch has finished doing everything. We should also have a 'clean dump', one that nothing has been changed in. To do this we will put two 'dump commands' into our patch file, one at the start, one at the end. Set up your patch file to look something like this:
Code: Select all
%ext ck4
#Clean dump
%dump DCLEAN.DMP
#Patches,
#More patches
#Modified dump
%dump DMOD.DMP
%end
Now when you run your mod two files will be created in your mod folder. These will be overwritten each time you run your mod, updating any changes. (As these are for testing be sure and remove the %dump commands when you release your mod.)
Now attempt to open the files. Hopefully you can't, the .DMP file type shouldn't be used by anything. You should get a suggested list of programs you can use that contains XVI32, if not you can browse your own computer to find XVI32 and select that. Make sure to tick 'always use this program'!
XVI32 will open with the files in two windows. It looks like a whole bunch of numbers on the left side and weird ASCII symbols on the right. This is the raw code of the Keen games. To look at our patch press ctrl-G to open the goto menu. There you can type in the very first number of your patch, in the case of our example this is '$5C9B' (You don't need the '$' but you can type it in if you want. Press enter.
You should now see a different set of numbers in the window, this s the code at the location of the patch. Do the same for the other window\file. Now you can see a before and after view of the game's code side-by-side. If you did everything right you should see a string of numbers like '6A $6F $10 $00' This seems to be a slightly garbled version of our patch's numbers, '$6F6AW $0010W' Ok, but what does that mean?
STEP 4: DEC, HEX, BYTES, WORDS AND LONGS
Now we move on to the structure of patches themselves and how they may be more precisely edited. Patches are nearly universally based on 'hexadecimal' where numbers are based on 16 instead of 10. Reading this short introduction may help, but isn't necessary. https://en.wikipedia.org/wiki/Hexadecimal
Basically patch numbers are a bit odd. Fortunately anyone with windows doesn't actually need to know much about this. Simply fire up windows inbuilt calculator and press alt-3 to covert it to programming mode. At the top left of the window there are four possible options, Bin, Oct, Dec and Hex. Switching between these will automatically convert a number you have typed in.
Normal numbers, and the mode you will start in, are 'dec' for 'decimal'. If we type in 10 here we can see the proper patch number by switching to 'hex' mode. We see 'A' meaning for 10 lives we should use this patch:
Code: Select all
#Lives Keen has at game start -Keen 5
%patch $5C9B $6F6AW $000AW #10 lives
This is unbelievably useful; a lot of patches can be hard to figure out if the numbers are large and in hex. This simple method will often shed light on things.
But why is the code arranged differently? Why was it scrambled when we looked at it? This is part of how CKPatch deals with information. As an example the following three patches do *exactly the same thing*:
Code: Select all
#Lives Keen has at game start -Keen 5
%patch $5C9B $6A $6F $03 $00
#Lives Keen has at game start -Keen 5
%patch $5C9B $6F6AW $0003W
#Lives Keen has at game start -Keen 5
%patch $5C9B $00036F6AL
The three patches are written using bytes, words and longs (Double words.) These are different ways of arranging the same data. Keen's code is arranged in bytes, in patches single two-digit numbers. Two of these make a word and four a long. But due to the interesting way (some) computers work to get these you need to rearrange the numbers slightly. $0003W makes sense, but as bytes the second part ($03) comes *before* the first ($00) When you build up a word or long from bytes you need to reverse the byte order!
This explains the odd way the code appears, but why use words and longs at all? For one thing, clarity; '$0003W' is simpler to deal with, 258 is $0102W in word form which is how it appears in windows calculator. Split up into bytes it's $02 $01 which is a little confusing. Many numbers in Keen use the word format, requiring two bytes. (And some require four.)
A note of cation, while you can rearrange patches like this, do NOT attempt to change a single byte into a word or long or vice-versa. The result will not 'fit' into Keen's code. The equation must balance, two bytes to a word, two words to a long.
STEP 5: EDITING EXISTING PATCHES
But something else is odd here, what does '$6F6AW' mean? It's coded in brown and a very big number, why is it there? The patch description mentions two hotlinks, one to the 'new game' patch for more patches and one to 'game stats': http://www.shikadi.net/keenwiki/Patch:Game_stats The Game Stats page has a number of interesting sections dealing in just how such numbers work. While not necessary reading for us yet, investigation will explain a lot about how patches work.
The vital takewaway is that by exploring the wiki instead of just straight copying a patcher can get a better idea of what their patches actually *do*. If in doubt looking at similar patches can be informative. More complex explanations including a full one about the brown numbers will be later. For now we focus on one question:
What if the wiki doesn't have what you want?
STEP 6: FIND AND REPLACE
Say we want to change Keen's standing animation so it's the same as his looking up one, but for some reason the wiki doesn't have a patch for Keen's standing animation. In this case we must look for possible patches in the game's code. Then we can write our own patch at that location! As such we open up the *clean* dump file in XVI32.
First we need to know what we're looking for. Obviously somewhere is a number for Keen's standing image. To find out what that is we open the mod's graphics folder and find Keen's standing sprite image. As it turns out there are two, left and right. If you're using Modkeen, tough luck, things get tricky. But in Keengraph the two images are 5SPR0108.BMP and 5SPR0116.BMP. These two numbers, 108 and 116 are what are used by the game. (In Modkeen they're not, sorry.)
Likewise Keen's looking up image (There's only one!) is 5SPR0124.BMP. Converting these in windows calculator gives us $6C and $74 as the originals and $7C as our desired change. In XVI32 we goto the search menu, select 'count' and type in '74' in the 'hex string' box.
1'947 matches. Oh.
But wait! Most numbers in Keen are words! That's $0074W or $74 $00! We search for that.
31 matches. Still a lot. Maybe try them later. What about $6C $00? 18 matches. Using Ctrl-F we can find the first one, then use the F3 key to find the next, and next, and next...
The first match is at $2AE4 (Look at the 'Adr. Hex' counter at the bottom left of the window.) The second at $3041E and so on. We thus start building a possible patch list that looks like this:
Code: Select all
#Possible Keen standing image patches:
%patch $2AE4 $007CW
%patch $3041E $007CW
But do we *really* want to test each of these out one at a time? That sounds like hard work. So let's patch smarter. We can eliminate a few right off the bat. The second patch for example. In XVI32 we can see on the right of the window a bunch of text, in fact the patch is part of the 'l' in 'normal', one of the difficulty options! That's probably not what we're looking for. The third patch is the same. We can toss out quite a few patches this way.
What's left we can test half at a time; if we have ten patches test 5 at once, if nothing happens, test the other five, if something happens discard the second set and split the 5 possible patches into 3 and 2. In this way a large number of patches can be tested in a short time. (Though some might crash the game, which makes things harder.)
But as it so happens a smart patcher won't even need to do this. The fourth possible match is at $30BCA, in fact the hex code it's buried in is '$74 $00 $6C $00 $03 $00' $74? Isn't that the other thing we were searching for? Looks suspicious! And won't you know it? These patches change Keen's standing animation:
Code: Select all
#Change Keen's standing animation in Keen 5
%patch $30BC8 $007CW
%patch $30BCA $007CW
For the true novice this is probably the only way of finding new patches. It's slow and inefficient but it works surprisingly often. But with all the patches we have, is there a way of being faster about things?
STEP 7: LOCATION, LOCATION, LOCATION
One method of being faster is getting an idea of where you should be looking. Quite often a patch exists for one game or situation but not the exact one you want. The Keen Vorticons and Keen Galaxy games form two series based on the same basic code, most pates work the same way between games. If you know a patch for one game you can often use it to make a patch for another.
We should expect that the game's code is organized in a similar manner in each game in a series, so stuff in one game will be in sort of the same place as it is in another. As an example consider the 'lives at start' patch from above. In Keen 4, 5 and 6 it is as follows:
Code: Select all
#New game lives patches
%patch $5CC7 $7A6AW $0003W #Keen 4
%patch $5C9B $6F6AW $0003W #Keen 5
%patch $5A9B $75A6W $0003W #Keen 6
Notice the locations are quite similar, when looking for matching patches we should test those closest to an existing patch first. This works within and across games.
We can also use an existing patch to get an idea where a related patch may be. For example the following patches list stuff Keen has when starting a new game in Keen 5:
Code: Select all
#Stuff Keen has at game start (Defaults)
%patch $5C8F $6F54W $0000W #Extra Keen at score (High word)
%patch $5C95 $6F52W $4E20W #Extra Keen at score (Low word)
%patch $5C9B $6F6AW $0003W #Lives (3)
%patch $5CA1 $6F56W $0005W #Ammo (5)
It's simple common sense that the patch for Keen's starting ammo will be near his starting lives and a simple look at the code is enough to confirm this and write the patch. Now let's look in more detail how we can use the structure of existing patches to make new ones.
STEP 8: COPYCAT PATCHES
Let's suppose you want to change the default difficulty of demo mode games. ( http://www.shikadi.net/keenwiki/Patch:Demo_mode ) There is have a patch for Keen 4 on the wiki, but not one for Keen 5, which you want:
Code: Select all
#Difficulty of demo mode -Keen 4
%patch $3EF6 $0002W #First game
%patch $5209 $0002W #Subsequent games
Looking for '$0002W' gets you hundreds of possible matches, that could take days to track down. but it's likely that the code around the patch is similar in the three Galaxy games. Opening a Keen 4 dump and going to the first patch we see the following code at $3EF2;
Code: Select all
$C7 $06 $70 $7A $05 $00 $C7 $06 $4A $47 $02 $00 $9A $A8 $08 $35 $1B
No matches. Rats! In hindsight this makes sense, we can't expect everything to be identical. So let's look for some other stuff nearby and see what we get. For various reasons stuff following $9As and $C7 $06s tends to change between games and even dump files. getting a feel for what does and doesn't change takes time and practice, but less then you'd think. From experience I expect '$05 $00 $C7 $06' and '$02 $00 $9A' not to change much between games, both involve numbers affecting the same thing across games for example.
Looking for the first one in Keen 4 gives us only TWO matches, both of which match the demo difficulty patches we have. And for Keen 5? Two matches! Right next to each match is a '$02 $00' that we need to change in our new patches. We thus make this patch and test it, and it works!:
Code: Select all
#Difficulty of demo mode -Keen 5
%patch $3EF0 $0002W #First game
%patch $5203 $0002W #Subsequent games
One final note for this part; a simple tool has been written to extract default patches from the games. GetPatch lets you take a patch location and extract the game's data at that location in patch form. This allows you to generate the (default) patch for a chunk of code in seconds without having to copy it out.
To run GetPatch simply drag the desired Keen data onto the program and type in your patch location (In hexadecimal, you don't need the '$' character.) The program will ask you for and 'extra skip', this is mostly irrelevant, it just makes the program read extra data when it comes across the Keen game's 'stop' signal. You can usually just press enter and get the patch written.
Patches are produced in a file called OUTPUT.TXT Some formatting errors may occur, the program is basic.