Difference between revisions of "Ru:Introduction to SourceMod Plugins"

From AlliedModders Wiki
Jump to: navigation, search
(ConVars)
m (Improvements for "Includes" section)
 
(13 intermediate revisions by 3 users not shown)
Line 3: Line 3:
 
Для получения информации о компиляции плагинов см. [[Compiling SourceMod Plugins]] (Компиляция SourceMod плагинов). Автор настоящей статьи использует редактор [http://www.crimsoneditor.com/ Crimson Editor] для написания плагинов. Вы можете использовать [http://www.pspad.com/ PSPad], [http://www.ultraedit.com/ UltraEdit], [http://notepad-plus.sourceforge.net/uk/site.htm Notepad++], [http://www.textpad.com/ TextPad], [http://sourceforge.net/projects/pawnstudio/ SourceMod IDE] или любой другой текстовый редактор.
 
Для получения информации о компиляции плагинов см. [[Compiling SourceMod Plugins]] (Компиляция SourceMod плагинов). Автор настоящей статьи использует редактор [http://www.crimsoneditor.com/ Crimson Editor] для написания плагинов. Вы можете использовать [http://www.pspad.com/ PSPad], [http://www.ultraedit.com/ UltraEdit], [http://notepad-plus.sourceforge.net/uk/site.htm Notepad++], [http://www.textpad.com/ TextPad], [http://sourceforge.net/projects/pawnstudio/ SourceMod IDE] или любой другой текстовый редактор.
  
=Структура плагина=
+
= Начиная с нуля =
Почти все плагины имеют три одинаковых элемента:
+
Откройте Ваш любимый текстовый редактор и создайте новый пустой файл. Теперь Вы можете начать писать код, используя основные функции языка, однако, Вы не можете использовать любые функции и особенности самого SourceMod, потому что компилятор ничего не знает о них. Это сделано специально, чтобы было возможно использовать SourcePawn отдельно от SourceMod. Но так как мы пишем плагин именно для SourceMod, самая лучшая идея - это в первую очередь получить доступ к оособенностям SourceMod. Этой цели можно достичь с помощью директивы <tt>#include</tt>. Она сообщает компилятору, что содержимое указанного файла нужно вставить в Ваш при компиляции.
*'''Includes''' - Позволяет получить доступ к SourceMod API, и если Вы хотите, к API от внешних SourceMod плагинов и расширений.
+
<pawn>#include <sourcemod></pawn>
*'''Info''' - Общественная информация о Вашем плагине.
+
Как это работает? Сначала обратите внимание, что имя файла мы обрамили в угловые скобки. Угловые скобки сообщают компилятору, что указанный файл нужно поискать в стандартных директориях подключаемых файлов. По-умолчанию, такая директория одна, и это '''scripting/include'''. Вы можете открыть эту папку и увидеть множество файлов с расширением <tt>.inc</tt> здесь. Всё это - подключаемые файлы SourceMod, которые включают в себя описание множества функций, тегов и других особенностей, доступных плагинам SourceMod. Подключаемые файлы, по сути, это такой же обычный текст, как и сам код плагинов, потому Вы можете без проблем открыть его любым текстовым редактором и прочитать. Вы можете обратить внимание, однако, что здесь не так много кода, чтобы эти функции SourceMod вообще работали, так как же оно работает? Они реализованы внутри ядра самого SourceMod и написаны на C++, и скомпилированы в двоичные исполняемые файлы, которые размещаются в папке '''bin'''. Так как SourcePawn-код и SourceMod-код связываются между собой, если компилятор ничего не знает о существовании последнего? Подключаемые файлы SourceMod реализованы таким образом, чтобы компилятор понимал, что реализация функций будет ''где-то в другом месте''. Компилятор понимает это, и генерирует специальный код, который вызовет внешнюю функцию. Когда SourceMod загружает Ваш плагин, он анализирует этот код и заменяет на вызов своих внутренних функций. Это называется [https://en.wikipedia.org/wiki/Dynamic_linker динамическим связыванием].
*'''Startup''' - Функция, которая осуществляет запуск процедур в Вашем плагине.
 
  
Плагин скелетной структуры выглядит следующим образом:
+
= Устанавливаем информацию о плагине =
<pawn>
+
Теперь, когда мы получили доступ к "фичам" SourceMod, самое время установить информацию, которая отображается через команду <tt>sm plugins list</tt>. Там нет ни одного "безымянного" плагина. Чтобы сделать это, заглянем внутрь '''sourcemod.inc''' и увидим там формат, в котором информация о плагине должна быть объявлена. Всегда полезно заглядывать внутрь включаемых файлов SM, чтобы найти неизвестную Вам информацию. Так же есть [https://sourcemod.net/new-api/ документация по API], но она может быть устаревшей, и там есть только файлы ядра SM, так что если Ваш плагин использует любое стороннее расширение или плагин, Вам придётся изучать inc-файлы. Так что, откройте '''sourcemod.inc''', и листайте вниз, пока не увидите это:
#include <sourcemod>
+
 
 +
<sourcepawn>/**
 +
* Plugin public information.
 +
*/
 +
struct Plugin
 +
{
 +
  public const char[] name; /**< Plugin Name */
 +
  public const char[] description; /**< Plugin Description */
 +
  public const char[] author; /**< Plugin Author */
 +
  public const char[] version; /**< Plugin Version */
 +
  public const char[] url; /**< Plugin URL */
 +
};</sourcepawn>
 +
и это:
 +
<sourcepawn>/**
 +
* Declare this as a struct in your plugin to expose its information.
 +
* Example:
 +
*
 +
* public Plugin myinfo =
 +
* {
 +
*    name = "My Plugin",
 +
*    //etc
 +
* };
 +
*/
 +
public Plugin myinfo;</sourcepawn>
 +
 
 +
Это говорит нам о том, что нам нужно создать глобальную публичную переменную <tt>myinfo</tt>, тип которой должен быть <tt>Plugin</tt>, который является структурой с 5-ью полями, и все - строки. Это может прозвучать сложно для новичка, но это просто. Так что давайте продолжим и создадим:
 +
<sourcepawn>public Plugin myinfo =
 +
{
 +
name = "Мой первый плагин",
 +
author = "Я",
 +
description = "Мой самый первый плагин",
 +
version = "1.0",
 +
url = "http://www.sourcemod.net/"
 +
};</sourcepawn>
 +
 
 +
Ключевое слово <tt>public</tt> говорит о том, что SourceMod будет иметь прямой доступ к нашей переменной. <tt>Plugin</tt> указывает тип нашей переменной. <tt>myinfo</tt>, очевидно, имя нашей переменной, как того требует SourceMod. Вы видите, что мы тут же её инициализируем и заполняем данными. Это предпочтительный, и единственный способ рассказать ядру, что за плагин оно загружает.
 +
 
 +
После всего этого, наш плагин полностью должен выглядеть так:
 +
<sourcepawn>#include <sourcemod>
 +
 
 +
public Plugin myinfo =
 +
{
 +
name = "Мой первый плагин",
 +
author = "Я",
 +
description = "Мой самый первый плагин",
 +
version = "1.0",
 +
url = "http://www.sourcemod.net/"
 +
};</sourcepawn>
 +
 
 +
= Делая код "запускаемым" =
 +
Мы уже включили "фичи" SourceMod и заполнили информацию о нашем плагине. Сейчас мы имеем хороший сформированный плагин, который можно скомпилировать и загрузить с помощью SourceMod. Однако, есть одна проблема - он не делает ничего. У Вас мог возникнуть "соблазн" начать писать код прямо после объявления <tt>myinfo</tt>, чтобы посмотреть, что он не компилируется. SourcePawn, в отличии от других скриптовых языков, вроде Lua, не разрешает помещать любой код вне функций. После прочтения этого, Вы, скорее всего, захотите объявить какую-нибудь функцию, назвать её, возможно, <tt>main</tt>, скомпилировать и запустить плагин, и увидеть, что Ваш код никогда не будет вызван. Так как нам сделать, чтобы SourceMod вызывал наш код? Именно по этой причине, у нас есть "форварды". '''Форварды''' ('''Forwards''') - прототипы функций, которые объявляются одной стороной, и которые могут быть реализованы - другой, как [https://ru.wikipedia.org/wiki/Callback_(%D0%BF%D1%80%D0%BE%D0%B3%D1%80%D0%B0%D0%BC%D0%BC%D0%B8%D1%80%D0%BE%D0%B2%D0%B0%D0%BD%D0%B8%D0%B5) функции обратного вызова (каллбеки)]. Когда первая сторона запускает вызов форварда, все остальные, у кого есть объявленный совпадающий каллбек, получают его вызов. SourceMod объявляет множество интересных форвардов, которые мы можем реализовать. Как Вы могли заметить, форварды - единственный способ, чтобы наш код был вызван, держите это в уме. Так что давайте реализуем форвард <tt>OnPluginStart</tt>. Как Вы могли догадаться, он вызывается, когда наш плагин запускается. Чтобы сделать это, нам нужно посмотреть на объявление <tt>OnPluginStart</tt>. Она располагается внутри '''sourcemod.inc''', файла, с которым мы уже знакомы, так что давайте найдём её:
 +
<sourcepawn>/**
 +
* Called when the plugin is fully initialized and all known external references
 +
* are resolved. This is only called once in the lifetime of the plugin, and is
 +
* paired with OnPluginEnd().
 +
*
 +
* If any run-time error is thrown during this callback, the plugin will be marked
 +
* as failed.
 +
*
 +
* It is not necessary to close any handles or remove hooks in this function. 
 +
* SourceMod guarantees that plugin shutdown automatically and correctly releases
 +
* all resources.
 +
*
 +
* @noreturn
 +
*/
 +
forward void OnPluginStart();</sourcepawn>
 +
Пустые скобки сообщают нам о том, что внутрь форварда не передаётся ни один аргумент; <tt>@noreturn</tt> внутри документации сообщает нам, что нам не нужно ничего возвращать. Крайне простой форвард. Так как написать правильный каллбек для этого? Для начала, наш каллбек должен иметь то же самое название, то есть <tt>OnPluginStart</tt>; во-вторых, наш каллбек должен иметь то же самое кол-во аргументов (в данном случае, ни одного); в-третьих, наш каллбек должен быть помечен ключевым словом <tt>public</tt>, чтобы SourceMod смог его вызвать. Так что простейшая реализация выглядит так:
 +
<sourcepawn>public void OnPluginStart()
 +
{
 +
}</sourcepawn>
 +
 
 +
Теперь мы можем писать код внутри фигурных скобок. Давайте выведем <tt>"Привет, мир!"</tt> в серверную консоль. Чтобы сделать это, нам нужно воспользоваться функцией <tt>PrintToServer</tt>. Она объявлена внутри файла '''console.inc''', однако, нам не нужно включать его, поскольку он уже включен как часть '''sourcemod.inc'''.
 +
<sourcepawn>/**
 +
* Sends a message to the server console.
 +
*
 +
* @param format Formatting rules.
 +
* @param ... Variable number of format parameters.
 +
* @noreturn
 +
*/
 +
native int PrintToServer(const char[] format, any ...);</sourcepawn>
 +
 
 +
Как Вы могли заметить, это "нативная" функция. Она реализована внутри ядра SM. Судя по аргументам, она относится к [[Format_Class_Functions_%28SourceMod_Scripting%29|функциям форматирующего типа]]. Однако, нам не нужно ничего форматировать сейчас, потому мы просто передадим строку <tt>"Привет, мир!"</tt>, как один-единственный аргумент:
 +
<sourcepawn>public void OnPluginStart()
 +
{
 +
PrintToServer("Привет, мир!");
 +
}</sourcepawn>
 +
 
 +
Готово! Полный исходный код Вашего плагина должен выглядеть так:
 +
<sourcepawn>#include <sourcemod>
  
public Plugin:myinfo =
+
public Plugin myinfo =
 
{
 
{
 
name = "Мой первый плагин",
 
name = "Мой первый плагин",
 
author = "Я",
 
author = "Я",
description = "Мой первый супер плагин",
+
description = "Мой самый первый плагин",
version = "1.0.0.0",
+
version = "1.0",
 
url = "http://www.sourcemod.net/"
 
url = "http://www.sourcemod.net/"
 
};
 
};
  
public OnPluginStart()
+
public void OnPluginStart()
 
{
 
{
// Выполнение единовременного запуска задач ...
+
PrintToServer("Привет, мир!");
}</pawn>
+
}</sourcepawn>
 
+
Скомпилируйте и загрузите его на Вашем сервере, и Вы увидите, что сообщение отобразится в серверной консоли.
Информация часть имеет специальную синтаксическую конструкцию. Вы не можете изменить любое из ключевых слов, или объявление <tt>public Plugin:myinfo</tt>. Хорошая идея заключается в том, чтобы скопировать и вставить эту скелетную структуру и отредактировать строки, чтобы начать работу.
 
  
 
=Включения=
 
=Включения=
 
Pawn требует включать файлы '''include''', как и C требует наличие заголовка у файла. Включение списков файлов всех структур, функций, вызовы и тегов, которые имеются в наличии. Есть три типа файлов:
 
Pawn требует включать файлы '''include''', как и C требует наличие заголовка у файла. Включение списков файлов всех структур, функций, вызовы и тегов, которые имеются в наличии. Есть три типа файлов:
*'''Core''' - <tt>sourcemod.inc</tt>, и все его включения. Все представленные в SourceMod Core.
+
*'''Ядро''' ('''Core''') - <tt>sourcemod.inc</tt>, и все его включения. Все представленные в SourceMod Core.
*'''Extension''' - добавляет зависимость от определенного расширения.
+
*'''Расширение''' ('''Extension''') - добавляет зависимость от определенного расширения.
*'''Plugin''' - добавляет зависимость от некоторых плагинов.
+
*'''Плагин''' ('''Plugin''') - добавляет зависимость от некоторых плагинов.
  
 
Файлы включения загружаются с помощью <tt>#include</tt> указателя компилятора.
 
Файлы включения загружаются с помощью <tt>#include</tt> указателя компилятора.
Line 145: Line 231:
 
RegAdminCmd("sm_myslap", Command_MySlap, ADMFLAG_SLAY)
 
RegAdminCmd("sm_myslap", Command_MySlap, ADMFLAG_SLAY)
  
sm_myslap_damage = CreateConVar("sm_myslap_damage", "5", "Default slap damage")
+
sm_myslap_damage = CreateConVar("sm_myslap_damage", "5", "Повреждение от удара по умолчанию")
 
AutoExecConfig(true, "plugin_myslap")
 
AutoExecConfig(true, "plugin_myslap")
 
}
 
}
Line 154: Line 240:
 
new damage = GetConVarInt(sm_myslap_damage)
 
new damage = GetConVarInt(sm_myslap_damage)
  
/* Остальное остается не тронутым! */
+
/* Остальное остается без изменений! */
 
</pawn>
 
</pawn>
  
=Showing Activity, Logging=
+
=Отображение активности, логирование=
Almost all admin commands should log their activity, and some admin commands should show their activity to in-game clients. This can be done via the [http://docs.sourcemod.net/api/index.php?fastload=show&id=599& LogAction()] and [http://docs.sourcemod.net/api/index.php?fastload=show&id=466& ShowActivity2()] functions. The exact functionality of ShowActivity2() is determined by the <tt>sm_show_activity</tt> cvar.
+
Почти все команды администратора должны логировать (записывать в лог) их активность, а некоторые команды администратора должны отобразить свою активность в игре для клиентов. Это может быть сделано через [http://docs.sourcemod.net/api/index.php?fastload=show&id=599& LogAction()] и [http://docs.sourcemod.net/api/index.php?fastload=show&id=466& ShowActivity2()] функции. Точное функциональность ShowActivity2() определяется <tt>sm_show_activity</tt> переменной.
  
For example, let's rewrite the last few lines of our slap command:
+
Например, давайте перепишем несколько последних строк нашей slap команды:
 
<pawn>
 
<pawn>
 
SlapPlayer(target, damage)
 
SlapPlayer(target, damage)
Line 168: Line 254:
 
GetClientName(target, name, sizeof(name))
 
GetClientName(target, name, sizeof(name))
  
ShowActivity2(client, "[SM] ", "Slapped %s for %d damage!", name, damage)
+
ShowActivity2(client, "[SM] ", "Вас ударил %s на %d повреждений!", name, damage)
 
LogAction(client, target, "\"%L\" slapped \"%L\" (damage %d)", client, target, damage)
 
LogAction(client, target, "\"%L\" slapped \"%L\" (damage %d)", client, target, damage)
  
Line 175: Line 261:
 
</pawn>
 
</pawn>
  
=Multiple Targets=
+
=Групповые цели=
To fully complete our slap demonstration, let's make it support multiple targets. SourceMod's [[Admin_Commands_%28SourceMod%29#How_to_Target|targeting system]] is quite advanced, so using it may seem complicated at first.
+
Чтобы полностью завершить нашу демонстрацию slap, давайте сделаем поддержку нескольких целей. [[Admin_Commands_%28SourceMod%29#How_to_Target|Targeting system]] в SourceMod достаточно усовершенствована, её использование может показаться сложным на первый взгляд.
  
The function we use is [http://docs.sourcemod.net/api/index.php?fastload=show&id=703& ProcessTargetString()]. It takes in input from the console, and returns a list of matching clients. It also returns a noun that will identify either a single client or describe a list of clients. The idea is that each client is then processed, but the activity shown to all players is only processed once. This reduces screen spam.
+
Мы используем функцию [http://docs.sourcemod.net/api/index.php?fastload=show&id=703& ProcessTargetString()]. Он принимает ввод с консоли, и возвращает список подходящих клиентов. Она также возвращает существительное, которые будет определять либо одного клиента или характеризовать список клиентов. Идея заключается в том, что каждый клиент будет обработан, но активность будет показана всем игрокам только один раз. Это уменьшит спам на экране.
  
This method of target processing is used for almost every admin command in SourceMod, and in fact FindTarget() is just a simplified version.
+
Этот метод обработки цели используется почти каждой командой администратора в SourceMod, а на самом деле FindTarget() является лишь упрощенной версией.
  
Full, final example:
+
Полный, окончательный пример:
 
<pawn>
 
<pawn>
 
#include <sourcemod>
 
#include <sourcemod>
Line 191: Line 277:
 
public Plugin:myinfo =
 
public Plugin:myinfo =
 
{
 
{
name = "My First Plugin",
+
name = "Мой первый плагин",
author = "Me",
+
author = "Я",
description = "My first plugin ever",
+
description = "Мой первый супер плагин",
 
version = "1.0.0.0",
 
version = "1.0.0.0",
 
url = "http://www.sourcemod.net/"
 
url = "http://www.sourcemod.net/"
Line 203: Line 289:
 
RegAdminCmd("sm_myslap", Command_MySlap, ADMFLAG_SLAY)
 
RegAdminCmd("sm_myslap", Command_MySlap, ADMFLAG_SLAY)
  
sm_myslap_damage = CreateConVar("sm_myslap_damage", "5", "Default slap damage")
+
sm_myslap_damage = CreateConVar("sm_myslap_damage", "5", "Повреждение от удара по умолчанию")
 
AutoExecConfig(true, "plugin_myslap")
 
AutoExecConfig(true, "plugin_myslap")
 
}
 
}
Line 212: Line 298:
 
new damage = GetConVarInt(sm_myslap_damage)
 
new damage = GetConVarInt(sm_myslap_damage)
  
/* Get the first argument */
+
/* Получаем первый аргумент */
 
GetCmdArg(1, arg1, sizeof(arg1))
 
GetCmdArg(1, arg1, sizeof(arg1))
  
/* If there are 2 or more arguments, and the second argument fetch
+
/* Если есть 2 или более аргументов, и второй аргумент получен
* is successful, convert it to an integer.
+
* успешно, превратить его в целое.
 
*/
 
*/
 
if (args >= 2 && GetCmdArg(2, arg2, sizeof(arg2)))
 
if (args >= 2 && GetCmdArg(2, arg2, sizeof(arg2)))
Line 224: Line 310:
  
 
/**
 
/**
* target_name - stores the noun identifying the target(s)
+
* target_name - сохраняет существительные установленной цели(ей)
* target_list - array to store clients
+
* target_list - массив для хранения клиентов
* target_count - variable to store number of clients
+
* target_count - переменная для хранения числа клиентов
* tn_is_ml - stores whether the noun must be translated
+
* tn_is_ml - сохраняет должно ли существительное быть переведено
 
*/
 
*/
 
new String:target_name[MAX_TARGET_LENGTH]
 
new String:target_name[MAX_TARGET_LENGTH]
Line 238: Line 324:
 
target_list,
 
target_list,
 
MAXPLAYERS,
 
MAXPLAYERS,
COMMAND_FILTER_ALIVE, /* Only allow alive players */
+
COMMAND_FILTER_ALIVE, /* Разрешено только живым игрокам */
 
target_name,
 
target_name,
 
sizeof(target_name),
 
sizeof(target_name),
 
tn_is_ml)) <= 0)
 
tn_is_ml)) <= 0)
 
{
 
{
/* This function replies to the admin with a failure message */
+
/* Эта функция отвечает администратору сообщение о неудачи */
 
ReplyToTargetError(client, target_count);
 
ReplyToTargetError(client, target_count);
 
return Plugin_Handled;
 
return Plugin_Handled;
Line 266: Line 352:
 
}</pawn>
 
}</pawn>
  
=Client and Entity Indexes=
+
=Клиентский и объектный индексы=
One major point of confusion with Half-Life 2 is the difference between the following things:
+
Одним основным вопросом путаницы с Half-Life 2 является разница между следующими вещами:
*Client index
+
*Индекс клиента (Client index)
*Entity index
+
*Индекс объекта (Entity index)
*Userid
+
*Идентификатор пользователя (Userid)
 +
 
 +
Первый ответ заключается в том, что клиенты это объекты. Таким образом, индекс клиента и индекс объекта одно и тоже. Когда SourceMod функция запрашивает индекс объекта, индекс клиента может быть указан. Когда SourceMod функция запрашивает индекс клиента, как правило, это означает, что только индекс клиента может быть указан.
  
The first answer is that clients are entities. Thus, a client index and an entity index are the same thing. When a SourceMod function asks for an entity index, a client index can be specified. When a SourceMod function asks for a client index, usually it means only a client index can be specified.
+
Быстрый способ проверить является ли индекс объекта клиентом - проверить находится ли он между 1 и [http://docs.sourcemod.net/api/index.php?fastload=show&id=397& GetMaxClients()] (включительно). Если сервер имеет максимум N клиентских слотов, то объекты с 1 по N, всегда зарезервированы для клиентов. Заметим, что 0 - верный индекс объекта; он является общим объектом (worldspawn).
  
A fast way to check if an entity index is a client is checking whether it's between 1 and [http://docs.sourcemod.net/api/index.php?fastload=show&id=397& GetMaxClients()] (inclusive).  If a server has N client slots maximum, then entities 1 through N are always reserved for clients. Note that 0 is a valid entity index; it is the world entity (worldspawn).
+
Идентификатор пользователя, это абсолютно другое. Сервер поддерживает общее "число соединений", и оно начинается с 1. Каждый раз, когда подключается новый клиент, общее число соединений увеличивается, и клиент получает новый номер, называемый идентификатором пользователя.
  
A userid, on the other hand, is completely differentThe server maintains a global "connection count" number, and it starts at 1.  Each time a client connects, the connection count is incremented, and the client receives that new number as their userid.
+
Например, первый подключившийся клиент имеет идентификатор пользователя 2. Если он вышел и соединился заново, его идентификатор будет 3 (если другие клиенты не подключились в этот период). Since clients are disconnected on mapchange, their userids change as wellUserids are a handy way to check if a client's connection status has changed.
  
For example, the first client to connect has a userid of 2. If he exits and rejoins, his userid will be 3 (unless another client joins in-between). Since clients are disconnected on mapchange, their userids change as well. Userids are a handy way to check if a client's connection status has changed.  
+
SourceMod предусматривает две функции для userid: [http://docs.sourcemod.net/api/index.php?fastload=show&id=442& GetClientOfUserId()] и [http://docs.sourcemod.net/api/index.php?fastload=show&id=402& GetClientUserId()].
  
SourceMod provides two functions for userids: [http://docs.sourcemod.net/api/index.php?fastload=show&id=442& GetClientOfUserId()] and [http://docs.sourcemod.net/api/index.php?fastload=show&id=402& GetClientUserId()].
+
=События=
 +
События являются информационными сообщениями передаваемые между объектами на сервере. Многие так же передаются от сервера к клиенту. Они определены в .res файлах в папке <tt>hl2/resource</tt> и папке <tt>resource</tt> конкретных модов. Основной список смотрите здесь [[Game Events (Source)|Source Game Events]].
  
=Events=
+
Важно отметить некоторые особенности событий:
Events are informational notification messages passed between objects in the server. Many are also passed from the server to the client. They are defined in .res files under the <tt>hl2/resource</tt> folder and <tt>resource</tt> folders of specific mods. For a basic listing, see [[Game Events (Source)|Source Game Events]].
+
*Они почти всегда носят информационных характер. Т.е., блокирование <tt>player_death</tt> не остановит смерть игрока. Он может заблокировать HUD или консольное сообщение или что то незначительное.
 +
*Они всегда используют userid вместо индексов клиента(client indexes).
 +
*То что они находятся в файле ресурсов не означает что они когда-либо будут вызываться или работать так как вы ожидаете. Моды, как известно, не должным образом документируют функционирование своих событий.
  
It is important to note a few concepts about events:
 
*They are almost always informational.  That is, blocking <tt>player_death</tt> will not stop a player from dying.  It may block a HUD or console message or something else minor.
 
*They always use userids instead of client indexes.
 
*Just because it is in a resource file does not mean it is ever called, or works the way you expect it to.  Mods are notorious at not properly documenting their event functionality.
 
  
An example of finding when a player dies:
+
Пример обнаружения, когда игрок умирает:
 
<pawn>
 
<pawn>
 
public OnPluginStart()
 
public OnPluginStart()
Line 362: Line 449:
  
  
=Further Reading=
+
=Продолжение обучения=
For further reading, see the "Scripting" section at the [http://docs.sourcemod.net/ SourceMod Documentation].
+
Для дальнейшего обучения, смотри раздел "Scripting" в [[Ru:SourceMod Documentation]].
  
 
[[Category:Ru:SourceMod Scripting]]
 
[[Category:Ru:SourceMod Scripting]]

Latest revision as of 00:49, 9 February 2021

Это руководство даст Вам основные понятия о написании SourceMod плагинов. Если вы не знакомы с языком SourcePawn, то Мы настоятельно рекомендуем ознакомиться со статьей Ru:Introduction to SourcePawn (Введение в SourcePawn).

Для получения информации о компиляции плагинов см. Compiling SourceMod Plugins (Компиляция SourceMod плагинов). Автор настоящей статьи использует редактор Crimson Editor для написания плагинов. Вы можете использовать PSPad, UltraEdit, Notepad++, TextPad, SourceMod IDE или любой другой текстовый редактор.

Начиная с нуля

Откройте Ваш любимый текстовый редактор и создайте новый пустой файл. Теперь Вы можете начать писать код, используя основные функции языка, однако, Вы не можете использовать любые функции и особенности самого SourceMod, потому что компилятор ничего не знает о них. Это сделано специально, чтобы было возможно использовать SourcePawn отдельно от SourceMod. Но так как мы пишем плагин именно для SourceMod, самая лучшая идея - это в первую очередь получить доступ к оособенностям SourceMod. Этой цели можно достичь с помощью директивы #include. Она сообщает компилятору, что содержимое указанного файла нужно вставить в Ваш при компиляции.

#include <sourcemod>

Как это работает? Сначала обратите внимание, что имя файла мы обрамили в угловые скобки. Угловые скобки сообщают компилятору, что указанный файл нужно поискать в стандартных директориях подключаемых файлов. По-умолчанию, такая директория одна, и это scripting/include. Вы можете открыть эту папку и увидеть множество файлов с расширением .inc здесь. Всё это - подключаемые файлы SourceMod, которые включают в себя описание множества функций, тегов и других особенностей, доступных плагинам SourceMod. Подключаемые файлы, по сути, это такой же обычный текст, как и сам код плагинов, потому Вы можете без проблем открыть его любым текстовым редактором и прочитать. Вы можете обратить внимание, однако, что здесь не так много кода, чтобы эти функции SourceMod вообще работали, так как же оно работает? Они реализованы внутри ядра самого SourceMod и написаны на C++, и скомпилированы в двоичные исполняемые файлы, которые размещаются в папке bin. Так как SourcePawn-код и SourceMod-код связываются между собой, если компилятор ничего не знает о существовании последнего? Подключаемые файлы SourceMod реализованы таким образом, чтобы компилятор понимал, что реализация функций будет где-то в другом месте. Компилятор понимает это, и генерирует специальный код, который вызовет внешнюю функцию. Когда SourceMod загружает Ваш плагин, он анализирует этот код и заменяет на вызов своих внутренних функций. Это называется динамическим связыванием.

Устанавливаем информацию о плагине

Теперь, когда мы получили доступ к "фичам" SourceMod, самое время установить информацию, которая отображается через команду sm plugins list. Там нет ни одного "безымянного" плагина. Чтобы сделать это, заглянем внутрь sourcemod.inc и увидим там формат, в котором информация о плагине должна быть объявлена. Всегда полезно заглядывать внутрь включаемых файлов SM, чтобы найти неизвестную Вам информацию. Так же есть документация по API, но она может быть устаревшей, и там есть только файлы ядра SM, так что если Ваш плагин использует любое стороннее расширение или плагин, Вам придётся изучать inc-файлы. Так что, откройте sourcemod.inc, и листайте вниз, пока не увидите это:

/**
 * Plugin public information.
 */
struct Plugin
{
   public const char[] name;		/**< Plugin Name */
   public const char[] description;	/**< Plugin Description */
   public const char[] author;		/**< Plugin Author */
   public const char[] version;		/**< Plugin Version */
   public const char[] url;			/**< Plugin URL */
};

и это:

/**
 * Declare this as a struct in your plugin to expose its information.
 * Example:
 *
 * public Plugin myinfo =
 * {
 *    name = "My Plugin",
 *    //etc
 * };
 */
public Plugin myinfo;

Это говорит нам о том, что нам нужно создать глобальную публичную переменную myinfo, тип которой должен быть Plugin, который является структурой с 5-ью полями, и все - строки. Это может прозвучать сложно для новичка, но это просто. Так что давайте продолжим и создадим:

public Plugin myinfo =
{
	name = "Мой первый плагин",
	author = "Я",
	description = "Мой самый первый плагин",
	version = "1.0",
	url = "http://www.sourcemod.net/"
};

Ключевое слово public говорит о том, что SourceMod будет иметь прямой доступ к нашей переменной. Plugin указывает тип нашей переменной. myinfo, очевидно, имя нашей переменной, как того требует SourceMod. Вы видите, что мы тут же её инициализируем и заполняем данными. Это предпочтительный, и единственный способ рассказать ядру, что за плагин оно загружает.

После всего этого, наш плагин полностью должен выглядеть так:

#include <sourcemod>
 
public Plugin myinfo =
{
	name = "Мой первый плагин",
	author = "Я",
	description = "Мой самый первый плагин",
	version = "1.0",
	url = "http://www.sourcemod.net/"
};

Делая код "запускаемым"

Мы уже включили "фичи" SourceMod и заполнили информацию о нашем плагине. Сейчас мы имеем хороший сформированный плагин, который можно скомпилировать и загрузить с помощью SourceMod. Однако, есть одна проблема - он не делает ничего. У Вас мог возникнуть "соблазн" начать писать код прямо после объявления myinfo, чтобы посмотреть, что он не компилируется. SourcePawn, в отличии от других скриптовых языков, вроде Lua, не разрешает помещать любой код вне функций. После прочтения этого, Вы, скорее всего, захотите объявить какую-нибудь функцию, назвать её, возможно, main, скомпилировать и запустить плагин, и увидеть, что Ваш код никогда не будет вызван. Так как нам сделать, чтобы SourceMod вызывал наш код? Именно по этой причине, у нас есть "форварды". Форварды (Forwards) - прототипы функций, которые объявляются одной стороной, и которые могут быть реализованы - другой, как функции обратного вызова (каллбеки). Когда первая сторона запускает вызов форварда, все остальные, у кого есть объявленный совпадающий каллбек, получают его вызов. SourceMod объявляет множество интересных форвардов, которые мы можем реализовать. Как Вы могли заметить, форварды - единственный способ, чтобы наш код был вызван, держите это в уме. Так что давайте реализуем форвард OnPluginStart. Как Вы могли догадаться, он вызывается, когда наш плагин запускается. Чтобы сделать это, нам нужно посмотреть на объявление OnPluginStart. Она располагается внутри sourcemod.inc, файла, с которым мы уже знакомы, так что давайте найдём её:

/**
 * Called when the plugin is fully initialized and all known external references 
 * are resolved. This is only called once in the lifetime of the plugin, and is 
 * paired with OnPluginEnd().
 *
 * If any run-time error is thrown during this callback, the plugin will be marked 
 * as failed.
 *
 * It is not necessary to close any handles or remove hooks in this function.  
 * SourceMod guarantees that plugin shutdown automatically and correctly releases 
 * all resources.
 *
 * @noreturn
 */
forward void OnPluginStart();

Пустые скобки сообщают нам о том, что внутрь форварда не передаётся ни один аргумент; @noreturn внутри документации сообщает нам, что нам не нужно ничего возвращать. Крайне простой форвард. Так как написать правильный каллбек для этого? Для начала, наш каллбек должен иметь то же самое название, то есть OnPluginStart; во-вторых, наш каллбек должен иметь то же самое кол-во аргументов (в данном случае, ни одного); в-третьих, наш каллбек должен быть помечен ключевым словом public, чтобы SourceMod смог его вызвать. Так что простейшая реализация выглядит так:

public void OnPluginStart()
{
}

Теперь мы можем писать код внутри фигурных скобок. Давайте выведем "Привет, мир!" в серверную консоль. Чтобы сделать это, нам нужно воспользоваться функцией PrintToServer. Она объявлена внутри файла console.inc, однако, нам не нужно включать его, поскольку он уже включен как часть sourcemod.inc.

/**
 * Sends a message to the server console.
 *
 * @param format		Formatting rules.
 * @param ...			Variable number of format parameters.
 * @noreturn
 */
native int PrintToServer(const char[] format, any ...);

Как Вы могли заметить, это "нативная" функция. Она реализована внутри ядра SM. Судя по аргументам, она относится к функциям форматирующего типа. Однако, нам не нужно ничего форматировать сейчас, потому мы просто передадим строку "Привет, мир!", как один-единственный аргумент:

public void OnPluginStart()
{
	PrintToServer("Привет, мир!");
}

Готово! Полный исходный код Вашего плагина должен выглядеть так:

#include <sourcemod>
 
public Plugin myinfo =
{
	name = "Мой первый плагин",
	author = "Я",
	description = "Мой самый первый плагин",
	version = "1.0",
	url = "http://www.sourcemod.net/"
};
 
public void OnPluginStart()
{
	PrintToServer("Привет, мир!");
}

Скомпилируйте и загрузите его на Вашем сервере, и Вы увидите, что сообщение отобразится в серверной консоли.

Включения

Pawn требует включать файлы include, как и C требует наличие заголовка у файла. Включение списков файлов всех структур, функций, вызовы и тегов, которые имеются в наличии. Есть три типа файлов:

  • Ядро (Core) - sourcemod.inc, и все его включения. Все представленные в SourceMod Core.
  • Расширение (Extension) - добавляет зависимость от определенного расширения.
  • Плагин (Plugin) - добавляет зависимость от некоторых плагинов.

Файлы включения загружаются с помощью #include указателя компилятора.

Команды

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

Описание

Во-первых, давайте смотреть на то, какая команда требуется администратору. Команды администратора регистрируются с использованием функции RegAdminCmd. Она требует название, функцию обратного вызова и флаги админа по умолчанию.

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

public OnPluginStart()
{
	RegAdminCmd("sm_myslap", Command_MySlap, ADMFLAG_SLAY)
}
 
public Action:Command_MySlap(client, args)
{
}

Теперь Мы успешно обеспечили выполнение команды -- хотя она не будет ничего делать. На самом деле, она скажет "Неизвестная команда", если Вы используете её! Причина в том, что отсутствует Action тег. По умолчанию функция ввода консольных команд заключается в том, чтобы ответить о неизвестной команде. Чтобы заблокировать эту функцию, вы должны создать новое действие:

public Action:Command_MySlap(client, args)
{
	return Plugin_Handled;
}

Теперь команда не будет сообщать об ошибке, но она по-прежнему не будет ничего делать.

Реализация

Давайте решим, что команда будет выглядеть так. Пусть будет она действовать как команда по умолчанию sm_slap:

sm_myslap <name|#userid> [damage]

Чтобы осуществить это, Нам потребуется несколько шагов:

  • Получить ввод с консоли. Для этого мы используем GetCmdArg().
  • Найти соответствия игрока. Для этого мы используем FindTarget().
  • Ударить его. Для этого мы используем SlapPlayer(), которая требует в том числе sdktools расширение в комплекте с SourceMod.
  • Сообщить администратору. Для этого мы используем ReplyToCommand().

Полный пример:

#include <sourcemod>
#include <sdktools>
 
public Plugin:myinfo =
{
	name = "Мой первый плагин",
	author = "Я",
	description = "Мой первый супер плагин",
	version = "1.0.0.0",
	url = "http://www.sourcemod.net/"
}
 
public OnPluginStart()
{
	RegAdminCmd("sm_myslap", Command_MySlap, ADMFLAG_SLAY)
}
 
public Action:Command_MySlap(client, args)
{
	new String:arg1[32], String:arg2[32]
	new damage
 
	/* Получаем первый аргумент */
	GetCmdArg(1, arg1, sizeof(arg1))
 
	/* Если есть 2 или более аргументов, и второй аргумент получен
	 * успешно, превратить его в целое.
	 */
	if (args >= 2 && GetCmdArg(2, arg2, sizeof(arg2)))
	{
		damage = StringToInt(arg2)
	}
 
	/* Попытка и нахождение соответствия игрока */
	new target = FindTarget(client, arg1)
	if (target == -1)
	{
		/* FindTarget() автоматически отвечает с
		 * причиной провала.
		 */
		return Plugin_Handled;
	}
 
	SlapPlayer(target, damage)
 
	new String:name[MAX_NAME_LENGTH]
 
	GetClientName(target, name, sizeof(name))
	ReplyToCommand(client, "[SM] Вас ударил %s на %d повреждений!", name, damage)
 
	return Plugin_Handled;
}

Для получения дополнительной информации о том, что такое %s и %d, см. Ru:Format Class Functions. Имейте в виду, что Вам никогда не придется отменять или удалить Ваши команды администратора. Если плагин выгружается, SourceMod очищает их за Вас.

ConVars

ConVars, известные также как cvars, глобальные консольные переменные в движке Source. Они могут иметь целые, десятичные, или строковые значения. Доступ к ConVar осуществляется через дескрипторы (Handles). С тех пор как ConVars имеют глобальный характер, Вам не нужно закрывать дескрипторы ConVar (фактически, Вы и не можете).

Удобная особенность ConVars заключается в том, что они легко настраиваются пользователями. Они могут быть помещены в любой .cfg файл, например server.cfg или sourcemod.cfg. Чтобы сделать удобнее их использование, SourceMod имеет AutoExecConfig() функции. Эта функция автоматически создает .cfg файл по умолчанию, содержащий все Ваши переменные (cvars), снабженные комментариями для пользователей. Очень рекомендую Вам вызывать её, если у Вас есть настраиваемые ConVars.

Давайте усовершенствуем Наш предыдущий пример новой ConVar. ConVar назовём sm_myslap_damage и она будет определять повреждение по умолчанию для удара игрока, если размер повреждений не указан.

new Handle:sm_myslap_damage = INVALID_HANDLE
 
public OnPluginStart()
{
	RegAdminCmd("sm_myslap", Command_MySlap, ADMFLAG_SLAY)
 
	sm_myslap_damage = CreateConVar("sm_myslap_damage", "5", "Повреждение от удара по умолчанию")
	AutoExecConfig(true, "plugin_myslap")
}
 
public Action:Command_MySlap(client, args)
{
	new String:arg1[32], String:arg2[32]
	new damage = GetConVarInt(sm_myslap_damage)
 
	/* Остальное остается без изменений! */

Отображение активности, логирование

Почти все команды администратора должны логировать (записывать в лог) их активность, а некоторые команды администратора должны отобразить свою активность в игре для клиентов. Это может быть сделано через LogAction() и ShowActivity2() функции. Точное функциональность ShowActivity2() определяется sm_show_activity переменной.

Например, давайте перепишем несколько последних строк нашей slap команды:

	SlapPlayer(target, damage)
 
	new String:name[MAX_NAME_LENGTH]
 
	GetClientName(target, name, sizeof(name))
 
	ShowActivity2(client, "[SM] ", "Вас ударил %s на %d повреждений!", name, damage)
	LogAction(client, target, "\"%L\" slapped \"%L\" (damage %d)", client, target, damage)
 
	return Plugin_Handled;
}

Групповые цели

Чтобы полностью завершить нашу демонстрацию slap, давайте сделаем поддержку нескольких целей. Targeting system в SourceMod достаточно усовершенствована, её использование может показаться сложным на первый взгляд.

Мы используем функцию ProcessTargetString(). Он принимает ввод с консоли, и возвращает список подходящих клиентов. Она также возвращает существительное, которые будет определять либо одного клиента или характеризовать список клиентов. Идея заключается в том, что каждый клиент будет обработан, но активность будет показана всем игрокам только один раз. Это уменьшит спам на экране.

Этот метод обработки цели используется почти каждой командой администратора в SourceMod, а на самом деле FindTarget() является лишь упрощенной версией.

Полный, окончательный пример:

#include <sourcemod>
#include <sdktools>
 
new Handle:sm_myslap_damage = INVALID_HANDLE
 
public Plugin:myinfo =
{
	name = "Мой первый плагин",
	author = "Я",
	description = "Мой первый супер плагин",
	version = "1.0.0.0",
	url = "http://www.sourcemod.net/"
}
 
public OnPluginStart()
{
	LoadTranslations("common.phrases")
	RegAdminCmd("sm_myslap", Command_MySlap, ADMFLAG_SLAY)
 
	sm_myslap_damage = CreateConVar("sm_myslap_damage", "5", "Повреждение от удара по умолчанию")
	AutoExecConfig(true, "plugin_myslap")
}
 
public Action:Command_MySlap(client, args)
{
	new String:arg1[32], String:arg2[32]
	new damage = GetConVarInt(sm_myslap_damage)
 
	/* Получаем первый аргумент */
	GetCmdArg(1, arg1, sizeof(arg1))
 
	/* Если есть 2 или более аргументов, и второй аргумент получен
	 * успешно, превратить его в целое.
	 */
	if (args >= 2 && GetCmdArg(2, arg2, sizeof(arg2)))
	{
		damage = StringToInt(arg2)
	}
 
	/**
	 * target_name - сохраняет существительные установленной цели(ей)
	 * target_list - массив для хранения клиентов
	 * target_count - переменная для хранения числа клиентов
	 * tn_is_ml - сохраняет должно ли существительное быть переведено
	 */
	new String:target_name[MAX_TARGET_LENGTH]
	new target_list[MAXPLAYERS], target_count
	new bool:tn_is_ml
 
	if ((target_count = ProcessTargetString(
			arg1,
			client,
			target_list,
			MAXPLAYERS,
			COMMAND_FILTER_ALIVE, /* Разрешено только живым игрокам */
			target_name,
			sizeof(target_name),
			tn_is_ml)) <= 0)
	{
		/* Эта функция отвечает администратору сообщение о неудачи */
		ReplyToTargetError(client, target_count);
		return Plugin_Handled;
	}
 
	for (new i = 0; i < target_count; i++)
	{
		SlapPlayer(target_list[i], damage)
		LogAction(client, target_list[i], "\"%L\" slapped \"%L\" (damage %d)", client, target_list[i], damage)
	}
 
	if (tn_is_ml)
	{
		ShowActivity2(client, "[SM] ", "Slapped %t for %d damage!", target_name, damage)
	}
	else
	{
		ShowActivity2(client, "[SM] ", "Slapped %s for %d damage!", target_name, damage)
	}
 
	return Plugin_Handled;
}

Клиентский и объектный индексы

Одним основным вопросом путаницы с Half-Life 2 является разница между следующими вещами:

  • Индекс клиента (Client index)
  • Индекс объекта (Entity index)
  • Идентификатор пользователя (Userid)

Первый ответ заключается в том, что клиенты это объекты. Таким образом, индекс клиента и индекс объекта одно и тоже. Когда SourceMod функция запрашивает индекс объекта, индекс клиента может быть указан. Когда SourceMod функция запрашивает индекс клиента, как правило, это означает, что только индекс клиента может быть указан.

Быстрый способ проверить является ли индекс объекта клиентом - проверить находится ли он между 1 и GetMaxClients() (включительно). Если сервер имеет максимум N клиентских слотов, то объекты с 1 по N, всегда зарезервированы для клиентов. Заметим, что 0 - верный индекс объекта; он является общим объектом (worldspawn).

Идентификатор пользователя, это абсолютно другое. Сервер поддерживает общее "число соединений", и оно начинается с 1. Каждый раз, когда подключается новый клиент, общее число соединений увеличивается, и клиент получает новый номер, называемый идентификатором пользователя.

Например, первый подключившийся клиент имеет идентификатор пользователя 2. Если он вышел и соединился заново, его идентификатор будет 3 (если другие клиенты не подключились в этот период). Since clients are disconnected on mapchange, their userids change as well. Userids are a handy way to check if a client's connection status has changed.

SourceMod предусматривает две функции для userid: GetClientOfUserId() и GetClientUserId().

События

События являются информационными сообщениями передаваемые между объектами на сервере. Многие так же передаются от сервера к клиенту. Они определены в .res файлах в папке hl2/resource и папке resource конкретных модов. Основной список смотрите здесь Source Game Events.

Важно отметить некоторые особенности событий:

  • Они почти всегда носят информационных характер. Т.е., блокирование player_death не остановит смерть игрока. Он может заблокировать HUD или консольное сообщение или что то незначительное.
  • Они всегда используют userid вместо индексов клиента(client indexes).
  • То что они находятся в файле ресурсов не означает что они когда-либо будут вызываться или работать так как вы ожидаете. Моды, как известно, не должным образом документируют функционирование своих событий.


Пример обнаружения, когда игрок умирает:

public OnPluginStart()
{
   HookEvent("player_death", Event_PlayerDeath)
}
 
public Event_PlayerDeath(Handle:event, const String:name[], bool:dontBroadcast)
{
   new victim_id = GetEventInt(event, "userid")
   new attacker_id = GetEventInt(event, "attacker")
 
   new victim = GetClientOfUserId(victim_id)
   new attacker = GetClientOfUserId(attacker_id)
 
   /* CODE */
}

Callback Orders and Pairing

SourceMod has a number of builtin callbacks about the state of the server and plugin. Some of these are paired in special ways which is confusing to users.

Pairing

Pairing is SourceMod terminology. Examples of it are:

  • OnMapEnd() cannot be called without an OnMapStart(), and if OnMapStart() is called, it cannot be called again without an OnMapEnd().
  • OnClientConnected(N) for a given client N will only be called once, until an OnClientDisconnected(N) for the same client N is called (which is guaranteed to happen).

There is a formal definition of SourceMod's pairing. For two functions X and Y, both with input A, the following conditions hold:

  • If X is invoked with input A, it cannot be invoked again with the same input unless Y is called with input A.
  • If X is invoked with input A, it is guaranteed that Y will, at some point, be called with input A.
  • Y cannot be invoked with any input A unless X was called first with input A.
  • The relationship is described as, "X is paired with Y," and "Y is paired to X."

General Callbacks

These callbacks are listed in the order they are called, in the lifetime of a plugin and the server.

  • AskPluginLoad() - Called once, immediately after the plugin is loaded from the disk.
  • OnPluginStart() - Called once, after the plugin has been fully initialized and can proceed to load. Any run-time errors in this function will cause the plugin to fail to load. This is paired with OnPluginEnd().
  • OnMapStart() - Called every time the map loads. If the plugin is loaded late, and the map has already started, this function is called anyway after load, in order to preserve pairing. This function is paired with OnMapEnd().
  • OnConfigsExecuted() - Called once per map-change after servercfgfile (usually server.cfg), sourcemod.cfg, and all plugin config files have finished executing. If a plugin is loaded after this has happened, the callback is called anyway, in order to preserve pairing. This function is paired with OnMapEnd().
  • At this point, most game callbacks can occur, such as events and callbacks involving clients (or other things, like OnGameFrame).
  • OnMapEnd() - Called when the map is about to end. At this point, all clients are disconnected, but TIMER_NO_MAPCHANGE timers are not yet destroyed. This function is paired to OnMapStart().
  • OnPluginEnd() - Called once, immediately before the plugin is unloaded. This function is paired to OnPluginStart().

Client Callbacks

These callbacks are listed in no specific order, however, their documentation holds for both fake and real clients.

  • OnClientConnect() - Called when a player initiates a connection. This is paired with OnClientDisconnect() for successful connections only.
  • OnClientAuthorized() - Called when a player gets a Steam ID. It is important to note that this may never be called. It may occur any time in between connect and disconnect. Do not rely on it unless you are writing something that needs Steam IDs, and even then you should use OnClientPostAdminCheck().
  • OnClientPutInServer() - Signifies that the player is in-game and IsClientInGame() will return true.
  • OnClientPostAdminCheck() - Called after the player is both authorized and in-game. That is, both OnClientAuthorized() and OnClientPutInServer() have been invoked. This is the best callback for checking administrative access after connect.
  • OnClientDisconnect() - Called when a player's disconnection ends. This is paired to OnClientConnect().

Frequently Asked Questions

Are plugins reloaded every mapchange?

Plugins, by default, are not reloaded on mapchange unless their timestamp changes. This is a feature so plugin authors have more flexibility with the state of their plugins.

Do I need to call CloseHandle in OnPluginEnd?

No. SourceMod automatically closes your Handles when your plugin is unloaded, in order to prevent memory errors.

Do I need to #include every individual .inc?

No. #include <sourcemod> will give you 95% of the .incs. Similarly, #include <sdktools> includes everything starting with <sdktools>.

Why don't some events fire?

There is no guarantee that events will fire. The event listing is not a specification, it is a list of the events that a game is capable of firing. Whether the game actually fires them is up to Valve or the developer.

Do I need to CloseHandle timers?

No. In fact, doing so may cause errors. Timers naturally die on their own unless they are infinite timers, in which case you can use KillTimer() or die gracefully by returning Plugin_Stop in the callback.

Are clients disconnected on mapchange?

All clients are fully disconnected before the map changes. They are all reconnected after the next map starts.


Продолжение обучения

Для дальнейшего обучения, смотри раздел "Scripting" в Ru:SourceMod Documentation.