Server plugins
You can help by updating the translation.
Also, please make sure the article tries to comply with the alternate languages guide.Движок Source поставляется с встроенным API для подключения 3rd party плагинов на подобии API в MetaMod на движке HL1. Этот документ предоставляет краткое описание предоставляемых интерфейсов и как их лучше использовать.
Contents
Необходимые подключения для компиляции
Чтобы скомпилировать ваш плагин, вы должны настроить компилятор, включив следующие директории:
* public * public/dlls * public/engine * public/tier0 * public/tier1 * public/vstdlib * tier1
Чтобы сделать это, Вам нужно получить SDK файлы, создав мод в Source SDK.
Компиляция примера
SDK содержит пример плагина который выполняет примеры различных возможностей доступных в плагине. Вы можите найти пример сдесь src/utils/serverplugin_sample. Под Windows загрузите проект serverplugin_empty.vcproj, под linux вы можите ввести:
make plugin
из директории linux_sdk.
Запуск плагина
Движок загружает плагины основанные на специально отформатированных файлах с ключевым занчением помещенных в директорию <mod dir>/addons/ (ее нужно будет создать, по умолчанию сервер устанавливается без неё). Для загрузки вашего плагина поместите файл с раширением vdf в эту директорию и который имеет следующий формат:
"Plugin"
{
"file" "serverplugin_empty"
}
Параметр "file" должен указывать на файл для загрузки. В этом примере бинарный файл от компиляции кода должен быть скопирован в директорию bin/ куда установлен сервер. Расширение (.dll для Windows) добавится автоматически к имени файла когда оно будет загружаться. Имя файла должно быть относительно основной папки bin/ сервера (например ../cstrike/addons/serverplugin_empty для указания файла из директории addons мода cstrike).
Примечание:"file" определяет плагин для загрузки, то есть он говорит Source Engine это файл; "serverplugin_empty" это путь к файлу.Пример:
"Plugin"
{
"file" "../cstrike/addons/serverplugin_empty"
}
Интерфейс IServerPlugin
Плагины работают расширяя интерфейс IServerPluginCallbacks движка. Движок совершает обратные вызовы к этому интерфейсу когда происходят различные события. Определение этого интерфейса может быть найдено в public/engine/iserverplugin.h. Тип PLUGIN_RESULT некоторых функций позволяет плагину контролировать доступен ли этот вызов к ниже расположенному коду или нет, детали смотрите в заголовочном файле.
Описание IServerPluginCallbacks
Load |
Эта функция вызывается когда плагин загружается движком. Это может произойти во время инициализации или в результате перезагрузки в результате которой он выгружался. Два параметра предоставляют фабрики интерфейсов через которые работает плагин. |
UnLoad |
Вызывается когда плагин выгружается, используйте эту функцию для отмены некоторых асинхронных задач и удаления всех ответных функций зарегистрированных движком (например игрового слушателя сообщений). |
Pause |
Вызывается когда работа плагина приостанавливается (то есть прекращает принимать вызовы но не выгружается). |
UnPause |
Вызывается кода плагин выводится из приостановленного состояния. Здесь можно восстановить любые асинхронные события используемые плагином. |
GetPluginDescription |
Данная функция должна возвращать определенную строку с описанием вашего плагина. Обычно тут присутствует имя и автор плагина. |
LevelInit |
Вызывается при запуске карты (map), это первая функция которую запускает сервер после загрузки карты. |
ServerActivate |
Вызывается когда сервер полностью начал новый уровень, это происходит после вызова LevelInit. Этот вызов предоставляет указатели на edict-список и maxplayer счетчик на сервере. |
GameFrame |
Вызывается с каждым фреймом сервера (обычно 60 раз в секунду). Производительность сервера очень зависит от времени выполнения этой функции, поэтому старайтесь свести к минимуму количество действий в этой функции. |
LevelShutdown |
Вызывается когда сервер переходит на другую карту или останавливается. Удаляйте любое размещение на карте в этом вызове. Этот вызов может производится несколько раз пока меняется карта. |
ClientConnect |
Вызывается когда клиент только присоединился к серверу. Установите bAllowConnect в false для блокирования пользователя к соединению. |
ClientPutInServer |
Вызывается в тот момент когда клиент рождается на сервере, перед spawn функцией сервера. |
ClientActive |
Вызывается после того как игрок окончательно создан и настроен модом. Используйте этот вызов для установки любых специальных свойств пользователя. |
ClientDisconnect |
Вызывается когда клиент отсоединяется от сервера. |
SetCommandClient |
Вызывается кодом ConVar для возможности отслеживания на каком клиенте вводится ConCommand. Используйте полученный индекс в ConCommands если вы хотите узнать кто запустил команду. Поскольку команды ConVar не имеют указа ассоциированного с ними когда они выполняются вы можете использовать этот индекс для нахождения Entity которая выполнила команду. Индекс на один меньше чем индекс Entity. |
ClientSettingsChanged |
Вызывается когда пользователь указывает cvars связанные с изменением игрока (например имя пользователя). Используйте эту функцию для контроля какие операции пользователю позволены для изменения их установок (например для ограничения имен пользователей). |
ClientCommand |
Вызывается когда удаленный клиент вводит команду в консоли. Это может быть использовано для предоставления команд клиентам (и ConCommand используется для имплементации сугубо серверных функций). |
NetworkIDValidated |
Вызывается когда сервер получает сетевой ID пользователя (например Steam ID). Заметьте что сетевой ID пользователя не устанавливется коннектом, вы должны дождаться ответа когда ID пройдет проверку. Этой функции указывается имя пользователя, вы должны искать среди соединенных пользователей ассоциированный edict указатель. Заметьте что имя клиента может измениться во времмя коннекта и проверки id, вы должны использовть индекс энтити для отслеживания нужных пользователей. Заметьте также что эта функция не вызывается для локальных пользователей когда запущен прослушивающий/не-выделенный сервер. |
Прослушивание событий
IGameEventManager2 (ранее использовался IGameEventManager) позволяет плагину прослушивать игровые события. Игровые события генерируются кодом Мода когда происходят интересующие вас события, например смерть игрока или установка бомбы. IGameEventManager2::AddListener может быть вызван для подписи на игровые сообщения. FireGameEvent затем вызывается в вашем плагине когда происходит событие. Данные содержащиеся в каждом сообщении описаны конфигурационными файлами сообщений, в частности:
hl2/resource/serverevents.reshl2/resource/GameEvents.res<mod dir>/resource/ModEvents.res
Создание ConVars и Commands
ConVars позволяют указать переменные которые пользователь может использовать для настройки поведения вашего плагина. ConCommands aпозволяют создавать комманды которые предоставляет ваш мод. Создание обоих просто и самодостаточно, ниже приводится пример кода создающий новую комманду empty_version и новую переменную plugin_empty. Эти комманды могут быть запущены из сервера или клиента, вы можите использовать индекс предоставляемые SetCommandClient для определения источника комманды.
CON_COMMAND( empty_version, "prints the version of the empty plugin" )
{
Msg( "Version:1.0.0.0\n" );
}
static ConVar empty_cvar("plugin_empty", "0", 0, "Example plugin cvar");
Взаимодействие с клиентами
Движок предоставляет интерфейс IServerPluginHelpers для отправки сообщений пользователям. Этот интерфейс предоставляет одну функцию, CreateMessage которая вызывается с 3 разными диалоговыми опциями для сообщения полозователей разными способами.
DIALOG_MSG, выводит простое текстовое сообщение пользователю.DIALOG_MENU, предоставляет пользователью меню с опциями.DIALOG_TEXT, показывает пользователю большое текстовое поле.
Примеры как использовать этот интерфейс показаны в примере плагина поставляемом с СДК. Кажое сообщение отображается 10 секунд на HUD, меню и текстовая опция до 200 секунд в GameUI. Только 1 сообщение может быть отображено одновременно, нужно завершить одно для перехода к следующему. Сообщения с более низким полем "level" могут быть использованы для перезаписи текущих сообщений (минимальное значение 0). Детальнее о доступных значениях полей можно найти в исходном коде.
Отладка плагина
Возможна при добавлении "-allowdebug" к строке запуска сервера.
Релиз вашего плагина
Когда вы готовы для публикации вашего плагина или beta тестинга, опубликуйте ваш серверный плагин на сайте комьюнити, таком как SourcePlugins.
