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

04 — Mods (custom volume, distribution-fed)

Supersedes 04-packwiz.md. packwiz is being removed. This describes the replacement: the server loads mods from a filtered local volume; clients keep getting the full set from the HeliosLauncher distribution.json.

Why drop packwiz

• The packwiz index tracked only 9 mods while the real modset (76 jars) lives in the distribution repo — packwiz was half-built and stale.
• Manual packwiz curation (.tmpl render → refresh → re-hash) is the flagged pain point, and a single missing file (custom/.gitkeep) crashlooped the server (404 → installer aborts → minecraft never starts).
• The launcher (HeliosLauncher) already distributes mods to clients via a Nebula-generated distribution.json. That is the canonical client mod list. The server just needs the same jars, minus client-only ones.

Architecture

ulicraft-distribution/dist            (another repo, = $DISTRIBUTION_WEB_ROOT)
  servers/ulicraft-1.21.1/
    forgemods/required/*.jar          ← 76 jars, Nebula-managed (SOURCE OF TRUTH)
  distribution.json                   ← generated by Nebula; CLIENT install list
        │                                     │
        │ caddy distribution. vhost           │ HeliosLauncher reads it →
        ▼                                     ▼ installs ALL listed mods (client)
  guests' launcher ◄───────────────────────────────────

ulicraft-server (this repo)
  mods-sides.json        ← { "<jar>": "client|server|both" }  (committed, editable)
  tooling/classify-mods  ← tomllib: seeds/updates mods-sides.json from jar manifests
  tooling/sync-server-mods ← copies both+server jars from $DIST → ./server-mods/
  server-mods/ (gitignored) ──mount──► minecraft /mods  (REMOVE_OLD_MODS=TRUE)

• Client distribution: unchanged. HeliosLauncher installs everything in distribution.json. No packwiz, no client zip.
• Server: filtered subset. Only both + server jars are copied into the mounted server-mods/. client-tagged jars never reach the server.
• Single source of jars: $DISTRIBUTION_WEB_ROOT/.../forgemods/required/. This repo stores no jars — only mods-sides.json.

Classification — tomllib only (no Modrinth)

tooling/classify-mods.py reads each jar's META-INF/neoforge.mods.toml with Python tomllib and derives a side from the minecraft/neoforge dependency side (the field modders use to declare a mod's environment):

manifest signal	derived side
minecraft (or neoforge) dep side = "CLIENT"	client
dep side = "SERVER"	server
dep side = "BOTH", unspecified, or no manifest	both (default)

Output is merged into mods-sides.json: existing (human-edited) entries are preserved; only new/unknown jars get a derived default. So the file is a one-time seed + permanent manual override surface. New jars default to both (your chosen default) unless their manifest says otherwise.

Accuracy + the manual step (important)

tomllib reliably catches hard client-only mods — ones that declare their minecraft/neoforge dep as CLIENT (e.g. sodium, iris). Those are exactly the mods that refuse/break on a dedicated server, so the must-exclude set is handled automatically.

It will not auto-exclude client-cosmetic mods that declare BOTH in their manifest (e.g. BetterF3, entityculling, sodium-extra, entity_texture_features, entity_model_features, ImmediatelyFast, drippyloadingscreen, melody, welcomescreen, Controlling, MouseTweaks, Searchables, tagtooltips, JustEnoughResources, TravelersTitles, BridgingMod, ponderjs, yeetusexperimentus). These load on the server harmlessly (wasted RAM, no crash) unless you mark them client in mods-sides.json. That manual curation is the "filter manually" step — classify-mods seeds, you trim cosmetic-client mods.

Also worth an explicit decision in the override file:

• CustomSkinLoader — server doesn't need it (skins resolve via Drasl/authlib); set client to keep it off the server.

mods-sides.json format

{
  "jei-1.21.1-neoforge-19.27.0.340.jar": "both",
  "sodium-neoforge-0.8.12-alpha.4+mc1.21.1.jar": "client",
  "ftb-essentials-neoforge-2101.1.9.jar": "both",
  "rightclickharvest-neoforge-4.6.1+1.21.1.jar": "server"
}

Key = exact jar filename (matches forgemods/required/*.jar). Value ∈ client | server | both. Hand-edit freely; classify-mods won't clobber it.

Tooling

tooling/classify-mods.py (dev-time, no network)

1. Enumerate $DISTRIBUTION_WEB_ROOT/servers/ulicraft-1.21.1/forgemods/required/*.jar.
2. For each jar not already in mods-sides.json: parse manifest → derive side (table above) → add entry.
3. Report: counts per side, and which jars were defaulted to both (so you know what to review). Never overwrites existing entries.
4. Optionally warn on entries in mods-sides.json whose jar no longer exists.

tooling/sync-server-mods.sh (deploy-time, offline) — replaces render-pack.sh

1. Read mods-sides.json.
2. mkdir -p server-mods; for each both/server jar, copy from $DISTRIBUTION_WEB_ROOT/.../forgemods/required/ → server-mods/.
3. Remove any server-mods/*.jar not currently selected (keeps it authoritative; REMOVE_OLD_MODS=TRUE in the container also enforces this on /data/mods).
4. Halt (non-zero exit) if a selected jar is missing from $DIST, or if mods-sides.json is absent — cautious, no silent partial sync.

docker-compose.yml changes

# remove:
#   PACKWIZ_URL: ...
#   extra_hosts: pack.${BASE_DOMAIN}:host-gateway   (auth. stays — authlib)
environment:
  MODS_FILE: ""            # ensure unset
  REMOVE_OLD_MODS: "TRUE"  # mounted folder is authoritative
volumes:
  - mc_data:/data
  - ./runtime:/extras:ro
  - ./server-mods:/mods:ro # itzg auto-syncs /mods → /data/mods

depends_on: caddy can drop (server no longer fetches pack. at boot); keep drasl (authlib). pack. caddy vhost + the ./pack/./custom mounts become dead — remove in the same pass.

Deploy flow (updated plan/14)

git pull --ff-only
tooling/render-config.sh        # drasl/nmsr/etc. (unchanged)
tooling/sync-server-mods.sh     # NEW — replaces render-pack.sh
tooling/fetch-authlib.sh
docker compose down --remove-orphans
docker compose up -d --build

$DISTRIBUTION_WEB_ROOT must be present on the host (already is — caddy mounts it). classify-mods.py is a dev step run when the modset changes; it is not in the deploy path (keeps deploy offline + deterministic).

Decommission checklist (on execution)

• tooling/classify-mods.py + generate initial mods-sides.json (review it).
• tooling/sync-server-mods.sh.
• compose: drop PACKWIZ_URL, pack. extra_host, ./pack/./custom mounts, pack. caddy vhost; add server-mods mount + REMOVE_OLD_MODS.
• delete tooling/render-pack.sh; remove its call from docs/deploy.
• delete pack/ (pack.toml, index.toml, *.pw.toml*, .packwizignore, CustomSkinLoader templates if duplicated in DIST) and custom/ (jars now sourced from $DIST).
• .gitignore: drop packwiz lines; add server-mods/.
• supersede plan/04-packwiz.md; update 05-minecraft.md, 14-deploy.md, CLAUDE.md (mod source section), and the landing join steps if they still reference pack.toml.
• resolves the host-local divergence around pack/ (cochi-host-local-divergence).

Open questions / risks

• Cosmetic-client mods load on the server unless manually set client — RAM waste, not a crash. Curate mods-sides.json over time.
• No manifest in a jar → defaults both. Acceptable; review the defaulted list classify-mods prints.
• Nebula regen may rename jars (version bumps) → mods-sides.json keys go stale; classify-mods re-seeds new names as both, and sync warns on missing-from-DIST. Re-curate on big mod updates.