Работа с конфигурационными файлами игрового сервера

MAATRIX GAMES

Сломать сервер одной лишней запятой в json или забытой кавычкой в ini — классика жанра, через которую проходит почти каждый, кто первый раз лезет в конфиг руками. Дальше начинается паника: сервер не стартует, в логе нечитаемая ошибка, а бэкапа нет. На самом деле работа с конфигами устроена одинаково почти во всех играх — меняются только форматы файлов и конкретные параметры. Разберём общий подход: где искать, как бэкапить, как не сломать синтаксис и когда применённые правки требуют рестарта, а когда обходятся без него.

Где лежит конфиг

Первое, с чем сталкивается новичок — конфиг не всегда лежит там, где ожидаешь. Общие правила, которые работают почти везде:

• Корень папки сервера. Так устроены Source-игры (server.cfg у CS2, Team Fortress 2, Left 4 Dead 2), Minecraft (server.properties), Rust (параметры чаще в строке запуска, но часть настроек — в server.cfg в папке server/<identity>/cfg/).
• Подпапка config/ или cfg/. ARK хранит основные файлы в ShooterGame/Saved/Config/<платформа>/ (GameUserSettings.ini и Game.ini), многие модовые сборки на Unreal Engine следуют похожей структуре.
• Подпапка с именем мода/фреймворка. FiveM держит конфиги ресурсов в resources/<имя-ресурса>/config.lua или .json в зависимости от ресурса, ESX и QBCore — в собственных config.lua внутри соответствующих папок фреймворка.
• Отдельная папка saves/ или worlds/ для настроек конкретного мира — актуально для Valheim, Palworld, где часть параметров генерации привязана к сохранению, а не к глобальному конфигу.

Если не уверены, где искать — самый надёжный способ на Linux-сервере:

find /home/gameserver -maxdepth 3 -iname "*.cfg" -o -iname "*.ini" -o -iname "*.properties" -o -iname "*.yml" -o -iname "*.yaml"

Команда пробежится по первым трём уровням вложенности и покажет все файлы, похожие на конфиги. Если у вас сервер через панель хостера (Pterodactyl и подобные), там обычно есть встроенный файловый менеджер с подсветкой синтаксиса — искать вручную через SSH не придётся.

Отдельно стоит помнить: часть параметров дублируется между строкой запуска сервера (стартовые флаги, которые панель хостинга подставляет при старте процесса) и файлом конфига. Если правите файл, а сервер запускается со скриптом, где те же параметры прописаны флагами — флаг обычно побеждает файл. Проверяйте оба места, если правка "не применяется" необъяснимо.

Backup перед любой правкой

Это не совет "на будущее", а обязательный шаг перед каждой сессией правок, даже если меняете одну строку. Одна опечатка в критичном параметре — и сервер не поднимется, а вы не будете помнить, что именно поменяли за последние двадцать минут возни с конфигом.

Минимальная привычка — копия с датой рядом:

cp server.cfg server.cfg.bak-$(date +%Y%m%d-%H%M)

Если правите несколько файлов сразу (например, и GameUserSettings.ini, и Game.ini для ARK), проще упаковать всю папку конфигов целиком:

tar -czf config-backup-$(date +%Y%m%d).tar.gz config/

Для тех, кто правит конфиги часто, есть смысл завести в папке сервера git-репозиторий только под конфиги (не под весь сервер — файлы миров и сейвы туда не нужны, это гигабайты лишнего):

git init
echo "*.log" >> .gitignore
git add server.cfg server.properties
git commit -m "baseline before edits"

Тогда откат — это git diff и git checkout -- server.cfg, а не поиск нужного .bak-файла среди десятка похожих. Плюс видно точный diff, что именно изменилось, если сервер вдруг перестал стартовать после серии правок за вечер.

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

Синтаксис популярных форматов

Форматов конфигов на практике всего четыре-пять, и у каждого свои грабли.

INI/CFG (ключ=значение) — самый простой и распространённый формат, используется в Source-играх, ARK, многих старых движках:

[ServerSettings]
DifficultyOffset=1.0
MaxPlayers=70
ServerPassword=

Грабли: секции в квадратных скобках чувствительны к регистру и к точному написанию — [ServerSettings] и [serversettings] в некоторых парсерах это разные секции, и параметр в неправильной секции просто игнорируется без ошибки. В .cfg-файлах Source-игр секций нет вообще, там просто список команд:

hostname "Мой сервер CS2"
sv_password ""
mp_maxrounds 24

JSON (вложенная структура) — используется в конфигах FiveM-ресурсов, части модов, в панелях управления:

