Skip to content

Latest commit

 

History

History
151 lines (115 loc) · 24.7 KB

README-Русский.md

File metadata and controls

151 lines (115 loc) · 24.7 KB
Raw

EXILED - EXtended In-runtime Library for External Development

EXILED - низкоуровневый фреймворк для серверов SCP: Secret Laboratory. Он предлагает систему событий, которую разработчики могут использовать для различных манипуляций, изменения кода игры или реализации собственных функций. Все ивенты EXILED сделаны с помощью Harmony, это означает, что для их функционирования не требуется прямого редактирования серверных сборок, что позволяет получить два уникальных преимущества:
  • Во-первых, весь код фреймворка может быть свободно опубликован и распространен, что позволяет разработчикам лучше понять, как он работает, а также предложить свои предложения по дополнению или изменению его функций.
  • Во-вторых, поскольку весь код, связанный с фреймворком, выполняется вне сборки сервера, такие вещи, как небольшие обновления игры, будут иметь незначительное влияние на фреймворк, если вообще будут иметь. Это делает его наиболее совместимым с будущими обновлениями игры, а также облегчает обновление, когда это нужно сделать.

Скачивание

Установка EXILED может показаться более сложной, чем установка других фреймворков, но на самом деле она довольно проста. Как упоминалось выше, большая часть EXILED не содержится в файле Assembly-CSharp.dll сервера, однако в файл Assembly-CSharp.dll необходимо внести одно изменение, которое требуется для того, чтобы EXILED действительно загружался на сервер при запуске, чистая сборка игры с уже внесенными изменениями будет поставляться с релизами.

Если вы решите использовать программу установки, она, при правильном запуске, "позаботится" об установке Exiled.Loader, Exiled.Updater, Exiled.Permissions, Exiled.API и Exiled.Events, а также о том, чтобы на вашем сервере был установлен правильный файл Assembly-CSharp.dll.

Windows

Автоматическая установка (подробнее)

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

  • Скачайте Exiled.Installer-Win.exe отсюда (нажмите на Assets -> нажмите на Installer).
  • Поместите его в папку вашего сервера (если вы еще не скачали выделенный сервер)
  • Дважды щелкните Exiled.Installer.exe или скачайте этот .bat и поместите его в папку сервера для установки последней предварительной версии.
  • Чтобы установить и получить плагины, ознакомьтесь с разделом Установка плагинов ниже. Примечание: Если вы устанавливаете EXILED на удаленный сервер, убедитесь, что вы запустили .exe от имени того же пользователя, который запускает ваши серверы SCP:SL (или пользователя с правами администратора).

Установка вручную

  • Скачайте Exiled.tar.gz отсюда.
  • Распакуйте его содержимое с помощью 7Zip или WinRar.
  • Переместите папку EXILED в %appdata% Примечание: Эта папка должна находиться в C:\Users\%UserName%\AppData\Roaming, и НЕ C:\Users\%UserName%\AppData\Roaming\SCP Secret Laboratory, и ЭТО ДОЛЖНО быть в (. ...)\AppData\Roaming, а не (...)\AppData!.
  • Переместите SCP Secret Laboratory в %appdata%.
    • Windows 10: Напишите %appdata% в Cortana / значке поиска или в строке проводника Windows.
    • Любая другая версия Windows: Нажмите Win + R и введите %appdata%.

Установка плагинов Windows

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

  • Чтобы установить плагин, просто:
    • Скачайте плагин с их страницы релизов (он ДОЛЖЕН быть .dll!)
    • Переместите его в: C:\Users\%UserName%\AppData\Roaming\EXILED\Plugins (переместите его сюда, нажав Win + R, а затем написав %appdata%)

Linux

Автоматическая установка (подробнее)

Примечание: Если вы устанавливаете EXILED на удаленный сервер, убедитесь, что вы запускаете программу установки от имени того же пользователя, который запускает ваши серверы SCP:SL (или root).

  • Скачайте Exiled.Installer-Linux отсюда (нажмите на Assets -> нажмите на Installer).
  • Установите его, набрав ./Exiled.Installer-Linux --path /путь/к/серверу или переместив его в папку сервера напрямую, перейдите в нее с помощью терминала (cd) и наберите: ./Exiled.Installer-Linux.
  • Если вам нужна последняя предварительная версия, просто добавьте --pre-releases. Пример: ./Exiled.Installer-Linux /home/scp/server --pre-releases.
  • Другой пример, если вы поместили Exiled.Installer-Linux в папку вашего сервера: /home/scp/server/Exiled.Installer-Linux --pre-releases
  • Чтобы установить и получить плагины, ознакомьтесь с разделом Установка плагинов ниже.

