169 lines
4.7 KiB
Markdown
169 lines
4.7 KiB
Markdown
# 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
|