This serves as a guide for using the Compare Files and Apply File Patch plugins in the BrawlInstaller plugin suite.

These plugins allow you to compare files to see their differences and then create patches that can be installed without affecting other components of your build.

To start with this guide, you'll first want to follow the installation instructions on the main page. Afterward, open BrawlCrate and navigate to Plugins > BrawlInstaller Plugins > Files > Compare Files.

When you choose to compare files, you will be prompted to select two separate files. The first prompt will ask you to select a base file, which is the file you wish to use as the basis for your comparison. The second prompt will ask you for an altered file. When the files are compared, the tool detects anything from the altered file that appears to be different from the base file and allows you to apply those changes to the base file or save them as a patch. As such, the base file should generally be the file you want to modify (or have modified in the past, if you're creating a patch based on a mod you've made), and the altered file should be the file you want to take the modifications from.

The file compare tool should support any files that can be read by BrawlCrate.

Once you've selected your files, a progress bar will appear as they are compared. This can take some time, depending on how large the files are and how many differences there are.

Once the comparison is complete, a new window will populate - the File Differences form.

The File Differences form allows you to view all the changes from the base file to the altered file, select which changes you want to keep, and then either apply those changes or save them as a patch file. It has the following components:

• Node View - A list on the left-hand side that displays all of the nodes that were found in the altered file to be different from nodes in the base file. When selected, the Node Info pane will display information about the node and what changes were made to it in the altered file.
  • Each node has a checkbox. When checked, the changes to this node will be applied to the base file if you choose to apply changes, and will be included in a patch if you choose to save the changes in a patch file.
  • Each node has an indicator by its name - ~ for modified, + for added, and - for removed.
• Node Info Pane - A pane on the right-hand side that displays information about the currently selected node.
  • Name - The name of the selected node as it appeared in the altered file.
  • Type - The type of the node.
  • Status - The change that was made to the node from the base file to the altered file. There are several statuses:
    • Modified - The node was altered in some way between the base file and altered file.
    • Added - The node did not exist in the base file, but did exist in the altered file.
    • Removed - The node existed in the base file, but did not exist in the altered file.
    • Folder - Nodes that are strictly folders and have no real properties of their own will display this status.
  • Force Add - By default, when changes are applied, any nodes that were added or modified will search for a matching node in the file, and if one is found, they will replace it. If this option is checked, the selected node will always be added instead of replacing, even if a match is found.
  • Replace All Contents - Only available on container nodes. When selected, if a match for the node is found, all content of the node being patched will be replaced by the new node and its children, rather than the child nodes getting patched individually. This option should only be picked if you wish to entirely replace a container rather than modify its contents individually. Checking this essentially makes all child node options irrelevant, as they will not be considered.
  • Color Smash Note - If a texture is part of a color smash group, a note will be present indicating such and listing what texture it shares data with.
  • Image Preview - Some texture nodes will display an image preview of the texture from the altered file.
• Apply to Base File - Click this button to immediately apply any of the selected changes to the base file used for comparison.
• Save as... - Click this button to save the changes to an external patch file, which can then be applied to a file at a later time.
• Cancel - Close the form.

As mentioned above, you can check or uncheck any nodes from the node view to change whether they are included when applying the changes or saving them to a patch file. When you apply the changes to a file, any nodes that show as Modified or Added will search for a matching node in the file, and if one is found, the existing node will be replaced with them. If a match cannot be found, however, the node will be added instead. If a node shows as Removed, it will search for a match and if it is found the matching node will be removed from the file. If you select the Force Add option on a node, it will be added even if a match is found for that node.

When you check or uncheck a node that contains other nodes, all of its child nodes will be updated as well. If you check a child node, any parent nodes will be checked.

If you select Apply to Base File, the form will close and a progress bar will appear while the changes are applied to your base file. Any nodes that were checked will have their changes applied - so for example, if you have a node with a Removed status checked in your node view, then when the patch is applied that node will be removed from the base file. Once the patch is completed, you will have the opportunity to review the changes. If everything looks good, you can simply save the file to keep the changes. If you don't like what was changed, you can close the file without saving. Regardless, any files in your default build path are automatically backed up by the program when they are patched.

