PackWeave/docs/design.md

PackWeave design document

Binary: packweave, pkwv
Target platform: Linux, Windows, MacOS

1. Overview & Goals

packweave is a high performance minecraft modpack project support tool. It use the modrinth and curseforge as the mod registry, and the toml defination language to describe mod file. Provider a better and convienent way to develop and debug the modpack.

Key Requirements Met:

• Represent mod .jar files as small, human-readable TOML metadata files
• Support mods hosted on Modrinth and CurseForge (URL + hash + update metadata)
• Support local/custom mods not published to any registry
• Download the Minecraft core jar and mod loader automatically
• Sync modpack project changes to a real game client directory incrementally
• Detect and sync extra files created by mods back into the project
• Import a modpack from CurseForge or Modrinth pack format
• Export the project to CurseForge and Modrinth pack formats
• Allow a modpack project to declare another modpack as a dependency
• Support named mod groups (e.g. magic, tech) for selective inclusion
• Detect and resolve mod conflicts when merging multiple modpack dependencies
• GUI of the cli

2. Workspace Architecture

PackWeave/
├─Cargo.toml
├─docs/
├─crates/
│   ├─packweave-core/           # manifest, sync, resolver, conflict detection
│   ├─ packweave-pack/          # modrinth/curseforge import-export (optional split)
│   ├─packweave-network/        # HTTP downloads, hash verification
│   ├─packweave-cli/            # main cli tool
│   └─packweave-gui/            # gui tool

3. mod description file (packwiz format)

the packwiz format of mod is

name = "Just Enough Items"
filename = "jei-1.21.1-neoforge.jar"
side = "both"          # "client" | "server" | "both"
pin = false            # if true, skip auto-updates

[download]

# optional
url = "https://..."
hash-format = "sha512"
hash = "<hash>"

# nessesary
mode = ""              # "" or "url" = normal, "metadata:curseforge" = no URL stored, "local" = use local mod file, "git" = custom mod in git repo

[update.modrinth]
mod-id = "u6dRKJwZ"
version = "YAcQ6elZ"

# OR

[update.curseforge]
project-id = 238222
file-id = 123456

# OR

[update.gitrepo]
git-url = "https://..."
branch = ...
loader = forge | neogforge | fabric | ...

[option]                # optional
optional = true
default = true
description = "Adds item tooltips"

the project define

name = "My Modpack"
author = "someone"
version = "1.0.0"
description = "..."
pack-format = "packwiz:1.1.0"

[versions]
minecraft = "1.21.1"
neoforge = "21.1.0"   # or fabric / quilt / forge

[export]
# optional, per-format export settings
# export
project-id = 123456    # your CurseForge project ID, embedded in the exported zip manifest

[options]
# optional, merged into viper config
# example
acceptable-game-versions = ["1.21", "1.21.1"]   # allow mods from these MC versions
no-internal-hashes = false                        # whether to skip hashing index files

4. Resource download pipline

There are three type of resource need to download.

4.1 game client

The mojang provider all the version of minecraft client.
https://piston-meta.mojang.com/mc/game/version_manifest_v2.json
use this json file to search all the version, and the detail message. It have the directly link of the client.jar, the assest and libraries.

• step 1: download the version manifest
• step 2: download the client jar
• step 3: download the libraries incremental
• step 4: download the assets index json
• step 5: download the assets

4.2 mod loader

neoforge/forge

since the neoforge/forge have there own installer(They even don't need the original client.jar).

• step 1: download the installer
• step 2: run the installer
• step 3: download the assest
• step 4: download the libraries.

fabric/quilt

the fabric or quilt don't need the installer.

• step 1: get available loader versions (https://meta.fabricmc.net/v2/versions/loader)
• step 2: fetch the version profile
• step 3: build the version JSON
• step 4: download the libraries.

4.3 mod

modrinth

every mod on modrinth have their own download link. Just use client to download.

curseforge

Downloading from curseforge is more complex.

• step1: try the api
  GET /v1/mods/{projectId}/files/{fileId} with an embedded API key, use downloadUrl if present.
• step2: construct CDN URL directly
  When downloadUrl is null, launchers construct the CurseForge CDN URL
• step3: if still fail, prompt user to download manually

5. import and export behaviour

6. GUI design

7. Configuration Structure

8. Networking, Proxy & Mirror

9. Security & Reliability

10. Dependency Matrix

11. Testing & CI Strategy