Automatic Modpack Updater

Modpack Updater

  Keep your modpack in sync automatically — ship a tiny pack, deliver the rest at launch.

  Modpack Updater is a lightweight NeoForge mod that downloads and updates your modpack straight from your own server, before the game finishes loading. Instead of re-publishing a full modpack every time a mod changes,
  you publish a minimal pack (NeoForge + this mod + a small config) once — and push every future update from your server. Players always launch into the latest version, no manual downloads, no re-installs.

  ---
  ✨ Features

  - Automatic sync at launch — checks your server on every start and pulls down anything new or changed.
  - Delta updates — only changed files are downloaded (compared by SHA-256), so updates are fast and bandwidth-friendly.
  - Self-healing — if a tracked file is deleted or corrupted, it's re-downloaded automatically.
  - Integrity-verified — every download is checked against its SHA-256 hash before being applied.
  - Live progress — shows download progress right on the NeoForge loading screen.
  - Version-safe — refuses to run on an incompatible NeoForge line and tells the player to update the base pack.
  - Server-agnostic — points at any HTTP endpoint via a simple config file. No vendor lock-in.

  ---
  ⚙️  How it works

  1. You install a minimal CurseForge pack containing NeoForge, this mod, and a config file.
  2. On launch, the mod reads config/modpack-updater.yaml, fetches the active manifest from your server, and compares it to what's on disk.
  3. New/changed files are downloaded and verified; files removed server-side are cleaned up.
  4. When an update is applied, the game restarts once so it boots cleanly into the new version — then you're playing.

  ▎ If no changes are found (the usual case), the game boots straight through with no delay.

  ---
  📝 Configuration

  config/modpack-updater.yaml:

  schemaVersion: 1
  modpackName: "My Awesome Modpack"
  modpackAuthor: "Your Name"
  versionCheckerUrl: "https://updates.example.com/api/active"
  fileBaseUrl: "https://updates.example.com/files"

  - versionCheckerUrl — returns the active manifest (pack info + file list with hashes).
  - fileBaseUrl — base URL the mod downloads files from.

  ---
  🔌 Server API

  Your server must expose two things. The mod is a plain HTTP client — any backend works.

  1. Manifest endpoint (versionCheckerUrl)

  GET <versionCheckerUrl> → 200 with this JSON body:

  {
    "version": "v1.2.3",
    "pack": {
      "name": "My Awesome Modpack",
      "version": "1.2.3",
      "minecraft": "1.21.1",
      "neoforge": "21.1.230"
    },
    "files": [
      { "path": "mods/example-1.0.jar", "sha256": "9f86d0818...", "size": 2097152 },
      { "path": "config/example.toml", "sha256": "2c26b46b6...", "size": 4096 }
    ]
  }

  ┌────────────────┬────────┬───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐
  │     Field      │  Type  │                                                                                Description                                                                                │
  ├────────────────┼────────┼───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┤
  │ version        │ string │ Identifier for the current pack version (used in the download path).                                                                                                      │
  ├────────────────┼────────┼───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┤
  │ pack.name      │ string │ Display name.                                                                                                                                                             │
  ├────────────────┼────────┼───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┤
  │ pack.version   │ string │ Human-readable pack version.                                                                                                                                              │
  ├────────────────┼────────┼───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┤
  │ pack.minecraft │ string │ Minecraft version, e.g. 1.21.1.                                                                                                                                           │
  ├────────────────┼────────┼───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┤
  │ pack.neoforge  │ string │ Required NeoForge version, e.g. 21.1.230. Compared by major.minor — a patch difference (21.1.227 vs 21.1.230) is allowed; a line change (21.1 vs 21.2) blocks the launch. │
  ├────────────────┼────────┼───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┤
  │ files[].path   │ string │ File path relative to the game directory, using / separators (e.g. mods/x.jar, config/x.toml, resourcepacks/x.zip).                                                       │
  ├────────────────┼────────┼───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┤
  │ files[].sha256 │ string │ SHA-256 of the file, hex. Case-insensitive; lowercase recommended.                                                                                                        │
  ├────────────────┼────────┼───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┤
  │ files[].size   │ number │ File size in bytes.                                                                                                                                                       │
  └────────────────┴────────┴───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘
  
  - Return 503 if no version is active yet — the mod treats this as "server unavailable" and aborts cleanly.
  - Any path not listed in files that the mod previously installed is deleted on the client (the manifest is the source of truth).

  2. File endpoint (fileBaseUrl)

  For each file, the mod requests:

  GET <fileBaseUrl>/<version>/<path>

  - <version> is the manifest's version; <path> is the file's path.
  - Each path segment is URL-encoded (spaces → %20, etc.), and / separators are preserved.
  - Must return 200 with the raw file bytes. The body is verified against the manifest's sha256 after download.

  Example — for version = "v1.2.3" and path = "resourcepacks/Cool Pack.zip":

  GET https://updates.example.com/files/v1.2.3/resourcepacks/Cool Pack.zip

  ---
  ✅ Requirements

  - Minecraft 1.21.1, NeoForge 21.1.x
  - Client-side

  ---
  🔧 Advanced
  
  - -Dmodpackupdater.skip=true — skip the update check for a single launch.
  - -Dmodpackupdater.config=<path> — use a config file outside the default location.