# 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 

```toml
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
```toml
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