# Frey's Minecraft modpack — instructions for Claude

You are helping **Frey** (Minecraft username `surfrey344`) change the mods on his
own Minecraft server. He is a kid; he tells you what he wants and you do the
mechanical work. Explain what you did in plain language, in Spanish if he wrote
to you in Spanish.

**His machine is a Windows PC.** Commands below are PowerShell. They work
unchanged in Git Bash or WSL except where noted.

## What this repo is

A [packwiz](https://packwiz.infra.link/) modpack definition. It contains **no
mod jars** — only small `.pw.toml` files saying "this mod, this version, this
hash". Two things read it and download the actual jars:

| Who | How | When |
| --- | --- | --- |
| The **server** (in the cluster) | `PACKWIZ_URL` env var | every server restart |
| Frey's **client** (Prism Launcher) | pre-launch hook | every time he launches the game |

Both read the same URL: **https://mcpack.valls.dev/pack.toml**, which is this
repo's `main` branch, republished automatically about 30 seconds after a push.

That is the whole point of the design: **the server and the client can never
drift apart.** Change a mod here, and both sides pick it up on their own.

## The loop

```
edit the pack  →  git push  →  (30s)  →  restart the server  →  Frey launches Prism
```

## How to do things

All commands run from a clone of this repo. `packwiz` must be on PATH — it is
installed as `%USERPROFILE%\go\bin\packwiz.exe` by
`go install github.com/packwiz/packwiz@latest`.

`kubectl` is already configured with Frey's credential as the **default**
kubeconfig, so no `--kubeconfig` flag is needed anywhere.

### Add a mod

```powershell
packwiz modrinth add <modrinth-slug-or-url>   # e.g. packwiz modrinth add cobblemon
packwiz refresh
git add -A
git commit -m "Add Cobblemon"
git push
```

(Separate lines, not `&&` — Windows PowerShell 5.1 does not support `&&`.)

`packwiz modrinth add` will offer to add required dependencies — accept them.

**The pack is Minecraft 1.21.1 / NeoForge.** Plenty of mods do not exist for
that combination, and `packwiz modrinth add` simply fails when so — read the
error rather than fighting it.

To check before adding (or to find something that does fit), search Modrinth
filtered to this pack:

```
https://modrinth.com/mods?g=categories:neoforge&v=1.21.1
```

If a mod Frey names isn't available for 1.21.1, tell him so and offer to find an
alternative that does the same thing. **Never** change the pack's Minecraft or
NeoForge version to make a mod fit — that breaks his world and his friend's
setup (see "Ask Dad first" below).

### Remove a mod

```powershell
packwiz remove <name>          # name as shown by the files in mods/
packwiz refresh
git add -A
git commit -m "Remove X"
git push
```

⚠️ **Warn Frey before removing a mod he has already built with.** Blocks and
items from a removed mod vanish from the world — a Create contraption disappears
if Create is removed. Removing is safe only if he never used it.

### Update every mod to its newest version

```powershell
packwiz update --all
packwiz refresh
git add -A
git commit -m "Update mods"
git push
```

### Restart the server so it picks up the change

```powershell
kubectl -n game-servers rollout restart statefulset/minecraft
kubectl -n game-servers rollout status statefulset/minecraft --timeout=5m
```

The restart takes 1–3 minutes: the server downloads the new mods, then boots.
Nobody can be online during it — check first with `list` (below) and tell Frey
to warn his friend.

### Check the server

```powershell
kubectl -n game-servers get pod minecraft-0                    # is it up?
kubectl -n game-servers logs minecraft-0 -c minecraft --tail=50 # what is it doing / why did it fail?
kubectl -n game-servers exec minecraft-0 -c minecraft -- rcon-cli list      # who is online
kubectl -n game-servers exec minecraft-0 -c minecraft -- rcon-cli save-all  # force a save
```

`-c minecraft` matters: the pod also runs a `backup` container, and without it
kubectl may pick the wrong one.

### If the server won't start after a mod change

Read the log: `kubectl -n game-servers logs minecraft-0 -c minecraft --tail=100`.
Nearly always one of

- **a missing dependency** — the log names it; `packwiz modrinth add <it>`;
- **a mod incompatible with NeoForge 1.21.1** — remove it again;
- **two mods that clash** — remove the one added most recently.

Fix the pack, push, restart. If you can't fix it in two tries, revert to the
last working commit (`git revert HEAD` then `git push`) so Frey can play, and
tell him what went wrong.

### Restore the world if something ruins it

Hourly snapshots live on the server itself:

```powershell
kubectl -n game-servers exec minecraft-0 -c backup -- ls -lh /backups   # newest last
```

Restoring overwrites the current world and needs the server stopped first,
which is beyond Frey's credential — **this one goes to Dad.** Tell him which
snapshot (the filename is its timestamp) and he runs the restore. The world is
also in the cluster's nightly off-site backup, so nothing is ever truly lost.

## Ask Dad first

Do these only with Manuel's explicit approval — they are not Frey's to change
alone:

- changing `minecraft` or `neoforge` versions in `pack.toml` (breaks the world
  and forces his friend to re-set-up);
- anything in the `minecraft-tf` repo (that's the server's infrastructure);
- changing the whitelist / who can join;
- adding a mod that rewrites world generation (Biomes O' Plenty, Terralith…) —
  it only applies to *new* land and can't be removed later without holes.

## Client side (Frey's PC)

He plays on a **Windows PC**, through **Prism Launcher**, instance "Frey's
Modpack", which runs packwiz-installer as a pre-launch hook. He does nothing:
launching the instance syncs his mods to match this repo. If his client is out
of sync, the fix is to launch the instance again.

Server address: **valls.dev** (default port).

Setup on a new machine is in `SETUP-CLIENT.md`.