Ru/Server plugins

Движок Source поставляется с встроенным API для подключения 3rd party плагинов на подобии API в MetaMod на движке HL1. Этот документ предоставляет краткое описание предоставляемых интерфейсов и как их лучше использовать.
=Необходимые подключения для компиляции=
Чтобы скомпилировать ваш плагин, вы должны настроить компилятор, включив следующие директории:
 * 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).
Пример:
 "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.res
* hl2/resource/GameEvents.res
* <mod dir>/resource/ModEvents.res
=Создание s и s=
s позволяют указать переменные которые пользователь может использовать для настройки поведения вашего плагина. s 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.
Category:Russian