vfstool

vfstool is a command-line utility for interacting with OpenMW's virtual file system (VFS). It allows users to locate files, serialize the VFS to various formats, extract files, and even collapse the VFS into a single directory for space savings, and to reuse OpenMW's feature set for other games.

Features

• Collapse the VFS: Create a set of hardlinks or symbolic links for the entire VFS in a target directory.
• Extract Files: Extract specific files from the VFS to a given directory.
• Find Files: Locate files in the VFS by name, extension, or other criteria.
• Serialize the VFS: Output the VFS structure in JSON, YAML, or TOML formats.
• Filter Remaining Files: Identify files in a directory that are replaced or not replaced by the VFS.

Installation

Clone the repository and build the tool using cargo:

git clone https://github.com/yourusername/vfstool.git
cd vfstool
cargo build --release

Usage

vfstool [OPTIONS] <COMMAND>

Global Options

• -c, --config <CONFIG>: Path to the directory containing openmw.cfg. If omitted, the system default location is used.
• -r, --use-relative: Use relative paths in output.
• -h, --help: Describe usage of the app or any subcommand

Commands

collapse

Collapse the VFS into a target directory using hardlinks, symbolic links, or file copies.

vfstool collapse [OPTIONS] <COLLAPSE_INTO>

Options:

• <COLLAPSE_INTO>: Target folder to collapse the VFS into.
• -a, --allow-copying: Fall back to copying files if linking fails.
• -e, --extract-archives: Extract files from BSA/BA2 archives during collapsing.
• -s, --symbolic: Use symbolic links instead of hardlinks.

extract

Extract a specific file from the VFS into a target directory.

vfstool extract <SOURCE_FILE> <TARGET_DIR>

Arguments:

• <SOURCE_FILE>: Full relative path to a VFS file (e.g., meshes/xbase_anim.nif).
• <TARGET_DIR>: Directory to extract the file to.

find-file

Locate a specific file in the VFS and return its absolute or relative path.

vfstool find-file [OPTIONS] <PATH>

Arguments:

• <PATH>: Full (relative) VFS path to query.

Options:

• -s, --simple: Output the result in a simple format (no colors or formatting).

find

Search for files in the VFS based on a query term.

vfstool find [OPTIONS] --path <PATH>

Options:

• -p, --path <PATH>: Query term, actual contents depend on search type. Mandatory
• -f, --format <FORMAT>: Output format (json, yaml, or toml). Default: yaml.
• -o, --output <OUTPUT>: Path to save the search results. If omitted, results are printed to stdout.
• -t, --type <TYPE>: Type of filter to use when searching. Default: name.

Filter Types:

• exact: Match the exact VFS path.
• name: Match files containing the query in their name.
• name-exact: Match files with the exact name.
• folder: Match files in a specific folder.
• prefix: Match files with a specific prefix.
• extension: Match files with a specific extension.
• stem: Match files by their stem (filename without extension).
• stem-exact: Match files by their exact stem.

remaining

Filter the VFS to show files replacing or not replacing contents of a given directory.

vfstool remaining [OPTIONS] <FILTER_PATH>

Arguments:

• <FILTER_PATH>: Absolute path to filter against.

Options:

• -r, --replacements-only: Show only files replacing contents of the given path.
• -f, --format <FORMAT>: Output format (json, yaml, or toml). Default: yaml.
• -o, --output <OUTPUT>: Path to save the filtered VFS. If omitted, results are printed to stdout.

Examples

Collapse the VFS into a directory with symlinks

vfstool collapse -s /path/to/target

This form is the most space-efficient variant of collapse, since it doesn't copy or extract files. It's fragile and most ideal for testing mods.

Collapse the VFS into a single directory, with extraction and hardlinks

vfstool -c C:\Games\Oblivion\openmw.cfg collapse -ae C:\Games\Oblivion\Data

This form consumes more space and takes longer due to extracting archive contents, but will perform better ingame and allow removing BSAs entirely.

Extract a file from the VFS

vfstool extract meshes/xbase_anim.nif /path/to/output

Find a file in the VFS

vfstool find-file meshes/xbase_anim.nif

Search for files by extension

vfstool find -t extension -f json -o results.json nif

Show files replacing contents of a directory

vfstool remaining -r /path/to/filter

License

This project is licensed under the MIT License. See the LICENSE file for details.