Плагины EXILED и LabAPI для SCP: Secret Laboratory

Сервер SCP: Secret Laboratory запускает плагины через LabAPI - официальный фреймворк Northwood, который входит в каждую сборку сервера. EXILED, более крупный фреймворк сообщества, теперь сам является плагином LabAPI, так что современный сервер может запускать родные плагины LabAPI и плагины EXILED бок о бок. Плагины - это файлы .dll, которые кладут в папки для конкретного порта или в глобальные папки в app data сервера; каждый при первом запуске пишет YAML-конфиг, а права на команды плагинов берутся из permissions.yml, где ключами служат имена ваших групп Remote Admin. Почти любая проблема с плагином сводится к одному из четырёх: плагин собран под другую версию игры или фреймворка, лежит не в той папке, его YAML не разобрался, или имя группы прав не совпадает в точности с группой Remote Admin. В этом руководстве они разобраны в том порядке, в каком вы с ними столкнётесь.

Про сам сервер - LocalAdmin, config_gameplay.txt, роли Remote Admin и верификацию - читайте в руководстве по серверу SCP: Secret Laboratory. Эта статья начинается там, где заканчивается та.

Как LabAPI и EXILED сочетаются друг с другом#

LabAPI - базовый слой. Его папки находятся в каталоге app data игры - ~/.config/SCP Secret Laboratory/ в Linux, %AppData%\SCP Secret Laboratory\ в Windows - в папке LabAPI, внутри которой plugins, dependencies и configs. По умолчанию он загружает плагины из папки global и из папки, названной по порту сервера, так что на одной машине может работать несколько серверов с разными наборами плагинов.

EXILED находится сверху. Его загрузчик - это плагин LabAPI, и после загрузки он читает собственное дерево, папку EXILED в том же корне app data. У такого наслоения есть одно следствие, которое стоит помнить: когда обновление игры поднимает мажорную версию LabAPI, весь стек EXILED ждёт обновления EXILED, а не одного плагина.

Что выбрать, в основном решают плагины, которые вам нужны. Плагин для LabAPI кладётся в папки LabAPI; плагину для EXILED нужен установленный EXILED, и кладётся он в папки EXILED. Если на странице плагина не указано ни то ни другое, он, скорее всего, устарел - старые плагины писались под выведенный из употребления NWAPI и на актуальных сборках не загружаются.

Папки и файлы бок о бок#

Два замечания к таблице. LabAPI также пишет properties.yml рядом с конфигом каждого плагина - там хранятся IsEnabled и переопределение UnsupportedLoading, и так можно выключить один плагин, не удаляя его. А раскладка конфигов EXILED зависит от настройки ConfigType загрузчика: сейчас по умолчанию стоит Separated - по файлу на плагин на порт, как показано выше, а Default складывает все плагины в один EXILED/Configs/<port>-config.yml с соответствующим <port>-translations.yml. Консольные команды econfig merge и econfig split переводят одно в другое. Старые руководства исходят из однофайловой раскладки; если вы не находите конфиг там, где его обещает руководство, причина в этом.

Установка EXILED#

EXILED ставится собственным установщиком, Exiled.Installer-Linux или Exiled.Installer-Win.exe, который скачивает релиз с GitHub и распаковывает его куда нужно:

$ ./Exiled.Installer-Linux --path /home/container \    --appdata /home/container/.config --exiled /home/container/.config

На хостинге важен именно --appdata. Сервер читает папку app data того пользователя, от которого запущен; если установщик записал всё в другое место, EXILED установлен, но никогда не загрузится. Если при запуске в консоли нет баннера EXILED, проверьте, совпадают ли пути, которые вывел установщик, с местом, где сервер держит свою папку config.

У загрузчика есть собственные настройки, они лежат в папке конфигов LabAPI под именем плагина загрузчика. По трём из них стоит принять решение, а не оставлять значение по умолчанию:

Автоматические обновления удобны на тестовом сервере и опасны на загруженном. Релиз EXILED, вышедший, пока плагины ещё собраны под предыдущий, - именно так сервер ломается, хотя его никто не трогал.

Установка и настройка плагина#

Порядок одинаков для обоих фреймворков:

1. Посмотрите на странице плагина, под какой фреймворк и какую версию игры он собран. Если что-то не совпадает, остановитесь.
2. Остановите сервер.
3. Положите DLL в папку плагинов, а перечисленные зависимости - в папку зависимостей. Глобальные папки действуют на все порты, папки портов - только на свой сервер.
4. Запустите сервер один раз. Плагин запишет конфиг по умолчанию.
5. Остановите сервер, отредактируйте конфиг и запустите снова - или отредактируйте и выполните команду перезагрузки.

Типичный конфиг плагина EXILED - обычный YAML с двумя ключами, которые есть у каждого плагина, is_enabled и debug, а за ними идут его собственные параметры:

is_enabled: truedebug: false# Message shown to a player on joinwelcome_message: 'Welcome to the Site-02 night shift'broadcast_duration: 6allowed_roles:- ClassD- Scientist

YAML беспощаден в конкретных вещах. Отступы - пробелы, никогда не табуляция. Значение с двоеточием, решёткой или спецсимволом в начале нужно брать в кавычки, а EXILED по умолчанию пишет строки в одинарных кавычках - держитесь этого стиля. Элементы списка - дефис и пробел в начале строки на нужной глубине. Если файл не разбирается, плагин либо загружается с настройками по умолчанию, либо не загружается вовсе, а ошибка видна в консоли при запуске; подробнее о ловушках YAML - в статье форматы конфигурационных файлов игровых серверов.

Конфиги плагинов LabAPI работают так же, в LabAPI/configs/<port>/<PluginName>/, обычно в виде config.yml, а имена полей выбирает автор плагина.

Перезагрузка без перезапуска

Перезапуск посреди раунда выкидывает всех, поэтому оба фреймворка умеют перезагружаться из консоли сервера или Remote Admin:

Перезагрузка конфигов безопасна для настроек, которые плагин читает по мере надобности. Настройки, которые читаются один раз при запуске, - список кастомных ролей, подключение к базе данных - всё равно могут потребовать перезапуска. Если перезагрузка будто ничего не делает, перезапустите сервер между раундами, прежде чем решить, что настройка сломана.

Права на команды плагинов#

Права Remote Admin определяют, что разрешают собственные команды игры. Команды плагинов проверяют второй слой - права фреймворка: строки вроде myplugin.kick, выданные группам.

В permissions.yml у EXILED ключами служат имена групп Remote Admin, плюс специальная группа user для всех, у кого группы нет:

user:  default: true  inheritance: []  permissions: []moderator:  inheritance: []  permissions:  - adminplugin.kick  - adminplugin.muteadmin:  inheritance:  - moderator  permissions:  - adminplugin.*owner:  inheritance: []  permissions:  - .*

Правила, на которых спотыкаются:

• Имена групп должны в точности совпадать с именами ролей в `config_remoteadmin.txt`. Группа, которой ничего не соответствует, игнорируется с предупреждением в консоли, которое пролетает при запуске.
• У каждой группы должны быть и `inheritance`, и `permissions`, даже пустые. Если пропустить одно, не разберётся весь файл, а не только эта группа.
• `default: true` отмечает группу для игроков без роли Remote Admin. Такая группа должна быть ровно одна.
• Подстановочные знаки. adminplugin.* даёт всё с этим префиксом; .* даёт вообще всё и уместно только у группы владельца.
• Наследование работает в одну сторону. admin, наследующий moderator, получает права модератора, а не наоборот.

После правки выполните reload permissions или собственную команду перезагрузки прав. У LabAPI аналог - LabAPI/configs/permissions.yml, тоже с ключами по именам групп Remote Admin и группой default для всех остальных; labapi permissions показывает, какие права есть у вас. Выдавайте права плагинов так же узко, как роли Remote Admin: модератор с .* - это владелец во всём, кроме названия. Тот же довод для доступа к панели - в статье сабпользователи и минимальные привилегии.

Выбор плагинов#

Самый безопасный источник - официальный каталог плагинов, из которого умеют ставить команды p в LocalAdmin. Помимо него плагины берут из релизов на GitHub. Несколько категорий и на что в них смотреть:

EXILED ставит Exiled.CustomItems, Exiled.CustomRoles, Exiled.Events и Exiled.Permissions как часть себя. Другим плагинам, которые от них зависят, отдельная установка не нужна.

Чем меньше, тем лучше. Каждый игровой плагин - это ещё один перехват тех же событий, и два плагина, меняющих одно и то же - волны респавна, выдачу ролей, подбор предметов, - взаимодействуют так, как ни один автор не проверял. Добавляйте плагины по одному и играйте раунд между добавлениями.

Любой плагин работает с полными правами сервера и видит каждое подключение игрока. Скачивайте из репозитория автора или из официального каталога, а не из перезалива в Discord-канале. Что может сделать враждебный плагин, рассказано в статье вредоносные плагины и моды, а привычки, которые уберегут от проблем, - в статье как держать модифицированный сервер в чистоте.

Как пережить обновления игры#

SCP: Secret Laboratory регулярно выпускает обновления, и сервер, который автоматически обновляется при перезапуске, получит их раньше, чем авторы плагинов. Картина знакомая: сервер стартует, лог заполняется MissingMethodException или отказами загрузить плагин, собранный под другую мажорную версию, и половины функций как не бывало.

Рабочий порядок:

