BepInEx: установка модов на сервер Valheim

MAATRIX GAMES

Голый ванильный сервер Valheim быстро упирается в потолок — хочется больше слотов на поясе, менее дурацкий баланс порталов или просто чуть более щедрый лут. Почти все моды под Valheim цепляются к игре через один и тот же фреймворк — BepInEx, и без него ни один .dll-мод на сервере просто не загрузится. Разберём, как поставить его правильно на уже работающий dedicated-сервер, не сломав автозапуск и не разойдясь версиями с игроками.

Что такое BepInEx и зачем он нужен

BepInEx — это фреймворк для инъекции плагинов в Unity-игры, и Valheim работает как раз на Unity. Сам по себе BepInEx ничего не меняет в игре — это просто загрузчик, который на старте сервера подхватывает .dll-файлы модов из своей папки и подключает их к игровому процессу через хуки Harmony. Подавляющее большинство модов Valheim (кроме совсем простых конфиг-патчей через утилиты вроде UnityDoorstop напрямую) требуют именно BepInEx как зависимость — это де-факто стандарт для этой игры, примерно как Forge или Fabric для Minecraft: один фреймворк-загрузчик, вокруг которого строится вся экосистема модов.

Если сервер ещё не поднят — сначала разверните его по базовой инструкции: как поднять сервер Valheim. Дальше в этой статье считаем, что у вас уже есть рабочий valheim_server.x86_64 с systemd-автозапуском, и мы ставим BepInEx поверх — как надстройку, а не с нуля.

Важный нюанс: под Valheim не берите произвольный BepInEx с официального GitHub — там лежит "голый" универсальный билд, который для Valheim придётся донастраивать руками (доустанавливать Unity Doorstop, прописывать пути). Комьюнити давно сошлось на готовой сборке специально под Valheim — она и описана ниже.

Скачиваем BepInExPack Valheim с Thunderstore

Thunderstore — основная площадка модов для Valheim (thunderstore.io), там же лежит и сама сборка фреймворка. Нужный пакет называется BepInExPack Valheim от автора denikson — это не голый BepInEx, а уже настроенная под Valheim связка BepInEx + Unity Doorstop с готовыми скриптами запуска и для Windows, и для Linux. Практически все моды на Thunderstore в качестве зависимости указывают именно этот пакет.

Открываете страницу пакета на valheim.thunderstore.io, скачиваете zip-архив (обычно 5-10 МБ) — либо через браузер на свой ПК и затем scp на сервер, либо wget прямой ссылкой на файл, если она у вас есть:

# на локальной машине, если скачали через браузер
scp BepInExPack_Valheim-*.zip valheim@ваш-сервер:/home/valheim/valheim-server/

Проверять контрольную сумму жёстко не обязательно, но полезно свериться, что версия пакета актуальна на момент установки — на странице Thunderstore указана дата последнего обновления и список изменений.

Устанавливаем на сервер: распаковка и структура папок

Главная грабля здесь — архив с Thunderstore распаковывается во вложенную папку BepInExPack_Valheim/, а не прямо в текущую директорию. Если просто сделать unzip в папке сервера, содержимое окажется на уровень глубже, чем нужно, и скрипты запуска не найдут valheim_server.x86_64 рядом с собой. Разворачиваем правильно:

