Серверные плагины

Движок Source поставляется с встроенным API для подключения 3rd party плагинов на подобии API в MetaMod на движке HL1. Этот документ предоставляет краткое описание предоставляемых интерфейсови как их лучше использовать.

Компиляция примера

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).

Интерфейс 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 не имеют edict ассоциированного с ними когда они выполняются вы можите использовать этот индекс для нахождения энтити которая выполнила комманду.

ClientSettingsChanged

Вызывается когда пользователь указывает cvars связанные с изменением игрока (например имя пользователя). Используйте эту функцию для контроля какие операции пользователю позволены для изменения их установок (например для ограничения имен пользователей).

ClientCommand

Вызывается когда удаленный клиент вводит комманду в конслоли. Это может быть использовано для предоставления комманд клиентам (и ConCommand используется для имплементации сугубо серверных функций).

NetworkIDValidated

Вызывается когда сервер получает сетевой ID пользователя (например Steam ID). Заметьте что сетевой ID пользователя не устанавливется коннектом, вы должны дождаться ответа когда ID пройдет проверку. Этой функции указывается имя пользователя, вы должны искать среди соединенных пользователей ассоциированный edict указатель. Заметьте что имя клиента может измениться во времмя коннекта и проверки id, вы должны использовть индекс энтити для отслеживания нужных пользователей.

Прослушивание событий

Интерфейс IGameEventManager позволяет плагину прослушивать игровые события. Игровые события генерируются кодом Мода когда происходят интересующие вас события, например смерть игрока или взрыв бомбы. IGameEventManager::AddListener может быть вызван для подписи на игровые сообщения. FireGameEvent затем вызывается в вашем плагине когда происходит событие. Данные содержащиеся в кажом сообщении описаны конфигурационными файлами сообщений:

  • hl2/resource/serverevents.res
  • hl2/resource/GameEvents.res
  • <mod dir>/resource/ModEvents.res

Создание ConVars и комманд

ConVars позволяют указать переменные которые пользователь может использовать для настройки поведения вашего плагина. ConCommands позволяют создавать комманды которые предоставляет ваш мод. Создание обоих просто и самодостаточно, ниже приводится пример кода создающий новую комманду 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 разными диалоговыми опциями для сообщения пользователей разными способами.

  1. DIALOG_MSG, выводит простое текстовое сообщение пользователю.
  2. DIALOG_MENU, предоставляет пользователю меню с опциями.
  3. DIALOG_TEXT, показывает пользователю большое текстовое поле.

Примеры как использовать этот интерфейс показаны в примере плагина поставляемом с СДК. Кажое сообщение отображается 10 секунд на HUD, меню и текстовая опция до 200 секунд в GameUI. Только 1 сообщение может быть отображено одновременно, нужно завершить одно для перехода к следующему. Сообщения с более низким полем «level» могут быть использованы для перезаписи текущих сообщений (минимальное значение 0). Детальнее о доступных значениях полей можно найти в исходном коде.

Автор: DarkLight.
26 января 2005, 20:08