Patch:Text patches

From KeenWiki
Jump to: navigation, search

This is a page explaining how text patches work. For more specific patches, such as the About Id text, see the relevant patch page (E.g Patch:About Id. Specific examples include Patch:End text, Patch:Help text, Patch:Previews text, Patch:Story text and Patch:Ordering Info.

A text patch is a patch that involves changing a string of text in the Keen executable. They differ from other patches in that machine instructions are not being altered, but textual data instead. A text patch has two patchable parts, the text itself, and the reference (or pointer) to the text. Text strings are stored in a region of the keen executable known as the "data segment." The reference to the text, or "pointer," is part of the actual game code, located in a separate segment. The location of the data segment for each Keen game is listed below:

Keen 1: $13050
Keen 2: $17780
Keen 3: $19820
Keen 4: $2EE70
Keen 5: $30340
Keen 6: $30D30
Keen D: $23A70

An example text patch is given below. It patches the name of the saved game files in Keen 3. (The '?' is replaced by the game number, e.g SAVED3.CK3) The first pair of patches changes the actual text in the executable. The second pair changes the values of the pointers. Notice that the two pointers are NOT the absolute location of the text from the beginning of the executable, but that location minus the data segment start (e.g. second patch: $1CA35 - $19820 = $3215).

Patch: Patch the text
%patch $1CA28 "SAVED?." $00      
#load game from this filename
%patch $1CA35 "SAVED?." $00
#save game to this filename

Patch: Patch Keen 3 saved game filename
%patch $A2BD $08 $32 
#Save game to
%patch $A44D $15 $32
#Load game from

Notice that the string is null-terminated ($00), that is, the byte $00 denotes the end of a string. Also note that a string patched to be longer than the original may overwrite other data in the executable. What this means for our example patch is that we can have some text shorter or the same length as the original. Thus 'SAVE?.' or 'GAME?.' are both ok, but 'SAVEGAME?.' is not. (In fact you will notice that these two pieces of text are almost right after each other.)

The 'newline' character, $0A, means 'go down a line' and is used in longer text patches. While some patches (Simple patches like the above or the Patch:Story text patch) don't need these, many do. As an example, this is some cheat text from Keen 4, as it is stored in the executable:

Patch: Keen 4 cheat text:
%patch $2F435 "Cheat Option!" $0A $0A
              "You just got all" $0A
              "the keys, 99 shots," $0A
              "and an extra keen!" $00

Here each line ends with $0A, so that the next line starts one line lower. Finally the text is ended with $00. The text has been arranged so this can be seen.

The restrictions on space and format can be annoying and at present there is only two programs that can partially automate some text patches. (Startext and The Neural Stunner) It is possible, with some skill, to rearrange text patches to allow yourself more space when patching. (By overwriting useless text or spare space for example.)

Text files

When a large amount of text is to be patched, it is often simpler to place it all into a text file and then use a %patchfile patch. That way the text can be edited easily in Notepad or Wordpad without having to worry about taxing CKPatch with long lines. In general this works with a specific class of text patch, notably the '*TEXT's (STORYTEXT, HELPTEXT...) in Keen Vorticons. The game here reads a large amount of text as a single block, automatically parsing the text. In fact, in Keen 1 the texts are external *.CK1 files with no need of a patch. An example is:

Patch: Keen 2
#Change the story, max file length 2'016 bytes
%patchfile $15BC0 "HELPTXT.CK2"

In this example the file "HELPTXT.CK2" would contain the new story's text. Note again, there is a limit to how much text the file can contain without overwriting other text.