F4Patch Readme

Table of Contents

  1. Overview
  2. Important Information (FAQ)
  3. Installation
  4. Upgrading
  5. Using F4Patch
  6. F4Patch Command Line
  7. .F4P File Format
  8. Installation Packages
  9. Writing Plugins
  10. License
  11. Special Thanks
  12. Comments and Technical Support
  13. F4Patch Versions / What's New

  1. OVERVIEW

    Are you tired of figuring out which patches you've applied and which ones you haven't? If so, try out F4Patch. It keeps everything straight for you and allows you to easily back out patches that you don't want to use.

  2. IMPORTANT INFORMATION (FAQ)

    F4Patch can be rebranded to be given different names, work with different programs, and look differently. Therefore, this readme may not be completely applicable to your version of F4Patch.

    Add-ons that are not a part of F4Patch may cause problems with F4Patch. If you have a question as to whether an add-on is compatible with F4Patch, please contact the add-on's author.

    *** IMPORTANT *** If a patch fails to apply, you are most likely using a 3rd party add-on that causes problems with the patch you are trying to apply. F4Patch is meant to be used with a clean installations. ANY OTHER ADD-ONS MAY CAUSE PROBLEMS. Also be sure that the executable that is defined in F4Patch is the correct one.

  3. INSTALLATION

    1. Remove your earlier installation. Manually delete remaining directories, just donīt forget to back up mission and configuration files you might want to save. Be aware that TEīs and missions can be non compatible between versions.
    2. Fresh installation of F4 from the CD. You should choose Typical (310 MB) or Full (565 MB) depending if you want those introduction movies etc.
    3. Apply the last official patches.
    4. Install the correct executable into your installation directory.
    5. Install the updated F4Patch program.
      1. Start the F4Patch program and make sure that the first command line is pointing to the correct executable. When you run F4Patch for the first time, F4Patch will try to identify the correct executable. F4Patch will look for various executable names. If it can not find any valid executable, it will display a default. If this isn't the correct executables you are using, click on the Browse button and locate the executable you wish to use. Once you have selected the executable you wish to use, a list of available patches that you have not yet applied will appear in the list on the left. Patches that you already have applied will appear in the list on the right. Click on the patch to see more information about the patch.
      2. Desktop shortcuts, and/or menu commands if you use them, have to be pointed at the correct executable. C:\MicroProse\Falcon4\FalconSP.exe -pf 100
      3. Defrag your installation partition (and keep doing so now and then)
      4. Once you have applied the patches you wish to use, you can run the program.

  4. UPGRADING

    Start F4Patch, remove every patch that you have applied, delete all the directories and files inside your F4Patch directory except for the Persist directory if one exists, and then install the new version of F4Patch following the above directions (skip steps 1-3).

    The above step is VERY IMPORTANT. If you do not remove your existing patches before installing a new version of F4Patch you run the risk of corruption.

    If you have your own custom .f4p files or some fix that is not included with F4Patch, you'll probably want to backup your F4Patch folder first.

  5. USING F4PATCH

    Click on the checkbox or radiocircle next to the patch name to add or remove a patch. Click on the Apply Changes button to apply the changes you have made with the patches. Click on the + or - sign next to a patch to expand or contract that patch's child patches.

    If a patch will not apply, you have most likely changed your files in a way that F4Patch can not understand. In most cases this can be solved by reinstalling the program and its latest patches.

    If patches are failing to apply, the Advanced Apply Patch button will give you the option to ignore failures and force the application of a patch. Ignoring errors and continuing with the application of a patch is not recommended and may have undesirable side effects. The current version of F4Patch will also not be able to restore your installation to its original state.

    F4Patch comes packaged as one packaged file. For some of the advanced features of F4Patch to work you will need to expand the package using the File->Expand Package menu command. You will need to do this in order to create new filters and add new patches that you've downloaded. When you download new patches, put the files you download into this F4Patch folder. F4Patch patch files will have a .f4p extension.

    If you want to save a list of patches that you have currently selected so that someone else may use your same patch list for multiplayer, select the File->Save Selected Patches as Filter menu item. You may need to use the File->Expand Package command first. You will then provide a name for your new filter and save it to a file. Make sure that you save your filter to the F4Patch folder.

    More advanced functions can be used by right clicking on the tree.

    The executable that you've defined can be executed by clicking the Launch button. Command line parameters for the executable can be defined by the View->Options->Launch Parameters... menu item.

    Normally every time F4Patch refreshes the patch list, it checks all the existing patches to see if they are currently applied. If you are making your own modifications, F4Patch may indicate that a patch that you have applied in the past is no longer applied. This is because F4Patch either detects a patch as applied or not applied. There is no middle ground. Once you have made a modification to the same data as an applied patch, when F4Patch checks again to see if that patch is applied, it is no longer applied in the strictest sense and will appear unchecked. In this case, F4Patch does not actually remove the patch, it just knows and indicates that it is no longer fully applied. To work around this issue, use the View->Options->Persistent Patching. When this option is turned on F4Patch will switch from double checking your installation to find the applied status of your patches to remembering what you have applied and what you haven't applied. Turning this option on is not recommended because if your installation is modified F4Patch could potentially cause corruption. This option is only recommended for developers creating new patches.

  6. F4PATCH COMMAND LINE

    There are five command line commands:

    -s
    Tells F4Patch to be completely silent.

    -v
    Tells F4Patch to be verbose. After performing a command it will report what it did. The default behavior is to only show non interactive feedback.

    -f <Filter Name or GUID>
    Applies the given filter. The GUID must be given without any dashes.

    -pa <Patch Name or GUID>
    Applies the given patch. The GUID must be given without any dashes.

    -pu <Patch Name or GUID>
    Unapplies the given patch. The GUID must be given without any dashes.

    The last three commands can specify more than one patch or filter by delimiting additional patches or filters with a space (-f Filter1 Filter2). You can also fully respecify the command (-f Filter1 -f Filter2).

  7. .F4P FILE FORMAT

    If you want to create patches for F4Patch, take a look at a .f4p file in a text editor. The format should be fairly obvious. To make a line a comment, put a semicolon as the first character on the line.

    Every .f4p patch has a unique identifier. This is called a GUID (Globally Unique IDentifier). GUID's are very important for several reasons. The first thing they do is give F4Patch a reliable way of identifying a specific patch. When a filter is created, the filter saves the ID of each of the patches that belong to it. For this reason it is very important that the IDs are unique. When creating a .f4p file, use the Tools->Generate GUID... menu option to generate a GUID. Then copy this ID into your .f4p file. IDs are also used to create Parent/Child relationships so a patch can identify another patch as its parent and so a patch can define what filters it belongs to.

    It is very important that when future versions of the patch are released that they keep the same ID as the older version. That way filters that use the old patch will automatically work with the new.

    This appears in the .f4p as:
    [ID]
    ID=518E65C5-9438-11B2-85AB-0050046B61BF

    .f4p files can also specify their parent patch. This can be specified in two different ways. First a patch can directly reference a parent by including "ParentID=518E65C5-9438-11B2-85AB-0050046B61BF" in the [ID] section, or the parent .f4p file can define a subdirectory to look for .f4p files in with the path group option. This looks like:

    [Options]
    CheckGroup/OptionGroup
    PathGroup=Labels

    All the .f4p files in the PathGroup subdirectory will automatically become child files of the .f4p that specified the PathGroup.

    Look at the Labels.f4p patch for an example of this.

    So now you've defined parent and child relationships. These are reflected in the F4Patch UI in the tree structure. For patches that replace entire files, having a copy of a new file of the parent and the original file of its child would be inefficient since they would be exactly the same file. For this reason you can include the special key "<ParentNew>" instead of a file name for the original copy of a file.

    For example:
    sim\ACDATA\f16.dat - <ParentNew>, FlightModels\f16.dat

    This indicates that this patch should as its original file use the new file of its parent.

    To help create [PatchInfo] sections, you can use the Tools->Create PatchInfo file... menu option. When you use this you will first have to pick the original file, then you will have to pick the new file, and then you will have to pick the file you would like the diff information to be saved to. The diff file that is created will have everything you need to create a [PatchInfo] section. The file name that the diff file uses will have a full path (e.g. F:\Games\Falcon4108\terrdata\objects\FALCON4.WCD). You will want to cut this down to its relative path (terrdata\objects\FALCON4.WCD) in order to use it.

    The [FileInfo] and [ZipInfo] sections have a special ability. First of all these sections normally work with original and new files that come with F4Patch. For some uses, such as replacing sounds or movies, including the original copy of a file with F4Patch would be prohibitive because of the large size. To get around this limitation start the original file name with "Persist\". F4Patch will recognize this special phrase and make a backup of the original file into to the "\F4Patch\Persist\" directory when the patch is applied. Then when the patch is unapplied, F4Patch will copy the original file out of the Persist directory back into its correct location.

    An .f4p file is made up of several different sections. Unneeded sections can be omitted. The format of an .f4p is:


    [ID] - Identifies this patch and any relationships.
    ID=GUID - Unique identifier for this patch.
    ParentID=GUID - Identifies this patches parent.
    RefreshID=GUID - A list of patches to refresh when this patch is applied or unapplied.
    FilterID=GUID - If this .f4p file is a filter, there will be a FilterID line for each patch that belongs to this filter. If this .f4p file is a patch, this will identify which filters this patch belongs to.
    OnAddApplyID - Apply another patch when this .f4p is applied.
    OnAddUnapplyID - Uanpply another patch when this .f4p is applied.
    OnRemoveApplyID - Apply another patch when this .f4p is unapplied.
    OnRemoveUnapplyID - Unapply another patch when this .f4p is unapplied.

    [Name] - The name you want to display.

    [Description] - The description you want to display.

    [Creator] - Who created the patch or enhancement.

    [Credit] - Does anyone else deserve credit?

    [Readme] - File with more information about the patch.

    [Options]

    • SkipVerify - F4Patch skip verification checks to make sure that it can back out the patch.
    • <!SkipTest!> - This flag is not really part of the [Options] section but is used on individual lines for specifying to F4Patch that it should skip the verification and patch application status of a specific instruction.
    • Filter - Indicates that this .f4p file is a filter and not a patch
    • AllFilter - This filter is a special filter that will display all patches.
    • DefaultFilter - This filter will be the filter displayed on startup.
    • HideFilter - Indicates that this filter should display all hidden patches.
    • WelcomeFilter - This filter will now be displayed as a filter on the Welcome screen.
    • NameFilterInclude - Regular Expression that works on the patch name to include patches automatically in the filter.
    • NameFilterExclude - Regular Expression that works on the patch name to exclude patches automatically in the filter.
    • OptionGroup - Indicates that this .f4p file is a parent that has mutually exclusive children.
    • CheckGroup - Indicates that this .f4p file is a parent that has child patches.
    • PathGroup={Folder Path} - Indicates that F4Patch should check the specified folder for additional .f4p files. The .f4p files found will be displayed as children of this group.
    • AutoAdd - Indicates that F4Patch should set this child checkbox patch to apply when its parent is applied.
    • Hidden - Indicates that this patch will only show up when a HideFilter is used. If a .f4p has this option it will never conflict with any other non-hidden patches.
    • F4PFolder - Tells F4Patch to search the folder specified with the PathGroup option for more patches. The patches that are found will not appear as child patches of this .f4p.
    • Refresh - Tells F4Patch to recheck the applied status of this patch whenever it is applied or unapplied. This is used for patches that reset default values.
    • PackageOptional - Tells F4Patch that this patch should not be automatically applied when it is part of a package.
    • NoPackage - Tells F4Patch to keep this patch from being added to packages (keeps private patches private).
    • ToolCommand - This .f4p will now appear in the tool menu and operate as a menu command.

    [AddAlert] - A message that is displayed when a patch is set to be applied.

    [RemoveAlert] - A message that is displayed when a patch is set to be unapplied.

    [Registry] - Registry entries
    ROOT\Key\Value \\ {Action [<ReplaceSubString>][<Set>]} \\ Orig Value \\ New Value

    [DirectoryInfo] - Directory operations
    {Action [<Create>]} : {Directory Name}

    [FileInfo] - Complete files you want to replace
    {FilePath from defined exe} : {Orig Replacement File} : {New Replacement File}
    Alternate syntax:
    {FilePath from defined exe} - {Orig Replacement File}, {New Replacement File}
    See the
    Persist section for more information.

    [CopyInfo] - Complete files you want to copy
    {Destination FilePath from defined exe} : {Source FilePath from defined exe}

    [PatchInfo] - Patch list for the user defined exe.
    {Offset} - {Orig Hex}, {New Hex}

    [FileName] - Name of zip file.
    {FilePath from defined exe}

    [ZipInfo] - Files within the FileName zip file that you want to replace.
    {FilePath from defined exe} - {Orig Replacement File}, {New Replacement File}
    See the Persist section for more information.

    [FileName] - >Name of another file you want to patch.
    {FilePath from defined exe}

    [PatchInfo] - Patch list for the .f4p defined file.
    {Offset} - {Orig Hex}, {New Hex}

    [FileName] - >Name of another file you want to patch.
    {FilePath from defined exe}

    [TextInfo] - Text change list for the .f4p defined file.
    {Action [<ReplaceSubString>]},{Delimiter},Orig Text{Delimiter}New Text

    [PluginInfo] - Plugin list
    {Plugin filename}:{Plugin defined data}

    [ShellInfo] - Execute other programs/open registered files (continue without waiting -- asynchronous)
    {Type [Apply | Unapply]} = {[<SystemCommand> | <F4PatchDir> | <InstallDir>] Command : [<SystemCommand> | <F4PatchDir> | <InstallDir>] Parameter}
    <SystemCommand> doesn't add any path.
    <F4PatchDir> adds the path of the F4Patch directory.
    <InstallDir> adds the path to the installation directory.

    [ProcessInfo] - Execute other programs (wait for completion -- synchronous)
    {Type [Apply | Unapply]} = {[<SystemCommand> | <F4PatchDir> | <InstallDir>] Command : [<SystemCommand> | <F4PatchDir> | <InstallDir>] Parameter}
    <SystemCommand> doesn't add any path.
    <F4PatchDir> adds the path of the F4Patch directory.
    <InstallDir> adds the path to the installation directory.

    [IncludeInfo] - Ensure files are included in installation packages
    {Filename}

    [ShortcutInfo] - Install shortcuts
    {FilePath from defined exe}


    Example .f4p file:

  8. INSTALLATION PACKAGES

    Once you've written your .f4p files you probably want to distribute them to other people. You have two choices. If the people you are distributing your work to already have F4Patch you can simply send them your .f4p files. If they don't have F4Patch you may want to create an Installation Package for them.

    To create an installation package, use the Tools->Create Installation Package menu command. This will present you with a dialog giving you some options for your installation package. Once you have selected the options you like, you will be asked to provide the name of your installation package. Once you provide this, F4Patch will create a special executable that will contain all the patches you have selected in one executable that can be easily given to others and used by them.

    The package options are:

    • Patch Selection
      • Selected Patches - Only include the patches that are currently selected (have a checkmark or circle with a dot in it next to the name) in the package.
      • All Patches and Filters - Include all the patches and filters regardless of whether they are selected.
      • Highlighted Patch - Only the patch that is currently highlighted (the name is surrounded by blue).
    • Interface
      • Simple - Dislays a small screen that only has a few buttons on it. This option is recommended when distributing packages to people that aren't familiar with F4Patch.
        • Hide Advanced Interface - Normally the Simple interface has a button that will allow the user to switch to the Advanced interface. Selecting this option will remove this button from the screen.
      • Advanced - The normal F4Patch screen that gives you the power to patch as you please.
      • None (Auto Apply) - Automatically applies the patches contained within the installer without user interaction.
    • Include Exe - Includes the currently selected exe (the one displayed in the box next to the "Executable:" label on the main screen into the package. It is highly recommended that if you include an exe that you give it a unique name. For example "Falcon4_MyExe.exe". That way if people uninstall your patch, they'll still have an executable.
      • Install Icon on Desktop - If the package installs an exe, this option will create a shortcut to that exe on the user's desktop.
      • Keep Exe on Unapply - Normally when the package is unapplied, F4Patch will also delete the exe that was installed. Checking this option will keep the exe in place.
    • Allow Expand Package - Normally users have the option of expanding the packages so they can add to the list of patches that they are using. Checking this option will remove this ability.
    • Include All Plugins - Normally F4Patch will only include plugins that are used by patches that are going into the package and plugins that appear on the Tools menu. This option will include all loaded plugins regardless of whether they are used.
    • Background Image - Allows the selection of a background image that is displayed full screen during installation. Must be in Windows bitmap (bmp) format.
    • Password - Password protects the installer.

    Note: If you include an exe named XXXXXX.exe then when people apply your patch, it will overwrite their existing XXXXXX.exe. Then if people unapply your patch, F4Patch will delete XXXXXX.exe leaving them without an exe. If your included exe is named something unique then this problem is averted.

  9. WRITING PLUGINS

    F4Patch supports plugins that can extend the functionality of F4Patch. If you want to write a plugin, you must make the following API available to F4Patch

    	// Allows F4Patch to get the version of the plugin so it can display it
    	// to the user
    	HRESULT DllGetVersion(DLLVERSIONINFO *pdvi);
    
    	// Allows F4Patch to get a description of the plugin so it can display it
    	// to the user
    	HRESULT PluginGetDescription(char* outDescription, 
    		int inMaxSize);
    
    	// Allows F4Patch to tell the plugin to present a dialog allowing the 
    	// user to customize the plugin
    	HRESULT PluginProperties();
    
    	// Gives the plugin the F4Patch folder
    	HRESULT PluginSetPatchDir(const char* inDir);
    
    	// Gives the plugin the user selected exe
    	HRESULT PluginSetExe(const char* inExe);
    
    	// Gives the plugin the user selected path
    	HRESULT PluginSetDir(const char* inDir);
    
    	// Allows F4Patch to figure out what kind of plugin this is and what kind
    	// of stuff the plugin does
    	HRESULT PluginGetType(int* inType);
    
    	// Allows F4Patch to figure out what files this plugin needs when its
    	// being packaged (Delimit with a colon ':')
    	HRESULT PluginGetPackageFiles(const char* inData, char* outFileList, 
    		int inMaxSize);
    
    	// Allows F4Patch to check whether or not a particular patch is applied
    	HRESULT PluginIsApplied(const char* inData, bool& outStatus);
    
    	// Allows F4Patch to check whether a patch can be applied (the plugin 
    	// should do error checking here)
    	HRESULT PluginCanApply(const char* inData, bool inAdvanced, 
    		char* outRetMessage, int inMaxSize, bool& outStatus);
    
    	// The plugin should apply the patch
    	HRESULT PluginApply(const char* inData, char* outRetMessage, 
    		int inMaxSize, bool& outStatus);
    
    	// Allows F4Patch to check whether a patch can be unapplied (the plugin
    	// should do error checking here)
    	HRESULT PluginCanUnapply(const char* inData, bool inAdvanced, 
    		char* outRetMessage, int inMaxSize, bool& outStatus);
    
    	// The plugin should unapply the patch
    	HRESULT PluginUnapply(const char* inData, char* outRetMessage, 
    		int inMaxSize, bool& outStatus);
    
    	// (Optional) Allows F4Patch to gather plugin tool info.  The passed string
    	// should be filled with a list of valid command names 
    	// (Delimit with a colon ':')
    	HRESULT PluginToolInfo(char* outCommandInfo, int inMaxSize);
    
    	// (Optional) The plugin tool command.  The passed parameter is the string 
    	// name of the command
    	HRESULT PluginToolCommand(const char* inCommandName);
    	
    For more information or for a F4Patch plugin SDK please contact
    Joel@Bierling.net

  10. LICENSE

    F4Patch is licensed as freeware. If you distribute F4Patch, you must include a copy of this readme file. The file must be unmodified except for changes to the included patches section. F4Patch may not be sold without prior authorization from Joel Bierling.

    If you'd like to donate $$ to the F4Patch project, I certainly won't stop you . My address is:
    703 Springwood Dr SE
    Kentwood, MI 49548
    USA

    All software has bugs. Hopefully F4Patch doesn't have any major ones. This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY. I, the author, am *NOT* responsible for any damage caused by the use of F4Patch.

  11. SPECIAL THANKS

    Thanks for your support!

    • Bruce C. Barbera
    • Col. Wrecking Crew
    • Slice - FreeBirds Virtual Pilots Squadron
    • Tux

  12. COMMENTS AND TECHNICAL SUPPORT

    Please send comments to:
    Joel Bierling
    Joel@Bierling.net
    http://www.bierling.net/joel/pages/falcon4/falcon4.htm

    For technical support please use the following resources. I'd love to be personally able to answer everyone's questions, but please understand that I'm doing this for free and I don't have a whole lot of extra time. Also, the more time I spend answering questions the less time I have to work on F4Patch adding features. However, if you can't find the answer to your question using one of these resources, let me know and I'll do my best to help you out.

    Technical Support:
    comp.sys.ibm.pc.games.flight-sim
    http://forums.delphiforums.com/falcon4/messages/?start=Start+Reading+%3E%3E
    http://www.checksix-fr.com
    http://www.frugalsworld.com

  13. F4PATCH VERSIONS / WHAT'S NEW


    Possible Future Changes:

    Version 5.0 (February 21, 2004)

    Version 4.3 (August 12, 2002)

    Version 4.2.2 (May 28, 2002)

    Version 4.2.1 (May 7, 2002)

    Version 4.2 (January 20, 2002)

    Version 4.1.6 (November 18, 2001)

    Version 4.1.5 (October 20, 2001)

    Version 4.1.4 (September 9, 2001)

    Version 4.1.3 (August 17, 2001)

    Version 4.1.2 (August 13, 2001)

    Version 4.1.1 (August 6, 2001)

    Version 4.1 (July 4, 2001)

    Version 4.0 (April 13, 2001)

    Version 3.2.5 (March 20, 2001)

    Version 3.2.4 (March 7, 2001)

    Version 3.2.3 (February 24, 2001)

    Version 3.2.2 (January 26, 2001)

    Version 3.2.1 (January 12, 2001)

    Version 3.2.0 (January 1, 2001)

    Version 3.1.0 (November 26, 2000)

    Version 3.0.1 (November 22, 2000)

    Version 3.0 (November 13, 2000)

    Version 2.1.1 (August 5, 2000)

    Version 2.1.0 (August 4, 2000)

    Version 2.0 (July 22, 2000)

    Version 1.4.1 (June 25, 2000)
    - Fixed bug where removing existing files (msvcrt.dll) was not possible.
    - Patch (.f4p) updates.

    Version 1.4 (June 11, 2000)
    - If a patch fails to apply, F4Patch will tell you specifically what is wrong.
    - Advanced apply allows the forced application of patches.
    - Comes with Falcon4_108i2.exe to prevent user confusion.
    - Scrolling patch description panes.
    - Other small improvements.
    - Patch (.f4p) updates.

    Version 1.3b (June 4, 2000)
    - Patch (.f4p) updates.

    Version 1.3a (May 25, 2000)
    - Patch (.f4p) updates.

    Version 1.3 (May 24, 2000)
    - Support for very complex patches (e.g. iBeta Realism Patch 2).
    - Additional error checking to manage conflicting patches.
    - PatchInfo tool to help create [PatchInfo] sections.
    - Patch (.f4p) updates.

    Version 1.2.1 (May 20, 2000)
    - Bugfix for Win9x systems where filename of the exe that it being used was not being saved.

    Version 1.2 (May 18, 2000)
    - New features
    - Patch (.f4p) updates.

    Version 1.1 (May 17, 2000)
    - Reads the registry to get the full path filename of the Falcon4.exe .
    - Supports a [FileName] parameter in the .f4p file so that F4Patch can patch other files than the main exe.
    - Supports a [FileInfo] parameter in the .f4p file so that F4Patch can patch complete files.
    - Can handle more than one offset per line in the [PatchInfo] section.
    - More error checking to make sure that it can back out patches. Other error checks added.
    - UI enhancements.
    - Patch (.f4p) updates.

    Version 1.0 (May 15, 2000)
    - First public release