Установка вручную

  • Убедитесь, что вы вошли в систему под пользователем, который запускает SCP-серверы.
  • Скачайте Exiled.tar.gz отсюда (SSH: щелкните правой кнопкой мыши и получите ссылку Exiled.tar.gz, затем введите: wget (link_to_download))
  • Чтобы извлечь его в текущую папку, введите tar -xzvf EXILED.tar.gz.
  • Переместите SCP Secret Laboratory папку в ~/.config. Примечание: Эта папка должна находиться в ~/.config, а НЕ В ~/.config/SCP Secret Laboratory (SSH: mv SCP Secret Laboratory ~/.config/)
  • Переместите папку EXILED в ~/.config. Примечание: Эта папка должна находиться в ~/.config, и НЕ В ~/.config/SCP Secret Laboratory (SSH: mv EXILED ~/.config/)

Устaновка плагинов Linux

Вот и все, теперь EXILED будет установлен и активен при следующей загрузке вашего сервера. Обратите внимание, что EXILED сам по себе почти ничего не делает, поэтому обязательно получайте новые плагины с нашего сервера Discord.

  • Чтобы установить плагин, просто:
    • Скачайте плагин с их страницы релизов (он ДОЛЖЕН быть .dll!)
    • Переместите его в: ~/.config/EXILED/Plugins (если вы используете SSH как root, то ищите нужный .config, который будет находиться в `/home/(SCP Server User)``)

Конфигурация

EXILED сам по себе предлагает некоторые опции конфигурации. Все они автоматически генерируются при запуске сервера и находятся в файле ~/.config/EXILED/Configs/(ПортСервера)-config.yml (%AppData%\EXILED\Configs\(ПортСервера)-config.yml на Windows).

Конфигурации плагинов НЕ будут находиться в файле config_gameplay.txt, вместо этого они устанавливаются в файле ~/.config/EXILED/Configs/(ПортСервера)-config.yml (%AppData%\EXILED\(ПортСервера)-config.yml на Windows). Однако некоторые плагины могут получать свои настройки конфигурации из других мест самостоятельно, это просто место по умолчанию для них в EXILED'е, поэтому при возникновении проблем обратитесь к отдельному плагину.

Для разработчиков

Если вы хотите создать плагин для EXILED, сделать это довольно просто. Если вы хотите получить более подробное руководство, посетите нашу страницу Начало работы.

Более полные и активно обновляемые руководства вы найдете на сайте EXILED.

  • Ваш плагин должен содержать класс, который наследуется от Exiled.API.Features.Plugin<>, если это не так, EXILED не загрузит ваш плагин при запуске сервера.
  • Когда плагин загружен, код в методе OnEnabled() вышеупомянутого класса срабатывает немедленно, он не ждет загрузки других плагинов. Он не ждет завершения процесса запуска сервера. Он не ждет ничего. При настройке метода OnEnabled() убедитесь, что вы не обращаетесь к вещам, которые еще не инициализированы сервером, таким как ServerConsole.Port или PlayerManager.localPlayer.
  • Если вам нужно получить доступ к вещам, которые не инициализированы до загрузки плагина, рекомендуется просто дождаться события WaitingForPlayers, если по какой-то причине вам нужно сделать это раньше, оберните код в цикл while(!x), который проверяет, что переменная/объект, который вам нужен, больше не является null, прежде чем продолжить.
  • EXILED поддерживает динамическую перезагрузку сборок плагинов во время работы сервера. Это означает, что если вам нужно обновить плагин, это можно сделать без перезагрузки сервера, однако, если вы обновляете плагин в середине выполнения, плагин должен быть правильно настроен для поддержки этого, иначе у вас будут очень плохие времена. Обратитесь к разделу Динамические обновления для получения дополнительной информации и рекомендаций.
  • В EXILED НЕТ событий OnUpdate, OnFixedUpdate или OnLateUpdate. Если вам по какой-то причине нужно запускать код так часто, вы можете использовать MEC-корутину, которая ждет один кадр, 0.01f, или использовать временной слой, например Timing.FixedUpdate.

Отключение исправлений событий EXILED.

В настоящее время эта функция больше не поддерживается.

MEC Coroutines

Если вы незнакомы с MEC, это будет очень краткий и простой учебник, который поможет вам начать работу. MEC Coroutines - это методы с таймером, которые поддерживают периоды ожидания перед продолжением выполнения, не прерывая основной поток игры. Корутины MEC безопасны для использования в Unity, в отличие от традиционной работы с потоками. НЕ пытайтесь создавать новые потоки для взаимодействия с Unity, они приведут к крашу сервера.

Чтобы использовать MEC, нужно будет добавить ссылку Assembly-CSharp-firstpass.dll из файлов сервера и написать using MEC;. Пример вызова простой корутины, которая повторяет себя с задержкой между каждым циклом:

using MEC;
using Exiled.API.Features;

public void SomeMethod()
{
    Timing.RunCoroutine(MyCoroutine());
}

public IEnumerator<float> MyCoroutine()
{
    for (;;) // Бесконечно повторять следующие действия
    {
        Log.Info("Эй, Я бесконечный цикл!"); // Вызов Log.Info для печати строки в журналы игровой консоли/сервера.
        yield return Timing.WaitForSeconds(5f); // Говорит coroutine подождать 5 секунд перед продолжением, поскольку это происходит в конце цикла, это эффективно останавливает цикл от повторения на 5 секунд.
    }
}

Настоятельно рекомендуется погуглить или спросить в Discord, если вы не знакомы с MEC и хотите узнать больше, получить совет или нуждаетесь в помощи. На вопросы, независимо от того, насколько они "глупые", всегда будут даны максимально полезные и понятные ответы, чтобы разработчики плагинов могли преуспеть. Лучший код лучше для всех.

Динамические обновления

EXILED как фреймворк поддерживает динамическую перезагрузку сборок плагинов, не требуя перезагрузки сервера. Например, если вы запускаете сервер с единственным плагином Exiled.Events и хотите добавить новый, вам не нужно перезагружать сервер для выполнения этой задачи. Вы можете просто использовать команду reload plugins в RemoteAdmin или в консоли сервера для перезагрузки всех плагинов EXILED, и загрузки новых, которые не были загружены ранее.

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

Для хостеров

  • Если вы обновляете плагин, убедитесь, что имя его сборки не совпадает с именем текущей установленной версии (если таковая имеется). Чтобы это сработало, плагин должен быть создан разработчиком с учетом динамических обновлений, простое переименование файла не поможет.
  • Если плагин поддерживает динамические обновления, то перед перезагрузкой EXILED убедитесь, что когда вы помещали новую версию плагина в папку "Plugins", вы также удалили старую версию из папки. Несоблюдение этого требования приведет ко многим и многим плохим вещам.
  • Ответственность за любые проблемы, возникающие при динамическом обновлении плагина, лежит исключительно на вас и разработчике данного плагина. Хотя EXILED полностью поддерживает и поощряет динамическое обновление, единственная возможность, что оно может не сработать или пойти не так, это если хост сервера или разработчик плагина сделали что-то не так. Прежде чем сообщать разработчикам EXILED об ошибке, связанной с динамическим обновлением, трижды проверьте, что все было сделано правильно обеими сторонами.

Для разработчиков

  • Плагины, которые хотят поддерживать динамическое обновление, должны отписываться от всех событий к которым они подключены, когда они отключены или перезагружены.
  • Плагины, имеющие пользовательские патчи Harmony, должны использовать какую-либо изменяемую переменную в имени экземпляра Harmony, и должны UnPatchAll() для своего экземпляра, когда плагин отключен или перезагружен.
  • Любые корутины, запущенные плагином в OnEnabled(), также должны быть завершены при отключении или перезагрузке плагина.

Все это можно сделать в методах OnReloaded() или OnDisabled() в классе плагина. Когда EXILED перезагружает плагины, он вызывает OnDisabled(), затем OnReloaded(), затем загружает новые сборки, а затем выполняет OnEnabled().

Обратите внимание, что я сказал новые сборки. Если вы замените сборку другой сборкой с таким же именем, она НЕ будет обновлена. Это связано с GAC (Global Assembly Cache), если вы попытаетесь "загрузить" сборку, которая уже находится в кэше, то вместо нее всегда будет использоваться кэшированная сборка. По этой причине, если ваш плагин будет поддерживать динамические обновления, вы должны собирать каждую версию с другим именем сборки в опциях сборки (переименование файла не работает). Также, поскольку старая сборка не "уничтожается", то вы не сможете отписаться, распатчить ваш экземпляр, остановить корутины и т.д., этот код будет продолжать выполняться, как и код новой версии. Это очень плохо.

Таким образом, плагины, поддерживающие динамические обновления, ОБЯЗАНЫ следовать этим рекомендациям, иначе они будут удалены с сервера Discord из-за потенциального риска для владельцев сервера.

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

Перевод сделал Ficus-x при помощи IRacle и Remuchi.