Patches
This article deals with changing how a Commander Keen game runs for use in mods. If you are looking for the changes between official releases of the Commander Keen games, see the version histories.
A patch, in the context of the Commander Keen community, refers to part of a script file that has been created for use with CKPatch, with the objective of modifying how a Commander Keen game runs. CKPatch works by loading the Commander Keen executable in memory, "patching in" a script file, and then running the executable with the patches applied.
A patch generally consists of three parts: a macro command, a pointer, and a macro argument. This can be best illustrated with an example, taken from the article Patch:Vortimom:
Vortimom
%patch $3D17 {$470CW} #Vortimom collision
%patch $4717 $3F $0F #Vortimom killed by Keen's shot
%patch $3D1C [$0005W] #Vortimom strength
The macro command is highlighted in green, the pointer (which tells CKPatch the memory address to be patched) is highlighted in cyan, and the macro argument is highlighted in either brown, pink, or blue. Pink is used for 'ordinary' patches, stuff that needs to be where it is and usually can't be altered. Blue is used for a magnitude, such as a speed or height or position, it is how big something is. Blue values can be any number you wish. Brown is used for values taken from a list. Brown values can be any one of a specific set of values, usually listed elsewhere on the wiki. In the patch above the $3F will crash the game if altered, the $0005W value can be anything you wish (The Vortimom can be as strong as you want, even taking ten thousand shots to kill.) while the $470CW can only be a value taken from the Keen 3 section of Patch:Sprite collision (Any other values will cause the game to crash). Finally, it will also be noticed that in this example each patch is followed by a comment, which is highlighted in grey.
It is important to note that almost all integer values for the patches found on the KeenWiki are in hexadecimal, and at least a rudimentary knowledge of the hexadecimal numbering system is required to understand what a patch does, and how to modify it. There are three kinds of macro arguments, 8-bit, 16-bit and 32-bit (1, 2 and 4 byte) a 16-bit value is worth TWO 8-bit values, a 32-bit is worth 4. 16-bit (or 'word') values are indicated by the suffix -W, while a 32-bit one is indicated by -L ('long') A 'relative' value is possible with word and long values and is used for special kinds of patches. The following shows how the hex value $12345678 can be patched in various forms:
Type Normal Relative 8-bit $78 $56 $34 $12 Not possible 16-bit $5678W $1234W $5678W $1234RW 32-bit $12345678L $12345678RL
If you are not familiar with the hexadecimal numbering system, it is possible to use decimal values, but you must be careful For example, in the patch above 16-bit values can be replaced with a decimal number from 0 to 65535, while an 8-bit value can take a decimal number of 0-255. This can be more intuitive than hex numbers (50 is half of 100, 10 is 1/5 of 50; the hex values of 32, 64 and A don't make quite as much sense.) Decimal values are mostly avoided on this wiki, but do make an appearance now and then, such as in palette patches.
When using hex or decimal numbers, you do not need to include leading zeroes. This $14W is the same as $0014W and 0 5 14 is the same as 00 05 14. There is no real reason to do this, but it does happen.
This article only covers the very basics of reading and creating patches; when it comes to patching, experimentation is often the best teacher.