Vintage Story: установка модов на сервер

MAATRIX GAMES

Ванильный Vintage Story уже глубокая игра, но рано или поздно хочется либо докрутить прогрессию (XSkills), либо добавить лут и вариативность (Wildcraft Fruit, Carry Capacity), либо просто поправить мелкие неудобства интерфейса. Проблема в том, что здесь модификации ставятся иначе, чем в большинстве игр из этого блога: нет Steam Workshop, нет автоматической загрузки модов клиенту, а версии мода на сервере и у игрока обязаны совпадать почти буквально. Разберём, где брать моды, куда их класть и как не словить рассинхрон при первом же коннекте игрока.

Где искать моды: официальная ModDB Vintage Story

У Vintage Story есть собственная площадка модов — mods.vintagestory.at — это и есть та самая «ModDB игры», о которой идёт речь: официальный каталог, встроенный в экосистему игры, а не сторонний агрегатор вроде generic ModDB.com или Nexus. Разработчики (Anego Studios) сами ссылаются на неё из клиента, и большинство активных модмейкеров публикуют новые версии именно там первыми.

На странице каждого мода стоит смотреть на три вещи до того, как жать «скачать»:

• Совместимость по версии игры — в блоке Dependencies или прямо в шапке страницы указано, под какую версию Vintage Story собран билд мода (например, game >= 1.20.0). Мод под старую версию может не загрузиться вообще или загрузиться с молчаливыми багами.
• Дата последнего обновления — Vintage Story меняется активно, и заброшенный полгода назад мод под текущий билд игры — частая причина краша при загрузке.
• Side (сторона) — на странице мода обычно помечено, нужен ли он только клиенту (визуальные твики, UI), только серверу (административные утилиты) или обеим сторонам (контентные моды — новые блоки, существа, механики). Это прямо влияет на то, куда его класть.

Не тащите моды с сомнительных сторонних сайтов и архивов «сборка модов одним файлом» — для Vintage Story такие сборки почти всегда содержат устаревшие версии, которые разваливаются при первом апдейте игры.

Формат модов и куда их класть

Vintage Story распознаёт три формата модов, и все они кладутся в одну и ту же папку без дополнительной сборки:

• .zip — самый частый формат. Внутри лежат modinfo.json, ассеты (текстуры, звуки, лут-таблицы) и, если мод не чисто ассетный, скомпилированные классы. Zip-архив распаковывать не нужно — игра читает его прямо так, как скачали.
• .cs — одиночный файл с исходником на C#, который Vintage Story компилирует на лету через встроенный Roslyn-компилятор при старте. Удобно для маленьких утилитарных модов, но при большом их числе заметно увеличивает время запуска сервера.
• .dll — уже скомпилированная библиотека, встречается реже, обычно у более сложных модов с нативными зависимостями.

Папка модов — Mods, и лежит она внутри dataPath вашего сервера, а не рядом с исполняемым server.sh. Если разворачивали сервер по нашей инструкции по установке Vintage Story с --dataPath /home/vsuser/vsserver/data, то полный путь такой:

/home/vsuser/vsserver/data/Mods

Папки может не быть при первом запуске — создайте её вручную:

mkdir -p /home/vsuser/vsserver/data/Mods

Загрузить архив на VPS можно через scp с локальной машины или сразу wget прямой ссылкой со страницы мода на mods.vintagestory.at:

scp CarryCapacity_1.9.2.zip vsuser@ваш-ip:/home/vsuser/vsserver/data/Mods/

После копирования перезапустите сервис:

sudo systemctl restart vsserver
journalctl -u vsserver -f

В логе при удачной загрузке будет строка вида Loaded mod: CarryCapacity vX.Y.Z — если её нет, а сервер поднялся, смотрите на ошибки чуть выше по логу: это почти всегда первый сигнал проблемы совместимости.

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

Это ключевое отличие Vintage Story от, скажем, Minecraft с Paper-плагинами: контентные моды обязаны совпадать по modid и версии у сервера и у каждого подключающегося игрока. При хендшейке клиент сверяет список модов сервера со своим, и если чего-то не хватает или версия расходится, подключение обрывается сразу, ещё до входа в мир — игрок увидит сообщение о недостающем или несовпадающем моде с конкретным modid и версией.

Из этого следует практическое правило: когда ставите контентный мод на сервер, тут же публикуйте для своих игроков точно такой же zip-файл той же версии (например, в закреплённом сообщении в Discord сообщества сервера) — вручную скачать и положить мод в клиентскую папку Mods обязан каждый игрок сам, автоматической докачки, как в Workshop-играх, здесь нет.

