# minecraft-lab

Платформа для пользовательских сборок **NeoForge/Forge без обязательных
аккаунтов**. Подтверждённая основа: Minecraft 1.21.1 + NeoForge 21.1.252,
Sophisticated Backpacks/Core и client-only Mouse Tweaks. Forge пока требует
отдельного spike. Текущий source release — 0.0.5.

## Сборка

Нужны Linux x86_64, Bash, Node.js 22+, npm, Git, curl, bsdtar и sha256sum.
Docker daemon для build не нужен. Bootstrap загружает закреплённые packwiz
и Compose в `.tools/`; npm parsers закреплены lockfile.

После clone из корня репозитория:

```bash
npm ci --ignore-scripts
scripts/spike-tools.sh
./mcpack build
```

Результат:

```text
dist/minecraft-lab-neoforge-spike-0.0.5/
├── minecraft-lab-neoforge-spike-0.0.5.mrpack
├── server/
├── manifest.json
└── SHA256SUMS
```

Build читает `platform/config.yaml`, работает в копии source и не меняет
исходники. Готовый релиз не перезаписывается. Для изменения source выбрать
новую pack version и явно выполнить refresh перед сборкой:

```bash
cd pack
../.tools/packwiz/packwiz refresh
cd ..
./mcpack build
```

Development build допускает dirty worktree и отмечает его в manifest.
`./mcpack build --release` требует чистого Git state.
Подробности: [docs/build.md](docs/build.md). Тесты: `npm test`.

## Моды

```bash
./mcpack add <modrinth-slug|ID|URL>
./mcpack remove <mod>
./mcpack update <mod>
./mcpack update --all
```

Команды работают с source через packwiz, сохраняют prompts и сообщения.
Для автоматического ответа добавить `--yes`. Перед следующим build выбрать
новую pack version. Подробности: [docs/mods.md](docs/mods.md).

## Клиент

Prism → Add Instance → Import: выбрать готовый `.mrpack`. В текущем WSL путь:

```text
\\wsl.localhost\archlinux\root\Projects\minecraft-lab\dist\minecraft-lab-neoforge-spike-0.0.5\minecraft-lab-neoforge-spike-0.0.5.mrpack
```

Можно запускать с offline-аккаунтом/Launch Offline. Адрес локального сервера
**127.0.0.1:25565**: `localhost` может разрешиться в IPv6 `::1`, тогда как
локальный Phase 0 Compose публикует только IPv4 loopback.
Удалённый сервер доступен напрямую по **192.168.1.61:25565**.

## Сервер

Server Compose внутри полного релиза использует pinned image, offline
authentication и абсолютные `MC_ROOT`/`MC_RELEASE_DIR`. Настройки из
`server/config/` релиза имеют приоритет над pack defaults. Локальные secrets
и EULA acceptance в артефакт не попадают; `.env.example` содержит EULA=FALSE.
Команда build сервер не запускает и runtime не меняет.

Для lifecycle готового релиза добавлен `scripts/server.sh` с проверкой
checksums, локальной EULA/UID/GID и привязкой runtime к релизу. Первоначальная
настройка и start/restart/recreate — [docs/runtime.md](docs/runtime.md).

`scripts/server.sh up --wait --wait-timeout 120` ожидает Minecraft status
query и стабильную работу. `scripts/server.sh health` проверяет уже созданный
контейнер. Crash, restart loop и timeout возвращают non-zero с report/logs:
[docs/health.md](docs/health.md).

Для проверки Compose нового релиза:

```bash
MC_ROOT="$PWD" MC_RELEASE_DIR="$PWD/dist/minecraft-lab-neoforge-spike-0.0.5" \
  .tools/docker-compose --project-name minecraft-lab-spike \
  --env-file dist/minecraft-lab-neoforge-spike-0.0.5/server/.env.example \
  -f dist/minecraft-lab-neoforge-spike-0.0.5/server/compose.yaml config --quiet
```

Текущий Phase 0 сервер остаётся на 0.0.1 и управляется прежним wrapper:

```bash
scripts/spike-server.sh ps
scripts/spike-server.sh logs --tail 100
```

Пользователь принял EULA для этого эксперимента. На новом host принятие
требуется отдельно. Готовый релиз хранится целиком; SSH deployment и
[rollback](docs/rollback.md) используют его без повторной сборки.

## Backup и восстановление

Для runtime с full-release binding:

```bash
MC_ROOT=/absolute/server-root MC_RELEASE_DIR=/absolute/full-release ./mcpack backup
./mcpack restore --backup /absolute/snapshot --destination /absolute/new-server-root
```

Backup останавливает сервер, проверяет архив всего runtime и сохраняет копию
исходного релиза. После успеха ранее запущенный сервер возвращается в работу.
Restore разрешён только в новый каталог; запуск выполняется отдельно.
Нужны GNU tar, zstd и права на чтение/сохранение владельцев данных.
Подробности и recovery procedure — [docs/backups.md](docs/backups.md).

## SSH deployment

```bash
./mcpack deploy --artifact /absolute/full-release
```

SSH target задаётся в `platform/config.yaml`, host `.env` готовится отдельно.
Deployment принимает clean releases, передаёт payload через rsync, проверяет
конфликты, создаёт backup и обновляет active/previous только после healthcheck.
Тот же healthy release повторно не перезапускается.
Порт и Node из nvm можно задать через `--ssh-config` и `--remote-node`.
Bind interface задаётся host `.env`: `MC_BIND_ADDRESS=0.0.0.0` для remote LAN,
`127.0.0.1` для локального запуска. Настроенный host и команды подключения — [docs/deploy.md](docs/deploy.md).

## Структура

`platform/` — config, compatibility record и build orchestration; `pack/` —
источник модпака; `server/` — Compose и settings; `scripts/` — CLI entry и
spike-утилиты. `docs/`, `examples/`, `testdata/`, `tests/` содержат результаты
и материалы проверок. Runtime, dist, tools, node_modules, backups и local
secrets исключены из Git, кроме placeholders.

Результаты: [Phase 0](docs/spike-results.md), [Phase 1](docs/phase1-results.md),
[Phase 2](docs/phase2-results.md), [Phase 3](docs/phase3-results.md),
[Phase 4](docs/phase4-results.md), [Phase 5](docs/phase5-results.md),
[Phase 6](docs/phase6-results.md), [Phase 7](docs/phase7-results.md),
[Phase 8](docs/phase8-results.md), [Phase 9](docs/phase9-results.md).

Выпуск из чистого Git worktree: `./mcpack release 0.0.6`.
Команда обновляет версию, проверяет сборку, коммитит `pack.toml`, собирает
финальный release и создаёт annotated tag. [Workflow и recovery](docs/releases.md).
Fabric-эксперимент архивирован в `examples/fabric-spike/` и
[fabric-spike-results.md](docs/fabric-spike-results.md).