If you select Save as..., you will be presented with a prompt to save your changes to a .filepatch file. Just like when applying changes, any nodes that are checked will be included in the file, just as they appear in this form. You can then use the Apply Patch plugin to apply the changes from the patch file at any time.

If you've created a .filepatch file using the Compare Files plugin, or you had a .filepatch file shared with you by someone, you can use that file to apply the changes from it to a file at any time. To do so, navigate to Plugins > BrawlInstaller Plugins > Files > Apply File Patch. You will immediately be asked to select a .filepatch file, then to select the file you wish to apply the changes to.

Once you've made your selections, the Patch Contents form will display.

The Patch Contents form is nearly identical to the File Differences form. The only notable differences are that it does not have the Save as... button and the Apply to Base File button is replaced with a simple Apply Changes button.

Note that all of the information displayed on this form is based on the patch at the time of creation. It does not display the differences between the patch and your selected file. That means that if a node shows as Modified, for example, it doesn't mean the node is actually different between your file and the patch, just that the nodes were different between the base file and the altered file that were used to create the patch. The form shows you exactly what the patch contains regardless of the file you are applying it to.

Just like the File Differences form, any options you select here will be included when you apply the changes. The behavior is exactly the same as that of the File Differences form. If two nodes are not actually different between the patch and your chosen file, no change will occur for that node.

Once you've made your selections, you can click Apply Changes, and a progress bar will display while the changes from the patch are applied to your chosen file. Afterward, you can review your changes and save the file if you like them, or close without saving to discard the changes.

Click here for a detailed breakdown of how these plugins work.

Comparison

When comparing files, the top-level nodes for both files are gathered up. Additionally, any nodes that are considered containers will have their children gathered as well. For each node gathered from the altered file, the gathered nodes from the original file are searched for any nodes with a matching TreePath - which is basically a string containing the node and all of its parent nodes (so for example, a node named Child that is a child of a node named Parent would have a TreePath of Parent/Child). If a match is found, the MD5 checksums of the nodes are compared. If they do not match, the node is considered modified, and it is included in the patch. Whether the MD5 matches or not, the node is then removed from consideration for future searches - this way multiple nodes can have the same TreePath and will still be detected correctly.

At the end of the comparison, if a node was found to exist in the altered file that did not exist in the base file, the node is considered added and is included in the patch. If a node was found to exist in the base file that did not exist in the altered file, the node is considered removed and is flagged for removal in the patch.

Application

When a patch is applied, the plugin takes all of the nodes included in the patch and searches for any matches in the file being patched. Like with comparisons, they are searched based on the node's TreePath. If a match is found and the node is considered modified or added, the changes from the node in the patch are applied to the node in the file being patched. If no match is found, the node from the patch is added to the file as a new node. If a node is marked for removal and is found in the file being patched, the node is removed from the file.

Containers

At this time, the following nodes are considered containers:

Containers

• ARCNode
• BRRESNode
• BLOCNode
• BRESGroupNode
• TyDataNode
• TyDataListNode
• GDORNode
• MDL0GroupNode
• ItmFreqNode
• ItmTableGroupNode
• GIB2Node
• GMOVNode
• GET1Node
• GLK2Node
• GNDVNode

Whenever a file is being searched, nodes that are considered containers will also have their children searched. If a patch including a container node is applied to a build, if a match for the container is found, the properties of the container will be updated instead of the node being replaced wholesale.

Special Cases

Some nodes are treated slightly differently from the norm. Here's a breakdown of these special cases.

• MDL0Nodes are typically treated as a standalone node, but if their children consist only of a Definitions and Bones folder, they will be treated as a container.
• For any node with a BoneIndex, when modified with a patch, the plugin will check if the BoneIndex is unique. If it is not, it will be incremented until it is, ensuring all BoneIndexes are unique.
• If a node is part of a build patch on a file with Update fighter IDs selected and is installed with a character package, it will be checked for properties named FighterID, SlotID, CosmeticID, or CSSSlotID, and if a match is found, it will be updated to match the ID chosen for the character being installed.
• When comparing files, if a node identified as a change is color smashed, all nodes that are part of it's color smash group will also be considered altered.