Garry's Mod — server.cfg и addon-манифест

MAATRIX GAMES

Если сервер уже стоит и коллекция Workshop подключена через host_workshop_collection, для большинства проектов на этом можно и остановиться. Но как только в дело вступает кастомный контент не из Workshop, собственный аддон, который нужно точечно догружать отдельно от основной коллекции, или ты сам публикуешь свои наработки — базового конфига мало. Разберём три вещи, которые обычно всплывают именно на этом этапе: fastdl для контента вне Workshop, манифест addon.json для сборки аддонов и функцию resource.AddWorkshop для точечной догрузки.

Когда базового host_workshop_collection не хватает

Workshop отлично закрывает 90% случаев: собрал коллекцию, прописал ID и -authkey в строке запуска — дальше про синхронизацию с клиентами можно не думать (это подробно разобрано в статье про установку аддонов из Steam Workshop). Но есть ситуации, где одной коллекции недостаточно.

Во-первых, контент, который по каким-то причинам не лежит в Workshop — старые кастомные карты без загруженной версии, приватные ресурсы сообщества, материалы с лицензионными ограничениями на публикацию. Для них нужен старый добрый fastdl.

Во-вторых, когда нужно догрузить конкретный Workshop-предмет из кода аддона или гейммода независимо от того, что стоит в общей коллекции сервера — например, базовый гейммод требует конкретный набор моделей оружия, и ты не хочешь, чтобы админ сервера мог случайно сломать логику, поменяв коллекцию.

В-третьих, если ты сам разрабатываешь или дорабатываешь аддоны и публикуешь их в Workshop — тут без манифеста addon.json и утилит gmad/gmpublish никуда, вручную зип-архивы Valve давно не принимает.

sv_downloadurl и fastdl: раздаём контент вне Workshop

Механизм fastdl старше Workshop и достался Garry's Mod от движка Source — это обычная HTTP-раздача файлов, которые движок определяет как «нужные клиенту, но отсутствующие локально» (карта, её текстуры, кастомные модели и звуки, привязанные к карте). Вместо того чтобы гнать эти файлы через игровой канал сервера медленно и с нагрузкой на сам процесс, клиент качает их напрямую с обычного веб-сервера.

Включается одной строкой в server.cfg:

sv_downloadurl "https://fastdl.твойдомен.ru/gmod"
sv_allowdownload 1
sv_allowupload 1

sv_allowdownload/sv_allowupload стоит оставить включёнными — это запасной путь через игровой канал на случай, если fastdl-сервер недоступен или конкретный файл на нём не нашёлся. Без fastdl раздача пойдёт этим медленным способом всегда, с ним — только как fallback.

Дальше нужен сам веб-сервер. Подойдёт что угодно, что отдаёт статику — nginx, Apache, тот же общий веб-хостинг, если он у тебя уже есть. Минимальный конфиг для nginx:

server {
    listen 80;
    server_name fastdl.твойдомен.ru;
    root /var/www/gmod-fastdl;
    autoindex off;

    location ~* \.(bsp|bz2|mdl|vtf|vmt|wav|mp3|phy|vvd|dx80\.vtx|dx90\.vtx)$ {
        add_header Cache-Control "public, max-age=604800";
    }
}

autoindex off не для красоты — открытый листинг папки с fastdl практически приглашение скачать всю твою карту/модели пачкой без игры на сервере, лучше это не показывать всем подряд.

Структура каталогов, сжатие и resource.AddFile

Файлы на fastdl-сервере должны лежать зеркально относительно garrysmod/, иначе движок просто не найдёт, что качать:

gmod-fastdl/
├── maps/
│   └── gm_mycustommap.bsp
├── materials/
│   └── mycustommap/...
├── models/
│   └── mycustommap/...
└── sound/
    └── mycustommap/...

Файлы стоит дополнительно сжать в .bz2 рядом с оригиналом (движок сам понимает, что file.bsp.bz2 — это сжатая версия file.bsp, и распакует её у клиента):

cd /var/www/gmod-fastdl
find maps materials models sound -type f ! -name "*.bz2" -exec bzip2 -k {} \;

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

Важный нюанс, который часто ловят: автоопределение fastdl работает только для контента, который сервер сам прекэширует движком — то есть всего, что физически зависит от загруженной карты (модели, звуки, материалы карты). А вот файлы, на которые ссылается только Lua-код — картинки для HUD, кастомные звуки через surface.PlaySound, шрифты — движок сам не отследит и не включит в список на закачку. Для них нужно явно объявить файл в коде аддона:

-- lua/autorun/server/sv_fastdl_resources.lua
resource.AddFile("materials/myaddon/hud_logo.png")
resource.AddFile("sound/myaddon/notify.wav")

Это одна из самых частых причин, почему «fastdl вроде настроен, а часть картинок у игроков всё равно не грузится» — файл physически лежит на веб-сервере, но клиенту никто не сказал, что его вообще нужно качать.

