Documentation Last modified: 2001-12-24 17:39

tola's.patching.engine enables you to create versatile patches with great speed and ease. It's entirely written in Win32 ASM and packed with a whole bunch of features. This page has the full documentation. So if you're interested in details just read on ...

License

tola's.patching.engine (c) Tola 2k++. You may freely distribute this program as long as you do not remove any of the included files from the archive. You may use and/or distribute any executable files created by this program. The software is provided "as is", the entire risk arising out of the use or performance of the program remains with recipient. The author shall in no event be liable for any consequential damages caused by the use of this program.

Main dialog/menu

Due to the huge amount of features (*cough*) implemented in t.p.e. 2.0, the gui is divided up using tab controls. General commands are accessible via the main menu. File menu   New Clears everything the user entered thus making it easy to create a new patch. Load Loads a previously saved patch file. Save Saves the current patch information for later use. If you save an offset/compare patch, it will become an offset/manual patch. This is because all the differences of the two files will be saved (currently you can only save the patch if the two files have the same size). Create Patch Creates the actual executable patch. Exit You guess.     Patchtype menu   Offset (compare) The patch will be generated by comparing two files. It will check both filesize and crc32 of the original file when executed and replace the bytes which are different in the patched file. Details here. Offset (manual) Same as above, but instead of automatically generating the patch data by comparing two files the user has to enter it manually. Details here. Seek&Destroy The data needed to create this patch has to be entered manually (see below). The patch will not check the filesize and crc32 of the original file. Details here. Loader The data needed to create this patch has to be entered manually (see below). The patch will not check the filesize and crc32 of the original file and won't display any dialog.     Preview menu   Preview Shows a preview of the patch's main dialog.     Options menu   Options Brings up the options dialog.

Options dialog

