VaMender

VaMender is a fast, backup-first VAR repair and dependency cleanup tool for Virt-a-Mate. It reconciles the full AddonPackages graph with VaM's own package-rescan log, repairs high-confidence metadata problems, relinks safe non-plugin references, conservatively retires old versions, and isolates content that cannot run with the installed library.

VaMender is designed around one rule: prove the replacement and preserve the original before changing a live VAR.

Why VaMender exists

I built VaMender after repeatedly trying to reach a state that VaM itself acknowledged as clean. Installing one reported dependency could introduce its own missing subdependencies, so the apparent fix produced more missing-package errors—the familiar dependency-hell rabbit hole. VaMender's primary purpose is to evaluate the complete installed dependency graph together with a fresh VaM rescan, then repeat the repair and closure process until VaM agrees with the result. That approach gave me a fully clean AddonPackages library for the first time.

Sharp VaM Tools is a fantastic companion and is highly recommended for the many targeted cleanups and other useful operations that VaMender deliberately cannot touch. Qvaro is another excellent, very fast, and well-made tool that is highly recommended for a less complex workflow and its comfortable UI/UX—even for experienced users. There are other good VAR managers as well; VaMender is focused on this VaM-acknowledged dependency-closure problem, not on replacing the ecosystem. If you develop or maintain a VAR manager, please try VaMender, incorporate the parts that help your users, and contribute ideas or improvements back to this project.

Caution

Never run a cleanup against your only copy of AddonPackages. Keep an independent full backup on a separate location or drive. VaMender's verified per-VAR restore points reduce risk, but they are not a substitute for your own complete, tested backup. You are responsible for reviewing plans, choosing a safe backup destination, preserving access to paid/private content, and verifying the result in VaM.

Safety model

• VaM must be closed before any write-capable command.
• Every rewritten or archived VAR is copied and SHA-256 verified first.
• All restore points are recorded in manifest.jsonl.
• Unknown licenses are never guessed.
• Script/plugin dependencies remain exact-version dependencies.
• Newer-version relinks are limited to non-plugin content with a local provider.
• Old versions are archived only after compatibility and post-rewrite checks.
• Stale VaM logs are ignored; locally provable references can still be handled.
• Paid, private, and authenticated content is never downloaded or bypassed.

What it fixes

• Missing, invalid, stale, or incomplete meta.json dependency data
• Direct VAR references present in content but absent from metadata
• False dependencies caused by material, morph, and parameter labels
• Safe non-plugin references to newer compatible local package versions
• VaM-sensitive package-name casing mismatches
• Unicode creator and package identifiers
• ZIP central/local-header mismatches reported by VaM
• Malformed VAR filenames with unambiguous metadata-backed identities, including redundant download suffixes such as _1 and (1)
• Byte-identical malformed filename duplicates, archived only after checksum verification and a whole-VAR backup
• VaM-confirmed references to internal files missing from an installed provider, with the deficient package identified for reacquisition
• Unusable dependency closures caused by genuinely absent packages
• Proven-safe duplicate and old package versions

VaMender does not invent a missing clothing item, silently substitute another asset, or delete the scene that references it. Static archive analysis may find dormant references that VaM never loads, so internal-member problems are only called runtime-confirmed when they also appear in a fresh VaM log.

Install

VaMender currently targets Windows, where Virt-a-Mate runs.

Recommended: download the official release

The official release is recommended for nearly everyone. It has passed the project's formatting, lint, test, and Windows build checks and includes the executable, PowerShell wrappers, documentation, and a SHA-256 checksum.

1. Download vamender-windows-x64.zip and vamender-windows-x64.zip.sha256 from the latest release.

2. Verify the ZIP before extracting it:

   $zip = ".\vamender-windows-x64.zip"
   $expected = ((Get-Content "$zip.sha256" -Raw).Trim() -split "\s+")[0]
   $actual = (Get-FileHash $zip -Algorithm SHA256).Hash.ToLowerInvariant()
   if ($actual -ne $expected) { throw "VaMender release checksum mismatch" }