addon.json: манифест для сборки и публикации аддона

Если ты дорабатываешь чужой аддон под свой сервер или пишешь свой с нуля и хочешь опубликовать его в Workshop — единица упаковки в GMod называется .gma (GMod Addon), и собирается она из папки с манифестом addon.json в корне (старый формат addon.txt Valve считает устаревшим, для новых аддонов используй json-вариант). Структура:

{
    "Title": "My Custom Weapon Pack",
    "Type": "weapon",
    "Tags": ["fun", "roleplay"],
    "Ignore":
    [
        "*.psd",
        "*.xcf",
        "*.git*",
        "source/*"
    ]
}

Type — категория аддона в Workshop (например gamemode, map, weapon, vehicle, npc, tool, effects, model, entity, servercontent); Tags — до двух-трёх тегов из списка, который Steam показывает при публикации через gmpublish. Точный набор допустимых значений периодически меняется на стороне Valve/Facepunch, так что если gmpublish ругается на конкретный тег или тип — свежий список стоит свериться прямо в интерфейсе публикации на steamcommunity.com.

Ignore — самая практичная часть манифеста для админа: список glob-паттернов файлов, которые НЕ попадут в собранный .gma. Сюда обычно уходят исходники в PSD/XCF, служебные файлы git, черновики карт (.vmf при готовом скомпилированном .bsp) — всё, что раздувает архив, но не нужно на клиенте. Без нормального Ignore итоговый .gma может оказаться в разы тяжелее, чем нужно, а игроки будут качать мусор, который никогда не используется в игре.

resource.AddWorkshop(): точечная догрузка отдельных предметов

Помимо общей коллекции сервера, у GMod есть механизм точечного добавления конкретного Workshop-предмета прямо из Lua-кода аддона или гейммода — функция resource.AddWorkshop:

-- lua/autorun/server/sv_force_workshop.lua
resource.AddWorkshop("123456789")  -- ID конкретного Workshop-предмета

Вызывается на сервере, при старте. Смысл в том, что этот способ не зависит от того, что прописано в host_workshop_collection — предмет догрузится клиентам в любом случае, даже если админ сервера потом поменяет основную коллекцию и забудет включить в неё этот ID. Это удобно, когда конкретная зависимость жёстко прошита в логике аддона (например, гейммод требует определённый пак анимаций или моделей оружия для работы, а не просто «для красоты»).

Не стоит злоупотреблять этим способом вместо нормальной коллекции — если через resource.AddWorkshop тянуть десятки предметов построчно, это менее прозрачно для администратора, чем один читаемый список коллекции на сайте Steam. Разумный баланс: основной контент — через коллекцию, жёсткие зависимости конкретного аддона — через resource.AddWorkshop прямо в его коде, чтобы аддон оставался рабочим сам по себе, независимо от настроек сервера.

Если после подключения нового аддона сервер начинает падать при загрузке карты или крашится у части игроков — это уже не тема fastdl или манифестов, тут стоит смотреть в сторону статьи про краш сервера из-за аддона.

Упаковка и обновление через gmad/gmpublish

Когда манифест addon.json готов и структура папки аддона (lua/, materials/, models/ и так далее) собрана, упаковка в .gma делается официальной утилитой gmad, которая идёт в комплекте с дедиком (bin/gmad_linux или gmad.exe на Windows-сборках):

./gmad_linux create -folder /home/gmod/myaddon -out /home/gmod/myaddon.gma

Публикация нового аддона в Workshop — через gmpublish, с иконкой предпросмотра:

./gmpublish_linux create -addon /home/gmod/myaddon.gma -icon /home/gmod/myaddon/icon.jpg

Команда вернёт ID нового Workshop-предмета — его и стоит использовать дальше в коллекции или в resource.AddWorkshop. Для обновления уже опубликованного аддона новой версией той же .gma:

./gmpublish_linux update -id 123456789 -addon /home/gmod/myaddon.gma -changes "Исправлена коллизия карты, обновлены текстуры"

Учти: путь и точное имя бинарника (gmad_linux/gmad, gmpublish_linux/gmpublish) может отличаться между версиями дедика и ОС — если команда не находится, поищи в bin/ каталога установки сервера, обычно там лежат обе утилиты. Публикация требует Steam-аккаунта с игрой в библиотеке (анонимного логина steamcmd для этого шага недостаточно), так что gmpublish обычно гоняют с локальной машины разработчика, а не с самого сервера.

Если экспериментируешь с несколькими гейммодами на одном сервере (DarkRP, TTT, sandbox) и подбираешь для каждого свой набор аддонов — обзор популярных вариантов есть в статье про гейммоды DarkRP, TTT и sandbox, а базовая установка самого сервера — в статье как поднять сервер Garry's Mod.

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