MCMapper-Mod/test/README.md

# Live test servers

Real Minecraft servers (via [itzg/docker-minecraft-server](https://github.com/itzg/docker-minecraft-server),
MIT — handles EULA acceptance, Forge/NeoForge installation, memory flags, etc. so this compose
file doesn't reimplement any of that) for exercising the mod end-to-end against a running
MCMapper-Backend stack — the thing the plan's own per-phase verification steps keep asking for
("place/break blocks, confirm they appear on the map") but that no session has actually done yet.

Only `mc-1_12_2` runs by default — it's the actual driving use case (Enigmatica 2, see the plan's
version priority). `mc-1_7_10` and `mc-neoforge-26_1` are opt-in via Compose profiles:

```
docker compose up                           # 1.12.2 only (default)
docker compose --profile legacy-1_7_10 up    # + 1.7.10
docker compose --profile neoforge-26_1 up    # + 26.1.2 NeoForge (least tested, lowest priority)
```

## 1. Start a backend stack

From `MCMapper-Backend`, either:
- `docker compose up` (full stack — api/frontend/worker/postgres/redis/caddy; Caddy publishes
  `:80` on the host, routing `/ws*` to `api` per the Caddyfile), or
- run `api` directly (`cd api && bun run dev`) for a lighter loop — it listens on `:3000` with no
  proxy in front.

Either way, register a server row so the mod has a token to authenticate with:

```
cd MCMapper-Backend/api
MCMAPPER_SEED_SERVER_NAME=test-1_12_2 MCMAPPER_SEED_SERVER_TOKEN=<pick-any-string> \
MCMAPPER_SEED_SERVER_AUTH_MODE=offline \
DATABASE_URL=postgres://mcmapper:mcmapper@localhost:<pg-port>/mcmapper bun run seed
```

(`authMode=offline` matches this compose's default `ONLINE_MODE=FALSE` — see docker-compose.yml's
comment on that variable. Use `online` + `ONLINE_MODE=TRUE` instead to test the real UUID-merge
identity path.) The admin panel (`/admin` on the frontend, Phase 6) is the other way to register a
server, if the backend is already up with `MCMAPPER_ADMIN_TOKEN` set.

## 2. Build the mod and drop the jar in

```
cd MCMapper-Mod
./gradlew :forge-1_12_2:build
cp forge-1_12_2/build/libs/forge-1_12_2-*.jar test/mods/forge/1.12.2/
```

(Swap the leaf/version for `forge-1_7_10`/`mods/forge/1.7.10` or `neoforge-26_1`/`mods/neoforge/26.1.2`
— note `neoforge-26_1` has its own standalone Gradle wrapper, see the root README's "Building". Mods
are split by loader first, then version — Forge and NeoForge mod jars aren't interchangeable even
for adjacent MC versions. Each `mods/<loader>/<version>/` directory maps straight to that server's
`/data/mods` — drop other mod jars in there too to test alongside MCMapper, and remove/swap them any
time, then `docker compose restart` to pick up the change; nothing in `mods/`/`config/` is ever
committed, see .gitignore.)

## 3. First boot, then configure

```
cd test
docker compose up -d
docker compose logs -f mc-1_12_2   # wait for "Done" / world generation to finish
```

The mod writes `config/mcmapper.cfg` with empty defaults on this first boot (it needs a
`backendUrl`/`serverToken` before it'll actually connect — see the root README's "Configuration"
section). Edit `test/config/forge/1.12.2/mcmapper.cfg`:

```
backendUrl=ws://host.docker.internal:80/ws
serverToken=<the token you seeded above>
```

Use `ws://host.docker.internal:80/ws` if the backend is running via its own `docker compose up`
(Caddy on host `:80`), or `ws://host.docker.internal:3000/ws` if you ran `bun run dev` for `api`
directly instead (no Caddy in front). `extra_hosts: host.docker.internal:host-gateway` in
docker-compose.yml is what makes that hostname resolve to the host machine from inside the MC
container — works the same whether the host's Docker is Docker Desktop or a bare Linux daemon
(Engine ≥20.10, which this project's own WSL2 dockerd is).

Then:

```
docker compose restart mc-1_12_2
```

## 4. Verify

Connect a real Minecraft 1.12.2 client to `localhost:${MC_1_12_2_PORT:-25565}` (offline/cracked
login works fine with the default `ONLINE_MODE=FALSE`), walk around to load some chunks, place/
break a few blocks, then check the map frontend (`http://localhost` if using the backend's own
`docker compose`, or `http://localhost:3001` if running `frontend` directly) — this is the actual
Phase 1 verification step from the plan, finally exercised against a real server rather than only
unit/integration tests. Also useful for later phases' own live-test callouts that were flagged but
never actually run: the atlas shader's `invertY` assumption (Phase 12) and real non-cube block
rendering (Phase 13, place/find a vanilla non-cube block like a torch or stairs — or attach a mod
that ships one, e.g. Thaumcraft, by dropping its jar in the same `mods/forge/1.12.2/` directory).

## Notes

- World/server data persists in named Docker volumes (`mc-1_12_2-data` etc.) across
  `docker compose restart`/`down` — use `docker compose down -v` to fully wipe a server and start
  over (e.g. after bumping the mod jar in a way that needs a clean world).
- `mods/<loader>/<version>/` and `config/<loader>/<version>/` contents are gitignored (except the
  `.gitkeep` placeholders that keep the mount points present in a fresh checkout) — nothing dropped
  in them is committed.
- To add other mods for stress-testing (Thaumcraft was the plan's named non-cube-model stress
  test for Phase 13) drop their jars in the same `mods/forge/1.12.2/` directory itzg's image reads
  from — no compose changes needed. itzg's image also supports `CURSEFORGE_FILES`/`MODRINTH_PROJECTS`
  for auto-downloading specific mods (CurseForge's downloads generally need a `CF_API_KEY` now);
  not wired up here since that needs per-mod IDs/an API key only you can supply — see itzg's own
  docs (https://docker-minecraft-server.readthedocs.io/) if you want that instead of manual jars.