The t.p.e. default settings defined via options dialog will be saved as default.tpc which resides in the main directory. If you're using t.p.e. in your group and want all patches to look the same you just have to give your default.tpc file to all members. User Defaults   Name This name will automatically be inserted in the Author edit box. Website title The name of your website (duh). Website address Address of your website (it is also possible to use a 'mailto' statemant, e.g. mailto:me@myhost.com).     Paths/Filenames   'Home directory' The default directory used when opening files. Default savepath The default directory used when creating patches or saving/loading patch files. Default filename The default filename used when creating patches or saving patch files. It is possible to specify a special name format string (see below).     Default icon   Preview Clicking the icon will bring up the file selection dialog Use default The default application icon will be used.     Dialogs/Bitmaps   Dialog template t.p.e. offers your three different patch dialog templates to choose from (no bitmap, bitmap on the left, bitmap on top). If you don't like neither of them you can create a custom dialog yourself. Custom dialog t.p.e. accepts custom dialogs that are compiled using any 32bit resource compiler such as BRC32. See the included file dialog.rc for details. Bitmap You can choose one bitmap (i.e. your group's logo) to be displayed in the patch dialog. t.p.e. supports any valid .bmp files. You should, however, refrain from using very big high-/truecolor images to keep the patch sizes small.     Other options   Default disclaimer Use load to load a new default disclaimer, show to view the disclaimer as it will appear in the patch, remove to delete the disclaimer. The maximum filesize for a disclaimer is 64k. External compressor Created patches are not compressed in any way by default. You may, however, have t.p.e. use any PE compressor to reduce patch file sizes after their creation (highly recommended). Specify path and filename of the compressor followed by any required command line parameters and/or the variable %1 which will be replaced by the actual filename during runtime. Example: c:\windows\command/upx.exe --best %1 If you don't specify any command line parameters the patch filename will be used as the only parameter. Version info If this options is enabled a program's title and version number as specified in its version information resource (if present) is inserted automatically as target title (applies to offset patches only).

Auto naming

It is possible to have t.p.e. automatically select appropriate filenames for your patches. You can specify a special name format string in the options dialog by using any text and any of these variables: Variables   %T Title (as entered by user) %t Title (lowercase) %A Author (as entered by user) %a Author (lowercase) %W Website title (as entered by user) %w Website title (lowercase) %S Replace spaces by underscores (default) %s Do not replace spaces %r Remove spaces

General tab

This tab allows the user to enter some general information, most of which will be displayed in the patch dialog. Patch information   Target title The title of the program/file being patched. Patch author Your name goes here (or your pet's, whichever you prefer). Website title The name of your website (optional). If you do not enter a title, the address will be displayed instead (if entered). Website address Entering a valid url in this field will make a weblink appear in the created patch which will open the default web browser when clicked on (it is also possible to use a mailto:me@myhost.com statement, see custom dialogs; optional). Additional information May be used to enter short messages or instructions on how to use the patch, release information etc. (optional)     Target file   Target file This edit box is only used for Seek & Destroy and Loader patches and contains the name of the file being patched.

Patch data tab

The contents of this tab control will change depending on the selected patch type.

Offset patch (compare)

File selection   Original file The original target file (not patched). Patched file The patched target file.This file's size may be equal to or greater than the original file's size. Target file Name of the target file, the name of the patched file is inserted by default.

Offset patch (manual)

File information   Filename Name of the file being patched. You can either enter it manually or select it using an open dialog, using the latter the correct values for File CRC and Filesize will be inserted automatically. File CRC The CRC32 of the file. This value cannot be changed manually but has to be calculated by selecting a file. If this field is left blank, no CRC checking on the target is performed before patching. Filesize Size of the target file. You can enter it by hand or retrieve it by selecting a file. If this field is left blank, the file size will not be checked before patching.     Patch data   Data The byte pattern to be written to the target file is entered here. Byte patterns consist of single byte hex values (each byte always consists of two characters) separated by commas. Offset The raw file offset where the patch data should be written to. This offset may not exceed the file size (if specified). RVA This button will only be enabled if you selected a PE file in the Filename field. If you then enter an (R)VA in the offset field (which may or may not include the image base) and click the RVA button, it will automatically be converted into the correct raw file offset. Add Adds the currently entered patch data and offset. Update Updates the currently selected patch data and offset. Remove Removes the currently selected patch data and offset.

Seek & destroy patch

This dialog let's you specify a (virtually) unlimited number of byte patterns the patch will be looking for. These byte patterns consist of single byte hex values (so each byte always consists of two characters) separated by commas. You may also use one or more wildcards by using '??' instead of a byte value. Patch data   Original pattern The byte pattern that should be replaced. This pattern may not start with a wildcard. New pattern The new (patched) byte pattern. The number of bytes already entered is displayed on the right.     Occurence   Replace all All possible occurences of the original byte pattern will be replaced. Replace nth Only the nth occurence of the original byte pattern will be replaced.     Commands   Add pattern Adds the currently entered byte patterns. Update Updates the currently selected pattern (double clicking any pattern in the list box will make it easier to edit it). Remove item Removes the currently selected pattern.     Example Let's say you wanted all occurences of the the String LAME to be replaced by 1337. You'd have to enter the following information: Original byte pattern: 4C,41,4D,45 New byte pattern: 31,33,33,37 Select 'All occurences' and confirm by clicking the 'Add pattern' button.

Loader (memory patch)

There are currently three types of loaders you can create, which are selectable from the 'Patch if...' group box. Patch if...   original bytes found The loader will let the target process run until the original patterns are found. You may also specify a timeout value which determines after how many miliseconds the loader should stop looking for the byte patterns and terminate the target process. window created The loader will run the target process and repeatedly check for any windows the process creates until it finds a window or window class that matches those you entered (click the 'more' button to enter/select a window name and/or window class name). waited for x ms The loader will start the process, wait for x miliseconds and then apply the patch.     Patch data   Byte patterns Entering byte patterns for loader works similar to seek & destroy patches. Specify an original and a new byte pattern (wildcards allowed) and the patch offset (virtual address). The number of bytes entered is displayed on the right.     Commands   Add pattern Adds the currently entered byte patterns/offset. Update Updates the currently selected pattern (double clicking any pattern in the list box will make it easier to edit it). Run The 'run' command is very important for the creation of loaders. When you start creating a new loader, the current target state is suspendend (shown next to the offset edit box), i.e. any byte patterns you enter before adding the 'run' command will be patched before actually running the target process (the loader type is ignored at that point). Remove Removes the currently selected pattern.

Registry patch tab

A registry patch will automatically be applied after the actual patch (not availabe for loaders). All you need to do is enter a valid registry file in the dialog or load one from disk (64k max). When the created patch is executed, the regfile will be extracted to the user's path designated for temporary files (usually \Windows\Temp), imported to the registry and deleted thereafter.

Disclaimer tab

The disclaimer, which is not available for loaders, will be displayed on patch startup. The user is required to agree to it before being able to use the patch. Just enter any text or load it from a file (64k max).

Integrity check tab

If you're planning to release your patches together with some other files (e.g. nfos or readme files) and want to make sure they don't get modified/redistributed, you can have the patch check for their presence and verify them. The drawback is that the user will not be able to extract or copy the patch only. If integrity check fails...   Disable patch The patch dialog will show up but the 'apply patch' button will be disabled, the dialog caption will be changed to 'integrity check failed'. Display message only The patch will display a message saying that the integrity check has failed. The user will still be able to use the patch.     Commands   Add file Adds a file to the list and calculates its CRC. Update CRC Updates the CRC of the selected file. Remove file Removes the file from the list.

Customize tab

This tab allows you to change the appearance of the created patch. Default icon   Preview Clicking the icon will bring up the file selection dialog Use default The default icon selected in the options dialog will be used.     Dialogs/Bitmaps   Dialog template t.p.e. offers your three different patch dialog templates to choose from (no bitmap, bitmap on the left, bitmap on top). If you don't like neither of them you can create a custom dialog yourself. Custom dialog t.p.e. accepts custom dialogs that are compiled using any 32bit resource compiler such as BRC32. See the included file dialog.rc for details. Bitmap You can choose one bitmap (i.e. your group's logo) to be displayed in the patch dialog. t.p.e. supports any valid .bmp files. You should, however, refrain from using very big high-/truecolor images to keep the patch sizes small.

Bugs/limitations/version history

t.p.e. has been tested a lot but there might still be some bugs in it. So please email me if you're having problems. Trying to compare files bigger than 15 MB will cause a messagebox to appear, asking you if you want to continue (due to the fact that processing files this big requires lots of memory in this implementation). The up-to-date version history is always packaged with the latest t.p.e. download.

Contact

Please direct all your flames, praises, feature suggestions et cetera to this email address.

(C) 2001 [ void ] 2man army