158 lines
7.6 KiB
Markdown
158 lines
7.6 KiB
Markdown
# 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).
|