Не все моды требуют этого. Чисто визуальные и клиентские твики (замена текстур интерфейса, HUD-моды, некоторые quality-of-life улучшения без изменения игровых данных) можно ставить только на клиент — серверу они не нужны и никак не мешают. Обратное тоже верно: административные утилиты (логирование, античит, серверные команды) обычно работают только на сервере и не требуют установки у игроков. Ориентируйтесь на пометку Side на странице мода — если сомневаетесь, ставьте на обе стороны, это безопаснее, чем гадать.

Пошаговая установка мода на пример

Разберём на конкретном примере — установка XSkills, популярного мода на систему прокачки навыков.

1. Откройте страницу мода на mods.vintagestory.at, проверьте совместимость с версией вашего сервера (её видно в логе при старте сервера или в serverconfig.json по номеру билда) и скачайте актуальный .zip.
2. Проверьте секцию Dependencies на странице — у XSkills есть зависимость от библиотечного мода XLib, без которого он не загрузится. Скачайте и его.
3. Скопируйте оба архива в Mods:

scp XSkills_*.zip XLib_*.zip vsuser@ваш-ip:/home/vsuser/vsserver/data/Mods/

1. Перезапустите сервер и проверьте лог на предмет ошибок загрузки:

sudo systemctl restart vsserver
journalctl -u vsserver -n 100 --no-pager | grep -i mod

1. Убедитесь, что оба мода отмечены как загруженные, зайдите на сервер тестовым клиентом с теми же двумя файлами в клиентской папке Mods и проверьте, что появился новый интерфейс навыков.
2. Разошлите игрокам те же zip-файлы той же версии для их клиентов.

Тот же порядок действий подходит для любого мода с зависимостями — сначала библиотечные моды, от которых он зависит, потом сам мод.

Зависимости, конфликты и порядок загрузки

Явного ручного порядка загрузки (как, например, в некоторых модульных играх, где список модов сортируется вручную) у Vintage Story нет — движок сам разрешает порядок на основе поля dependencies в modinfo.json каждого мода: если мод A объявляет зависимость от мода B, B гарантированно инициализируется раньше. Вам нужно только убедиться, что все объявленные зависимости физически лежат в папке Mods.

Типичная структура modinfo.json, если любопытно, что смотрит движок:

{
  "type": "content",
  "modid": "xskills",
  "name": "XSkills",
  "version": "1.7.4",
  "dependencies": {
    "game": "1.20.0",
    "xlib": ""
  }
}

Конфликты между модами в Vintage Story случаются реже, чем в играх с открытой правкой байткода — большинство модов добавляют новый контент через API, а не переписывают чужой код. Но столкновения всё же бывают: два мода регистрируют один и тот же идентификатор блока или предмета, либо оба патчат одну и ту же лут-таблицу несовместимым образом. Если сервер после установки нового мода начал странно себя вести (не крашится, но, например, дублируется рецепт крафта или пропадает дроп с руды) — временно отключите последний добавленный мод и проверьте, воспроизводится ли проблема без него.

Обновление, отключение и типичные ошибки

Отключить мод без удаления. Уберите его файл из папки Mods в отдельную резервную подпапку (например, Mods/disabled/) — Vintage Story сканирует только корень Mods, и вложенные подпапки с модами не трогает. Перезапуск сервиса — мод перестаёт грузиться.

Обновление при выходе новой версии игры. Крупные обновления Vintage Story нередко ломают часть модов — движок сверяет поле game в зависимостях и просто откажется грузить мод, версия которого явно не покрывает текущий билд. Перед обновлением сервера проверьте страницы всех установленных модов на mods.vintagestory.at на предмет свежих билдов под новую версию, и только потом обновляйте сам сервер. Подробный разбор того, что стоит автоматизировать в этом процессе, а что опасно пускать на автопилот, — в статье про автообновление модов на сервере.

Частые ошибки и что они значат:

• Mod requires game version X, but you have Y — версия игры не подходит под требования мода. Решение: обновить сервер или найти билд мода под текущую версию.
• Мод не появляется в логе вообще — файл лежит не в той папке (проверьте, что это именно dataPath/Mods, а не папка рядом с server.sh) или архив повреждён при копировании — перекачайте заново.
• Клиент выбрасывает при подключении с сообщением о недостающем моде — на сервере есть мод, которого нет у игрока (или наоборот). Сверьте списки Mods на обеих сторонах построчно.
• Сервер запускается, но крашится именно при заходе в конкретный старый мир — иногда виноват не сам мод, а несовместимые данные, записанные им в сохранение до обновления. Это отдельная и более неприятная категория проблем — если попали именно в неё, у нас есть отдельный разбор краша сервера при загрузке мира.
• Дублирующийся modid у двух разных модов из разных источников — переименуйте архив не поможет, только удалить один из конфликтующих модов, movid жёстко зашит внутри modinfo.json.

Если сервер вообще не поднимается после добавления модов и непонятно, где смотреть в первую очередь, начните с общей диагностики запуска Vintage Story — она пригодится независимо от того, моды виноваты или что-то другое.

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