ulicraft-server-v1/plan/04-packwiz.md

packwiz — modpack source of truth + offline mod mirror

Summary

packwiz (installed at ~/go/bin/packwiz) authors the modpack. The ./pack directory is the single source of truth for mods, consumed by both:

• the server (itzg PACKWIZ_URL), and
• clients (Fjord launcher imports the pack / packwiz-installer).

Caddy serves ./pack at packwiz.ulicraft.local. packwiz only emits metadata (pack.toml, index.toml, mods/*.pw.toml); the .pw.toml files reference Modrinth/CF CDN URLs, so true offline requires mirroring jars locally.

Behaviors confirmed

• Prune: packwiz-installer tracks a manifest and removes client mods no longer in the index on re-run. (Server side via itzg likewise re-syncs.)
• Download source: jars come from CDN URLs in .pw.toml, NOT the pack host — unless URLs are rewritten to the local mirror.
• itzg side filtering: itzg downloads server-side mods only. Client-only mods MUST be tagged side = "client" (not both) or the server may pull and crash on them.

Offline mod mirror (the key work)

tooling/mirror-mods.sh (see 08-tooling.md):

1. Parse each mods/*.pw.toml, download the jar into ./mirror/mods/.
2. Copy jars into ./pack/mods-files/ (served at packwiz.ulicraft.local/...).
3. Rewrite each [download] url to point at http://packwiz.ulicraft.local/....
4. packwiz refresh to recompute hashes/index.

Result: server + clients install mods entirely from the LAN. No CDN at party time.

NeoForge pinning

pack.toml pins MC 1.21.1 + NeoForge 21.1.x. Verify exact NeoForge build against projects.neoforged.net before locking.

Tasks

• packwiz init → ./pack (MC 1.21.1, modloader neoforge, pinned version)
• Curate mod shortlist (perf/tech/magic/storage/QoL/worldgen/map/voice)
• Tag client-only mods side = "client"
• packwiz refresh; verify index.toml committed (clients fetch it)
• Write tooling/mirror-mods.sh (vendor jars + rewrite URLs + refresh)
• Point server PACKWIZ_URL=http://packwiz.ulicraft.local/pack.toml
• .gitignore the vendored ./mirror/ jars; keep ./pack/*.toml tracked
• Test offline install end-to-end (cut internet, install on a fresh client)