AlliedModders Wiki - User contributions [en]

Category:Ru:SourceMod Scripting

2021-02-11T09:39:00Z

HolyHender: /* Информация */

Эта категория содержит статьи о написании скриптов под SourceMod с использованием SourcePawn.

===Введение===
*[[Ru:Introduction to SourcePawn|Ru:Introduction to SourcePawn]] - Введение в SourcePawn. Обучение синтаксису языка.
*[[Ru:Introduction to SourceMod Plugins|Ru:Introduction to SourceMod Plugins]] - Введение в SourceMod плагины. Создаем Ваш "первый плагин".
*[http://docs.sourcemod.net/api API Reference] - Поиск сценариев в справочнике API.

===Основной API===
*[[Ru:AutoConfigs (SourceMod Scripting)|Автоконфиги]] - Автоматическое создание .cfg файлов.
*[[Ru:Commands (SourceMod Scripting)|Команды]] - Консольные команды/ввод.
*[[Ru:ConVars (SourceMod Scripting)|Консольные переменные (ConVar)]] - Консольные переменные (cvars).
*[[Ru:Events (SourceMod Scripting)|События (Events)]] - Игровые события Half-Life.
*[[Ru:KeyValues (SourceMod Scripting)|Структура Ключ-Значение (KeyValues)]] - KeyValues анализ/запись файла.
*[[Ru:Menu API (SourceMod)|Меню]] - Создание и отображение меню.
*[[Ru:SQL (SourceMod Scripting)|SQL]] - Использование баз данных (MySQL, SQLite).
*[[Ru:Timers (SourceMod Scripting)|Таймеры (Timers)]] - Вызов таймеров.
*[[Ru:DataPacks|Пакеты данных (DataPack)]] - Создание и управление DataPack.
*[[Ru:Translations (SourceMod Scripting)|Переводы]] - Создание локализаций.

===Продвинутый API===
*[[Admin API (SourceMod)|API администрирования]] - Использование кэша администратора.
*[[Admin Menu (SourceMod Scripting)|API админского меню]] - Закрепление в меню администратора.
*[[Creating Natives (SourceMod Scripting)|Создание нативных функция]] - Разоблачение API других плагинов.
*[[Function Calling API (SourceMod Scripting)|API вызова функция]] - Вызовы внешних функций.
*[[Optional Requirements (SourceMod Scripting)|Необязательные требования]] - Управление зависимостями.
*[[SDKTools (SourceMod Scripting)|SDKTools]] - Использование мощного SDK уровней абстракции.
*[[TempEnts (SourceMod SDKTools)|Временные объекты]] - Использование временных объектов.

===Информация===
*[[Ru:Format Class Functions (SourceMod Scripting)|Форматирование текста]] - Всё про форматирование текста.
*[[Handles (SourceMod Scripting)|Handles]] - Обзор Handle и несколько распространённых типов.
*[[Optimizing Plugins (SourceMod Scripting)|Optimizing Plugins]] - Советы по оптимизации.
*[[Tags (Scripting)|Tags]] - Всё о тэгах.
*[[Vectors Explained (Scripting)|Vectors Explained]] - Объяснение типов Вектора.

===Дополнительные средства===
*[http://docs.sourcemod.net/api API Reference] - API по кодированию на SourcePawn.
*[[Entity Properties]] - Explanation of Source entity properties.
*[[Game Events (Source)|Game Events]] - Список игровых событий для популярных модификаций.
*[[Mod TempEnt List (Source)|Temp Entity Lists]] - Список временных объектов для популярных модификаций.
*[[SourceMod Profiler]] - Отслеживание производительности и оптимизации.

Category:Ru:SourceMod Scripting

2021-02-11T09:38:32Z

HolyHender: /* Информация */

Эта категория содержит статьи о написании скриптов под SourceMod с использованием SourcePawn.

===Введение===
*[[Ru:Introduction to SourcePawn|Ru:Introduction to SourcePawn]] - Введение в SourcePawn. Обучение синтаксису языка.
*[[Ru:Introduction to SourceMod Plugins|Ru:Introduction to SourceMod Plugins]] - Введение в SourceMod плагины. Создаем Ваш "первый плагин".
*[http://docs.sourcemod.net/api API Reference] - Поиск сценариев в справочнике API.

===Основной API===
*[[Ru:AutoConfigs (SourceMod Scripting)|Автоконфиги]] - Автоматическое создание .cfg файлов.
*[[Ru:Commands (SourceMod Scripting)|Команды]] - Консольные команды/ввод.
*[[Ru:ConVars (SourceMod Scripting)|Консольные переменные (ConVar)]] - Консольные переменные (cvars).
*[[Ru:Events (SourceMod Scripting)|События (Events)]] - Игровые события Half-Life.
*[[Ru:KeyValues (SourceMod Scripting)|Структура Ключ-Значение (KeyValues)]] - KeyValues анализ/запись файла.
*[[Ru:Menu API (SourceMod)|Меню]] - Создание и отображение меню.
*[[Ru:SQL (SourceMod Scripting)|SQL]] - Использование баз данных (MySQL, SQLite).
*[[Ru:Timers (SourceMod Scripting)|Таймеры (Timers)]] - Вызов таймеров.
*[[Ru:DataPacks|Пакеты данных (DataPack)]] - Создание и управление DataPack.
*[[Ru:Translations (SourceMod Scripting)|Переводы]] - Создание локализаций.

===Продвинутый API===
*[[Admin API (SourceMod)|API администрирования]] - Использование кэша администратора.
*[[Admin Menu (SourceMod Scripting)|API админского меню]] - Закрепление в меню администратора.
*[[Creating Natives (SourceMod Scripting)|Создание нативных функция]] - Разоблачение API других плагинов.
*[[Function Calling API (SourceMod Scripting)|API вызова функция]] - Вызовы внешних функций.
*[[Optional Requirements (SourceMod Scripting)|Необязательные требования]] - Управление зависимостями.
*[[SDKTools (SourceMod Scripting)|SDKTools]] - Использование мощного SDK уровней абстракции.
*[[TempEnts (SourceMod SDKTools)|Временные объекты]] - Использование временных объектов.

===Информация===
*[[Deprecation Schedule (SourceMod Scripting)|Deprecation Schedule]] - Which functions are getting removed.
*[[Ru:Format Class Functions (SourceMod Scripting)|Форматирование текста]] - Всё про форматирование текста.
*[[Handles (SourceMod Scripting)|Handles]] - Обзор Handle и несколько распространённых типов.
*[[Optimizing Plugins (SourceMod Scripting)|Optimizing Plugins]] - Советы по оптимизации.
*[[Tags (Scripting)|Tags]] - Всё о тэгах.
*[[Vectors Explained (Scripting)|Vectors Explained]] - Объяснение типов Вектора.

===Дополнительные средства===
*[http://docs.sourcemod.net/api API Reference] - API по кодированию на SourcePawn.
*[[Entity Properties]] - Explanation of Source entity properties.
*[[Game Events (Source)|Game Events]] - Список игровых событий для популярных модификаций.
*[[Mod TempEnt List (Source)|Temp Entity Lists]] - Список временных объектов для популярных модификаций.
*[[SourceMod Profiler]] - Отслеживание производительности и оптимизации.

Category:Ru:SourceMod Scripting

2021-02-11T09:37:43Z

HolyHender: /* Информация */

Эта категория содержит статьи о написании скриптов под SourceMod с использованием SourcePawn.

===Введение===
*[[Ru:Introduction to SourcePawn|Ru:Introduction to SourcePawn]] - Введение в SourcePawn. Обучение синтаксису языка.
*[[Ru:Introduction to SourceMod Plugins|Ru:Introduction to SourceMod Plugins]] - Введение в SourceMod плагины. Создаем Ваш "первый плагин".
*[http://docs.sourcemod.net/api API Reference] - Поиск сценариев в справочнике API.

===Основной API===
*[[Ru:AutoConfigs (SourceMod Scripting)|Автоконфиги]] - Автоматическое создание .cfg файлов.
*[[Ru:Commands (SourceMod Scripting)|Команды]] - Консольные команды/ввод.
*[[Ru:ConVars (SourceMod Scripting)|Консольные переменные (ConVar)]] - Консольные переменные (cvars).
*[[Ru:Events (SourceMod Scripting)|События (Events)]] - Игровые события Half-Life.
*[[Ru:KeyValues (SourceMod Scripting)|Структура Ключ-Значение (KeyValues)]] - KeyValues анализ/запись файла.
*[[Ru:Menu API (SourceMod)|Меню]] - Создание и отображение меню.
*[[Ru:SQL (SourceMod Scripting)|SQL]] - Использование баз данных (MySQL, SQLite).
*[[Ru:Timers (SourceMod Scripting)|Таймеры (Timers)]] - Вызов таймеров.
*[[Ru:DataPacks|Пакеты данных (DataPack)]] - Создание и управление DataPack.
*[[Ru:Translations (SourceMod Scripting)|Переводы]] - Создание локализаций.

===Продвинутый API===
*[[Admin API (SourceMod)|API администрирования]] - Использование кэша администратора.
*[[Admin Menu (SourceMod Scripting)|API админского меню]] - Закрепление в меню администратора.
*[[Creating Natives (SourceMod Scripting)|Создание нативных функция]] - Разоблачение API других плагинов.
*[[Function Calling API (SourceMod Scripting)|API вызова функция]] - Вызовы внешних функций.
*[[Optional Requirements (SourceMod Scripting)|Необязательные требования]] - Управление зависимостями.
*[[SDKTools (SourceMod Scripting)|SDKTools]] - Использование мощного SDK уровней абстракции.
*[[TempEnts (SourceMod SDKTools)|Временные объекты]] - Использование временных объектов.

===Информация===
*[[Deprecation Schedule (SourceMod Scripting)|Deprecation Schedule]] - Which functions are getting removed.
*[[Форматирование текста (SourceMod Scripting)|Ru:Format Class Functions]] - Всё про форматирование текста.
*[[Handles (SourceMod Scripting)|Handles]] - Обзор Handle и несколько распространённых типов.
*[[Optimizing Plugins (SourceMod Scripting)|Optimizing Plugins]] - Советы по оптимизации.
*[[Tags (Scripting)|Tags]] - Всё о тэгах.
*[[Vectors Explained (Scripting)|Vectors Explained]] - Объяснение типов Вектора.

===Дополнительные средства===
*[http://docs.sourcemod.net/api API Reference] - API по кодированию на SourcePawn.
*[[Entity Properties]] - Explanation of Source entity properties.
*[[Game Events (Source)|Game Events]] - Список игровых событий для популярных модификаций.
*[[Mod TempEnt List (Source)|Temp Entity Lists]] - Список временных объектов для популярных модификаций.
*[[SourceMod Profiler]] - Отслеживание производительности и оптимизации.

Ru:Commands (SourceMod Scripting)

2021-02-11T09:36:39Z

HolyHender: /* Добавление команд */

[[SourceMod]] позволяет создать вам консольные команды, похожие на [[AMX Mod X]]. Есть два главных вида консольных команд:
*'''Серверные команды''' - Срабатывают с одним из следующих способов ввода:
**С помощью консоли сервера
**С помощью удаленной консоли (RCON)
**Функция ServerCommand(), либо из SourceMod либо [[Half-Life 2]] движка
*'''Консольные команды''' - Срабатывают с одним из следующих способов ввода:
**С помощью консоли клиента
**Любой из методов ввода серверных команд

Для серверных команд не существует клиентского индекса. Для консольных/клиентских команд, существует клиентский индекс, но он может быть 0, чтобы показать, что команда с сервера.

Обратите внимание, что кнопка-бинд "commands", такие как +attack и +duck, они не консольные команды. Эти команды отдельно передаются, посколько они отдельно привязаны.

=Серверные команды=
Как отмечалось выше, серверные команды срабатывают через консоль сервера, будь то удалённую, локальную, или через движок Source. Индекс клиента не связан с серверными командами.

Серверные команды регистрируются через <tt>RegServerCmd()</tt> функцию, расположенную в <tt>console.inc</tt>. При регистрации команды, вы можете записать поверх существующей команды, и таким образом, возвращаемое значение становится важным.
*<tt>Plugin_Continue</tt> - The original server command will be processed, if there was one. Если серверная команда создана плагином, здесь не будет эффекта.
*<tt>Plugin_Handled</tt> - The original server command will not be processed, if there was one. Если серверная команда создана плагином, здесь не будет эффекта.
*<tt>Plugin_Stop</tt> - The original server command will not be processed, if there was one. Additionally, no further hooks will be called for this command until it is fired again.

==Добавление серверных команд==
Допустим, мы хотим добавить тестовую команду, чтобы показать как Half-Life 2 вычисляет аргументы команды. Вот возможная реализация:
<pawn>
public void OnPluginStart()
{
RegServerCmd("test_command", Command_Test)
}

public Action Command_Test(int args)
{
char arg[128]
char full[256]

GetCmdArgString(full, sizeof(full))

PrintToServer("Строка аргумента: %s", full)
PrintToServer("Количество аргументов: %d", args)
for (int i = 1; i <= args; i++)
{
GetCmdArg(i, arg, sizeof(arg))
PrintToServer("Аргумент %d: %s", i, arg)
}
}
</pawn>

==Блокирование серверных команд==
Допустим мы хотим отключить "kickid" команду на сервере. Нет причин делать это, но для примера сойдет:
<pawn>
public void OnPluginStart()
{
RegServerCmd("kickid", Command_KickId);
}

public Action Command_Kickid(int args)
{
return Plugin_Handled;
}
</pawn>

=Консольные команды=
В отличие от серверных команд, консольные могут быть вызваны, как сервером, так и клиентом, так что callback функция получает клиентский индекс, а также количество аргументов. Если сервер использовал команду, клиентский индекс будет 0.

When returning the <tt>Action</tt> from the callback, the following effects will happen:
*<tt>Plugin_Continue</tt>: The original functionality of the command (if any) will still be processed. If there was no original functionality, the client will receive "Unknown command" in their console.
*<tt>Plugin_Handled</tt>: The original functionality of the command (if any) will be blocked. If there was no functionality originally, this prevents clients from seeing "Unknown command" in their console.
*<tt>Plugin_Stop</tt>: Same as <tt>Plugin_Handled</tt>, except that this will be the last hook called.

Обратите внимание, в отличие от AMX Mod X, SourceMod не сможет зарегистрировать командные фильтры. т.е. нет эквивалента этой команды:
<pawn>register_clcmd("say /ff", "Command_SayFF");</pawn>

Это было удаленно, чтобы сделать наш код проще и быстрее. Написание такого же функционала легче и показано ниже.

==Добавление команд==
Создать клиентские команды очень просто. Давайте переделаем нашу тест команду, чтобы можно было отобразить информацию о клиенте.

<pawn>public void OnPluginStart()
{
RegConsoleCmd("test_command", Command_Test);
}

public Action Command_Test(int client, int args)
{
char arg[128], full[256];

GetCmdArgString(full, sizeof(full))

if (client)
{
char name[32];
GetClientName(client, name, sizeof(name));
PrintToServer("Команда от клиента: %s", name);
}
else
{
PrintToServer("Команда от сервера.");
}

PrintToServer("Строка аргументов: %s", full);
PrintToServer("Количество аргументов: %d", args);

for (int i = 1; i <= args; i++)
{
GetCmdArg(i, arg, sizeof(arg));
PrintToServer("Аргумент %d: %s", i, arg);
}
}</pawn>

==Захват команд==
Пример: захват типичной команды say. Let's say we want to tell players whether FF is enabled when they say '/ff' in game.

Before we implement this, a common point of confusion with the 'say' command is that Half-Life 2 (and Half-Life 1), by default, send it with the text in one big quoted string. This means if you say "I like hot dogs," your command will be broken down as such:
*Argument string: "I like hot dogs"
*Argument count: 1
*Argument #1: I like hot dogs

However, if a player types this in their console: <tt>say I like yams</tt>, it will be broken up as:
*Argument string: I like yams
*Argument count: 3
*Argument #1: I
*Argument #2: like
*Argument #3: yams

Thus, to take into account both of these situations, we are going to use <tt>GetCmdArgString</tt> and manually parse the input.

<pawn>public void OnPluginStart()
{
RegConsoleCmd("say", Command_Say)
}

public Action Command_Say(int client, int args)
{
char text[192]
GetCmdArgString(text, sizeof(text))

int startidx = 0
if (text[0] == '"')
{
startidx = 1
/* Лишаем ковычки от окончания, если есть */
int len = strlen(text);
if (text[len-1] == '"')
{
text[len-1] = '\0'
}
}

if (StrEqual(text[startidx], "/ff"))
{
Handle ff = FindConVar("mp_friendlyfire")
if (GetConVarInt(ff))
{
PrintToConsole(client, "Огонь по товарищам включен.")
} else {
PrintToConsole(client, "Огонь по товарищам выключен.")
}
/* Блокирование сообщения клиента от вещания */
return Plugin_Handled
}

/* Пусть работает как обычно */
return Plugin_Continue
}</pawn>

==Создание Админской команды==
Давайте создадим простую админскую команду, которая позволяет кикнуть игрока, по его полному имени.

<pawn>public void OnPluginStart()
{
RegAdminCmd("admin_kick",
Command_Kick,
ADMFLAG_KICK,
"Кикает игрока по нику")
}

public Action Command_Kick(int client, int args)
{
if (args < 1)
{
PrintToConsole(client, "Использование: admin_kick <ник>")
return Plugin_Handled
}

char name[32]
int maxplayers, target = -1
GetCmdArg(1, name, sizeof(name))

maxplayers = GetMaxClients()
for (int i = 1; i <= maxplayers; i++)
{
if (!IsClientConnected(i))
{
continue
}
char other[32]
GetClientName(i, other, sizeof(other))
if (StrEqual(name, other))
{
target = i
}
}

if (target == -1)
{
PrintToConsole(client, "Не могу найти игрока с ником: \"%s\"", name)
return Plugin_Handled
}

ServerCommand("kickid %d", GetClientUserId(target));

return Plugin_Handled
}</pawn>

==Иммунитет==
В нашем прошлом примере, мы не сделали иммунитет. Иммунитет является гораздно сложной системой в SourceMod, чем это было в AMX Mod X, и не существует просто флага, чтобы обозначить его. Вместо, этого существует две функции:
*<tt>CanAdminTarget</tt>: Проверяет исходные значения AdminId для иммунитета.
*<tt>CanUserTarget</tt>: Проверяет внутриигровых клиентов для иммунитета.

While immunity is generally tested ''player versus player'', it is possible you might want to check for immunity and not have a targetting client. While there is no convenience function for this yet, a good idea might be to check for either ''default'' or ''global'' immunity on the player's groups (these can be user-defined for non-player targeted scenarios).

When checking for immunity, the following heuristics are performed in this exact order:
<ol><li>If the targeting AdminId is <tt>INVALID_ADMIN_ID</tt>, targeting fails.</li>
<li>If the targetted AdminId is <tt>INVALID_ADMIN_ID</tt>, targeting succeeds.</li>
<li>If the targeting admin has <tt>Admin_Root</tt> (<tt>ADMFLAG_ROOT</tt>), targeting succeeds.</li>
<li>If the targetted admin has global immunity, targeting fails.</li>
<li>If the targetted admin has default immunity, and the targeting admin belongs to no groups, targeting fails.</li>
<li>If the targetted admin has specific immunity from the targeting admin via group immunities, targeting fails.</li>
<li>If no conclusion is reached via the previous steps, targeting succeeds.</li>
</ol>

So, how can we adapt our function about to use immunity?

<pawn>public Action Command_Kick(int client, int args)
{
if (args < 1)
{
PrintToConsole(client, "Использование: admin_kick <ник>")
return Plugin_Handled
}

char name[32]
int maxplayers, target = -1
GetCmdArg(1, name, sizeof(name))

maxplayers = GetMaxClients()
for (int i = 1; i <= maxplayers; i++)
{
if (!IsClientConnected(i))
{
continue
}
char other[32]
GetClientName(i, other, sizeof(other))
if (StrEqual(name, other))
{
target = i
}
}

if (target == -1)
{
PrintToConsole(client, "Не могу найти игрока с ником: \"%s\"", name)
return Plugin_Handled
}

if (!CanUserTarget(client, target))
{
PrintToConsole(client, "Вы не можете использовать этого клиента как цель.")
return Plugin_Handled
}

ServerCommand("kickid %d", GetClientUserId(target))

return Plugin_Handled
}</pawn>

=Только клиентские команды=
SourceMod exposes a forward that is called whenever a client executes any command string in their console, called <tt>OnClientCommand</tt>. An example of this looks like:

<pawn>public Action OnClientCommand(int client, int args)
{
char cmd[16]
GetCmdArg(0, cmd, sizeof(cmd)); /* Получаем название команды */

if (StrEqual(cmd, "test_command"))
{
/* Получаем клиентскую команду! Блокируем её... */
return Plugin_Handled
}

return Plugin_Continue
}</pawn>

It is worth noting that not everything a client sends will be available through this command. Command registered via external sources in C++ may not be available, especially if they are created via <tt>CON_COMMAND</tt> in the game mod itself. For example, "say" is usually implemented this way, because it can be used by both clients and the server, and thus it does not channel through this forward.

=Чат триггеры=
SourceMod будет автоматически создавать чат триггеры для каждой команды, которую вы сделали (по ревизии 900). Для примера, если вы создали консольную команду "sm_megaslap", администраторы смогут набрать ее и в <tt>say</tt>/<tt>say_team</tt> режимах:
<pre>!sm_megaslap
!megaslap
/sm_megaslap
/megaslap</pre>

SourceMod будет выполнять эту команду и ее аргументы, как если бы она пришла из консоли клиента.
*"<tt>!</tt>" является ''публичным'' триггером по умолчанию (<tt>PublicChatTrigger</tt> в <tt>configs/core.cfg</tt>) и ваша команда будет отображена всем клиентам.
*"<tt>/</tt>" является ''скрытым'' триггером по умолчанию (<tt>SilentChatTrigger</tt> в <tt>configs/core.cfg</tt>) и ваша команда не будет показана остальным клиентам

SourceMod будет исполнять только те команды, которые зарегистрированы с <tt>RegConsoleCmd</tt> или <tt>RegAdminCmd</tt>, и только если эти команды уже не используются Half-life 2 движком или другим игровым модом. Если команда идет с префиксом "sm_", то "sm_" можно исключить, из написания в чате.

Консольные команды, которые хотят поддерживать использование в качестве триггера чата, не должны использовать нативы вроде <tt>PrintTo*</tt>. Вместо этого, они должны использовать <tt>ReplyToCommand()</tt>, которая будет автоматически печатать ваше сообщение либо в виде сообщения чата либо в виде консоли клиента, в зависимости от источника команды.

[[Category:Ru:SourceMod Scripting]]

Ru:Commands (SourceMod Scripting)

2021-02-11T09:35:21Z

HolyHender: /* Блокирование серверных команд */

[[SourceMod]] позволяет создать вам консольные команды, похожие на [[AMX Mod X]]. Есть два главных вида консольных команд:
*'''Серверные команды''' - Срабатывают с одним из следующих способов ввода:
**С помощью консоли сервера
**С помощью удаленной консоли (RCON)
**Функция ServerCommand(), либо из SourceMod либо [[Half-Life 2]] движка
*'''Консольные команды''' - Срабатывают с одним из следующих способов ввода:
**С помощью консоли клиента
**Любой из методов ввода серверных команд

Для серверных команд не существует клиентского индекса. Для консольных/клиентских команд, существует клиентский индекс, но он может быть 0, чтобы показать, что команда с сервера.

Обратите внимание, что кнопка-бинд "commands", такие как +attack и +duck, они не консольные команды. Эти команды отдельно передаются, посколько они отдельно привязаны.

=Серверные команды=
Как отмечалось выше, серверные команды срабатывают через консоль сервера, будь то удалённую, локальную, или через движок Source. Индекс клиента не связан с серверными командами.

Серверные команды регистрируются через <tt>RegServerCmd()</tt> функцию, расположенную в <tt>console.inc</tt>. При регистрации команды, вы можете записать поверх существующей команды, и таким образом, возвращаемое значение становится важным.
*<tt>Plugin_Continue</tt> - The original server command will be processed, if there was one. Если серверная команда создана плагином, здесь не будет эффекта.
*<tt>Plugin_Handled</tt> - The original server command will not be processed, if there was one. Если серверная команда создана плагином, здесь не будет эффекта.
*<tt>Plugin_Stop</tt> - The original server command will not be processed, if there was one. Additionally, no further hooks will be called for this command until it is fired again.

==Добавление серверных команд==
Допустим, мы хотим добавить тестовую команду, чтобы показать как Half-Life 2 вычисляет аргументы команды. Вот возможная реализация:
<pawn>
public void OnPluginStart()
{
RegServerCmd("test_command", Command_Test)
}

public Action Command_Test(int args)
{
char arg[128]
char full[256]

GetCmdArgString(full, sizeof(full))

PrintToServer("Строка аргумента: %s", full)
PrintToServer("Количество аргументов: %d", args)
for (int i = 1; i <= args; i++)
{
GetCmdArg(i, arg, sizeof(arg))
PrintToServer("Аргумент %d: %s", i, arg)
}
}
</pawn>

==Блокирование серверных команд==
Допустим мы хотим отключить "kickid" команду на сервере. Нет причин делать это, но для примера сойдет:
<pawn>
public void OnPluginStart()
{
RegServerCmd("kickid", Command_KickId);
}

public Action Command_Kickid(int args)
{
return Plugin_Handled;
}
</pawn>

=Консольные команды=
В отличие от серверных команд, консольные могут быть вызваны, как сервером, так и клиентом, так что callback функция получает клиентский индекс, а также количество аргументов. Если сервер использовал команду, клиентский индекс будет 0.

When returning the <tt>Action</tt> from the callback, the following effects will happen:
*<tt>Plugin_Continue</tt>: The original functionality of the command (if any) will still be processed. If there was no original functionality, the client will receive "Unknown command" in their console.
*<tt>Plugin_Handled</tt>: The original functionality of the command (if any) will be blocked. If there was no functionality originally, this prevents clients from seeing "Unknown command" in their console.
*<tt>Plugin_Stop</tt>: Same as <tt>Plugin_Handled</tt>, except that this will be the last hook called.

Обратите внимание, в отличие от AMX Mod X, SourceMod не сможет зарегистрировать командные фильтры. т.е. нет эквивалента этой команды:
<pawn>register_clcmd("say /ff", "Command_SayFF");</pawn>

Это было удаленно, чтобы сделать наш код проще и быстрее. Написание такого же функционала легче и показано ниже.

==Добавление команд==
Создать клиентские команды очень просто. Давайте переделаем нашу тест команду, чтобы можно было отобразить информацию о клиенте.

<pawn>public void OnPluginStart()
{
RegConsoleCmd("test_command", Command_Test)
}

public Action Command_Test(int client, int args)
{
char arg[128]
char full[256]

GetCmdArgString(full, sizeof(full))

if (client)
{
char name[32]
GetClientName(client, name, sizeof(name))
PrintToServer("Команда от клиента: %s", name)
} else {
PrintToServer("Команда от сервера.")
}

PrintToServer("Строка аргументов: %s", full)
PrintToServer("Количество аргументов: %d", args)
for (int i = 1; i <= args; i++)
{
GetCmdArg(i, arg, sizeof(arg))
PrintToServer("Аргумент %d: %s", i, arg)
}
}</pawn>

==Захват команд==
Пример: захват типичной команды say. Let's say we want to tell players whether FF is enabled when they say '/ff' in game.

Before we implement this, a common point of confusion with the 'say' command is that Half-Life 2 (and Half-Life 1), by default, send it with the text in one big quoted string. This means if you say "I like hot dogs," your command will be broken down as such:
*Argument string: "I like hot dogs"
*Argument count: 1
*Argument #1: I like hot dogs

However, if a player types this in their console: <tt>say I like yams</tt>, it will be broken up as:
*Argument string: I like yams
*Argument count: 3
*Argument #1: I
*Argument #2: like
*Argument #3: yams

Thus, to take into account both of these situations, we are going to use <tt>GetCmdArgString</tt> and manually parse the input.

<pawn>public void OnPluginStart()
{
RegConsoleCmd("say", Command_Say)
}

public Action Command_Say(int client, int args)
{
char text[192]
GetCmdArgString(text, sizeof(text))

int startidx = 0
if (text[0] == '"')
{
startidx = 1
/* Лишаем ковычки от окончания, если есть */
int len = strlen(text);
if (text[len-1] == '"')
{
text[len-1] = '\0'
}
}

if (StrEqual(text[startidx], "/ff"))
{
Handle ff = FindConVar("mp_friendlyfire")
if (GetConVarInt(ff))
{
PrintToConsole(client, "Огонь по товарищам включен.")
} else {
PrintToConsole(client, "Огонь по товарищам выключен.")
}
/* Блокирование сообщения клиента от вещания */
return Plugin_Handled
}

/* Пусть работает как обычно */
return Plugin_Continue
}</pawn>

==Создание Админской команды==
Давайте создадим простую админскую команду, которая позволяет кикнуть игрока, по его полному имени.

<pawn>public void OnPluginStart()
{
RegAdminCmd("admin_kick",
Command_Kick,
ADMFLAG_KICK,
"Кикает игрока по нику")
}

public Action Command_Kick(int client, int args)
{
if (args < 1)
{
PrintToConsole(client, "Использование: admin_kick <ник>")
return Plugin_Handled
}

char name[32]
int maxplayers, target = -1
GetCmdArg(1, name, sizeof(name))

maxplayers = GetMaxClients()
for (int i = 1; i <= maxplayers; i++)
{
if (!IsClientConnected(i))
{
continue
}
char other[32]
GetClientName(i, other, sizeof(other))
if (StrEqual(name, other))
{
target = i
}
}

if (target == -1)
{
PrintToConsole(client, "Не могу найти игрока с ником: \"%s\"", name)
return Plugin_Handled
}

ServerCommand("kickid %d", GetClientUserId(target));

return Plugin_Handled
}</pawn>

==Иммунитет==
В нашем прошлом примере, мы не сделали иммунитет. Иммунитет является гораздно сложной системой в SourceMod, чем это было в AMX Mod X, и не существует просто флага, чтобы обозначить его. Вместо, этого существует две функции:
*<tt>CanAdminTarget</tt>: Проверяет исходные значения AdminId для иммунитета.
*<tt>CanUserTarget</tt>: Проверяет внутриигровых клиентов для иммунитета.

While immunity is generally tested ''player versus player'', it is possible you might want to check for immunity and not have a targetting client. While there is no convenience function for this yet, a good idea might be to check for either ''default'' or ''global'' immunity on the player's groups (these can be user-defined for non-player targeted scenarios).

When checking for immunity, the following heuristics are performed in this exact order:
<ol><li>If the targeting AdminId is <tt>INVALID_ADMIN_ID</tt>, targeting fails.</li>
<li>If the targetted AdminId is <tt>INVALID_ADMIN_ID</tt>, targeting succeeds.</li>
<li>If the targeting admin has <tt>Admin_Root</tt> (<tt>ADMFLAG_ROOT</tt>), targeting succeeds.</li>
<li>If the targetted admin has global immunity, targeting fails.</li>
<li>If the targetted admin has default immunity, and the targeting admin belongs to no groups, targeting fails.</li>
<li>If the targetted admin has specific immunity from the targeting admin via group immunities, targeting fails.</li>
<li>If no conclusion is reached via the previous steps, targeting succeeds.</li>
</ol>

So, how can we adapt our function about to use immunity?

<pawn>public Action Command_Kick(int client, int args)
{
if (args < 1)
{
PrintToConsole(client, "Использование: admin_kick <ник>")
return Plugin_Handled
}

char name[32]
int maxplayers, target = -1
GetCmdArg(1, name, sizeof(name))

maxplayers = GetMaxClients()
for (int i = 1; i <= maxplayers; i++)
{
if (!IsClientConnected(i))
{
continue
}
char other[32]
GetClientName(i, other, sizeof(other))
if (StrEqual(name, other))
{
target = i
}
}

if (target == -1)
{
PrintToConsole(client, "Не могу найти игрока с ником: \"%s\"", name)
return Plugin_Handled
}

if (!CanUserTarget(client, target))
{
PrintToConsole(client, "Вы не можете использовать этого клиента как цель.")
return Plugin_Handled
}

ServerCommand("kickid %d", GetClientUserId(target))

return Plugin_Handled
}</pawn>

=Только клиентские команды=
SourceMod exposes a forward that is called whenever a client executes any command string in their console, called <tt>OnClientCommand</tt>. An example of this looks like:

<pawn>public Action OnClientCommand(int client, int args)
{
char cmd[16]
GetCmdArg(0, cmd, sizeof(cmd)); /* Получаем название команды */

if (StrEqual(cmd, "test_command"))
{
/* Получаем клиентскую команду! Блокируем её... */
return Plugin_Handled
}

return Plugin_Continue
}</pawn>

It is worth noting that not everything a client sends will be available through this command. Command registered via external sources in C++ may not be available, especially if they are created via <tt>CON_COMMAND</tt> in the game mod itself. For example, "say" is usually implemented this way, because it can be used by both clients and the server, and thus it does not channel through this forward.

=Чат триггеры=
SourceMod будет автоматически создавать чат триггеры для каждой команды, которую вы сделали (по ревизии 900). Для примера, если вы создали консольную команду "sm_megaslap", администраторы смогут набрать ее и в <tt>say</tt>/<tt>say_team</tt> режимах:
<pre>!sm_megaslap
!megaslap
/sm_megaslap
/megaslap</pre>

SourceMod будет выполнять эту команду и ее аргументы, как если бы она пришла из консоли клиента.
*"<tt>!</tt>" является ''публичным'' триггером по умолчанию (<tt>PublicChatTrigger</tt> в <tt>configs/core.cfg</tt>) и ваша команда будет отображена всем клиентам.
*"<tt>/</tt>" является ''скрытым'' триггером по умолчанию (<tt>SilentChatTrigger</tt> в <tt>configs/core.cfg</tt>) и ваша команда не будет показана остальным клиентам

SourceMod будет исполнять только те команды, которые зарегистрированы с <tt>RegConsoleCmd</tt> или <tt>RegAdminCmd</tt>, и только если эти команды уже не используются Half-life 2 движком или другим игровым модом. Если команда идет с префиксом "sm_", то "sm_" можно исключить, из написания в чате.

Консольные команды, которые хотят поддерживать использование в качестве триггера чата, не должны использовать нативы вроде <tt>PrintTo*</tt>. Вместо этого, они должны использовать <tt>ReplyToCommand()</tt>, которая будет автоматически печатать ваше сообщение либо в виде сообщения чата либо в виде консоли клиента, в зависимости от источника команды.

[[Category:Ru:SourceMod Scripting]]

Category:Ru:SourceMod Scripting

2021-02-11T09:34:53Z

HolyHender: /* Информация */

Эта категория содержит статьи о написании скриптов под SourceMod с использованием SourcePawn.

===Введение===
*[[Ru:Introduction to SourcePawn|Ru:Introduction to SourcePawn]] - Введение в SourcePawn. Обучение синтаксису языка.
*[[Ru:Introduction to SourceMod Plugins|Ru:Introduction to SourceMod Plugins]] - Введение в SourceMod плагины. Создаем Ваш "первый плагин".
*[http://docs.sourcemod.net/api API Reference] - Поиск сценариев в справочнике API.

===Основной API===
*[[Ru:AutoConfigs (SourceMod Scripting)|Автоконфиги]] - Автоматическое создание .cfg файлов.
*[[Ru:Commands (SourceMod Scripting)|Команды]] - Консольные команды/ввод.
*[[Ru:ConVars (SourceMod Scripting)|Консольные переменные (ConVar)]] - Консольные переменные (cvars).
*[[Ru:Events (SourceMod Scripting)|События (Events)]] - Игровые события Half-Life.
*[[Ru:KeyValues (SourceMod Scripting)|Структура Ключ-Значение (KeyValues)]] - KeyValues анализ/запись файла.
*[[Ru:Menu API (SourceMod)|Меню]] - Создание и отображение меню.
*[[Ru:SQL (SourceMod Scripting)|SQL]] - Использование баз данных (MySQL, SQLite).
*[[Ru:Timers (SourceMod Scripting)|Таймеры (Timers)]] - Вызов таймеров.
*[[Ru:DataPacks|Пакеты данных (DataPack)]] - Создание и управление DataPack.
*[[Ru:Translations (SourceMod Scripting)|Переводы]] - Создание локализаций.

===Продвинутый API===
*[[Admin API (SourceMod)|API администрирования]] - Использование кэша администратора.
*[[Admin Menu (SourceMod Scripting)|API админского меню]] - Закрепление в меню администратора.
*[[Creating Natives (SourceMod Scripting)|Создание нативных функция]] - Разоблачение API других плагинов.
*[[Function Calling API (SourceMod Scripting)|API вызова функция]] - Вызовы внешних функций.
*[[Optional Requirements (SourceMod Scripting)|Необязательные требования]] - Управление зависимостями.
*[[SDKTools (SourceMod Scripting)|SDKTools]] - Использование мощного SDK уровней абстракции.
*[[TempEnts (SourceMod SDKTools)|Временные объекты]] - Использование временных объектов.

===Информация===
*[[Deprecation Schedule (SourceMod Scripting)|Deprecation Schedule]] - Which functions are getting removed.
*[[Форматирование текста (SourceMod Scripting)|Ru:Format Class Functions]] - Всё про форматирование текста.
*[[Handles (SourceMod Scripting)|Handles]] - Обзор Handle и несколько распространённых типов.
*[[Оптимизация плагина (SourceMod Scripting)|Optimizing Plugins]] - Советы по оптимизации.
*[[Tags (Scripting)|Tags]] - Всё о тэгах.
*[[Vectors Explained (Scripting)|Vectors Explained]] - Объяснение типов Вектора.

===Дополнительные средства===
*[http://docs.sourcemod.net/api API Reference] - API по кодированию на SourcePawn.
*[[Entity Properties]] - Explanation of Source entity properties.
*[[Game Events (Source)|Game Events]] - Список игровых событий для популярных модификаций.
*[[Mod TempEnt List (Source)|Temp Entity Lists]] - Список временных объектов для популярных модификаций.
*[[SourceMod Profiler]] - Отслеживание производительности и оптимизации.

Category:Ru:SourceMod Scripting

2021-02-08T18:01:29Z

HolyHender: /* Основной API */

Эта категория содержит статьи о написании скриптов под SourceMod с использованием SourcePawn.

===Введение===
*[[Ru:Introduction to SourcePawn|Ru:Introduction to SourcePawn]] - Введение в SourcePawn. Обучение синтаксису языка.
*[[Ru:Introduction to SourceMod Plugins|Ru:Introduction to SourceMod Plugins]] - Введение в SourceMod плагины. Создаем Ваш "первый плагин".
*[http://docs.sourcemod.net/api API Reference] - Поиск сценариев в справочнике API.

===Основной API===
*[[Ru:AutoConfigs (SourceMod Scripting)|Автоконфиги]] - Автоматическое создание .cfg файлов.
*[[Ru:Commands (SourceMod Scripting)|Команды]] - Консольные команды/ввод.
*[[Ru:ConVars (SourceMod Scripting)|Консольные переменные (ConVar)]] - Консольные переменные (cvars).
*[[Ru:Events (SourceMod Scripting)|События (Events)]] - Игровые события Half-Life.
*[[Ru:KeyValues (SourceMod Scripting)|Структура Ключ-Значение (KeyValues)]] - KeyValues анализ/запись файла.
*[[Ru:Menu API (SourceMod)|Меню]] - Создание и отображение меню.
*[[Ru:SQL (SourceMod Scripting)|SQL]] - Использование баз данных (MySQL, SQLite).
*[[Ru:Timers (SourceMod Scripting)|Таймеры (Timers)]] - Вызов таймеров.
*[[Ru:DataPacks|Пакеты данных (DataPack)]] - Создание и управление DataPack.
*[[Ru:Translations (SourceMod Scripting)|Переводы]] - Создание локализаций.

===Продвинутый API===
*[[Admin API (SourceMod)|API администрирования]] - Использование кэша администратора.
*[[Admin Menu (SourceMod Scripting)|API админского меню]] - Закрепление в меню администратора.
*[[Creating Natives (SourceMod Scripting)|Создание нативных функция]] - Разоблачение API других плагинов.
*[[Function Calling API (SourceMod Scripting)|API вызова функция]] - Вызовы внешних функций.
*[[Optional Requirements (SourceMod Scripting)|Необязательные требования]] - Управление зависимостями.
*[[SDKTools (SourceMod Scripting)|SDKTools]] - Использование мощного SDK уровней абстракции.
*[[TempEnts (SourceMod SDKTools)|Временные объекты]] - Использование временных объектов.

===Информация===
*[[Deprecation Schedule (SourceMod Scripting)|Deprecation Schedule]] - Which functions are getting removed.
*[[Ru:Format Class Functions (SourceMod Scripting)|Ru:Format Class Functions]] - Всё про форматирование текста.
*[[Handles (SourceMod Scripting)|Handles]] - Обзор Handle и несколько распространённых типов.
*[[Optimizing Plugins (SourceMod Scripting)|Optimizing Plugins]] - Советы по оптимизации.
*[[Tags (Scripting)|Tags]] - Всё о тэгах.
*[[Vectors Explained (Scripting)|Vectors Explained]] - Объяснение типов Вектора.

===Дополнительные средства===
*[http://docs.sourcemod.net/api API Reference] - API по кодированию на SourcePawn.
*[[Entity Properties]] - Explanation of Source entity properties.
*[[Game Events (Source)|Game Events]] - Список игровых событий для популярных модификаций.
*[[Mod TempEnt List (Source)|Temp Entity Lists]] - Список временных объектов для популярных модификаций.
*[[SourceMod Profiler]] - Отслеживание производительности и оптимизации.

Menu API (SourceMod)=ru

2021-02-08T17:39:06Z

HolyHender: /* Простое меню */

SourceMod обладает большим API для создания и отображений меню для клиентов. В отличии от AMX Mod X, API SourceMod'a обладает широким функционалом. Меню базируются на обратных вызовах (callbacks), которые гарантированно будут вызваны.

Для C++, API меню может быть найдено в <tt>public/IMenuManager.h</tt>. Для SourcePawn - <tt>scripting/include/menus.inc</tt>.

=Объекты=
Система меню SourceMod основана на объектно ориентированной иерархии. Понимание этой иерархии, даже для скриптинга, является ключевым моментом для эффективного использования меню.

==Стили==
Высший уровень объектов называется ''MenuStyle'' (<tt>IMenuStyle</tt> в C++). Стили описывают уникальную систему меню. Всего есть два стиля, встроенных в SourceMod:
*Valve Styly, так же называемым "ESC" меню; 8 пунктов на странице, нельзя добавить текст без занятия слота или спрятать (отключить) текст.
*Radio Style, так же называемый "AMX" меню; 10 пунктов на странице, можно добавить любой текст.

Каждый MenuStyle обладает своими правилами и свойствами. Вы можете считать, что каждый из них существует на раздельных "каналах". Например, два разных меню могут быть на экране игрока, будучи Valve и Radio меню одновременно, и SourceMod сможет обработать их обоих без всяких проблем. Это всё возможно благодаря тому, что каждый стиль отслеживает свои меню отдельно.

==Панели==
Меню низшего уровня называется ''Панелью'' (<tt>IMenuPanel</tt> в C++). Панель - один ''''кусок'''' текста. Пункты и текст могут добавляться к панели столько раз, сколько поддерживает родительский стиль. Например, Valve стиль не поддерживает отображение текста без занятия слота или отключенных пунктов. Однако с Radio стилем панели это становится возможным, и вы можете отобразить большое количество текста так, как вам это захочется.

Панель считается временным объектом. Она создается, рендерится, отображается, и затем удаляется. Хотя она может быть сохранена на неопределенное время, если в этом есть необходимость.

Правила и ограничения Vavle стиля:
*Максимум пунктов на странице: 8
*Отключенный текст не отображается.
*Нельзя написать текст, не заняв слота.
*Пробелы не добавляются к пробелам\новым линиям, добавляя чувство "ограниченности".
*Пользователь должен нажать "ESC" или быть в своей консоли, чтобы увидеть меню.

Правила и ограничения Radio стиля:
*10 пунктов на странице
*Заглавия белые; пункты желтые, если не отключены. Если отключены, то белого цвета.
*Нулевой элемент всегда белый. Для согласованности это значит, что навигационное управление всегда белое и находится в следующей секции, и просто не отрисовывается, если отсутствует.

==Меню==
Наконец, есть просто ''Меню'' (<tt>IBaseMenu</tt> in C++). Это вспомогательный объект, созданный для хранения базированных на меню выбираемых пунктов. В отличии от низкоуровневых панелей, меню содержит '''пункты''', и может содержать только те пункты, которые можно выбрать (т.е. занимающие слоты). Они делятся на две категории:
*Не нумерованные: эти меню могут иметь определенное число пунктов, и не имеют навигационных опций, кроме кнопки "Выход", которая всегда добавляется на последнюю позицию, поддерживаемую стилем.
**Valve Стиль: максимум пунктов: 8
**Radio Стиль: максимум пунктов: 10
*Нумерованные: такие меню могут содержать сколь угодно пунктов. Во время отображения будет показано только определенное число пунктов. Автоматически будут добавлены навигационные пункты, таким образом, игроки легко могут возвращаться назад и вперед к определенным "страницам" пунктов меню.
**"Назад" всегда отображается как первый навигационный пункт, третий с конца поддерживаемых позиций. Не будет добавлен, если меню содержит только одну страницу. Если нет никаких предыдущих страниц, текст никогда не будет отображен, ни в каком стиле. Если возможно, то меню будет дополнено необходимыми пробелами.
***Valve Стиль, позиция: 6
***Radio Стиль, позиция: 8
**"Вперед" всегда отображается как второй навигационный пункт, второй с конца из доступных позиций. Не отображается, если меню состоит из одной страницы. Если нет следующих страниц, то текс не будет отображен при любом стиле. Если возможно, то меню будет дополнено необходимыми пробелами.
***Valve Стиль, позиция: 7
***Radio Стиль, позиция: 9
**"Выход" отображается, если у меню включена кнопка "выход". Всегда занимает последнюю из возможных позиций
***Valve Стиль, позиция: 8
***Radio Стиль, позиция: 10

Цель меню - упростить процедуру хранения, отображения, и вычисления выбранного пункта. Таким образом, меню не позволяет добавлять пустой текст, так как это значительно усложняет алгоритм отображения.

Внутренне, меню отображается через ''RenderMenu'' алогритм. Этот алгоритм создает временную панель и заполняет её пунктами из меню. Эта панель отображается клиенту. Алгоритм пытается создать свободное перемещение по всем меню, и по всем стилям. Таким образом, все меню отображаются через <tt>IBaseMenu</tt> класс, или <tt>Menu</tt> дескрипторы (Handles), и будет выглядеть и действовать так же, как и меню API, основанное на панельном API.

=Обратные вызовы (callbacks)=
==Краткий обзор==
Меню базируются на системе обратных вызовов. Каждый обратный вызов предоставляет собой действие, которые происходят во время ''цикла отображения меню''. Цикл состоит из множества уведомлений:
*Начало уведомления.
**Уведомление об отображении, если меню может быть отображено клиенту.
**Уведомление о выборе пункта или кнопки отмены.
*Конец уведомления.

Так как ''End'' обозначает конец полного цикла отображения, то обычно его используют для уничтожения временных меню.

==Спецификация==
Детальное объяснение этих событий ниже. Для C++, <tt>IBaseMenu</tt> указатель всегда доступен. Для SourcePawn, <tt>Menu</tt> хандл и <tt>MenuAction</tt> всегда установлены в <tt>MenuHandler</tt> callback. В отличии от C++, SourcePawn API позволяет вызвать лишь некоторые действия, если они были запрошены во время создания меню. Это сделано в целях оптимизации. Однако, эти действия не могут быть не вызваны.

*'''Start'''. Меню было признано. Это не означает, что меню будет отображено; однако, это гарантирует, что событие "OnMenuEnd" будет вызвано.
**<tt>OnMenuStart()</tt> в C++.
**<tt>MenuAction_Start</tt> в SourcePawn. Не будет вызвано, если не было запрошено.
***<tt>param1</tt>: Игнорируется (всегда 0).
***<tt>param2</tt>: Игнорируется (всегда 0).
*'''Display'''. Меню отобразилось клиенту.
**<tt>OnMenuDisplay()</tt> в C++. <tt>IMenuPanel</tt> доступны указатель и индекс клиента.
**<tt>MenuAction_Display</tt> в SourcePawn. Не будет вызвано, если не было запрошено.
***<tt>param1</tt>: Индекс клиента.
***<tt>param2</tt>: Хандл меню.
*'''Select'''. Пункт был выбран. Будет дана позиция пункта в меню, а не нажатая кнопка (если меню не является панелью)
**<tt>OnMenuSelect()</tt> в C++. Передаются индекс клиента и позиция пункта.
**<tt>MenuAction_Select</tt> в SourcePawn. Это действие всегда вызывается, вне зависимости от запроса.
***<tt>param1</tt>: Индекс клиента.
***<tt>param2</tt>: Позиция пункта.
*'''Cancel'''. Отображение меню у одного из клиентов было закрыто.
**<tt>OnMenuCancel()</tt> в C++. Доступна причина закрытия.
**<tt>MenuAction_Cancel</tt> в SourcePawn. Это действие всегда вызывается, вне зависимости от запроса.
***<tt>param1</tt>: Индекс клиента.
***<tt>param2</tt>: Код причины закрытия меню.
*'''End'''. Цикл отображения меню закончился; это означает, что "Start" действие было, и одно из действий "Select" или "Cancel" так же произошло. Обычно в этом месте отчищаются ресурсы меню или само меню удаляется.
**<tt>OnMenuEnd()</tt> в C++.
**<tt>MenuAction_End</tt> в SourcePawn. Это действие всегда вызывается, вне зависимости от запроса.
***<tt>param1</tt>: Причина завершения меню.
***<tt>param2</tt>: если param1 == MenuEnd_Cancelled, то здесь содержится код причины закрытия меню.

==Панели==
Для панелей цикл жизни другой. Панели могут вызывать лишь два callback'а из написанных выше, и гарантируется, что один из них точно будет вызван для данного цикла отображения. Для C++, <tt>IBaseMenu</tt> указатель будет всегда <tt>NULL</tt>. Для SourcePawn, меню Handle будет всегда <tt>INVALID_HANDLE</tt>.

*'''Select'''. Кнопка была нажата. Этой кнопкой может быть любое число. Например, если в панели у вас 2 пункта, то клиент может вызвать это событие, нажав "43".
**<tt>OnMenuSelect()</tt> в C++. Передаются индекс клиента и нажатая кнопка.
**<tt>MenuAction_Select</tt> в SourcePawn.
***<tt>param1</tt>: Индекс клиента.
***<tt>param2</tt>: Номер нажатой клавиши.
*'''Cancel'''. Отображение меню у одного из клиентов было закрыто.
**<tt>OnMenuCancel()</tt> в C++. Доступна причина закрытия.
**<tt>MenuAction_Cancel</tt> в SourcePawn.
***<tt>param1</tt>: Индекс клиента.
***<tt>param2</tt>: Код причины закрытия меню.

=Примеры=
Для начала попробуем сделать очень простое меню:

<pre>Вы любите яблоки?
1. Да
2. Нет</pre>

Сделаем это как меню и как панель, чтобы увидеть различия в их API.

==Простое меню==
Сперва напишем наш пример через API Меню. Для пошагового руководства смотрите [[Menus Step By Step (SourceMod Scripting)]].

<pawn>public void OnPluginStart()
{
// зарегистрировали консольную команду menu_test1 для открытия меню.
RegConsoleCmd("menu_test1", Menu_Test1);
}

// хандл меню
int MenuHandler1(Menu menu, MenuAction action, int param1, int param2)
{
/* Если был выбран какой-либо пункт, то сообщим клиенту о его выборе. */
if (action == MenuAction_Select)
{
char info[32]; // переменная для хранения выбора
bool found = GetMenuItem(menu, param2, info, sizeof(info)); // получаем информацию о выбранном в меню пункте
PrintToConsole(param1, "Вы нажали: %d (найдено? %d информация: %s)", param2, found, info); // пишем клиенту в консоль
}
/* Если меню было отменено, то сообщим об этом серверу. */
else if (action == MenuAction_Cancel)
{
PrintToServer("Клиент %d' закрыл меню. Причина: %d", param1, param2);
}
/* Если меню "закончилось", то удалим его из памяти */
else if (action == MenuAction_End)
{
delete menu;
}
}

Action Menu_Test1(int client, int args)
{
new Handle:menu = CreateMenu(MenuHandler1);
SetMenuTitle(menu, "Вы любите яблоки?");
AddMenuItem(menu, "да", "да");
AddMenuItem(menu, "нет", "нет");
SetMenuExitButton(menu, false);
DisplayMenu(menu, client, 20);

return Plugin_Handled;
}</pawn>

Несколько очень важных замечаний о этом примере:
*Одно из <tt>Select</tt> или <tt>Cancel</tt> событий всегда будет отослано обработчику действий (action handler).
*<tt>End</tt> всегда будет отослано обработчику действий (action handler).
*Мы удаляем наше меню в <tt>End</tt> действии, потому что наш дескриптор (Handle) нам больше не нужен. Если бы мы удалили его после <tt>DisplayMenu</tt>, это бы отменило отображение меню клиенту.
*Меню по умолчанию имеет кнопку выхода. В нашем примере мы его отключили.
*Наше меню будет отображаться 20 секунд. Это означает, что если клиент ничего не выбрал в течении 20 секунд, то меню будет закрыто. Это обычно необходимо для меню с голосованиями. В отличии от AMX Mod X, вам не нужно создавать таймер, чтобы быть увереным, что меню "закончилось".
*Мы создали и уничтожили новый дескриптор меню (Menu Handle), однако мы можем этого и не делать. Вполне допустимо создать дескриптор (Handle) один раз для всего времени жизни плагина.
*Чтобы нормально отображались русские буквы, кодировка файла должна быть UTF-8 (без BOOM), иначе будут квадратики вместо русских букв.

Наше законченное меню и приложенный вывод в консоли выглядит как на картинке ниже (был выбран ответ "Да", и картинка взята с англ вики, прим. переводчика).

[[Image:Basic_menu_1.PNG]]

==Базовая панель==
Теперь давайте перепишем наш пример с использованием Панели вместо Меню.

<pawn>public OnPluginStart()
{
// зарегистрировали консольную команду panel_test1 для открытия меню.
RegConsoleCmd("panel_test1", Panel_Test1);
}

public PanelHandler1(Handle:menu, MenuAction:action, param1, param2)
{
if (action == MenuAction_Select)
{
PrintToConsole(param1, "Вы выбрали: %d", param2);
} else if (action == MenuAction_Cancel) {
PrintToServer("Клиент %d' закрыл панель. Причина: %d", param1, param2);
}
}

public Action:Panel_Test1(client, args)
{
new Handle:panel = CreatePanel();
SetPanelTitle(panel, "Вы любите яблоки?");
DrawPanelItem(panel, "Да");
DrawPanelItem(panel, "Нет");

SendPanelToClient(panel, client, PanelHandler1, 20);

CloseHandle(panel);

return Plugin_Handled;
}</pawn>

Как вы можете заметить, Панели сильно отличаются от Меню:
*Мы можем удалить Панель как только закончим его отображать. Мы можем создать Панель один раз, и продолжать использовать его много раз, однако мы можем удалить его в любой момент, без нарушения цикла отображения клиентского меню.
*Обработчик Панели (Handler) получает гораздо меньше информации. Так как Панели разрабатывались как грубый вывод текста, была сохранена возможность добавления информации без занятия слота. Поэтому обработчик может знать лишь об отмене или о нажатии любой клавиши с номером.
*Отсутствует автоматизация. Вы не можете добавить больше определенного числа выбираемых пунктов и добавить нумерацию. Автоматический контроль требует использования тяжелого объектного API Меню.

Наше законченная панель и приложеный вывод в консоли выглядит как на картинке ниже (был выбран ответ "Да", и картинка взята с англ вики, прим. переводчика):

[[Image:Basic_panel_1.PNG]]

==Базовое меню с нумерацией==
Теперь сделаем пример с большим функционалом -- нумерацией. Попробуем сделать меню для смены карты. Самый простой путь - прочесть <tt>maplist.txt</tt> файл в начале плагина и создать меню по этому файла.

Так как чтение и парсинг файла довольно долгая операция, мы будем делать это только раз за карту. Поэтому мы построим меню в <tt>OnMapStart</tt>, и мы не будем вызывать <tt>CloseHandle</tt> до события <tt>OnMapEnd</tt>.

Исходный код:
<pawn>new Handle:g_MapMenu = INVALID_HANDLE

public OnPluginStart()
{
RegConsoleCmd("menu_changemap", Command_ChangeMap);
}

public OnMapStart()
{
g_MapMenu = BuildMapMenu();
}

public OnMapEnd()
{
if (g_MapMenu != INVALID_HANDLE)
{
CloseHandle(g_MapMenu);
g_MapMenu = INVALID_HANDLE;
}
}

Handle:BuildMapMenu()
{
/* открываем файл */
new Handle:file = OpenFile("maplist.txt", "rt");
if (file == INVALID_HANDLE)
{
return INVALID_HANDLE;
}

/* создаем хандл меню */
new Handle:menu = CreateMenu(Menu_ChangeMap);
new String:mapname[255];
while (!IsEndOfFile(file) && ReadFileLine(file, mapname, sizeof(mapname)))
{
if (mapname[0] == ';' || !IsCharAlpha(mapname[0]))
{
continue;
}
/* выбрасываем все пробелы из названия */
new len = strlen(mapname);
for (new i=0; i<len; i++)
{
if (IsCharSpace(mapname[i]))
{
mapname[i] = '\0';
break;
}
}
/* проверяем карту на валидность */
if (!IsMapValid(mapname))
{
continue;
}
/* добавляем карту в меню */
AddMenuItem(menu, mapname, mapname);
}
/* не забываем закрыть файл! */
CloseHandle(file);

/* наконец, устанавливаем заглавие меню */
SetMenuTitle(menu, "Выберите карту:");

return menu;
}

public Menu_ChangeMap(Handle:menu, MenuAction:action, param1, param2)
{
if (action == MenuAction_Select)
{
new String:info[32];

/* получаем информацию о пункте */
new bool:found = GetMenuItem(menu, param2, info, sizeof(info));

/* говорим об этом клиенту */
PrintToConsole(param1, "Вы выбрали: %d (найдено? %d информация: %s)", param2, found, info);

/* меняем карту */
ServerCommand("changelevel %s", info);
}
}

public Action:Command_ChangeMap(client, args)
{
if (g_MapMenu == INVALID_HANDLE)
{
PrintToConsole(client, "Файл maplist.txt не был найден!");
return Plugin_Handled;
}

DisplayMenu(g_MapMenu, client, MENU_TIME_FOREVER);

return Plugin_Handled;
}</pawn>

Результатом такого меню будет множество пунктов (<tt>maplist.txt</tt> файл содержал примерно 18 карт). Таким образом, конечное меню содержит три страницы, которые идут друг за другом, и выглядят вот так:

[[Image:Basic_menu_2_page1.PNG]]
[[Image:Basic_menu_2_page2.PNG]]
[[Image:Basic_menu_2_page3.PNG]]

Сообщение в консоль будет выведено до смены карты, например, если выбрали <tt>cs_office</tt>:
<pre>Вы выбрали: 8 (найдено? 1 информация: cs_office)</pre>

Отображение и разработка этого меню через <tt>ShowMenu</tt> сообщение или <tt>Панельный</tt> API занимает много времени и является довольно сложной задачей. Придется отслеживать все пункты в массиве большого размера, страницы, которые пользователь просматривает, и написать функцию, которая будет вычислять, на основе текущей странице, пункт, который был выбран и какую кнопку нажали. Меню системы это всё делает за вас.

'''Заметки:'''
*Пункты управления, которые не доступны, не рисуются. Например, на первой странице вы не можете нажать "назад", а на последней странице вы не можете нажать "вперед". Несмотря на это, меню пытается удерживать каждый интерфейс последовательно. Таким образом, визуально, каждая навигационная клавиша всегда на одной и той же позиции.
*Если указать таймаут меню, то переключение между страницами не воздействует на общее время открытия меню. Например, если мы установим таймаут на 20 секунд, то каждое листание страницы будет устанавливать таймайт равный (20 - время, уже затраченное на просмотр). Только переоткрытие меню позволит вернуть таймаут времени на 20 секунд.
*Если отключить кнопку выхода, то не смотря на это, пункты 8 и 9 будут всё так же "назад" и вперед, соответственно.
*Мы не освобождаем дескриптор (Handle) меню в <tt>MenuAction_End</tt>, потому что наше меню глобальное/статическое, и нам не нужно пересоздавать его каждый раз.
*На изображении отображена кнопка "Назад". В SourceMod версии 1011 и выше, кнопка "Назад" была переименована в "Предыдующая", и "Назад" зарезервированно для "ExitBack" функциональности. (актуально для ENG версии, на ру вроде бы оба пункта "назад". прим. переводчик)

=Голосование=
SourceMod также имеет API для отображения меню как голосования для больше чем одного клиента. SourceMod автоматически обрабатываем выбранные пункты and randomly picking a tie-breaker (не знаю как перевести. прим. переводчика). Так же API голосования добавляет два новых значения для <tt>MenuAction</tt>, которые во время отображения меню всегда вызываются.

*<tt>MenuAction_VoteStart</tt>: Вызывается после <tt>MenuAction_Start</tt>, когда голосование оффициально началось.
*<tt>MenuAction_VoteEnd</tt>: Вызывается после того, как все клиенты проголосовали или отменили свои меню голосований. Выбранный предмет может быть получен через <tt>param1</tt>. Вызывается '''перед''' <tt>MenuAction_End</tt>. Важно заметить, что это не замена <tt>MenuAction_End</tt>, это разные вещи. Нельзя освобождать меню в <tt>MenuAction_VoteEnd</tt>. '''Заметка:''' не вызывается, если используется <tt>SetVoteResultCallback</tt>().
*<tt>MenuAction_VoteCancel</tt>: Вызывается, если меню было отмеено в процессе голосования. Если вызвалось, то <tt>MenuAction_VoteEnd</tt> или обратный вызов (callback) для результата голосований не будет вызваны, но <tt>MenuAction_End</tt> будет после этого. Причина отмены голосования находится в <tt>param1</tt>.

Система меню - это то же самое меню, только с двумя дополнительными свойствами:
*Только одно голосование может быть активно. Вы должны проверять, не запущено ли голосование (<tt>IsVoteInProgress</tt>()), иначе <tt>VoteMenu</tt>() не сработает.
*Если клиент во время голосования отключится, то его голос будет недействительным.

Пример внизу показывает, как создать функцию <tt>DoVoteMenu()</tt>, которая будет спрашивать, хотят ли они сменить карту на предложенную.

==Простое Голосование==
<pawn>public Handle_VoteMenu(Handle:menu, MenuAction:action, param1, param2)
{
if (action == MenuAction_End)
{
/* Вызывается после VoteEnd */
CloseHandle(menu);
} else if (action == MenuAction_VoteEnd) {
/* 0=да, 1=нет */
if (param1 == 0)
{
new String:map[64];
GetMenuItem(menu, param1, map, sizeof(map));
ServerCommand("changelevel %s", map);
}
}
}

DoVoteMenu(const String:map[])
{
if (IsVoteInProgress())
{
return;
}

new Handle:menu = CreateMenu(Handle_VoteMenu);
SetMenuTitle(menu, "Сменить карту на: %s?", map);
AddMenuItem(menu, map, "да");
AddMenuItem(menu, "no", "нет");
SetMenuExitButton(menu, false);
VoteMenuToAll(menu, 20);
}</pawn>

==Продвинутое Голосование==
Если вам нужно больше информации о результатах голосовании, чем вам дает <tt>MenuAction_VoteEnd</tt>, вы можете указать отдельный обратный вызов (callback). Новый обратный вызов будет давать больше информации, но за опреденную цену: <tt>MenuAction_VoteEnd</tt> не будет вызвано, и вам придется самим решать, как обработать результат. Это делается с помощью <tt>SetVoteResultCallback</tt>().

Пример:
<pawn>public Handle_VoteMenu(Handle:menu, MenuAction:action, param1, param2)
{
if (action == MenuAction_End)
{
/* Вызывается после VoteEnd */
CloseHandle(menu);
}
}

public Handle_VoteResults(Handle:menu,
num_votes,
num_clients,
const client_info[][2],
num_items,
const item_info[][2])
{
/* Проверяем, нет ли сразу двух победителей */
new winner = 0;
if (num_items > 1
&& (item_info[0][VOTEINFO_ITEM_VOTES] == item_info[1][VOTEINFO_ITEM_VOTES]))
{
winner = GetRandomInt(0, 1);
}

new String:map[64];
GetMenuItem(menu, item_info[winner][VOTEINFO_ITEM_INDEX], map, sizeof(map));
ServerCommand("changelevel %s", map);
}

DoVoteMenu(const String:map[])
{
if (IsVoteInProgress())
{
return;
}

new Handle:menu = CreateMenu(Handle_VoteMenu);
SetVoteResultCallback(menu, Handle_VoteResults);
SetMenuTitle(menu, "Сменить карту на: %s?", map);
AddMenuItem(menu, map, "Yes");
AddMenuItem(menu, "no", "No");
SetMenuExitButton(menu, false);
VoteMenuToAll(menu, 20);
}</pawn>

=ExitBack=
ExitBack - специальный термин для обозначения "ExitBack Кнопки". По умолчанию эта кнопка отключена. Обычно нумерованные меню не имеют пункта "Назад" для первой страници. Если "ExitBack" кнопка включена, появится кнопка "Назад".

Выбор опции "ExitBack" для меню в обратном вызове будет в действии <tt>MenuCancel_ExitBack</tt> и <tt>MenuEnd_ExitBack</tt>. Функциональность этого такая же, как и у простого выхода из меню; дополнительная функциональность должна быть определена через обратный вызов.

=Освобождение Дескрипторов (Handle) меню=
Важно закрывать дескриптор меню в <tt>MenuAction_End</tt>. <tt>MenuAction_End</tt> вызывается когда меню закрылось и больше не нужно.

=Переводы=
Есть возможность динамически переводить меню для каждого игрока через <tt>MenuAction_DisplayItem</tt> callback. Специальный натив, <tt>RedrawMenuItem</tt>, используется чтобы преобразовать текст внутри вызова. Давайте переделаем наш пример голосования с переводами.

<pawn>public Handle_VoteMenu(Handle:menu, MenuAction:action, param1, param2)
{
if (action == MenuAction_End)
{
/* Вызывается после VoteEnd */
CloseHandle(menu);
} else if (action == MenuAction_VoteEnd) {
/* 0=да, 1=нет */
if (param1 == 0)
{
new String:map[64];
GetMenuItem(menu, param1, map, sizeof(map));
ServerCommand("changelevel %s", map);
}
} else if (action == MenuAction_DisplayItem) {
/* Получаем отображаемую строку, будем использовать как фразу перевода */
decl String:display[64];
GetMenuItem(menu, param2, "", 0, _, display, sizeof(display));

/* Переводим строку на язык клиента */
decl String:buffer[255];
Format(buffer, sizeof(buffer), "%T", display, param1);

/* Перерисовываем текст */
return RedrawMenuItem(buffer);
} else if (action == MenuAction_Display) {
/* Дескриптор панели будет вторым параметром */
new Handle:panel = Handle:param2;

/* Get the map name we're changing to from the first item */
/* Получаем название карты, на которую меняем, из первого пункта */
decl String:map[64];
GetMenuItem(menu, 0, map, sizeof(map));

/* Переводим нашу фразу */
decl String:buffer[255];
Format(buffer, sizeof(buffer), "%T", "Change map to?", client, map);

SetPanelTitle(panel, buffer);
}
}

DoVoteMenu(const String:map[])
{
if (IsVoteInProgress())
{
return;
}

new Handle:menu = CreateMenu(Handle_VoteMenu, MenuAction_DisplayItem|MenuAction_Display);
SetMenuTitle(menu, "Сменить карту на: %s?", map);
AddMenuItem(menu, map, "Yes");
AddMenuItem(menu, "no", "No");
SetMenuExitButton(menu, false);
VoteMenuToAll(menu, 20);
}</pawn>

[[Category:SourceMod Development]]
[[Category:SourceMod Scripting]]

{{LanguageSwitch}}