cd /home/valheim/valheim-server
unzip BepInExPack_Valheim-*.zip -d /tmp/bepinex-tmp
mv /tmp/bepinex-tmp/BepInExPack_Valheim/* .
rm -rf /tmp/bepinex-tmp
chmod +x start_server_bepinex.sh

После этого в папке сервера, рядом с valheim_server.x86_64 и valheim_server_Data/, должны появиться:

valheim-server/
├── valheim_server.x86_64
├── valheim_server_Data/
├── start_server_bepinex.sh      # запуск сервера с BepInEx на Linux
├── start_game_bepinex.sh
├── doorstop_config.ini
├── unstripped_corlib/
└── BepInEx/
    ├── core/                     # сам фреймворк, не трогаем
    ├── config/                   # конфиги модов появятся здесь после первого запуска
    ├── patchers/
    └── plugins/                  # сюда кладём моды

Если вместо этой структуры вы видите папку BepInExPack_Valheim внутри папки сервера — значит распаковали на уровень глубже, повторите mv ещё раз, поднимая содержимое.

Кладём моды в BepInEx/plugins и правим автозапуск

Каждый мод с Thunderstore обычно распространяется тоже как zip, внутри которого либо сразу лежит .dll-файл, либо папка BepInEx/plugins/ИмяМода/ с .dll и сопутствующими файлами (иконки, конфиги, зависимости вроде дополнительных .dll библиотек). Распаковываете и кладёте содержимое именно в BepInEx/plugins/ вашего сервера:

cd /home/valheim/valheim-server/BepInEx/plugins
unzip ~/downloads/SomeMod-1.2.3.zip -d SomeMod

Никаких дополнительных регистраций не нужно — BepInEx на старте сам сканирует всё, что лежит в plugins/, и подгружает валидные .dll. Если мод зависит от другого мода (частая история — многие плагины требуют библиотеку Jotunn как общий фреймворк для контента), убедитесь, что зависимость тоже лежит в plugins/, иначе загрузка упадёт с ошибкой отсутствующей сборки.

Дальше нужно поменять, что именно запускает systemd — раньше юнит стартовал valheim_server.x86_64 напрямую, теперь нужно стартовать start_server_bepinex.sh с теми же аргументами, что были раньше:

# /etc/systemd/system/valheim.service
[Service]
WorkingDirectory=/home/valheim/valheim-server
ExecStart=/home/valheim/valheim-server/start_server_bepinex.sh \
  -name "MyServer" -port 2456 -world "Dedicated" \
  -password "supersecret1" -public 1 \
  -savedir "/home/valheim/valheim-server/saves"

Скрипт start_server_bepinex.sh — это тонкая обёртка: он выставляет переменные окружения Doorstop (DOORSTOP_ENABLE, путь до BepInEx.Preloader.dll) и передаёт все аргументы дальше в valheim_server.x86_64 как есть. Поэтому параметры запуска (имя, порт, пароль, мир, -savedir) остаются ровно теми же, что вы использовали при базовой установке — меняется только сам исполняемый файл в ExecStart.

sudo systemctl daemon-reload
sudo systemctl restart valheim

Синхронизация модов с клиентами

Это, пожалуй, самая частая причина «я не могу зайти на сервер друга» в модовых Valheim-сообществах. Клиент должен иметь тот же набор модов той же версии, что и сервер — при малейшем расхождении часть модов (особенно те, что трогают рецепты, префабы или сетевые данные) либо десинхронизируются молча, либо явно откажут в подключении с ошибкой несовместимости. Ставить моды клиентам вручную, гоняя zip-архивы по Discord — то ещё мучение, поэтому для игроков обычно используют менеджер модов: r2modman или его форк Thunderstore Mod Manager. Оба умеют:

• скачать конкретный профиль модов одной ссылкой (можно экспортировать профиль сервера и разослать код игрокам);
• держать несколько профилей под разные серверы, не смешивая моды между собой;
• сами подтягивать BepInEx нужной версии для клиента — вручную распаковывать архивы игрокам не придётся, это делает менеджер.

Практика, которая экономит нервы: заведите у себя на сервере профиль модов в r2modman (или просто список mod-name@version), экспортируйте код профиля через кнопку "Export" — и присылайте этот код всем, кто подключается. Так исключается ситуация, когда кто-то поставил более новую версию мода с багфиксом, а остальные — нет.

Проверяем, что BepInEx реально загрузился

После systemctl restart valheim смотрите вывод сервера:

journalctl -u valheim -f

При успешной загрузке в самом начале лога должны быть строки вида:

[Message: BepInEx] BepInEx 5.4.x - valheim_server
[Message: BepInEx] Running under Unity v2020.x.x
[Info   :   BepInEx] Loading [SomeMod 1.2.3]
[Info   :   BepInEx] Loading [Jotunn 2.x.x]
[Info   :   BepInEx] Chainloader startup complete

Если этих строк нет вообще, а сервер стартует как будто BepInEx не подключился — скорее всего, systemd всё ещё запускает valheim_server.x86_64 напрямую, а не start_server_bepinex.sh (проверьте ExecStart), либо start_server_bepinex.sh не получил прав на выполнение. Полный лог со всеми деталями загрузки плагинов также пишется в файл BepInEx/LogOutput.log в папке сервера — туда стоит заглянуть в первую очередь при ошибке, там обычно видно, какой именно мод не смог загрузиться и почему (чаще всего — не хватает зависимости в plugins/ или несовместимая версия самого BepInEx с версией мода).

Если после установки конкретного мода сервер перестал стартовать вовсе — временно уберите его .dll из plugins/ и перезапустите: если сервер поднимается, проблема локализована, дальше разбираться проще, чем со всей пачкой модов сразу.

Частые вопросы