1. Знайте, что у вас запущено. Держите список плагинов с версиями и ссылками на источники рядом с бэкапами конфигов.
2. Закрепляйтесь перед днём патча. Когда Northwood анонсирует обновление, решите, будете ли ставить его сразу. Сервер может несколько дней посидеть на предыдущей сборке, пока плагины догоняют, - при условии, что клиенты ещё могут подключиться; при мажорном обновлении не могут, и обновляться придётся в любом случае.
3. Сначала обновляйте фреймворки, потом плагины. LabAPI приходит вместе с игрой; затем EXILED; затем каждый плагин, собранный под новую версию.
4. Не включайте загрузку неподдерживаемых плагинов. LoadUnsupportedPlugins в LabAPI по умолчанию false, чтобы плагин, собранный под другую мажорную версию, отклонялся, а не загружался. Плагин, который загрузился и сбоит посреди раунда, хуже того, что не загрузился.
5. Проверяйте до часа пик. Второй сервер на другом порту с теми же плагинами стоит недорого - как держать его честным, рассказано в статье тестовый сервер рядом с рабочим.

На RE:NODE консоль сервера SCP:SL - это консоль LocalAdmin с историей команд, так что reload configs и pluginmanager show вводятся там же, где читается вывод. Папки плагинов и конфигов доступны в файловом менеджере и по SFTP, а слот бэкапа, сделанный перед каждым обновлением, - самый быстрый путь назад к рабочему набору: восстановление - одна кнопка. Вкладка Schedules может делать ежедневный перезапуск в тихий час, и это же естественный момент, чтобы ставить обновления осознанно, а не когда сервер случайно перезапустится. Порядок восстановления - в статье что делать, когда обновление мода всё сломало.

Производительность#

Медленным сервер SCP:SL делают плагины, а не игроки. Сервер держит фиксированную частоту тиков, и каждый обработчик на частом событии - движение игрока, урон, подбор предмета - выполняется внутри тика. Команда tps из EXILED показывает текущую частоту в консоли. Если она падает с установленными плагинами и не падает без них, отключайте плагины по одному через pluginmanager disable между раундами, пока частота не восстановится. Один плагин, обращающийся к базе данных при каждом событии урона, может вдвое снизить частоту тиков на заполненном сервере. Что чувствуют игроки, когда она падает, объясняется в статье что на самом деле значит tick rate.

Решение проблем#

Нет баннера EXILED при запуске. Загрузчика нет в LabAPI/plugins/global/ или в папке порта, или EXILED установлен в другую папку app data, а не в ту, которую читает сервер. Запустите установщик заново с --appdata, указывающим на правильный корень.

Плагин в списке, но ничего не происходит. is_enabled равен false, его отключает properties.yml или не хватает зависимости - консоль при загрузке скажет, что именно.

`MissingMethodException` после обновления. Плагин собран под предыдущую версию игры или фреймворка. Обновите или удалите его.

Команды плагина говорят, что у вас нет прав. Имя группы в permissions.yml не совпадает с именем роли Remote Admin, или файл не разобрался, потому что у какой-то группы нет inheritance или permissions.

Изменения в конфиге откатываются. YAML не разобрался, и были заново созданы значения по умолчанию. Проверьте файл, восстановите свою копию и посмотрите в консоль после следующего запуска.

Конфиг не там, где пишет руководство. Руководство исходит из однофайловой раскладки EXILED. Загляните в EXILED/Configs/Plugins/ или выполните econfig merge.

FAQ#

Нужен ли EXILED, чтобы запускать плагины?

Нет. LabAPI встроен в сервер и запускает плагины LabAPI без всякой дополнительной установки. EXILED нужен только для плагинов, написанных под EXILED, - а это по-прежнему значительная часть доступного.

Могут ли плагины LabAPI и EXILED работать одновременно?

Да. Загрузчик EXILED сам является плагином LabAPI, так что оба вида загружаются вместе. Цена - лишний слой, который нужно обновлять при смене мажорной версии LabAPI.

Куда кладутся конфиги плагинов на сервере с несколькими портами?

LabAPI хранит конфиги в LabAPI/configs/<port>/, а раздельная раскладка EXILED пишет по файлу на порт в папке конфига каждого плагина. Плагины из папки global загружаются для всех портов, но конфиги всё равно получают по портам.

Почему не работает моя группа прав?

Имя группы должно в точности совпадать с ролью в config_remoteadmin.txt, а у каждой группы должны быть строки и inheritance, и permissions. Одна неправильно оформленная группа мешает загрузке всего файла.

Стоит ли разрешать EXILED обновляться самому?

Не на рабочем сервере. Автоматическое обновление может поставить новый EXILED раньше, чем его начнут поддерживать ваши плагины. Обновляйтесь намеренно, проверив каждый плагин и сделав бэкап.

Как перезагрузить конфиг плагина без перезапуска?

Используйте reload configs для EXILED или labapi reload configs для LabAPI - из консоли сервера или Remote Admin. Настройки, которые плагин читает только при запуске, всё равно требуют перезапуска.