3. Extract the ZIP and run:

   .\vamender.exe --version
   .\vamender.exe --help

Optional: build from source

Build from source only when you want to inspect or modify the code, contribute to the project, or produce your own build. Otherwise, use the official release above.

Install the required build toolchain, then:

git clone https://github.com/tbitcs/vamender.git
cd vamender
cargo build --release --locked
.\target\release\vamender.exe --help

The compiled executable is written to target\release\vamender.exe.

Recommended workflow

1. Open VaM and run Add-On Package Manager → Rescan Packages.
2. Close VaM completely.
3. Run a read-only plan.
4. Run the automatic backup-first cleanup.
5. Reopen VaM, rescan packages, and review the new log.

$tool = ".\target\release\vamender.exe"
$vam = "D:\VaM\AddonPackages"
$backup = "E:\VaMender-Backups"

& $tool plan $vam --out .\reports\plan
& $tool run $vam --backup $backup --out .\reports\cleanup

The included wrapper performs the same automatic run:

.\cleanup.ps1 `
  -AddonPackages "D:\VaM\AddonPackages" `
  -Backup "E:\VaMender-Backups"

Use comprehensive-cleanup.ps1 when you prefer review gates between repair and migration stages.

Commands

Command	Purpose	Changes VARs
check	Inventory packages and unresolved dependencies; add --deep for full CRC validation	No
plan	Build a VaM-log-aware cleanup and quarantine plan	No
repair	Plan or apply safe metadata and archive-header repairs	With --apply
migrate	Plan or apply conservative old-version migration	With --apply
run	Apply the full safe workflow without review gates	Yes
restore	Restore checksum-verified VARs from a backup manifest	Yes

Run vamender <command> --help for complete options.

Reports

Every command writes three predictable handoff files:

• actions_taken.txt — concise work completed
• actions_required.txt — blockers and the next user action
• missing_dependencies.txt — one unresolved package ID per line

The automatic run command keeps detailed stage reports under _details/ while preserving the same three-file top-level handoff.

Restore

Close VaM first. Existing files are skipped unless --overwrite is supplied. When overwriting, VaMender preserves the displaced file under restore-conflicts.

& $tool restore $vam "$backup\manifest.jsonl"
& $tool restore $vam "$backup\manifest.jsonl" --last 10
& $tool restore $vam "$backup\manifest.jsonl" --overwrite

Because a manifest can be cumulative, --last N is useful for undoing only the most recent cleanup batch.

Scope and limitations

VaMender does not attempt to repair arbitrary scripts, binary assets, artistic content, or creator-specific behavior. It cannot prove that every newer package is semantically interchangeable, so script migrations and changed resource payloads stay blocked. Missing content must be acquired through VaM, the Virt-a-Mate Hub, or another source you are authorized to use.

The one non-automatable authority step is VaM's package rescan. VaM does not provide a supported headless rescan interface, so open VaM and rescan after library changes before using its log as fresh runtime evidence.

Contributing

Fork the repository, create a focused branch, and open a pull request into main. Required formatting, lint, test, Windows build, and CodeQL checks must pass before a change can be merged.

See CONTRIBUTING.md, MAINTAINERS.md, SECURITY.md, and CHANGELOG.md for project ownership, policies, and release history.

License and disclaimer

VaMender is available under the MIT License.

VaMender is an independent community project. It is not affiliated with or endorsed by Meshed VR, Virt-a-Mate, or the developers of Sharp VaM Tools.

Use VaMender at your own risk. To the maximum extent permitted by law, the author, tbitcs, contributors, and the VaMender project are not responsible for data loss, corruption, loss of access to content, broken scenes, licensing issues, downtime, lost revenue, or other direct or indirect damages arising from use or misuse of the software. See DISCLAIMER.md for the full project disclaimer.