modpackvc

Git-friendly metadata + lockfiles for Minecraft modpacks.

modpackvc is a C++ CLI utility that treats a Minecraft modpack like a real software project:

• No jars in Git – only manifests and config/overrides.
• Deterministic lockfiles – anyone can rehydrate the exact same pack.
• Collaboration-first – use branches and PRs to evolve a pack together.

The end goal: A human-editable pack.toml plus a deterministic pack.lock.toml for readable diffs, reproducible installs, and CI-friendly workflows.

⚠️ Status: early WIP – basic CLI structure and manifest/lockfile plumbing first, remote API support later.

---

Why?

Traditional modpack sharing has a few pain points:

• Binary bloat in Git – committing jars makes repos huge, noisy, and hard to diff.
• Unclear state – “What exactly was in the pack when it worked?” is hard to answer.
• Collaboration friction – it’s awkward for multiple people to safely edit a pack together.

modpackvc aims to fix that by:

• Storing only metadata (mod IDs, versions, sources, hashes) plus config/overrides in Git.
• Rehydrating the actual mod jars from official sources when you run a single command.
• Giving you readable diffs and a clean workflow for PRs and CI checks.

---

High-level design

The project is split into:

• Core library (modpackvc_core)
  • Pure C++20, no UI framework.
  • Knows about packs, mods, manifests, lockfiles, hashing, and simple validation.
• CLI frontend (mpvc)
  • Thin wrapper using [CLI11] for argument parsing.
  • Calls into the core library to do the actual work.
• (Future) GUI frontend
  • Will reuse the same core library, likely built with Qt or similar.

The core data model lives in include/mcpack/, with implementations in src/.

---

Current CLI commands (planned v0.1)

These are the initial, local-only commands:

mpvc init [path]

Initialize .mcpack/ metadata in a directory.

Usage:

mpvc init              # Initialize in current directory
mpvc init ~/mypack     # Initialize in specific directory

What it does:

• Creates .mcpack/ directory if it doesn't exist
• Generates a starter pack.toml manifest with default values:

  [pack]
  name = "My Pack"
  description = "My first git-friendly modpack"
  minecraft_version = "1.20.1"
  loader = "fabric"

• Sets up the basic structure for version control

Options:

• [path] - Optional path to initialize (defaults to current directory)

---

mpvc status [path]

Show the current state of the pack.

Usage:

mpvc status            # Check status in current directory
mpvc status ~/mypack   # Check status in specific directory

What it does:

• Reads the pack.toml manifest
• Displays pack metadata (name, version, loader)
• Shows configured mods and their versions
• Reports any inconsistencies or missing files

Options:

• [path] - Optional path to check (defaults to current directory)

---

mpvc snapshot [path]

Create a deterministic lockfile from the current pack state.

Usage:

mpvc snapshot           # Snapshot current directory
mpvc snapshot ~/mypack  # Snapshot specific directory

What it does:

• Scans the pack directory for all mod files
• Calculates SHA-256 hashes for each mod
• Generates/updates pack.lock.toml with:
  • Exact mod versions
  • File hashes for verification
  • Dependency resolution state
  • Timestamp of snapshot
• Ensures reproducible pack installation

Options:

• [path] - Optional path to snapshot (defaults to current directory)

Output example:

# pack.lock.toml
[lockfile]
version = "1.0"
generated = "2025-12-17T10:30:00Z"

[[mods]]
id = "fabric-api"
version = "0.92.0+1.20.1"
sha256 = "abc123..."
source = "modrinth"

---

General Options

All commands support:

• -h, --help - Display help for the command
• -v, --version - Show version information

Examples:

# Get help for a specific command
mpvc init --help

# Check CLI version
mpvc --version

# Typical workflow
cd my-modpack/
mpvc init                    # Set up metadata
# ... add mods manually ...
mpvc snapshot                # Lock current state
git add .mcpack/ config/     # Commit metadata only
git commit -m "Initial pack setup"

---

Workflow Example

# 1. Initialize a new pack
mkdir awesome-pack && cd awesome-pack
mpvc init

# 2. Edit pack.toml to add mod references
nano .mcpack/pack.toml

# 3. Create a snapshot/lockfile
mpvc snapshot

# 4. Check everything looks good
mpvc status

# 5. Commit to Git (no jar files!)
git init
git add .mcpack/ config/
git commit -m "Initial modpack manifest"