Server plugins:ru

From Valve Developer Community
Revision as of 15:41, 30 August 2006 by KindDragon (talk | contribs)

(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to: navigation, search

Движок 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).

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

Создание 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 разными диалоговыми опциями для сообщения полозователей разными способами.

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

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

Отладка вашего плугина

Когда добавляете "-allowdebug" к строке запуска сервера.

Релиз вашего плугина

Когда вы готовы для публикации вашего плугина или beta тестинга, опубликуйте ваш серверный плугин на сайте комунити, на таком как SourcePlugins.