VMFMergeTool

Copyright © 2020 by DKY (Ryan Lam)

VMF Merge Tool is an experimental tool for Source Engine level design teams. It allows multiple level designers to concurrently work on a common level without conflicts, by merging each designer's work on top of a common "parent" source file.

VMFMergeTool requires the user to supply a list of paths to VMF-formatted files, preferably generated by Hammer. One of these files MUST be a "parent", or common ancestor, of the other files. If this is not the case, I cannot make any guarantees about VMFMerge's output.

VMFMerge merges VMF sources in a process consisting of four stages:

1. First, it determines which VMF file is the "parent", or common ancestor, of the other VMFs. It does this by comparing internally-embedded revision numbers and using the VMF with the lowest revision number. You can also "force" a particular VMF to be treated as the parent VMF (highly not recommended), if you really want to.

2. Next, the tool determines the set of changes ("deltas") that were made between the parent and its "children". This produces a "delta list" for each child; each delta list represents the minimum set of changes that are necessary to transform the parent VMF into the corresponding child.

3. The delta lists from each child are collectively merged into a single master list of deltas. During this process, the tool will attempt to merge equivalent deltas into one, and emit warnings for any pairs of deltas that are found to conflict.

4. Finally, the tool goes through the master delta list and "replays" each delta on top of the parent VMF. The result is a merged VMF consisting of all the changes made in each of the children, applied to the parent.

Current version: 0.1.2 BETA

GUI Usage

To start VMFMerge in GUI mode, run vmfmerge-gui.exe.

CLI Usage

vmfmerge-cli.exe [-h] [--version] [-v] [-n] [-i] [-p] [-A] vmf [vmf ...]

Positional arguments:
  vmf                   The name of a *.vmf file, or the path to a *.vmf file.

Optional arguments:
  -h, --help            Show a help message and exit.
  
  --version             Show program's version number and exit.
  
  -v, --verbose         Noisily display progress messages throughout the
                        procedure. (Currently unimplemented)
                        
  -n, --no-auto-parent  Do not try to automatically figure out which VMF is
                        the parent VMF. Instead, simply assume that the first
                        VMF in the argument list is the parent. (Can be
                        dangerous-- Use with care!)
                        
  -i, --dump-individual
                        Instead of merging, output a list of individual per-
                        file deltas to stdout.
                        
  -p, --dump-proposed   Instead of merging, output a list of all proposed
                        merge deltas to stdout.
                        
  -A, --aggressive      Enable aggressive conflict resolution. This will use 
                        some currently undertermined tie-breaking method to 
                        resolve delta conflicts during the merge phase, 
                        instead of emitting warnings.
                        (Currently unimplemented)

Running or Building From Source

The VMFMerge source files are available on GitHub: https://github.com/darthryking/VMFMergeTool

To run or build VMFMerge from source, you must have the following dependencies installed:

• Python 3.7
• PySide2 (if running/building VMFMerge in GUI mode)