{
  "server": {
    "name": "My Server",
    "maxPlayers": 32,
    "plugins": ["EssentialsX", "WorldEdit"]
  }
}

Главная грабля JSON — запятые. Лишняя запятая после последнего элемента массива или объекта (trailing comma) — и файл невалиден целиком, парсер откажется его читать. JSON также не прощает комментарии // или # — некоторые движки допускают расширенный JSON5 с комментариями, но это не стандарт, и полагаться на это без проверки документации конкретной игры не стоит.

YAML (вложенная структура через отступы) — часто встречается в конфигах плагинов Minecraft (Paper, Spigot, Bukkit-плагины вроде EssentialsX):

server:
  name: My Server
  max-players: 32
  plugins:
    - EssentialsX
    - WorldEdit

Грабля YAML — отступы. Табуляция вместо пробелов ломает структуру (YAML требует именно пробелов, обычно два на уровень), а несовпадение отступов между соседними строками одного уровня — частая причина, почему плагин не грузится после ручной правки config.yml.

Проверка синтаксиса перед применением

Правило простое: невалидный json или yaml не запустит сервис, который его читает, а в логе вы получите в лучшем случае номер строки, в худшем — общее "failed to parse config" без подробностей. Проверять файл до перезапуска — дешевле, чем потом разбираться, что сломалось.

Для JSON — быстрая проверка через python3, стоит почти на любом Linux-сервере из коробки:

python3 -m json.tool config.json > /dev/null && echo "OK" || echo "BROKEN"

Если вывод "BROKEN" — команда покажет строку и позицию ошибки прямо над этим.

Для YAML — тоже через Python, если установлен модуль pyyaml:

python3 -c "import yaml; yaml.safe_load(open('config.yml'))" && echo "OK"

Если pyyaml не стоит, pip install pyyaml займёт секунды, либо можно воспользоваться любым онлайн-валидатором (например, встроенным в редакторы вроде VS Code — там подсветка синтаксиса сразу покажет невалидный блок красным до сохранения).

Для INI/CFG строгой схемы валидации обычно нет — синтаксис слишком простой, чтобы сломаться структурно, но там легко ошибиться в имени параметра (опечатка в MaxPlayers вместо MaxPlayers — условно, лишний пробел или неверный регистр) — движок просто проигнорирует параметр с неизвестным именем, никакой ошибки не будет, а поведение сервера не изменится, что сбивает с толку сильнее, чем явный краш. Тут единственная защита — сверяться с официальной документацией параметров конкретной игры, а не копировать чужой конфиг из случайного форумного треда без понимания, что каждая строка делает.

Применение изменений: рестарт или reload

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

Требуют полного рестарта почти всегда:

• Параметры сети — порт, IP-бинд, RCON-порт и пароль.
• Параметры генерации мира — сид, размер карты (ARK, Rust, Valheim).
• Загружаемые при старте списки модов/плагинов — сервер сканирует папку с модами один раз при запуске.
• Лимиты памяти и параметры JVM для Minecraft — прописываются в скрипте запуска, а не в конфиге, применяются только при перезапуске процесса.

Можно применить без остановки (через RCON или встроенную команду):

• Minecraft — команда /reload перечитывает часть конфигов и плагины, но у неё плохая репутация: /reload известен тем, что иногда ломает состояние уже загруженных плагинов (утечки памяти, дублирование листенеров событий). На практике многие опытные админы предпочитают точечный reload конкретного плагина через его собственную команду (/essentials:reload и подобные), а не глобальный /reload.
• Source-игры — большинство cvar-параметров в server.cfg применяются сразу при выполнении через консоль или RCON, без рестарта — именно поэтому server.cfg можно исполнить заново командой exec server.cfg в консоли сервера.
• Rust — часть параметров (server.hostname, лимиты чата) меняется на лету через консоль/RCON, но параметры мира требуют полного рестарта процесса.

Если не уверены, какой конкретно параметр требует рестарта в вашей игре — самый безопасный путь: применить через reload/RCON, тут же проверить, сработало ли изменение (status или аналог в конкретной игре), и если нет — просто перезапустить сервер в окно с минимумом игроков. Это надёжнее, чем гадать по форумам, которые часто устарели относительно текущей версии игры.

Если у вас сервер поднят через панель управления хостинга — там обычно есть кнопка "Restart" с ожиданием graceful shutdown (сервер сначала сохраняет мир, потом останавливается), это безопаснее, чем kill процесса напрямую, если ваш конфиг живёт вне docker-обвязки хостера.

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