Files

The Files tab lets you compare files, generate patches from the changes between them, and then apply those patches to any BrawlLib-compatible files.

Compare Files

The left-hand side of the form allows you to select two files to compare.

• Left File - The base file used for comparison.
• Right File - The file to compare to the left file. Anything that differs in the right file from the left file will be considered a change and displayed after comparison.
• Compare - This button compares the left and right files. Only enabled if both file fields are filled in.
• Browse... - This button allows you to open an existing .fpatch file generated by BrawlInstaller to view its contents and apply it.

Changes Form

After comparing two files or opening a file patch, the changes between the two files/in the file patch will be displayed on the right-hand side. The following controls are available here.

• Changes List - On the left side of the changes pane is a list of all changes in the generated patch. Each item in the list has the following components:
  • Checkbox - Checked items will be included in the patch if you save it or apply it to a target file. Unchecked items will be excluded.
  • Icon - An icon indicating the node type is displayed.
  • Change Indicator - A symbol indicating what type of change. + means the item was detected as added between left file to the right file. - means the item was detected as an item that was removed from the left file to the right file. ~ means the item was detected as changed from the left file to the right file. No indicator means the item was not changed or is not technically a valid node.
  • Name - The name of the item is displayed.
• Node Info - The node info pane on the right-side displays information about your selected node, and has a few controls as well.
  • Name - The name of the selected item.
  • Type - The type of the selected node.
  • Status - What kind of change was detected for this item between the left and right files.
  • Force Add - When checked, if the changes are applied to a target file, this node will always be added as a new node instead of a replacing an existing one, even if a matching node is found in the target file. This only displays for nodes that have actual changes and were not removed.
  • 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.
  • Target File - The file to apply changes to when you click "Apply to Target". By default, this will be filled in with the left file after doing a file comparison, but can be changed to any file you wish.
  • 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.
  • Apply to Target - When clicked, applies all enabled changes in the change list to the target file. When changes are applied, any nodes that show as Altered 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.

Note that all of the information displayed on this form is based on the patch at the time of creation. If you've opened an .fpatch file, it does not display the differences between the patch and your target file. That means that if a node shows as Altered, 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 left file and the right 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.

Build Patches

Build patches allow you to search a build for relevant files and patch them if they're found. They also allow you to supply files that can be used if a match is not found or to always be installed.

The main purpose of build patches is to provide a way to package mods that make changes to multiple files in a build without requiring users to replace entire files in their build. This means they can install your mod while retaining any changes they've already made to BrawlCrate-compatible files that your mod makes changes to. This can be useful for menu mods, Subspace Emissary mods, or really any mod that would otherwise require manually editing files in BrawlCrate. By utilizing file and build patches, you can package virtually any mod in an easy-to-install format.

Build patches can also be included with fighter packages to be installed alongside them.

The following fields are present on the build patch configuration form:

• Build Patch Entry List - A list of all entries included in the build patch. When an entry is selected, controls appear to configure it. The + and - buttons on the side let you add or remove entries.
• Browse... - The browse button allows you to browse to an existing .bpatch file and load it into the editor.
• Path - Configures the relative path to the target file for the currently selected build patch entry. This is the location in a build where the file that is to be patched or replaced can be found, starting at the root of the build. For example, if you are trying to patch or replace the file sc_selcharacter.pac in Project+, you would set this field to pf\menu2\sc_selcharacter.pac. When the build patch is installed, this entry will search for the file at this location.
• Patch File - The .fpatch to install if the file in the Path filed is found. If it is found, this patch will be applied to the file automatically just like applying a regular file patch.
• File - If the file in the Path field cannot be found, or if the Patch File field is left empty, this file will be installed instead at the location specified in the Path field. If this file is meant to be a backup in the former case, it is recommended to set this file to an already patched version of the file you would like to otherwise patch. If you do not expect the file to already exist in a user's build, you may just supply this file without a patch.
• Overwrite file if it exists - If this is selected, then if the Patch File field is empty and the File field is filled in, the file at the location specified in the Path field will be completely replaced with the supplied file. The main purpose of this is if you have files that cannot be read by BrawlCrate, and thus cannot be patched, but that you wish to update in the build when installed.
• Save as... - When clicked, prompts you to select a location to save your configuration as a .bpatch file, which can be shared or applied to a build later.
• Apply to Build - Applies the currently loaded build patch to your build. Only available if build path is configured.

How does it work?

Click here for a detailed breakdown of how this feature works.

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 program 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.
• 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.