AlliedModders Wiki - User contributions [en]

Counter-Strike: Source Weapons

2011-11-03T13:25:23Z

Frenzzy:

== Entity Names for Weapons ==

<pawn>
glock
usp
p228
deagle
elite
fiveseven
m3
xm1014
galil
ak47
scout
sg552
awp
g3sg1
famas
m4a1
aug
sg550
mac10
tmp
mp5navy
ump45
p90
m249
vest
vesthelm
flashbang
hegrenade
smokegrenade
defuser
nvgs
c4
</pawn>

==Item Names for Weapons(GivePlayerItem)==

<pawn>

weapon_glock
weapon_usp
weapon_p228
weapon_deagle
weapon_elite
weapon_fiveseven
weapon_m3
weapon_xm1014
weapon_galil
weapon_ak47
weapon_scout
weapon_sg552
weapon_awp
weapon_g3sg1
weapon_famas
weapon_m4a1
weapon_aug
weapon_sg550
weapon_mac10
weapon_tmp
weapon_mp5navy
weapon_ump45
weapon_p90
weapon_m249
//vest
item_assaultsuit //vest+helm
weapon_flashbang
weapon_hegrenade
weapon_smokegrenade
item_defuser
//nvgs
weapon_c4
</pawn>

<pawn>
enum WeaponType
{
Weapon_Glock = 0,
weapon_USP,
Weapon_P228,
Weapon_Deagle,
Weapon_Elite,
Weapon_FiveSeven,
Weapon_M3,
Weapon_XM1014,
Weapon_Galil,
Weapon_AK47,
Weapon_Scout,
Weapon_SG552,
Weapon_AWP,
Weapon_G3SG1,
Weapon_Famas,
Weapon_M4A1,
Weapon_Aug,
Weapon_SG550,
Weapon_Mac10,
Weapon_TMP,
Weapon_MP5Navy,
Weapon_Ump45,
Weapon_P90,
Weapon_M249,
Weapon_Vest,
Weapon_VestHelm,
Weapon_FlashBang,
Weapon_HEGrenade,
Weapon_SmokeGrenade,
Weapon_Defuser,
Weapon_NightVision,
Weapon_C4
Weapon_Max
};
</pawn>

Ru:Introduction to SourcePawn

2011-06-25T18:10:32Z

Frenzzy:

Это руководство призвано дать Вам самые основные представления по основам написания сприптов в SourcePawn. [[Pawn]] это "скриптовый" язык используемый для внедрения функциональности в других программах. Это означает, что это не самостоятельный язык, как C++ или Java, и его элементы будут отличаться в различных приложениях. SourcePawn это вариация языка Pawn используемая в [[SourceMod]].

Это руководство не расскажет Вам как писать SourceMod плагины; оно предназначено для получения общих представлений о синтаксисе и семантике этого языка. Читайте отдельную статью [[Ru:Introduction to SourceMod Plugins]] (Введение в SourceMod плагины), для введения в SourceMod API.

=Введение для новичков=
Этот раздел создан не для программистов. Если Вы по прежнему в замешательстве, Вы можете прочитать книги о других языках программирования, таких как PHP, Python, или Java, чтобы получить более полное представление о программировании.

==Идентификаторы/Ключевые слова==
Идентификаторы представляет собой набор букв, цифр и/или нижнего подчеркивания, что представляет собой нечто уникальное. Идентификаторы вводятся с учетом регистра (в отличие от PHP, где иногда это не требуется). Идентификаторы не начинаются с какого-либо специального символа, но они должны начинаться с буквы.

Есть несколько зарезервированных символов, которые имеют особое значение. Например, <tt>if</tt>, <tt>for</tt>, и <tt>return</tt> специальные конструкции в языке, которые будут описаны позднее. Они не могут быть использованы в качестве названий идентификаторов.

==Переменные==
Существует несколько важных конструкций, которые Вы должны знать, прежде чем приступить к написанию сценария. Во-первых, это '''переменные'''. Переменная это идентификатор, который содержит данные. Например, переменная "a" может содержать числа "2", "16", "0", и так далее. Переменные создаются для хранения данных внутри программы. Переменные должны быть объявлены до их использования, с помощью ключевого слова "new". Данные можно присвоить переменной, используя знак равенства (=). Пример:

<pawn>new a, b, c, d;

a = 5;
b = 16;
c = 0;
d = 500;</pawn>

В SourcePawn, переменные бывают двух типов, которые будут более подробно описаны далее.
*Однострочные (могут содержать только произвольные числовые данные), как показано выше.
*Многострочные (могут содержать целый ряд текстовых символов)

==Функции==
Следующим важным понятием являются '''функции'''. Функции идентификаторов или имен, которые выполняют действия. Это означает, что когда вы их активируете, они выполняют конкретную последовательность кода. Есть несколько типов функций, но все функции активируется одинаковым образом. "Вызов функции" является термином ссылающимся на функцию действия. Функция числовых переменных строятся так:
<pawn>функция(<параметры>)</pawn>

Примеры:

<pawn>show(56); //Активирует функцию "show" и присваивает ей число 56
show(); //Активирует функцию "show" без каких-либо данных, пустую
show(a); //Активирует функцию "show" и присваивает ей переменную с данными
</pawn>

Каждый фрагмент данных передаваемый вызываемой функции, называется '''параметр'''. Функция может иметь любое количество параметров (но есть "допустимый" предел в SourceMod: 32). Параметры будут описаны далее в этой статье.

==Комментарии==
Примечания и любой текст, который пишется после "//" считается "Комментарием", а не фактическим кодом. Есть два стиля комментариев:
*<tt>//</tt> - Двойная косая черта, всё следующие после этой строки игнорируется.
*<tt>/* */</tt> - Много-строчный комментарий, весь текст, внутри звездочек игнорируются. You cannot nest these.

==Массивы==
Описание массивов. Вы можете группировать код в виде "массивов", разделенных { и }. Это фактически создает возможность работать с целым массивом как с одним оператором. Например:

<pawn>{
here;
is;
some;
code;
}</pawn>

Массивы с фигурными скобками используются достаточно широко в программировании. Массивы кода могут быть вложенными друг в друга. Это хорошая возможность адаптировать последовательность когда и сделать его удобочитаемым, благодаря отступам код не будет смотреться как одна большая и длинная макаронина.

=Особенности языка=
Pawn может показаться очень похожим на другие языки программирования, например C, но Pawn от них фундаментально отличается. Не столь важно, чтобы Вы сейчас же поняли его отличия, но они понадобятся, если Вы уже знаете один из языков программирования.
*'''Pawn не печатает''' Pawn имеет только один тип данных - '''однострочный'''. Подробнее будет описано позже. [В дальнейшем автор рассказывает, что существует два типа данных: однострочный и многострочный]
*'''Pawn не собирает мусор''' Pawn, как язык, не имеет встроенных ресурсов памяти, и потому он не мусорит. Если функция выделит память, то Вы отвечаете за её освобождение.
*'''Pawn не объектно-ориентированный язык''' Pawn является процедурным, и полагается на подпрограммы. Также у него нету C подобных структур.
*'''Pawn не функциональный.''' Pawn является процедурным, и не поддерживает функции "лямбды" (Lambda), поздние присвоения, и все то, что можно найти в языках высшего уровня, таких как Python и Ruby.
*'''Pawn однопоточный''' As of this writing, Pawn is not thread safe.
*'''Pawn не интерпретируемый''' Ну, почти. Он интерпретируется на очень низком уровне. Вы должны скомпилировать код, из которого получится бинарный файл. Эта программа будет работать на той платформе, которую использует хост. Это ускоряет загрузку и позволяет легче находить ошибки.

Этот язык был выпущен ITB CompuPhase. Язык разработан для устройств низкого уровня и таким образом конечные программы очень маленькие по размеру и очень быстрые.

=Переменные=
В Pawn есть всего два типа переменных: '''однострочные''' и '''многострочные'''. Однострочные могут содержать 32 бита цифровых данных. Многострочные - последовательный список из UTF-8 символов.

'''однострочные''' не имеет своего типа, однако они могут быть '''маркированы'''(tagged). Тег позволяет Вам указывать, где определенную ячейку можно использовать. Типичные теги:
*(пусто), или '''_''' - Нет тега. Обычно используют для целых чисел ([http://en.wikipedia.org/wiki/Integer Integers]).
*'''Float''' - используют для чисел с плавающей точкой (небольших).
*'''bool''' - используют для хранения значений '''true''' (истина) или '''false''' (ложь).

Со строками все по другому, они будут рассмотрены далее.

==Объявления==
Примеры разных правильных объявлений переменных.
<pawn>
new a = 5;
new Float:b = 5.0;
new bool:c = true;
new bool:d = 0; //Работает, поскольку 0 равно false (ложь)
</pawn>

Неправильные объявления переменных
<pawn>
new a = 5.0; //Несоответствие тегов. 5.0 с тегом Float
new Float:b = 5; //Несоответствие тегов. 5 без тега.
</pawn>

Если переменная не определена в объявлении то ее значения станет 0
<pawn>
new a; //значение 0
new Float:b; //значение 0.0
new bool:c; //значение false
</pawn>

==Присвоение==
Переменным могут быть присвоены данные после создания. Пример:
<pawn>new a, Float:b, bool:c;

a = 5;
b = 5.0;
c = true;
</pawn>

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

==Описание==
Массив объявляется с помощью квадратных скобок. Вот некоторые примеры массивов:
<pawn>
new players[32]; //Набор из 32 однострочных (числовых) данных
new Float:origin[3]; //Набор из 3 чисел с плавающей точкой
</pawn>

По умолчанию, массивам присваиваются нули. Вы можете присвоить им разные значения по умолчанию, однако:
<pawn>
new numbers[5] = {1, 2, 3, 4, 5}; //Набор 1, 2, 3, 4, 5 из однострочных данных.
new Float:origin[3] = {1.0, 2.0, 3.0}; //Набор 1.0, 2.0, 3.0 из однострочных данных.
</pawn>

Вы можете оставить массив без размера, если вы собираетесь заранее присвоить ему данные. Например:
<pawn>
new numbers[] = {1, 3, 5, 7, 9};
</pawn>

Компилятор будет автоматически делать вывод о том, что Вы хотите получить массив размером 5.

==Использование==
Использование массива равносильно использованию обычных переменной. Единственное отличие массива состоит в том, что он должен быть '''индексируемым'''. Индексирование массива означает присутствие возможности выбрать элемент, который Вы хотите использовать.

Вот пример кода с использованием индексов:
<pawn>
new numbers[5], Float:origin[3];

numbers[0] = 1;
numbers[1] = 2;
numbers[2] = 3;
numbers[3] = 4;
numbers[4] = 5;
origin[0] = 1.0;
origin[1] = 2.0;
origin[2] = 3.0;
</pawn>

Заметим, что '''индекс''' это текст, который находится в квадратных скобках. Индекс всегда начинается с нуля. То есть, если массив имеет N элементов, его действительный индекс от 0 до N-1. Доступ к данным с индексами работает так же, как с обычной переменной.

Использование неверного индекса вызовет ошибку. Например:
<pawn>
new numbers[5];

numbers[5] = 20;</pawn>

Это может выглядеть верно, но число 5 не является допустимым индексом. Наибольшим значением индекса является число 4.

Вы можете использовать любые выражения, как индекс. Например:
<pawn>new a, numbers[5];

a = 1; //Сделает a = 1
numbers[a] = 4; //Сделает numbers[1] = 4
numbers[numbers[a]] = 2; //Сделает numbers[4] = 2
</pawn>

Выражения будут обсуждаться подробнее в конце статьи.

=Строки=
Строки являются удобным способом хранения текста. Символы хранятся в массиве. Строка ограничивается '''нулевым символом''', или 0. Без нулевого символа, Pawn не знает, где остановить чтение строки. Все строки в SourcePawn используют кодировку UTF-8.

Отметим, что строки имеют комбинацию из массивов и однострочных переменных. В отличие от других языков, это означает, что Вы должны знать заранее, как много места будут использовать строки. Это означает, что строки не являются динамичными. Они могут лишь вырасти до размера, которым Вы их ограничили.

''Примечание для специалистов: они фактически не однострочные. SourcePawn использует 8-битный строки для хранения массивов в качестве оптимизации. Это и есть то, что делает строки типом, а не меткой.''

==Использование==
Строки были созданы почти в равной степени и для массивов. Например:
<pawn>
new String:message[] = "Hello!";
new String:clams[6] = "Clams";
</pawn>

Это равносильно следующему:
<pawn>
new String:message[7], String:clams[6];

message[0] = 'H';
message[1] = 'e';
message[2] = 'l';
message[3] = 'l';
message[4] = 'o';
message[5] = '!';
message[6] = 0;
clams[0] = 'C';
clams[1] = 'l';
clams[2] = 'a';
clams[3] = 'm';
clams[4] = 's';
clams[5] = 0;
</pawn>

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

Заметим, что строка должна быть заключена в двойных кавычках, а символ в одиночных.

==Символы==
Особенность текста может быть использована в любой строке или однострочной переменной. Например:
<pawn>new String:text[] = "Crab";
new clam;

clam = 'D'; //Устанавливает однострочной переменной значение 'D'
text[0] = 'A'; //Меняет 'C' на 'A', сейчас получилось 'Arab'
clam = text[0]; //Устанавливает однострочной переменной значение 'A'
text[1] = clam; //Меняет 'r' на 'A', сейчас получилось 'AAab'
</pawn>

То, что вы не можете сделать, это соотнести символы массивов со строками. Внутреннее хранение отличается. Например:
<pawn>
new clams[] = "Clams"; //Не верно, нужен тип String:
new clams[] = {'C', 'l', 'a', 'm', 's', 0}; //Верно, но это НЕ СТРОКА.
</pawn>

=Функции=
Функции, как отмечалось ранее, имеют отдельные составляющие кода, которые выполняют определенные действия. Функции могут быть задействованы или '''вызвоны''' с '''параметрами''', которые дают особые настройки.

Существуют два типа вызова функции:
*'''прямой вызов''' - Вы специально вызываете функцию в своем коде.
*'''обратный вызов''' - Применение вызова функций в Вашем коде, как если бы это было событием триггера (совокупность условий, инициирующих выполнение действия).

Существуют шесть видов функций:
*'''native''': Прямая, внутренняя функция, предусмотренная в приложении.
*'''public''': Функция обратного вызова, что делает её видимой для приложения и других сценариев.
*'''normal''': Нормальная функция, которую Вы можете только вызвать.
*'''static''': The scope of this function is restricted to the current file, can be used in combination with stock.
*'''stock''': Нормальная функция, предусмотренная если включает в себя файл. Если не используется, то не компилируется.
*'''forward''': Эта функция представляет собой глобальное событие, предусмотренная приложением. Если Вы её привели в исполнение, она будет вызвона.

Весь код в Pawn должен существовать в функциях. Это основное отличие от языков, таких как PHP, Perl и Python, которые позволяют Вам писать глобальный код. Это происходит потому, что Pawn вызывается на основе другого языка: он реагирует на действия от родительского приложения, и функции должны быть написаны для обработки этих действий. Хотя наш пример, часто содержат свободно плавающий код, это сделано исключительно для демонстрационных целей. Свободно плавающий код в нашем примере означает, что код является частью ряда функций.

==Описание==
В отличие от переменных, функции, не нужно объявлять, прежде чем использовать их. Функции имеют две части, '''модель''' и '''тело'''. Модель содержит имя Вашей функции и параметры, которые она будет принимать. Тело является контейнером для кода.

Пример функции:
<pawn>
AddTwoNumbers(first, second)
{
new sum = first + second;

return sum;
}</pawn>

Это простая функция. Модель этой строки:
<pawn>AddTwoNumbers(first, second)</pawn>

Распишем по отдельности:
*<tt>AddTwoNumbers</tt> - Название функции.
*<tt>first</tt> - Название первого параметра, который представляет собой простой элемент.
*<tt>second</tt> - Название второго параметра, который представляет собой простой элемент.

Тело представляет собой простой блок кода. Он создает новую переменную, названную <tt>sum</tt>, и присваивает ей значение этих двух параметров, добавленных совместно (другие выражения будут позже). Важно заметить оператор <tt>return</tt>, в котором обозначается конец функции и возврат с полученными значениями из этой функции. Все функции ''возвращают значения'' после завершения. Это означает, например:

<pawn>new sum = AddTwoNumbers(4, 5);</pawn>

Приведенный выше код будет присваивать число 9 к sum. Функция получает два значения и передает новое значение sum в качестве '''возвращаемого значения'''. Если функция не имеет возвращаемого значения или не имеет значений для возврата, то возвращается 0 по умолчанию.

Функция может принимать любые типы значений. Она может вернуть любую однострочную переменную, но не массивы или строки. Пример:
<pawn>Float:AddTwoFloats(Float:a, Float:b)
{
new Float:sum = a + b;

return sum;
}</pawn>

''Заметим, что если в приведенной выше функции, Вам вернулась не Float значение, Вы получите не соответствие значений.''

Можно, конечно, передавать переменные в функции:
<pawn>new numbers[3] = {1, 2, 0};

numbers[2] = AddTwoNumbers(numbers[0], numbers[1]);</pawn>

Заметим, что однострочные переменные передаются '''по значению'''. То есть, их значение не может быть изменено функцией. Например:
<pawn>new a = 5;

ChangeValue(a);

ChangeValue(b)
{
b = 5;
}</pawn>

Этот код не будет менять значение <tt>a</tt>. Это происходит потому, что копия этого значения в <tt>a</tt> передается вместо <tt>a</tt> самостоятельно.

Больше примеров функций будут демонстрироваться и в других частях статьи.

==Publics==
Публичные функции используются для осуществления обратных вызовов. Вы не должны создавать какую-либо публичную функцию, если это вынудит выполнение обратного вызова. Например, вот два обратных вызова из <tt>sourcemod.inc</tt>:

<pawn>forward OnPluginStart();
forward OnClientDisconnected(client);</pawn>

Чтобы выполнить и получить эти два события, Вы должны написать такие функции как:

<pawn>public OnPluginStart()
{
/* Код здесь */
}

public OnClientDisconnected(client)
{
/* Код здесь */
}</pawn>

Ключевое слово '''public''' делает функцию публичной, а также позволяет родительскому приложению непосредственно вызывать функцию.

==Natives==
Natives имеют встроенные функции, предоставляемые SourceMod. Вы можете вызвать их, как если бы они были normal функциями. Например, SourceMod имеет следующие функции:

<pawn>native FloatRound(Float:num);</pawn>

Её можно вызвать таким образом:
<pawn>new num = FloatRound(5.2); //Результат в num = 5</pawn>

==Параметры массива==
Вы можете передавать массивы или строки в качестве параметров. Важно отметить, что они идут '''как ссылка'''. То есть не делать копию данных, а отдавать непосредственно ссылки на данные. Существует простой способ объяснить это более конкретно.

<pawn>
new example[] = {1, 2, 3, 4, 5};

ChangeArray(example, 2, 29);

ChangeArray(array[], index, value)
{
array[index] = value;
}</pawn>

Эта функция устанавливает заданный индекс в массиве с учетом значений. Когда она запускается на примере нашего массива, она меняет индекс 2 для значения 3 на 29. То есть:
<pawn>example[2] = 29;</pawn>

Это возможно лишь потому, что массив может быть непосредственно изменён. Чтобы предотвратить массив от изменения, можно пометить его как постоянную <tt>const</tt>. Это позволит понизить риск на ошибку в коде от её изменения. Например:

<pawn>CantChangeArray(const array[], index, value)
{
array[index] = value; //Не компилируется
}</pawn>

Это хорошая идея использовать <tt>const</tt> в параметрах массивов и Вы будете точно знать, что массив не будет изменен; это может предотвратить ошибки кодирования.

=Выражения=
Выражения являются точно такими же, какими они существуют в математике. Это группы операторов/символов, которые приходятся на один фрагмент данных. Они часто заключены в скобках (внутри скобок). Они содержат строгий "порядок операций". Они могут содержать переменные, функции, цифры и выражения сами могут быть вложенные внутрь других выражений, и даже приняты в качестве параметров.

Приведем пример простейшего выражения:
<pawn>
0; //Возвращает число 0
(0); //Так же возвращает число 0
</pawn>

Хотя выражения могут возвращать значения, они также могут ответить какое значение содержит ответ ''ноль или не ноль''. В этом смысле, ''ноль'' является ''ложью'' (false), а ''не нулевое'' значение ''истиной'' (true). Например, -1 ''истина'' в Pawn, поскольку она не является нулем. Не думайте, что отрицательные числа являются ложными.

Порядок операций выражения аналогичен языку C. PMDAS: Parenthesis, Multiplication, Division, Addition, Subtraction. Вот несколько примеров выражений:
<pawn>
5 + 6; //Вычисляет как 11
5 * 6 + 3; //Вычисляет как 33
5 * (6 + 3); //Вычисляет как 45
5.0 + 2.3; //Вычисляет как 7.3
(5 * 6) % 7; //Modulo operator, вычисляет как 2
(5 + 3) / 2 * 4 - 9; //Вычисляет как 7
</pawn>

Как уже отмечалось, выражения могут содержать переменные, или даже функции:
<pawn>
new a = 5 * 6;
new b = a * 3; //Вычисляет как 90
new c = AddTwoNumbers(a, b) + (a * b);
</pawn>

Примечание: String manipulation routines may be found in the string.inc file located in the include subdirectory. They may be browsed through the [http://docs.sourcemod.net/api/ API Reference] as well.

==Операторы==
Есть несколько полезных дополнительных операторов в Pawn. Первый набор упрощает аутоагрегацию выражения. Например:
<pawn>new a = 5;

a = a + 5;</pawn>

Может быть переписан, как:
<pawn>new a = 5;
a += 5;</pawn>

Это верно в отношении следующих операторов в Pawn:
*Four-function: *, /, -, +
*Bit-wise: |, &, ^, ~, <<, >>

Кроме того, существуют инкремент/декремент операторы:
<pawn>a = a + 1;
a = a - 1;</pawn>

Может быть упрощено, как:
<pawn>a++;
a--;</pawn>

Дополнительно отметим, что ++ или -- может быть представлен до переменной (до-инкремент, до-декремент) или после переменной (пост-инкремент, пост-декремент). Разница заключается в том, как остальная часть выражения содержащие их, видит результат.

* ''До:'' Переменная увеличивается до определения и остальная часть выражения видит новое значение.
* ''Пост:'' Переменная увеличивается после определения и остальная часть выражения видит старое значение.

Иными словами, <tt>a++</tt> определяет значение как <tt>a</tt> в то время как <tt>++a</tt> определяет значение как <tt>a + 1</tt>. В обоих случаях <tt>a</tt> увеличивается на <tt>1</tt>.

Например:

<pawn>new a = 5;
new b = a++; // b = 5, a = 6 (1)
new c = ++a; // a = 7, c = 7 (2)
</pawn>

(1) <tt>b</tt> присваивается <tt>a</tt> со ''старым'' значением, ''до'' того, как он будет увеличено до <tt>6</tt>. (2) <tt>c</tt> присваивается <tt>a</tt> с ''новым'' значением, ''после'' того, как он увеличивается до <tt>7</tt>.

==Операторы сравнения==
Существуют шесть операторов для сравнения двух числовых значений, а результат является либо истиной (не ноль) или ложью (ноль):
*<tt>a == b</tt> - Действительно, если и b имеет то же значение.
*<tt>a != b</tt> - Действительно, если b имеет другое значение.
*<tt>a > b</tt> - Действительно, если оно больше b
*<tt>a >= b</tt> - Действительно, если оно больше или равно b
*<tt>a < b</tt> - Действительно, если оно меньше b
*<tt>a <= b</tt> - Действительно, если оно меньше или равно b

Например:
<pawn>
(1 != 3); //Определяется как истина, поскольку 1 не равно 3.
(3 + 3 == 6); //Определяется как истина, поскольку 3+3 равно 6.
(5 - 2 >= 4); //Определяется как ложь, поскольку 3 меньше 4.
</pawn>

Заметим, что эти операторы не работают с массивами и строками. То есть, вы не можете сравнить их с помощью <tt>==</tt>.

==Действительные операторы==
Действительные операторы могут быть скомбинированы тремя булевыми (boolean) операторами:
*<tt>a && b</tt> - Истина, если a и b истинные. Ложь, если a и (или) b ложные.
{| border="1" cellpadding="2" cellspacing="0" align="center"
! <tt>&&</tt> !! 0 !! 1
|-
! 0
| 0 || 0
|-
! 1
| 0 || 1
|}
*<tt>a || b</tt> - Истина, если a или b (или обе переменные) истинные. Ложь, если обе переменные a и b ложные.
{| border="1" cellpadding="2" cellspacing="0" align="center"
! <tt><nowiki>||</nowiki></tt> !! 0 !! 1
|-
! 0
| 0 || 1
|-
! 1
| 1 || 1
|}
*<tt>!a</tt> - Истина, если a ложь. Ложь, если a истина.
{| border="1" cellpadding="2" cellspacing="0" align="center"
! <tt>!</tt> !! 0 !! 1
|-
!
| 1 || 0
|}

Например:
<pawn>
(1 || 0); //Определяется как истина, так как выражение 1 истинное
(1 && 0); //Определяется как ложь, так как выражение 0 ложное
(!1 || 0); //Определяется как ложь, так как выражение !1 ложное.
</pawn>

==Левое/правое значения==
Два важных понятия левого и правого значений, или левостороннее и правостороннее значения. Левостороннее значение имеет то, что появляется на левой стороне выражения, а правостороннее значение - появляется на правой стороне выражения.

Например:
<pawn>
new a = 5;</pawn>

В этом примере <tt>a</tt> является левосторонним значением и <tt>5</tt> является правосторонним значением.

Правила:
*'''Выражения никогда не будут левосторонними значениями'''.
*'''Переменные являются двумя, левосторонними и правосторонними значениями'''.

=Условия=
Условия позволяют Вам запускать код, определенное условие выполнено.

==Если соответствует==
Если соответствует одно или более условий. Например:

<pawn>
if (a == 5)
{
/* Код будет запущен, если условие будет истинным */
}</pawn>

Они могут быть расширены для более сложных случаев:
<pawn>
if (a == 5)
{
/* Код */
}
else if (a == 6)
{
/* Код */
}
else if (a == 7)
{
/* Код */
}</pawn>

Вы так же можете обрабатывать случаи, даже если выражение не верно. Например:
<pawn>
if (a == 5)
{
/* Код */
}
else
{
/* Код, который будет запущен если нет истинного выражения */
}</pawn>

==Оператор выбора==
Оператор выбора будет ограничен условием. Он необходим для выражения, выполняющего код для целого ряда возможных значений. Например:

<pawn>
switch (a)
{
case 5:
{
/* Код */
}
case 6:
{
/* Код */
}
case 7:
{
/* Код */
}
case 8, 9, 10:
{
/* Код */
}
default:
{
/* будет запущен, если не одно условие не соответствует */
}
}</pawn>

В отличие от некоторых других языков, оператор выбора не проваливается. То есть существуют случаи, когда код не будет запущен. При случае совпадения его код выполняется, а ключ является местом для немедленного прекращения.

=Циклы=
Циклы позволяют Вам без труда повторять выполнение кода, пока условие станет истинным.

==For циклы==
For циклы, это циклы, которые состоят из четырех частей:
*Оператор '''инициализации''' - запускается один раз перед первым циклом.
*Оператор '''условия''' - проверяет условие и запускает следующий цикл, в том числе первый. Цикл прекращается, когда это выражение становится ложным.
*Оператор '''итерации''' - запускается после каждого цикла.
* '''тело''' цикла - запускается каждый раз, пока оператор '''условия''' вычисляется как истинный.

<pawn>
for ( /* инициализация */ ; /* условие */ ; /* итерация */ )
{
/* тело */
}
</pawn>

Простым примером является функция сложения массива:
<pawn>
new array[10] = {1, 2, 3, 4, 5, 6, 7, 8, 9, 10};
new sum = SumArray(array, 10);

SumArray(const array[], count)
{
new total;

for (new i = 0; i < count; i++)
{
total += array[i];
}

return total;
}</pawn>

По отдельности:
*<tt>new i = 0</tt> - Создает новую переменную для цикла, и устанавливает её в 0.
*<tt>i < count</tt> - Только запускает цикл, если <tt>i</tt> меньше, чем <tt>count</tt>. Это гарантирует, что чтение цикла прекращается в определенный момент. В этом случае, мы не хотим читать недействительные индексы в массиве.
*<tt>i++</tt> - Увеличивает <tt>i</tt> на единицу после каждого цикла. Это гарантирует, что цикл не будет запущен вечно; в конце концов <tt>i</tt> станет слишком большим, и цикл завершится.

Таким образом, функция <tt>SumArray</tt> будет циклом каждого действительного индекса массива, каждый раз добавляя это значение в sum. Для циклов очень распространены массивы такие, как в нашем примере.

==While циклы==
While циклы являются менее распространенными, чем for циклы, но на самом деле это более простые циклы. Они имеют только две части:
*Оператор '''условия''' - проверяется перед началом каждого цикла. Цикл прекращается, когда условие становится ложным.
*'''тело''' цикла - запускается каждый раз пока цикл выполняется.

<pawn>
while ( /* условие */ )
{
/* тело */
}
</pawn>

До тех пор, пока условие выражения остается истинным, цикл будет выполняться. Каждый for цикл может быть переписан, как while цикл:

<pawn>
/* инициализация */
while ( /* условие */ )
{
/* тело */
/* итерация */
}
</pawn>

Вот предыдущий for цикл переписан как while цикл:
<pawn>
SumArray(const array[], count)
{
new total, i;

while (i < count)
{
total += array[i];
i++;
}

return total;
}</pawn>

Существуют также '''do...while''' циклы, которые используются еще реже. Они работают как и while циклы, но проверяют условие ПОСЛЕ каждого цикла, а не перед ним. Это означает, что цикл всегда будет запущен, по крайней мере один раз. Например:

<pawn>
do
{
/* тело */
}
while ( /* условие */ );
</pawn>

==Управление циклами==
Существуют два случая, в которых Мы хотели бы контролировать цикл:
*'''пропустить''' одну итерацию или цикл и продолжить выполнение цикла как обычно, или;
*'''разорвать''' цикл целиком, прежде чем он закончится.

Допустим у вас есть функция, которая принимает массив и ищет соответствия цифр. Вы хотите его остановить, когда число будет найдено:
<pawn>
/**
* Возвращает массив, если индекс значения, или -1, не найдены.
*/
SearchInArray(const array[], count, value)
{
new index = -1;

for (new i = 0; i < count; i++)
{
if (array[i] == value)
{
index = i;
break;
}
}

return index;
}</pawn>

Конечно, эту функцию можно вернуть и способом <tt>return i</tt>, но пример показывает, как <tt>break</tt> может остановить цикл.

Кроме того, ключевое слово <tt>continue</tt> пропускает итерации цикла. Например, Мы хотим суммировать все четные числа:

<pawn>
SumEvenNumbers(const array[], count)
{
new sum;

for (new i = 0; i < count; i++)
{
/* If divisibility by 2 is 1, we know it's odd */
if (array[i] % 2 == 1)
{
/* Пропускаем оставшуюся часть итерации цикла */
continue;
}
sum += array[i];
}

return sum;
}</pawn>

=Область действия=
Область действия относится к '''удобочитаемости''' кода. Это означает, что код одного уровня не может быть "виден" в коде другого уровня. Пример:

<pawn>
new A, B, C;

Function1()
{
new B;

Function2();
}

Function2()
{
new C;
}</pawn>

В этом примере, <tt>A</tt>, <tt>B</tt>, и <tt>C</tt> имеют '''глобальную область действия'''. Их можно увидеть в любой функции. Вместе с тем, <tt>B</tt> в функции <tt>Function1</tt> не является той же переменной, как <tt>B</tt> на глобальном уровне. Вместо этого она находится в '''локальной области действия''', и поэтому является '''локально изменяемой'''.

Кроме того, функции <tt>Function1</tt> и <tt>Function2</tt> ничего не знают о существовании других переменных.

Она так же является не только локальной переменной функции <tt>Function1</tt>, но и создается заново каждый раз, когда функция вызывается. Попробуйте представить это:
<pawn>
Function1()
{
new B;

Function1();
}</pawn>

В приведенном выше примере, функция <tt>Function1</tt> вызывает сама себя. Конечно, это бесконечной рекурсии (а это очень плохо), но идея заключается в том, что каждый раз, когда функция срабатывает, то создается новая копия <tt>B</tt>. Когда функция завершается, <tt>B</tt> уничтожается, и её значение теряется.

Это свойство можно объяснить проще тем, что область действия переменной равна уровню её вложенности. То есть, переменная на глобальной области действия видна для всех функций. Переменная в локальной области действия видна всему блоку кода расположенному "ниже" этого уровня. Например:

<pawn>Function1()
{
new A;

if (A)
{
A = 5;
}
}</pawn>

Приведенный выше код является действительным, поскольку в область действия распространяется по всей функции. Однако этот код, работать не будет:
<pawn>
Function1()
{
new A;

if (A)
{
new B = 5;
}

B = 5;
}</pawn>

Отметим, что <tt>B</tt> объявляется в новом блоке кода. Это означает, что <tt>B</tt> доступна только в том блоке кода, в котором была создана (и всем под-блокам вложенных внутри него). Как только блок кода прекращается, <tt>B</tt> становится не действительной.

=Динамические массивы=
Динамические массивы это массивы, которые не имеют фиксированного размера. Например:

<pawn>Function1(size)
{
new array[size];

/* Код */
}</pawn>

Динамические массивы могут иметь любое выражение, соответствующее их размеру до тех пор, пока выражение вычисляется, как число большее чем 0. Как и для обычных массивов, SourcePawn не сможет узнать размер массива после того, как он будет создан; Вы должны задать его, если хотите использовать массив позднее.

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

=Расширенное объявление переменных=
Переменные могут быть объявлены более длинным путем чем просто <tt>new</tt>.

==decl==
===Назначение===
По умолчанию, все переменные в Pawn будут инициализированы как нуль. Если есть явная инициализация, переменная инициализируется для выражения <tt>=</tt> определенным символам. В локальной области действия, это может потребовать время на выполнение. Ключевое слово <tt>decl</tt> (которое действительно только в локальной области действия) было введено, чтобы позволить решать пользователю, хочит ли он инициализировать переменную или нет.

Примечание: <tt>decl</tt> не должно быть использовано на одну однострочную переменную. Это почти никогда не будет выгодно.

===Объяснение===
Например:

<pawn>
new c = 5;
new d;
new String:blah[512];

Format(blah, sizeof(blah), "%d %d", c, d);
</pawn>

В этом коде, <tt>c</tt> равна 5 и <tt>d</tt> равна 0. Во время выполнения этого кода затраты на инициализацию незначительные. Вместе с тем, <tt>blah</tt> является большим массивом, и затраты на инициализацию всего массива могут быть больше 0 сек. и иметь плохие последствия в определенных ситуациях.

Заметим, что <tt>blah</tt> не должен быть нулевой. В период времени с объявления <tt>new</tt> и и перемещения в <tt>Format()</tt>, массив <tt>blah</tt> никогда не будет загружен или прочитан. Данный код будет более эффективен, если будет написанный следующим образом:

<pawn>
new c = 5;
new d;
decl String:blah[512];

Format(blah, sizeof(blah), "%d %d", c, d);
</pawn>

===Предостережения===
Обратная сторона <tt>decl</tt> состоит в том, что его переменные будут начинаться с "ненужного" содержания. Например, если мы будем использовать:

<pawn>
new c = 5;
new d;
decl String:blah[512];

PrintToServer("%s", blah);

Format(blah, sizeof(blah), "%d %d", c, d);
</pawn>

Этот код может привести к падению сервера, так как массив <tt>blah</tt> может быть полностью испорчен (строки требуют нулевой символ, который может отсутствовать). Точно так же, если мы сделаем:

<pawn>
new c = 5;
decl d;
decl String:blah[512];

Format(blah, sizeof(blah), "%d %d", c, d);
</pawn>

Значение <tt>d</tt> в настоящее время не определенно. Оно может быть любым значением, отрицательным или положительным.

Заметим, что это легко и эффективно обезопасит строки. Пример ниже показывает, как предотвратить строки от мусора:
<pawn>
decl String:blah[512];

blah[0] = '\0';
</pawn>

===Золотые правила===
*'''Используйте decl только, если в период объявления и загрузки/чтения значения, Вы абсолютно уверены, что есть по крайней мере одно хранилище/операция, которая отдает переменной действительные данные.'''
*'''Не оптимизируйте преждевременно.''' Кроме того, нет необходимости использовать <tt>decl</tt> на не-массивы, поскольку нет никаких дополнительных затрат на инициализацию однго однострочного значения.

===Примечания===
Обратите внимание, что <tt>decl</tt> переменную инициализировать явно, но '''ТОЛЬКО''' как строку:
<pawn>
decl String:blah[512] = "a";
</pawn>

However, any other tag will fail to compile, because the purpose of <tt>decl</tt> is to avoid any initialization:
<pawn>
decl Float:blah[512] = {1.0};
</pawn>

Даже несмотря на то, что строка имеет только один символ, оператор <tt>new</tt> гарантирует, что остальная часть массива будет нулевой.

Также обратите внимание, он является неправильным для явной инициализации <tt>decl</tt>:
<pawn>decl String:blah[512] = "a";</pawn>

Приведенный выше код не будет компилироваться, потому что цель <tt>decl</tt> состоит в том, чтобы избежать каких-либо инициализаций.

==static==
Ключевое слово <tt>static</tt> входит в глобальную и локальную область действия. Оно имеет различные значения в каждой из них.

===Глобальный static===
Глобальные static переменные могут быть доступны только в рамках того же файла. Например:

<pawn>//file1.inc
static Float:g_value1 = 0.15f;

//file2.inc
static Float:g_value2 = 0.15f;</pawn>

Если плагин включает в себя оба этих файла, он не сможет использовать <tt>g_value1</tt> или <tt>g_value2</tt>. Это простой механизм сокрытия информации, и аналогичен элементам объявления переменных, например <tt>private</tt> в таких языках, как C++, Java, или C#.

===Локальный static===
Локальная static переменная является глобальной переменной, которая является видимой лишь из её местной области действия. Например:

<pawn>
MyFunction(inc)
{
static counter = -1;

counter += inc;

return counter;
}</pawn>

В этом примере, <tt>counter</tt> технически глобальная переменная -- она инициализируется один раз как -1 и никогда не инициализируется заново. Оно не существует в наборе. Это означает, что при каждом запуске функции <tt>MyFunction</tt>, переменная <tt>counter</tt> и ее хранение в памяти одно и тоже.

Возьмем следающий пример:
<pawn>MyFunction(5);
MyFunction(6);
MyFunction(10);</pawn>

В этом примере, <tt>counter</tt> может быть <tt>-1 +5 +6 +10</tt>, или <tt>20</tt>, поскольку она сохраняется за рамками этой функции. Это может создавать проблемы для рекурсивной функции: если ваша функция может быть рекурсивной, то <tt>static</tt>, как правило, не является хорошей идеей, если только Ваш код не реентерабельный.

Преимуществом локальных static переменных является то, что Вам не придется загромождать свой сценарий глобальными переменными. До тех пор, пока переменной не нужно читать другую функцию, Вы можете его пихать внутрь функции и её сохранение будет гарантировано.

Заметим, что statics может существовать в любой локальной области действия:

<pawn>
MyFunction(inc)
{
if (inc > 0)
{
static counter;
return (counter += inc);
}
return -1;
}</pawn>

[[Category:Ru:SourceMod Scripting]]

Ru:Introduction to SourceMod Plugins

2008-12-30T12:56:59Z

Frenzzy: /* Client and Entity Indexes */

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

Для получения информации о компиляции плагинов см. [[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] или любой другой текстовый редактор.

=Структура плагина=
Почти все плагины имеют три одинаковых элемента:
*'''Includes''' - Позволяет получить доступ к SourceMod API, и если Вы хотите, к API от внешних SourceMod плагинов и расширений.
*'''Info''' - Общественная информация о Вашем плагине.
*'''Startup''' - Функция, которая осуществляет запуск процедур в Вашем плагине.

Плагин скелетной структуры выглядит следующим образом:
<pawn>
#include <sourcemod>

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

public OnPluginStart()
{
// Выполнение единовременного запуска задач ...
}</pawn>

Информация часть имеет специальную синтаксическую конструкцию. Вы не можете изменить любое из ключевых слов, или объявление <tt>public Plugin:myinfo</tt>. Хорошая идея заключается в том, чтобы скопировать и вставить эту скелетную структуру и отредактировать строки, чтобы начать работу.

=Включения=
Pawn требует включать файлы '''include''', как и C требует наличие заголовка у файла. Включение списков файлов всех структур, функций, вызовы и тегов, которые имеются в наличии. Есть три типа файлов:
*'''Core''' - <tt>sourcemod.inc</tt>, и все его включения. Все представленные в SourceMod Core.
*'''Extension''' - добавляет зависимость от определенного расширения.
*'''Plugin''' - добавляет зависимость от некоторых плагинов.

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

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

==Описание==
Во-первых, давайте смотреть на то, какая команда требуется администратору. Команды администратора регистрируются с использованием функции [http://docs.sourcemod.net/api/index.php?fastload=show&id=471& RegAdminCmd]. Она требует '''название''', '''функцию обратного вызова''' и '''флаги админа по умолчанию'''.

Функция обратного вызова это то, на что ссылаться используемая команда каждый раз. [http://docs.sourcemod.net/api/index.php?fastload=show&id=469& Нажми здесь], чтобы просмотреть её прототип. Пример:

<pawn>
public OnPluginStart()
{
RegAdminCmd("sm_myslap", Command_MySlap, ADMFLAG_SLAY)
}

public Action:Command_MySlap(client, args)
{
}</pawn>

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

<pawn>public Action:Command_MySlap(client, args)
{
return Plugin_Handled;
}</pawn>

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

==Реализация==
Давайте решим, что команда будет выглядеть так. Пусть будет она действовать как команда по умолчанию <tt>sm_slap</tt>:
<pre>sm_myslap <name|#userid> [damage]</pre>

Чтобы осуществить это, Нам потребуется несколько шагов:
*Получить ввод с консоли. Для этого мы используем [http://docs.sourcemod.net/api/index.php?fastload=show&id=473& GetCmdArg()].
*Найти соответствия игрока. Для этого мы используем [http://docs.sourcemod.net/api/index.php?fastload=show&id=144& FindTarget()].
*Ударить его. Для этого мы используем [http://docs.sourcemod.net/api/index.php?fastload=show&id=42& SlapPlayer()], которая требует в том числе <tt>sdktools</tt> расширение в комплекте с SourceMod.
*Сообщить администратору. Для этого мы используем [http://docs.sourcemod.net/api/index.php?fastload=show&id=462& ReplyToCommand()].

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

<pawn>
#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;
}</pawn>

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

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

Удобная особенность ConVars заключается в том, что они легко настраиваются пользователями. Они могут быть помещены в любой .cfg файл, например <tt>server.cfg</tt> или <tt>sourcemod.cfg</tt>. Чтобы сделать удобнее их использование, SourceMod имеет [http://docs.sourcemod.net/api/index.php?fastload=show&id=607& AutoExecConfig()] функции. Эта функция автоматически создает .cfg файл по умолчанию, содержащий все Ваши переменные (cvars), снабженные комментариями для пользователей. Очень рекомендую Вам вызывать её, если у Вас есть настраиваемые ConVars.

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

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

/* Остальное остается без изменений! */
</pawn>

=Отображение активности, логирование=
Почти все команды администратора должны логировать (записывать в лог) их активность, а некоторые команды администратора должны отобразить свою активность в игре для клиентов. Это может быть сделано через [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> переменной.

Например, давайте перепишем несколько последних строк нашей slap команды:
<pawn>
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;
}
</pawn>

=Групповые цели=
Чтобы полностью завершить нашу демонстрацию slap, давайте сделаем поддержку нескольких целей. [[Admin_Commands_%28SourceMod%29#How_to_Target|Targeting system]] в SourceMod достаточно усовершенствована, её использование может показаться сложным на первый взгляд.

Мы используем функцию [http://docs.sourcemod.net/api/index.php?fastload=show&id=703& ProcessTargetString()]. Он принимает ввод с консоли, и возвращает список подходящих клиентов. Она также возвращает существительное, которые будет определять либо одного клиента или характеризовать список клиентов. Идея заключается в том, что каждый клиент будет обработан, но активность будет показана всем игрокам только один раз. Это уменьшит спам на экране.

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

Полный, окончательный пример:
<pawn>
#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;
}</pawn>

=Клиентский и объектный индексы=
Одним основным вопросом путаницы с Half-Life 2 является разница между следующими вещами:
*Индекс клиента (Client index)
*Индекс объекта (Entity index)
*Идентификатор пользователя (Userid)

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

Быстрый способ проверить является ли индекс объекта клиентом - проверить находится ли он между 1 и [http://docs.sourcemod.net/api/index.php?fastload=show&id=397& 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: [http://docs.sourcemod.net/api/index.php?fastload=show&id=442& GetClientOfUserId()] и [http://docs.sourcemod.net/api/index.php?fastload=show&id=402& GetClientUserId()].

=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]].

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>
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 */
}</pawn>

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

*[http://docs.sourcemod.net/api/index.php?fastload=show&id=576& AskPluginLoad()] - Called once, immediately after the plugin is loaded from the disk.
*[http://docs.sourcemod.net/api/index.php?fastload=show&id=575& 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()'''.
*[http://docs.sourcemod.net/api/index.php?fastload=show&id=580& 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().'''
*[http://docs.sourcemod.net/api/index.php?fastload=show&id=582& OnConfigsExecuted()] - Called once per map-change after <tt>servercfgfile</tt> (usually <tt>server.cfg</tt>), <tt>sourcemod.cfg</tt>, 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).
*[http://docs.sourcemod.net/api/index.php?fastload=show&id=581& OnMapEnd()] - Called when the map is about to end. At this point, all clients are disconnected, but <tt>TIMER_NO_MAPCHANGE</tt> timers are not yet destroyed. '''This function is paired to OnMapStart().'''
*[http://docs.sourcemod.net/api/index.php?fastload=show&id=577& 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.

*[http://docs.sourcemod.net/api/index.php?fastload=show&id=388& OnClientConnect()] - Called when a player initiates a connection. '''This is paired with OnClientDisconnect() for successful connections only.'''
*[http://docs.sourcemod.net/api/index.php?fastload=show&id=394& 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().
*[http://docs.sourcemod.net/api/index.php?fastload=show&id=389& OnClientPutInServer()] - Signifies that the player is in-game and IsClientInGame() will return true.
*[http://docs.sourcemod.net/api/index.php?fastload=show&id=396& 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.
*[http://docs.sourcemod.net/api/index.php?fastload=show&id=390& 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. <tt>#include <sourcemod></tt> will give you 95% of the .incs. Similarly, <tt>#include <sdktools></tt> 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 <tt>Plugin_Stop</tt> 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]].

[[Category:Ru:SourceMod Scripting]]

Ru:Introduction to SourceMod Plugins

2008-12-30T12:07:42Z

Frenzzy: /* Further Reading */

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

Для получения информации о компиляции плагинов см. [[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] или любой другой текстовый редактор.

=Структура плагина=
Почти все плагины имеют три одинаковых элемента:
*'''Includes''' - Позволяет получить доступ к SourceMod API, и если Вы хотите, к API от внешних SourceMod плагинов и расширений.
*'''Info''' - Общественная информация о Вашем плагине.
*'''Startup''' - Функция, которая осуществляет запуск процедур в Вашем плагине.

Плагин скелетной структуры выглядит следующим образом:
<pawn>
#include <sourcemod>

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

public OnPluginStart()
{
// Выполнение единовременного запуска задач ...
}</pawn>

Информация часть имеет специальную синтаксическую конструкцию. Вы не можете изменить любое из ключевых слов, или объявление <tt>public Plugin:myinfo</tt>. Хорошая идея заключается в том, чтобы скопировать и вставить эту скелетную структуру и отредактировать строки, чтобы начать работу.

=Включения=
Pawn требует включать файлы '''include''', как и C требует наличие заголовка у файла. Включение списков файлов всех структур, функций, вызовы и тегов, которые имеются в наличии. Есть три типа файлов:
*'''Core''' - <tt>sourcemod.inc</tt>, и все его включения. Все представленные в SourceMod Core.
*'''Extension''' - добавляет зависимость от определенного расширения.
*'''Plugin''' - добавляет зависимость от некоторых плагинов.

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

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

==Описание==
Во-первых, давайте смотреть на то, какая команда требуется администратору. Команды администратора регистрируются с использованием функции [http://docs.sourcemod.net/api/index.php?fastload=show&id=471& RegAdminCmd]. Она требует '''название''', '''функцию обратного вызова''' и '''флаги админа по умолчанию'''.

Функция обратного вызова это то, на что ссылаться используемая команда каждый раз. [http://docs.sourcemod.net/api/index.php?fastload=show&id=469& Нажми здесь], чтобы просмотреть её прототип. Пример:

<pawn>
public OnPluginStart()
{
RegAdminCmd("sm_myslap", Command_MySlap, ADMFLAG_SLAY)
}

public Action:Command_MySlap(client, args)
{
}</pawn>

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

<pawn>public Action:Command_MySlap(client, args)
{
return Plugin_Handled;
}</pawn>

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

==Реализация==
Давайте решим, что команда будет выглядеть так. Пусть будет она действовать как команда по умолчанию <tt>sm_slap</tt>:
<pre>sm_myslap <name|#userid> [damage]</pre>

Чтобы осуществить это, Нам потребуется несколько шагов:
*Получить ввод с консоли. Для этого мы используем [http://docs.sourcemod.net/api/index.php?fastload=show&id=473& GetCmdArg()].
*Найти соответствия игрока. Для этого мы используем [http://docs.sourcemod.net/api/index.php?fastload=show&id=144& FindTarget()].
*Ударить его. Для этого мы используем [http://docs.sourcemod.net/api/index.php?fastload=show&id=42& SlapPlayer()], которая требует в том числе <tt>sdktools</tt> расширение в комплекте с SourceMod.
*Сообщить администратору. Для этого мы используем [http://docs.sourcemod.net/api/index.php?fastload=show&id=462& ReplyToCommand()].

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

<pawn>
#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;
}</pawn>

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

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

Удобная особенность ConVars заключается в том, что они легко настраиваются пользователями. Они могут быть помещены в любой .cfg файл, например <tt>server.cfg</tt> или <tt>sourcemod.cfg</tt>. Чтобы сделать удобнее их использование, SourceMod имеет [http://docs.sourcemod.net/api/index.php?fastload=show&id=607& AutoExecConfig()] функции. Эта функция автоматически создает .cfg файл по умолчанию, содержащий все Ваши переменные (cvars), снабженные комментариями для пользователей. Очень рекомендую Вам вызывать её, если у Вас есть настраиваемые ConVars.

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

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

/* Остальное остается без изменений! */
</pawn>

=Отображение активности, логирование=
Почти все команды администратора должны логировать (записывать в лог) их активность, а некоторые команды администратора должны отобразить свою активность в игре для клиентов. Это может быть сделано через [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> переменной.

Например, давайте перепишем несколько последних строк нашей slap команды:
<pawn>
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;
}
</pawn>

=Групповые цели=
Чтобы полностью завершить нашу демонстрацию slap, давайте сделаем поддержку нескольких целей. [[Admin_Commands_%28SourceMod%29#How_to_Target|Targeting system]] в SourceMod достаточно усовершенствована, её использование может показаться сложным на первый взгляд.

Мы используем функцию [http://docs.sourcemod.net/api/index.php?fastload=show&id=703& ProcessTargetString()]. Он принимает ввод с консоли, и возвращает список подходящих клиентов. Она также возвращает существительное, которые будет определять либо одного клиента или характеризовать список клиентов. Идея заключается в том, что каждый клиент будет обработан, но активность будет показана всем игрокам только один раз. Это уменьшит спам на экране.

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

Полный, окончательный пример:
<pawn>
#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;
}</pawn>

=Client and Entity Indexes=
One major point of confusion with Half-Life 2 is the difference between the following things:
*Client index
*Entity index
*Userid

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.

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

A userid, on the other hand, is completely different. The 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.

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

=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]].

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>
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 */
}</pawn>

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

*[http://docs.sourcemod.net/api/index.php?fastload=show&id=576& AskPluginLoad()] - Called once, immediately after the plugin is loaded from the disk.
*[http://docs.sourcemod.net/api/index.php?fastload=show&id=575& 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()'''.
*[http://docs.sourcemod.net/api/index.php?fastload=show&id=580& 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().'''
*[http://docs.sourcemod.net/api/index.php?fastload=show&id=582& OnConfigsExecuted()] - Called once per map-change after <tt>servercfgfile</tt> (usually <tt>server.cfg</tt>), <tt>sourcemod.cfg</tt>, 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).
*[http://docs.sourcemod.net/api/index.php?fastload=show&id=581& OnMapEnd()] - Called when the map is about to end. At this point, all clients are disconnected, but <tt>TIMER_NO_MAPCHANGE</tt> timers are not yet destroyed. '''This function is paired to OnMapStart().'''
*[http://docs.sourcemod.net/api/index.php?fastload=show&id=577& 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.

*[http://docs.sourcemod.net/api/index.php?fastload=show&id=388& OnClientConnect()] - Called when a player initiates a connection. '''This is paired with OnClientDisconnect() for successful connections only.'''
*[http://docs.sourcemod.net/api/index.php?fastload=show&id=394& 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().
*[http://docs.sourcemod.net/api/index.php?fastload=show&id=389& OnClientPutInServer()] - Signifies that the player is in-game and IsClientInGame() will return true.
*[http://docs.sourcemod.net/api/index.php?fastload=show&id=396& 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.
*[http://docs.sourcemod.net/api/index.php?fastload=show&id=390& 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. <tt>#include <sourcemod></tt> will give you 95% of the .incs. Similarly, <tt>#include <sdktools></tt> 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 <tt>Plugin_Stop</tt> 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]].

[[Category:Ru:SourceMod Scripting]]

Ru:Introduction to SourceMod Plugins

2008-12-30T12:00:30Z

Frenzzy: /* Multiple Targets */

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

Для получения информации о компиляции плагинов см. [[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] или любой другой текстовый редактор.

=Структура плагина=
Почти все плагины имеют три одинаковых элемента:
*'''Includes''' - Позволяет получить доступ к SourceMod API, и если Вы хотите, к API от внешних SourceMod плагинов и расширений.
*'''Info''' - Общественная информация о Вашем плагине.
*'''Startup''' - Функция, которая осуществляет запуск процедур в Вашем плагине.

Плагин скелетной структуры выглядит следующим образом:
<pawn>
#include <sourcemod>

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

public OnPluginStart()
{
// Выполнение единовременного запуска задач ...
}</pawn>

Информация часть имеет специальную синтаксическую конструкцию. Вы не можете изменить любое из ключевых слов, или объявление <tt>public Plugin:myinfo</tt>. Хорошая идея заключается в том, чтобы скопировать и вставить эту скелетную структуру и отредактировать строки, чтобы начать работу.

=Включения=
Pawn требует включать файлы '''include''', как и C требует наличие заголовка у файла. Включение списков файлов всех структур, функций, вызовы и тегов, которые имеются в наличии. Есть три типа файлов:
*'''Core''' - <tt>sourcemod.inc</tt>, и все его включения. Все представленные в SourceMod Core.
*'''Extension''' - добавляет зависимость от определенного расширения.
*'''Plugin''' - добавляет зависимость от некоторых плагинов.

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

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

==Описание==
Во-первых, давайте смотреть на то, какая команда требуется администратору. Команды администратора регистрируются с использованием функции [http://docs.sourcemod.net/api/index.php?fastload=show&id=471& RegAdminCmd]. Она требует '''название''', '''функцию обратного вызова''' и '''флаги админа по умолчанию'''.

Функция обратного вызова это то, на что ссылаться используемая команда каждый раз. [http://docs.sourcemod.net/api/index.php?fastload=show&id=469& Нажми здесь], чтобы просмотреть её прототип. Пример:

<pawn>
public OnPluginStart()
{
RegAdminCmd("sm_myslap", Command_MySlap, ADMFLAG_SLAY)
}

public Action:Command_MySlap(client, args)
{
}</pawn>

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

<pawn>public Action:Command_MySlap(client, args)
{
return Plugin_Handled;
}</pawn>

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

==Реализация==
Давайте решим, что команда будет выглядеть так. Пусть будет она действовать как команда по умолчанию <tt>sm_slap</tt>:
<pre>sm_myslap <name|#userid> [damage]</pre>

Чтобы осуществить это, Нам потребуется несколько шагов:
*Получить ввод с консоли. Для этого мы используем [http://docs.sourcemod.net/api/index.php?fastload=show&id=473& GetCmdArg()].
*Найти соответствия игрока. Для этого мы используем [http://docs.sourcemod.net/api/index.php?fastload=show&id=144& FindTarget()].
*Ударить его. Для этого мы используем [http://docs.sourcemod.net/api/index.php?fastload=show&id=42& SlapPlayer()], которая требует в том числе <tt>sdktools</tt> расширение в комплекте с SourceMod.
*Сообщить администратору. Для этого мы используем [http://docs.sourcemod.net/api/index.php?fastload=show&id=462& ReplyToCommand()].

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

<pawn>
#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;
}</pawn>

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

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

Удобная особенность ConVars заключается в том, что они легко настраиваются пользователями. Они могут быть помещены в любой .cfg файл, например <tt>server.cfg</tt> или <tt>sourcemod.cfg</tt>. Чтобы сделать удобнее их использование, SourceMod имеет [http://docs.sourcemod.net/api/index.php?fastload=show&id=607& AutoExecConfig()] функции. Эта функция автоматически создает .cfg файл по умолчанию, содержащий все Ваши переменные (cvars), снабженные комментариями для пользователей. Очень рекомендую Вам вызывать её, если у Вас есть настраиваемые ConVars.

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

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

/* Остальное остается без изменений! */
</pawn>

=Отображение активности, логирование=
Почти все команды администратора должны логировать (записывать в лог) их активность, а некоторые команды администратора должны отобразить свою активность в игре для клиентов. Это может быть сделано через [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> переменной.

Например, давайте перепишем несколько последних строк нашей slap команды:
<pawn>
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;
}
</pawn>

=Групповые цели=
Чтобы полностью завершить нашу демонстрацию slap, давайте сделаем поддержку нескольких целей. [[Admin_Commands_%28SourceMod%29#How_to_Target|Targeting system]] в SourceMod достаточно усовершенствована, её использование может показаться сложным на первый взгляд.

Мы используем функцию [http://docs.sourcemod.net/api/index.php?fastload=show&id=703& ProcessTargetString()]. Он принимает ввод с консоли, и возвращает список подходящих клиентов. Она также возвращает существительное, которые будет определять либо одного клиента или характеризовать список клиентов. Идея заключается в том, что каждый клиент будет обработан, но активность будет показана всем игрокам только один раз. Это уменьшит спам на экране.

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

Полный, окончательный пример:
<pawn>
#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;
}</pawn>

=Client and Entity Indexes=
One major point of confusion with Half-Life 2 is the difference between the following things:
*Client index
*Entity index
*Userid

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.

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

A userid, on the other hand, is completely different. The 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.

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

=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]].

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>
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 */
}</pawn>

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

*[http://docs.sourcemod.net/api/index.php?fastload=show&id=576& AskPluginLoad()] - Called once, immediately after the plugin is loaded from the disk.
*[http://docs.sourcemod.net/api/index.php?fastload=show&id=575& 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()'''.
*[http://docs.sourcemod.net/api/index.php?fastload=show&id=580& 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().'''
*[http://docs.sourcemod.net/api/index.php?fastload=show&id=582& OnConfigsExecuted()] - Called once per map-change after <tt>servercfgfile</tt> (usually <tt>server.cfg</tt>), <tt>sourcemod.cfg</tt>, 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).
*[http://docs.sourcemod.net/api/index.php?fastload=show&id=581& OnMapEnd()] - Called when the map is about to end. At this point, all clients are disconnected, but <tt>TIMER_NO_MAPCHANGE</tt> timers are not yet destroyed. '''This function is paired to OnMapStart().'''
*[http://docs.sourcemod.net/api/index.php?fastload=show&id=577& 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.

*[http://docs.sourcemod.net/api/index.php?fastload=show&id=388& OnClientConnect()] - Called when a player initiates a connection. '''This is paired with OnClientDisconnect() for successful connections only.'''
*[http://docs.sourcemod.net/api/index.php?fastload=show&id=394& 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().
*[http://docs.sourcemod.net/api/index.php?fastload=show&id=389& OnClientPutInServer()] - Signifies that the player is in-game and IsClientInGame() will return true.
*[http://docs.sourcemod.net/api/index.php?fastload=show&id=396& 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.
*[http://docs.sourcemod.net/api/index.php?fastload=show&id=390& 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. <tt>#include <sourcemod></tt> will give you 95% of the .incs. Similarly, <tt>#include <sdktools></tt> 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 <tt>Plugin_Stop</tt> 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.

=Further Reading=
For further reading, see the "Scripting" section at the [http://docs.sourcemod.net/ SourceMod Documentation].

[[Category:Ru:SourceMod Scripting]]

Ru:Introduction to SourceMod Plugins

2008-12-30T11:54:41Z

Frenzzy: /* ConVars */

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

Для получения информации о компиляции плагинов см. [[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] или любой другой текстовый редактор.

=Структура плагина=
Почти все плагины имеют три одинаковых элемента:
*'''Includes''' - Позволяет получить доступ к SourceMod API, и если Вы хотите, к API от внешних SourceMod плагинов и расширений.
*'''Info''' - Общественная информация о Вашем плагине.
*'''Startup''' - Функция, которая осуществляет запуск процедур в Вашем плагине.

Плагин скелетной структуры выглядит следующим образом:
<pawn>
#include <sourcemod>

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

public OnPluginStart()
{
// Выполнение единовременного запуска задач ...
}</pawn>

Информация часть имеет специальную синтаксическую конструкцию. Вы не можете изменить любое из ключевых слов, или объявление <tt>public Plugin:myinfo</tt>. Хорошая идея заключается в том, чтобы скопировать и вставить эту скелетную структуру и отредактировать строки, чтобы начать работу.

=Включения=
Pawn требует включать файлы '''include''', как и C требует наличие заголовка у файла. Включение списков файлов всех структур, функций, вызовы и тегов, которые имеются в наличии. Есть три типа файлов:
*'''Core''' - <tt>sourcemod.inc</tt>, и все его включения. Все представленные в SourceMod Core.
*'''Extension''' - добавляет зависимость от определенного расширения.
*'''Plugin''' - добавляет зависимость от некоторых плагинов.

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

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

==Описание==
Во-первых, давайте смотреть на то, какая команда требуется администратору. Команды администратора регистрируются с использованием функции [http://docs.sourcemod.net/api/index.php?fastload=show&id=471& RegAdminCmd]. Она требует '''название''', '''функцию обратного вызова''' и '''флаги админа по умолчанию'''.

Функция обратного вызова это то, на что ссылаться используемая команда каждый раз. [http://docs.sourcemod.net/api/index.php?fastload=show&id=469& Нажми здесь], чтобы просмотреть её прототип. Пример:

<pawn>
public OnPluginStart()
{
RegAdminCmd("sm_myslap", Command_MySlap, ADMFLAG_SLAY)
}

public Action:Command_MySlap(client, args)
{
}</pawn>

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

<pawn>public Action:Command_MySlap(client, args)
{
return Plugin_Handled;
}</pawn>

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

==Реализация==
Давайте решим, что команда будет выглядеть так. Пусть будет она действовать как команда по умолчанию <tt>sm_slap</tt>:
<pre>sm_myslap <name|#userid> [damage]</pre>

Чтобы осуществить это, Нам потребуется несколько шагов:
*Получить ввод с консоли. Для этого мы используем [http://docs.sourcemod.net/api/index.php?fastload=show&id=473& GetCmdArg()].
*Найти соответствия игрока. Для этого мы используем [http://docs.sourcemod.net/api/index.php?fastload=show&id=144& FindTarget()].
*Ударить его. Для этого мы используем [http://docs.sourcemod.net/api/index.php?fastload=show&id=42& SlapPlayer()], которая требует в том числе <tt>sdktools</tt> расширение в комплекте с SourceMod.
*Сообщить администратору. Для этого мы используем [http://docs.sourcemod.net/api/index.php?fastload=show&id=462& ReplyToCommand()].

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

<pawn>
#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;
}</pawn>

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

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

Удобная особенность ConVars заключается в том, что они легко настраиваются пользователями. Они могут быть помещены в любой .cfg файл, например <tt>server.cfg</tt> или <tt>sourcemod.cfg</tt>. Чтобы сделать удобнее их использование, SourceMod имеет [http://docs.sourcemod.net/api/index.php?fastload=show&id=607& AutoExecConfig()] функции. Эта функция автоматически создает .cfg файл по умолчанию, содержащий все Ваши переменные (cvars), снабженные комментариями для пользователей. Очень рекомендую Вам вызывать её, если у Вас есть настраиваемые ConVars.

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

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

/* Остальное остается без изменений! */
</pawn>

=Отображение активности, логирование=
Почти все команды администратора должны логировать (записывать в лог) их активность, а некоторые команды администратора должны отобразить свою активность в игре для клиентов. Это может быть сделано через [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> переменной.

Например, давайте перепишем несколько последних строк нашей slap команды:
<pawn>
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;
}
</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.

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.

This method of target processing is used for almost every admin command in SourceMod, and in fact FindTarget() is just a simplified version.

Full, final example:
<pawn>
#include <sourcemod>
#include <sdktools>

new Handle:sm_myslap_damage = INVALID_HANDLE

public Plugin:myinfo =
{
name = "My First Plugin",
author = "Me",
description = "My first plugin ever",
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", "Default slap damage")
AutoExecConfig(true, "plugin_myslap")
}

public Action:Command_MySlap(client, args)
{
new String:arg1[32], String:arg2[32]
new damage = GetConVarInt(sm_myslap_damage)

/* Get the first argument */
GetCmdArg(1, arg1, sizeof(arg1))

/* If there are 2 or more arguments, and the second argument fetch
* is successful, convert it to an integer.
*/
if (args >= 2 && GetCmdArg(2, arg2, sizeof(arg2)))
{
damage = StringToInt(arg2)
}

/**
* target_name - stores the noun identifying the target(s)
* target_list - array to store clients
* target_count - variable to store number of clients
* tn_is_ml - stores whether the noun must be translated
*/
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, /* Only allow alive players */
target_name,
sizeof(target_name),
tn_is_ml)) <= 0)
{
/* This function replies to the admin with a failure message */
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;
}</pawn>

=Client and Entity Indexes=
One major point of confusion with Half-Life 2 is the difference between the following things:
*Client index
*Entity index
*Userid

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.

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

A userid, on the other hand, is completely different. The 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.

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

=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]].

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>
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 */
}</pawn>

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

*[http://docs.sourcemod.net/api/index.php?fastload=show&id=576& AskPluginLoad()] - Called once, immediately after the plugin is loaded from the disk.
*[http://docs.sourcemod.net/api/index.php?fastload=show&id=575& 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()'''.
*[http://docs.sourcemod.net/api/index.php?fastload=show&id=580& 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().'''
*[http://docs.sourcemod.net/api/index.php?fastload=show&id=582& OnConfigsExecuted()] - Called once per map-change after <tt>servercfgfile</tt> (usually <tt>server.cfg</tt>), <tt>sourcemod.cfg</tt>, 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).
*[http://docs.sourcemod.net/api/index.php?fastload=show&id=581& OnMapEnd()] - Called when the map is about to end. At this point, all clients are disconnected, but <tt>TIMER_NO_MAPCHANGE</tt> timers are not yet destroyed. '''This function is paired to OnMapStart().'''
*[http://docs.sourcemod.net/api/index.php?fastload=show&id=577& 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.

*[http://docs.sourcemod.net/api/index.php?fastload=show&id=388& OnClientConnect()] - Called when a player initiates a connection. '''This is paired with OnClientDisconnect() for successful connections only.'''
*[http://docs.sourcemod.net/api/index.php?fastload=show&id=394& 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().
*[http://docs.sourcemod.net/api/index.php?fastload=show&id=389& OnClientPutInServer()] - Signifies that the player is in-game and IsClientInGame() will return true.
*[http://docs.sourcemod.net/api/index.php?fastload=show&id=396& 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.
*[http://docs.sourcemod.net/api/index.php?fastload=show&id=390& 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. <tt>#include <sourcemod></tt> will give you 95% of the .incs. Similarly, <tt>#include <sdktools></tt> 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 <tt>Plugin_Stop</tt> 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.

=Further Reading=
For further reading, see the "Scripting" section at the [http://docs.sourcemod.net/ SourceMod Documentation].

[[Category:Ru:SourceMod Scripting]]

Ru:Translations (SourceMod Scripting)

2008-12-30T11:34:58Z

Frenzzy: /* Использование в плагине */

__FORCETOC__
[[SourceMod]], так же как и его предшественник AMX Mod X, содержит встроенный Multi-Lingual Translation layer ("ML"). Система ML является одной из дополнительных SourceMod систем, предназначенная для повышения гибкости платформы, насколько это возможно. Она полностью поддерживает UTF-8.

=Введение=
Система SourceMod ML базируется на следующих терминах:
*'''Языки''': Предварительно заданные языки перевода устанавливаются в <tt>configs\languages.cfg</tt>. Если язык перевода отсутствует в этом файле, он не может быть переведен до тех пор, пока не будет добавлен в этот файл и обновлена кэш-память переводов.
*'''Фразы'''/'''Ключи перевода''': Короткие, общие ключевые фразы, используемые для определения набора переводов. Они находятся в конфигурационных файлах в папке <tt>translations</tt>. Они называются <tt>файлы перевода</tt>.
*'''Переводы''': Содержат фразы текста перевода для данного языка. Они находятся в <tt>файлах перевода</tt>.

'''Примечание''': Переводы и Фразы, чувствительны к регистру.

==Формат файла==
Многоязычный формат файлов перевода содержится в стандартной конфигурационной форме от Valve. Она состоит из одного главного раздела, <tt>"Phrases"</tt>, который содержит любое число имен подразделов. Каждый подраздел определяется одним именем <tt>Фразы</tt>, и не могут иметь в себе подразделы. Они обладают следующими свойствами:
*'''Ключ''': "#format"
**'''Значение''': Разделенные запятыми, пары индексов и форматов
*'''Ключ''': Двух символьный код языка.
**'''Значение''': Языковой перевод строки.

Пример:
<pre>"Phrases"
{
"Welcome"
{
"en" "Welcome to SourceMod"
"ru" "Добро пожаловать в SourceMod"
}
}</pre>

В приведенном выше примере, два перевода определяется по имени фразы "Welcome" - одна для английского, и одна для русского языка. Вместе с тем, рассмотрим фразу, которая может вставлять определенные слова, как в этом примере:
<pre>"Phrases"
{
"Pants"
{
"en" "pants"
"ru" "трусы"
}
//НЕПРАВИЛЬНЫЙ ПРИМЕР: "Frenzzy трусы горят!"
"OnFire_plural"
{
"en" "%s's %s are on fire!"
"ru" "%s %s горят!"
}
}</pre>

В приведенном Выше примере, порядок слов изменился. Фраза на английском вставляет объект первым, а фраза на русском предписывает объект вторым. На русском языке фраза должна выглядеть следующим образом: ''Трусы Frenzzy горят!''. Это создает проблему для скриптов, которые всегда просматривают формат параметров в одном порядке. Чтобы решить эту проблему, было введено свойство <tt>#format</tt>. Оно предопределяет порядок формата параметров. Пример:
<pre>"Phrases"
{
//Пример: "Трусы Frenzzy горят!"
"OnFire_plural"
{
"#format" "{1:s},{2:s}"
"en" "{1}'s {2} are on fire!"
"ru" "{2} {1} горят!"
}
//Пример: "Привет, Frenzzy!"
"Hello"
{
"#format" "{1:s}"
"en" "Hello, {1}"
"ru" "Привет, {1}"
}
}</pre>

Формат строки состоит из разделов которые разделяются запятыми, а каждый раздел заключен в скобках. Каждый раздел имеет ''индекс'' и ''спецификатор формата'', которые разделяются двоеточиями. Спецификаторы формата следуют общим правилам [[Ru:Format Class Functions (SourceMod Scripting)|форматирования]], однако в настоящее время, они поддерживаются только в следующих видах:
*'''d'''/'''i''': Отображение десятичных/целых значений
*'''x''': Отображение шестнадцатеричных значений
*'''f''': Отображение числа с плавающей точкой
*'''s''': Отображение строки
*'''c''': Отображение символов (поддерживается UTF-8)

Заметим, что в настоящее время специальный формат типа "%T" не допускает внутри языка перевод строки.

=Использование в плагине=
Плагины должны вызывать функцию <tt>LoadTranslations</tt> на каждый файл с переводом, который они хотят использовать. Если это не будет сделано, то никакие переводы работать не будут, даже если другой плагин загрузил те же самые файлы. Это поможет предотвратить конфликты фраз между плагинами.

'''Примечание''': языковые файлы загружаться после каждой смены карты (mapchange). Даже если плагин будет перезагружен, кэшированный перевод файлов остается до следующей карты.

Встроенный перевод работает в любых [[Ru:Format Class Functions (SourceMod Scripting)|формат-классовых]] функциях. Вводится новый спецификатор формата '%T', который указывает формат вставки определенного перевода фразы. В отличие от всех других спецификаторов формата, он требует как минимум двух параметров:
*'''1-ый параметр''': Строка, содержащая фразу для перевода.
*'''2-ой параметр''': Одно из следующих:
**Постоянная <tt>LANG_SERVER</tt>, которая определяет язык перевода по умолчанию.
**Константа player ID, которая определяет язык перевода установленный игроком.
*'''3-ий параметр и больше''': Вывод во фразе спецификаторов формата, если это необходимо.

Примерами являются:
<pawn>new String:name[32], String:buffer[128];
GetClientName(client, name, sizeof(name));
PrintToChat(client, "[SourceMod] %T", "Hello", client, name);
Format(buffer, sizeof(buffer), "[SourceMod] %T", "Hello", LANG_SERVER, name);</pawn>

Формат параметров в отдельности:
*<tt>"Hello"</tt>: Фраза для перевода.
*<tt>client/LANG_SERVER</tt>: Кто получит перевод фразы.
*<tt>name</tt>: The "Hello" phrase requires one string, so this will appear in the translated phrase.

Наконец, существует вторая форма однострочного перевода, используя '%t'. Она допускается только в функциях, которые действуют непосредственно на одного или нескольких клиентов. Она исключает второй параметр, и использует указанного клиента. Пример:
<pawn>PrintToChat(client, "[SourceMod] %t", "Hello", name);</pawn>

Как видно из этого примера, Мы не должны указывать индекс клиента больше, чем один раз. Таким образом, как правило, более удобны для использования ограниченные версии '%t' в функциях, таких как <tt>PrintToChat</tt>. Однако, в функциях, которые не "управляют игроком", таких, как <tt>Format</tt> или <tt>PrintToServer</tt>, может быть использован только '%T'.

[[Category:Ru:SourceMod Scripting]]

Ru:Translations (SourceMod Scripting)

2008-12-30T11:34:34Z

Frenzzy: /* Usage in a Plugin */

__FORCETOC__
[[SourceMod]], так же как и его предшественник AMX Mod X, содержит встроенный Multi-Lingual Translation layer ("ML"). Система ML является одной из дополнительных SourceMod систем, предназначенная для повышения гибкости платформы, насколько это возможно. Она полностью поддерживает UTF-8.

=Введение=
Система SourceMod ML базируется на следующих терминах:
*'''Языки''': Предварительно заданные языки перевода устанавливаются в <tt>configs\languages.cfg</tt>. Если язык перевода отсутствует в этом файле, он не может быть переведен до тех пор, пока не будет добавлен в этот файл и обновлена кэш-память переводов.
*'''Фразы'''/'''Ключи перевода''': Короткие, общие ключевые фразы, используемые для определения набора переводов. Они находятся в конфигурационных файлах в папке <tt>translations</tt>. Они называются <tt>файлы перевода</tt>.
*'''Переводы''': Содержат фразы текста перевода для данного языка. Они находятся в <tt>файлах перевода</tt>.

'''Примечание''': Переводы и Фразы, чувствительны к регистру.

==Формат файла==
Многоязычный формат файлов перевода содержится в стандартной конфигурационной форме от Valve. Она состоит из одного главного раздела, <tt>"Phrases"</tt>, который содержит любое число имен подразделов. Каждый подраздел определяется одним именем <tt>Фразы</tt>, и не могут иметь в себе подразделы. Они обладают следующими свойствами:
*'''Ключ''': "#format"
**'''Значение''': Разделенные запятыми, пары индексов и форматов
*'''Ключ''': Двух символьный код языка.
**'''Значение''': Языковой перевод строки.

Пример:
<pre>"Phrases"
{
"Welcome"
{
"en" "Welcome to SourceMod"
"ru" "Добро пожаловать в SourceMod"
}
}</pre>

В приведенном выше примере, два перевода определяется по имени фразы "Welcome" - одна для английского, и одна для русского языка. Вместе с тем, рассмотрим фразу, которая может вставлять определенные слова, как в этом примере:
<pre>"Phrases"
{
"Pants"
{
"en" "pants"
"ru" "трусы"
}
//НЕПРАВИЛЬНЫЙ ПРИМЕР: "Frenzzy трусы горят!"
"OnFire_plural"
{
"en" "%s's %s are on fire!"
"ru" "%s %s горят!"
}
}</pre>

В приведенном Выше примере, порядок слов изменился. Фраза на английском вставляет объект первым, а фраза на русском предписывает объект вторым. На русском языке фраза должна выглядеть следующим образом: ''Трусы Frenzzy горят!''. Это создает проблему для скриптов, которые всегда просматривают формат параметров в одном порядке. Чтобы решить эту проблему, было введено свойство <tt>#format</tt>. Оно предопределяет порядок формата параметров. Пример:
<pre>"Phrases"
{
//Пример: "Трусы Frenzzy горят!"
"OnFire_plural"
{
"#format" "{1:s},{2:s}"
"en" "{1}'s {2} are on fire!"
"ru" "{2} {1} горят!"
}
//Пример: "Привет, Frenzzy!"
"Hello"
{
"#format" "{1:s}"
"en" "Hello, {1}"
"ru" "Привет, {1}"
}
}</pre>

Формат строки состоит из разделов которые разделяются запятыми, а каждый раздел заключен в скобках. Каждый раздел имеет ''индекс'' и ''спецификатор формата'', которые разделяются двоеточиями. Спецификаторы формата следуют общим правилам [[Ru:Format Class Functions (SourceMod Scripting)|форматирования]], однако в настоящее время, они поддерживаются только в следующих видах:
*'''d'''/'''i''': Отображение десятичных/целых значений
*'''x''': Отображение шестнадцатеричных значений
*'''f''': Отображение числа с плавающей точкой
*'''s''': Отображение строки
*'''c''': Отображение символов (поддерживается UTF-8)

Заметим, что в настоящее время специальный формат типа "%T" не допускает внутри языка перевод строки.

=Использование в плагине=
Плагины должны вызывать функцию <tt>LoadTranslations</tt> на каждый файл с переводом, который они хотят использовать. Если это не будет сделано, то никакие переводы работать не будут, даже если другой плагин загрузил те же самые файлы. Это поможет предотвратить конфликты фраз между плагинами.

'''Примечание''': языковые файлы загружаться после каждой смены карты (mapchange). Даже если плагин будет перезагружен, кэшированный перевод файлов остается до следующей карты.

Встроенный перевод работает в любых [[Ru:Format Class Functions (SourceMod Scripting)|формат-классовых]] функциях. Вводится новый спецификатор формата '%T', который указывает формат вставки определенного перевода фразы. В отличие от всех других спецификаторов формата, он требует как минимум двух параметров:
*'''1-ый параметр''': Строка, содержащая фразу для перевода.
*'''2-ой параметр''': Одно из следующих:
**Постоянная <tt>LANG_SERVER</tt>, которая определяет язык перевода по умолчанию.
**Константа player ID, которая определяет язык перевода установленный игроком.
*'''3-ий параметр и выше''': Вывод во фразе спецификаторов формата, если это необходимо.

Примерами являются:
<pawn>new String:name[32], String:buffer[128];
GetClientName(client, name, sizeof(name));
PrintToChat(client, "[SourceMod] %T", "Hello", client, name);
Format(buffer, sizeof(buffer), "[SourceMod] %T", "Hello", LANG_SERVER, name);</pawn>

Формат параметров в отдельности:
*<tt>"Hello"</tt>: Фраза для перевода.
*<tt>client/LANG_SERVER</tt>: Кто получит перевод фразы.
*<tt>name</tt>: The "Hello" phrase requires one string, so this will appear in the translated phrase.

Наконец, существует вторая форма однострочного перевода, используя '%t'. Она допускается только в функциях, которые действуют непосредственно на одного или нескольких клиентов. Она исключает второй параметр, и использует указанного клиента. Пример:
<pawn>PrintToChat(client, "[SourceMod] %t", "Hello", name);</pawn>

Как видно из этого примера, Мы не должны указывать индекс клиента больше, чем один раз. Таким образом, как правило, более удобны для использования ограниченные версии '%t' в функциях, таких как <tt>PrintToChat</tt>. Однако, в функциях, которые не "управляют игроком", таких, как <tt>Format</tt> или <tt>PrintToServer</tt>, может быть использован только '%T'.

[[Category:Ru:SourceMod Scripting]]

Ru:Translations (SourceMod Scripting)

2008-12-30T10:50:06Z

Frenzzy: /* Формат файла */

__FORCETOC__
[[SourceMod]], так же как и его предшественник AMX Mod X, содержит встроенный Multi-Lingual Translation layer ("ML"). Система ML является одной из дополнительных SourceMod систем, предназначенная для повышения гибкости платформы, насколько это возможно. Она полностью поддерживает UTF-8.

=Введение=
Система SourceMod ML базируется на следующих терминах:
*'''Языки''': Предварительно заданные языки перевода устанавливаются в <tt>configs\languages.cfg</tt>. Если язык перевода отсутствует в этом файле, он не может быть переведен до тех пор, пока не будет добавлен в этот файл и обновлена кэш-память переводов.
*'''Фразы'''/'''Ключи перевода''': Короткие, общие ключевые фразы, используемые для определения набора переводов. Они находятся в конфигурационных файлах в папке <tt>translations</tt>. Они называются <tt>файлы перевода</tt>.
*'''Переводы''': Содержат фразы текста перевода для данного языка. Они находятся в <tt>файлах перевода</tt>.

'''Примечание''': Переводы и Фразы, чувствительны к регистру.

==Формат файла==
Многоязычный формат файлов перевода содержится в стандартной конфигурационной форме от Valve. Она состоит из одного главного раздела, <tt>"Phrases"</tt>, который содержит любое число имен подразделов. Каждый подраздел определяется одним именем <tt>Фразы</tt>, и не могут иметь в себе подразделы. Они обладают следующими свойствами:
*'''Ключ''': "#format"
**'''Значение''': Разделенные запятыми, пары индексов и форматов
*'''Ключ''': Двух символьный код языка.
**'''Значение''': Языковой перевод строки.

Пример:
<pre>"Phrases"
{
"Welcome"
{
"en" "Welcome to SourceMod"
"ru" "Добро пожаловать в SourceMod"
}
}</pre>

В приведенном выше примере, два перевода определяется по имени фразы "Welcome" - одна для английского, и одна для русского языка. Вместе с тем, рассмотрим фразу, которая может вставлять определенные слова, как в этом примере:
<pre>"Phrases"
{
"Pants"
{
"en" "pants"
"ru" "трусы"
}
//НЕПРАВИЛЬНЫЙ ПРИМЕР: "Frenzzy трусы горят!"
"OnFire_plural"
{
"en" "%s's %s are on fire!"
"ru" "%s %s горят!"
}
}</pre>

В приведенном Выше примере, порядок слов изменился. Фраза на английском вставляет объект первым, а фраза на русском предписывает объект вторым. На русском языке фраза должна выглядеть следующим образом: ''Трусы Frenzzy горят!''. Это создает проблему для скриптов, которые всегда просматривают формат параметров в одном порядке. Чтобы решить эту проблему, было введено свойство <tt>#format</tt>. Оно предопределяет порядок формата параметров. Пример:
<pre>"Phrases"
{
//Пример: "Трусы Frenzzy горят!"
"OnFire_plural"
{
"#format" "{1:s},{2:s}"
"en" "{1}'s {2} are on fire!"
"ru" "{2} {1} горят!"
}
//Пример: "Привет, Frenzzy!"
"Hello"
{
"#format" "{1:s}"
"en" "Hello, {1}"
"ru" "Привет, {1}"
}
}</pre>

Формат строки состоит из разделов которые разделяются запятыми, а каждый раздел заключен в скобках. Каждый раздел имеет ''индекс'' и ''спецификатор формата'', которые разделяются двоеточиями. Спецификаторы формата следуют общим правилам [[Ru:Format Class Functions (SourceMod Scripting)|форматирования]], однако в настоящее время, они поддерживаются только в следующих видах:
*'''d'''/'''i''': Отображение десятичных/целых значений
*'''x''': Отображение шестнадцатеричных значений
*'''f''': Отображение числа с плавающей точкой
*'''s''': Отображение строки
*'''c''': Отображение символов (поддерживается UTF-8)

Заметим, что в настоящее время специальный формат типа "%T" не допускает внутри языка перевод строки.

=Usage in a Plugin=
Plugins must call <tt>LoadTranslations</tt> on each translation file they wish to use. Failure to do so will cause any translations to fail, even if another plugin loads the same file. This is to help prevent phrase-clashes between plugins.

'''Note''': Language files are reloaded every mapchange. Even if the plugin gets reloaded, the translation file stays cached until next map.

Inline translation works in any [[Format Class Functions (SourceMod Scripting)|format-class]] of functions. A new format specifier, '%T', is introduced, which instructs the format routine to insert a translated phrase. Unlike all other format specifiers, this requires a minimum of two parameters:
*'''1st Parameter''': A string containing the phrase to be translated.
*'''2nd Parameter''': One of the following:
**The <tt>LANG_SERVER</tt> constant, which specifies a translation to the default language.
**A player ID constant, which specifies a translation to the player's set language.
*'''3rd Parameter and higher''': Inputs into the phrase's format specifiers, if necessary.

Examples of this are:
<pawn>new String:name[32], String:buffer[128];
GetClientName(client, name, sizeof(name));
PrintToChat(client, "[SourceMod] %T", "Hello", client, name);
Format(buffer, sizeof(buffer), "[SourceMod] %T", "Hello", LANG_SERVER, name);</pawn>

A breakdown of the format parameters:
*<tt>"Hello"</tt>: The phrase to translate.
*<tt>client/LANG_SERVER</tt>: Who to translate the phrase to.
*<tt>name</tt>: The "Hello" phrase requires one string, so this will appear in the translated phrase.

Lastly, there is a second form of inline translation, using '%t'. This is only allowed in functions which act directly on one or more clients. It eliminates the second parameter, and uses the original client specified. Example:
<pawn>PrintToChat(client, "[SourceMod] %t", "Hello", name);</pawn>

As you can see from this example, we did not have to specify the client index more than once. Thus, it is usually more convenient to use the limited '%t' version in functions such as <tt>PrintToChat</tt>. However, in functions which are not "player directed," such as <tt>Format</tt> or <tt>PrintToServer</tt>, only '%T' can be used.

[[Category:Ru:SourceMod Scripting]]

Ru:Translations (SourceMod Scripting)

2008-12-30T10:48:58Z

Frenzzy: /* Формат файла */

__FORCETOC__
[[SourceMod]], так же как и его предшественник AMX Mod X, содержит встроенный Multi-Lingual Translation layer ("ML"). Система ML является одной из дополнительных SourceMod систем, предназначенная для повышения гибкости платформы, насколько это возможно. Она полностью поддерживает UTF-8.

=Введение=
Система SourceMod ML базируется на следующих терминах:
*'''Языки''': Предварительно заданные языки перевода устанавливаются в <tt>configs\languages.cfg</tt>. Если язык перевода отсутствует в этом файле, он не может быть переведен до тех пор, пока не будет добавлен в этот файл и обновлена кэш-память переводов.
*'''Фразы'''/'''Ключи перевода''': Короткие, общие ключевые фразы, используемые для определения набора переводов. Они находятся в конфигурационных файлах в папке <tt>translations</tt>. Они называются <tt>файлы перевода</tt>.
*'''Переводы''': Содержат фразы текста перевода для данного языка. Они находятся в <tt>файлах перевода</tt>.

'''Примечание''': Переводы и Фразы, чувствительны к регистру.

==Формат файла==
Многоязычный формат файлов перевода содержится в стандартной конфигурационной форме от Valve. Она состоит из одного главного раздела, <tt>"Phrases"</tt>, который содержит любое число имен подразделов. Каждый подраздел определяется одним именем <tt>Фразы</tt>, и не могут иметь в себе подразделы. Они обладают следующими свойствами:
*'''Ключ''': "#format"
**'''Значение''': Разделенные запятыми, пары индексов и форматов
*'''Ключ''': Двух символьный код языка.
**'''Значение''': Языковой перевод строки.

Пример:
<pre>"Phrases"
{
"Welcome"
{
"en" "Welcome to SourceMod"
"ru" "Добро пожаловать в SourceMod"
}
}</pre>

В приведенном выше примере, два перевода определяется по имени фразы "Welcome" - одна для английского, и одна для русского языка. Вместе с тем, рассмотрим фразу, которая может вставлять определенные слова, как в этом примере:
<pre>"Phrases"
{
"Pants"
{
"en" "pants"
"ru" "трусы"
}
//НЕПРАВИЛЬНЫЙ ПРИМЕР: "Frenzzy трусы горят!"
"OnFire_plural"
{
"en" "%s's %s are on fire!"
"ru" "%s %s горят!"
}
}</pre>

В приведенном Выше примере, порядок слов изменился. Фраза на английском вставляет объект первым, а фраза на русском предписывает объект вторым. На русском языке фраза должна выглядеть следующим образом: ''Трусы Frenzzy горят!''. Это создает проблему для скриптов, которые всегда просматривают формат параметров в одном порядке. Чтобы решить эту проблему, было введено свойство <tt>#format</tt>. Оно предопределяет порядок формата параметров. Пример:
<pre>"Phrases"
{
//Пример: "Frenzzy трусы горят"
"OnFire_plural"
{
"#format" "{1:s},{2:s}"
"en" "{1}'s {2} are on fire!"
"es" "{2} {1} горят!"
}
//Пример: "Привет, Frenzzy!"
"Hello"
{
"#format" "{1:s}"
"en" "Hello, {1}"
"es" "Привет, {1}"
}
}</pre>

Формат строки состоит из разделов которые разделяются запятыми, а каждый раздел заключен в скобках. Каждый раздел имеет ''индекс'' и ''спецификатор формата'', которые разделяются двоеточиями. Спецификаторы формата следуют общим правилам [[Ru:Format Class Functions (SourceMod Scripting)|форматирования]], однако в настоящее время, они поддерживаются только в следующих видах:
*'''d'''/'''i''': Отображение десятичных/целых значений
*'''x''': Отображение шестнадцатеричных значений
*'''f''': Отображение числа с плавающей точкой
*'''s''': Отображение строки
*'''c''': Отображение символов (поддерживается UTF-8)

Заметим, что в настоящее время специальный формат типа "%T" не допускает внутри языка перевод строки.

=Usage in a Plugin=
Plugins must call <tt>LoadTranslations</tt> on each translation file they wish to use. Failure to do so will cause any translations to fail, even if another plugin loads the same file. This is to help prevent phrase-clashes between plugins.

'''Note''': Language files are reloaded every mapchange. Even if the plugin gets reloaded, the translation file stays cached until next map.

Inline translation works in any [[Format Class Functions (SourceMod Scripting)|format-class]] of functions. A new format specifier, '%T', is introduced, which instructs the format routine to insert a translated phrase. Unlike all other format specifiers, this requires a minimum of two parameters:
*'''1st Parameter''': A string containing the phrase to be translated.
*'''2nd Parameter''': One of the following:
**The <tt>LANG_SERVER</tt> constant, which specifies a translation to the default language.
**A player ID constant, which specifies a translation to the player's set language.
*'''3rd Parameter and higher''': Inputs into the phrase's format specifiers, if necessary.

Examples of this are:
<pawn>new String:name[32], String:buffer[128];
GetClientName(client, name, sizeof(name));
PrintToChat(client, "[SourceMod] %T", "Hello", client, name);
Format(buffer, sizeof(buffer), "[SourceMod] %T", "Hello", LANG_SERVER, name);</pawn>

A breakdown of the format parameters:
*<tt>"Hello"</tt>: The phrase to translate.
*<tt>client/LANG_SERVER</tt>: Who to translate the phrase to.
*<tt>name</tt>: The "Hello" phrase requires one string, so this will appear in the translated phrase.

Lastly, there is a second form of inline translation, using '%t'. This is only allowed in functions which act directly on one or more clients. It eliminates the second parameter, and uses the original client specified. Example:
<pawn>PrintToChat(client, "[SourceMod] %t", "Hello", name);</pawn>

As you can see from this example, we did not have to specify the client index more than once. Thus, it is usually more convenient to use the limited '%t' version in functions such as <tt>PrintToChat</tt>. However, in functions which are not "player directed," such as <tt>Format</tt> or <tt>PrintToServer</tt>, only '%T' can be used.

[[Category:Ru:SourceMod Scripting]]

Ru:Translations (SourceMod Scripting)

2008-12-30T10:43:03Z

Frenzzy: /* Введение */

__FORCETOC__
[[SourceMod]], так же как и его предшественник AMX Mod X, содержит встроенный Multi-Lingual Translation layer ("ML"). Система ML является одной из дополнительных SourceMod систем, предназначенная для повышения гибкости платформы, насколько это возможно. Она полностью поддерживает UTF-8.

=Введение=
Система SourceMod ML базируется на следующих терминах:
*'''Языки''': Предварительно заданные языки перевода устанавливаются в <tt>configs\languages.cfg</tt>. Если язык перевода отсутствует в этом файле, он не может быть переведен до тех пор, пока не будет добавлен в этот файл и обновлена кэш-память переводов.
*'''Фразы'''/'''Ключи перевода''': Короткие, общие ключевые фразы, используемые для определения набора переводов. Они находятся в конфигурационных файлах в папке <tt>translations</tt>. Они называются <tt>файлы перевода</tt>.
*'''Переводы''': Содержат фразы текста перевода для данного языка. Они находятся в <tt>файлах перевода</tt>.

'''Примечание''': Переводы и Фразы, чувствительны к регистру.

==Формат файла==
Многоязычный формат файлов перевода содержится в стандартной конфигурационной форме от Valve. Она состоит из одного главного раздела, <tt>"Phrases"</tt>, который содержит любое число имен подразделов. Каждый подраздел определяется одним именем <tt>Фразы</tt>, и не могут иметь в себе подразделы. Они обладают следующими свойствами:
*'''Key''': "#format"
**'''Value''': Comma-delimited, ordered pairs of indexes and format strings.
*'''Key''': Two-letter language code.
**'''Value''': Language translation string.

Пример:
<pre>"Phrases"
{
"Welcome"
{
"en" "Welcome to SourceMod"
"ru" "Добро пожаловать в SourceMod"
}
}</pre>

В приведенном выше примере, два перевода определяется по имени фразы "Welcome" - одна для английского, и одна для русского языка. Вместе с тем, рассмотрим фразу, которая может вставлять определенные слова, как в этом примере:
<pre>"Phrases"
{
"Pants"
{
"en" "pants"
"ru" "трусы"
}
//НЕПРАВИЛЬНЫЙ ПРИМЕР: "Frenzzy трусы горят!"
"OnFire_plural"
{
"en" "%s's %s are on fire!"
"ru" "%s %s горят!"
}
}</pre>

В приведенном Выше примере, порядок слов изменился. Фраза на английском вставляет объект первым, а фраза на русском предписывает объект вторым. На русском языке фраза должна выглядеть следующим образом: ''Трусы Frenzzy горят!''. Это создает проблему для скриптов, которые всегда просматривают формат параметров в одном порядке. Чтобы решить эту проблему, было введено свойство <tt>#format</tt>. Оно предопределяет порядок формата параметров. Пример:
<pre>"Phrases"
{
//Пример: "Frenzzy трусы горят"
"OnFire_plural"
{
"#format" "{1:s},{2:s}"
"en" "{1}'s {2} are on fire!"
"es" "{2} {1} горят!"
}
//Пример: "Привет, Frenzzy!"
"Hello"
{
"#format" "{1:s}"
"en" "Hello, {1}"
"es" "Привет, {1}"
}
}</pre>

Формат строки состоит из разделов которые разделяются запятыми, а каждый раздел заключен в скобках. Каждый раздел имеет ''индекс'' и ''спецификатор формата'', которые разделяются двоеточиями. Спецификаторы формата следуют общим правилам [[Ru:Format Class Functions (SourceMod Scripting)|форматирования]], однако в настоящее время, они поддерживаются только в следующих видах:
*'''d'''/'''i''': Отображение десятичных/целых значений
*'''x''': Отображение шестнадцатеричных значений
*'''f''': Отображение числа с плавающей точкой
*'''s''': Отображение строки
*'''c''': Отображение символов (поддерживается UTF-8)

Заметим, что в настоящее время специальный формат типа "%T" не допускает внутри языка перевод строки.

=Usage in a Plugin=
Plugins must call <tt>LoadTranslations</tt> on each translation file they wish to use. Failure to do so will cause any translations to fail, even if another plugin loads the same file. This is to help prevent phrase-clashes between plugins.

'''Note''': Language files are reloaded every mapchange. Even if the plugin gets reloaded, the translation file stays cached until next map.

Inline translation works in any [[Format Class Functions (SourceMod Scripting)|format-class]] of functions. A new format specifier, '%T', is introduced, which instructs the format routine to insert a translated phrase. Unlike all other format specifiers, this requires a minimum of two parameters:
*'''1st Parameter''': A string containing the phrase to be translated.
*'''2nd Parameter''': One of the following:
**The <tt>LANG_SERVER</tt> constant, which specifies a translation to the default language.
**A player ID constant, which specifies a translation to the player's set language.
*'''3rd Parameter and higher''': Inputs into the phrase's format specifiers, if necessary.

Examples of this are:
<pawn>new String:name[32], String:buffer[128];
GetClientName(client, name, sizeof(name));
PrintToChat(client, "[SourceMod] %T", "Hello", client, name);
Format(buffer, sizeof(buffer), "[SourceMod] %T", "Hello", LANG_SERVER, name);</pawn>

A breakdown of the format parameters:
*<tt>"Hello"</tt>: The phrase to translate.
*<tt>client/LANG_SERVER</tt>: Who to translate the phrase to.
*<tt>name</tt>: The "Hello" phrase requires one string, so this will appear in the translated phrase.

Lastly, there is a second form of inline translation, using '%t'. This is only allowed in functions which act directly on one or more clients. It eliminates the second parameter, and uses the original client specified. Example:
<pawn>PrintToChat(client, "[SourceMod] %t", "Hello", name);</pawn>

As you can see from this example, we did not have to specify the client index more than once. Thus, it is usually more convenient to use the limited '%t' version in functions such as <tt>PrintToChat</tt>. However, in functions which are not "player directed," such as <tt>Format</tt> or <tt>PrintToServer</tt>, only '%T' can be used.

[[Category:Ru:SourceMod Scripting]]

Ru:Translations (SourceMod Scripting)

2008-12-28T16:31:43Z

Frenzzy:

Ru:Format Class Functions (SourceMod Scripting)

2008-12-28T16:21:37Z

Frenzzy: /* Расширенный формат */

=Введение=
Формат классов функций, аргументов переменной - функции в [[SourceMod]] которые позволяют Вам форматировать строки. Простой пример этой <tt>Format()</tt> функции, выглядит следующим образом:

<pawn>decl String:buffer[512];
Format(buffer, sizeof(buffer), "Ваше имя: %s", userName);</pawn>

Если userName содержит "<tt>Frenzzy</tt>", содержимое <tt>buffer</tt> будет: "<tt>Ваше имя: Frenzzy</tt>". Прототип этих функций почти всегда содержит следующие параметры:
<pawn>const String:fmt[], {Handle,Float,_}:...</pawn>

Например, обратите внимание на эти два выражения:
<pawn>native Format(String:buffer[], maxlength, const String:fmt[], {Handle,Float,_}:...);
native PrintToClient(client, String:fmt[], {Handle,Float,_}:...);</pawn>

Таким образом, <tt>PrintToClient</tt> является формат-классовой функцией. Она может быть использована точно так же, как было показано ранее:
<pawn>PrintToClient(client, "Ваше имя: %s", userName);</pawn>

=Спецификаторы Формата=
Спецификаторы Формата имеют код, который позволяет указать, какие типы данных будут отображаться. Наиболее распространенными спецификаторами являются:
*'''Числовые'''
**'''d''' или '''i''': Целое число как десятичные
**'''b''': Бинарные символы в значении
**'''f''': Числа с плавающей точкой
**'''x''' or '''X''': Шестнадцатеричное представление бинарных значений (применение заглавных букв влияет на шестнадцатеричный регистр букв)
*'''Символ(ы)'''
**'''s''': Строка
**'''t''' или '''T''': Переводы фраз (см. в [[Translations (SourceMod_Scripting)#Inline_Translations|Inline Translations]])
**'''c''': Вывод одного символа (совместимо с UTF-8)
*'''Специальные'''
**'''L''': Требуется индекс клиента; расширяется до 1<2><3><>, где 1 - имя игрока, 2 - userid игрока, и 3 - Steam ID игрока. Если клиент имеет индекс 0, строка будет: <tt><nowiki>Console<0><Console><Console></nowiki></tt>
**'''N''': Требуется индекс клиента; расширяется до строки, содержащей имя игрока. Если клиент имеет индекс 0, строка будет: <tt>Console</tt>

=Испрльзование=
Спецификаторы формата обозначаются символом <tt>'%s'</tt>. Например, чтобы отобразилось число с плавающей точкой, десятичное число и строка, Вы можете использовать этот код:
<pawn>new Float:fNum = 5.0;
new iNum = 5
new String:str[] = "5"

PrintToClient(client, "Десятичное число: %d Число с плавающей точкой: %f Строка: %s", iNum, fNum, str);</pawn>

'''Примечание''': Использование неправильных типов данных спецификаторов может быть очень опасно. Всегда убедитесь, что выводится правильный тип. Например, указание строки и передача числа, может привести к падению сервера.

=Расширенный формат=
Спецификаторы формата имеют расширенный синтаксис для управления различными аспектами того, как будут выводиться данные.
Полный синтаксис: <tt>%[flags][width][.precision]specifier</tt>

Каждый раздел в квадратных скобках является дополнительным расширением. Описание поддерживаемых SourceMod расширений формата:
*'''%''': Очевидно, что это требуется всегда.
*'''flags''':
**'''-''': Выравнивание по левому краю (выравнивание по правому краю установлено по умолчанию)
**'''0''': Заполняет 0 вместо пробелов в случае необходимости (см. '''width''' ниже).
*'''width''': Минимальное количество символов, которые будут отображены. Если отображаемая величина будет короче, чем это число, результат будет заполнен пустым пространством. Значение так же не обрежится, даже если результат будет длинее.
*'''precision''':
**'''For integers''': определяет минимальное количество цифр для отображения (или заполняет пробелами/нулями, если она меньше минимальной).
**'''For strings''': определяет максимальное количество символов для отображения.
**'''For floats''': определяет количество цифр для отображения ''после запятой''.
**'''For all other types''': нет эффекта.
*'''specifier''': символ указывающий тип данных (требуется всегда).

Для получения более подробной информации см. [http://www.cplusplus.com/reference/clibrary/cstdio/printf.html printf] из C Standard Library, хотя не Все режимы из C поддерживаются.

[[Category:Ru:SourceMod Scripting]]

Ru:Format Class Functions (SourceMod Scripting)

2008-12-28T16:19:50Z

Frenzzy: /* Расширенное форматирование */

=Введение=
Формат классов функций, аргументов переменной - функции в [[SourceMod]] которые позволяют Вам форматировать строки. Простой пример этой <tt>Format()</tt> функции, выглядит следующим образом:

<pawn>decl String:buffer[512];
Format(buffer, sizeof(buffer), "Ваше имя: %s", userName);</pawn>

Если userName содержит "<tt>Frenzzy</tt>", содержимое <tt>buffer</tt> будет: "<tt>Ваше имя: Frenzzy</tt>". Прототип этих функций почти всегда содержит следующие параметры:
<pawn>const String:fmt[], {Handle,Float,_}:...</pawn>

Например, обратите внимание на эти два выражения:
<pawn>native Format(String:buffer[], maxlength, const String:fmt[], {Handle,Float,_}:...);
native PrintToClient(client, String:fmt[], {Handle,Float,_}:...);</pawn>

Таким образом, <tt>PrintToClient</tt> является формат-классовой функцией. Она может быть использована точно так же, как было показано ранее:
<pawn>PrintToClient(client, "Ваше имя: %s", userName);</pawn>

=Спецификаторы Формата=
Спецификаторы Формата имеют код, который позволяет указать, какие типы данных будут отображаться. Наиболее распространенными спецификаторами являются:
*'''Числовые'''
**'''d''' или '''i''': Целое число как десятичные
**'''b''': Бинарные символы в значении
**'''f''': Числа с плавающей точкой
**'''x''' or '''X''': Шестнадцатеричное представление бинарных значений (применение заглавных букв влияет на шестнадцатеричный регистр букв)
*'''Символ(ы)'''
**'''s''': Строка
**'''t''' или '''T''': Переводы фраз (см. в [[Translations (SourceMod_Scripting)#Inline_Translations|Inline Translations]])
**'''c''': Вывод одного символа (совместимо с UTF-8)
*'''Специальные'''
**'''L''': Требуется индекс клиента; расширяется до 1<2><3><>, где 1 - имя игрока, 2 - userid игрока, и 3 - Steam ID игрока. Если клиент имеет индекс 0, строка будет: <tt><nowiki>Console<0><Console><Console></nowiki></tt>
**'''N''': Требуется индекс клиента; расширяется до строки, содержащей имя игрока. Если клиент имеет индекс 0, строка будет: <tt>Console</tt>

=Испрльзование=
Спецификаторы формата обозначаются символом <tt>'%s'</tt>. Например, чтобы отобразилось число с плавающей точкой, десятичное число и строка, Вы можете использовать этот код:
<pawn>new Float:fNum = 5.0;
new iNum = 5
new String:str[] = "5"

PrintToClient(client, "Десятичное число: %d Число с плавающей точкой: %f Строка: %s", iNum, fNum, str);</pawn>

'''Примечание''': Использование неправильных типов данных спецификаторов может быть очень опасно. Всегда убедитесь, что выводится правильный тип. Например, указание строки и передача числа, может привести к падению сервера.

=Расширенный формат=
Спецификаторы формата имеют расширенный синтаксис для управления различными аспектами того, как будут выводиться данные. Полный синтаксис: <tt>%[flags][width][.precision]specifier</tt>

Каждый раздел в квадратных скобках является дополнительным расширением. Описание поддерживаемых SourceMod расширений формата:
*'''%''': Очевидно, что это требуется всегда.
*'''flags''':
**'''-''': Выравнивание по левому краю (выравнивание по правому краю установлено по умолчанию)
**'''0''': Заполняет 0 вместо пробелов в случае необходимости (см. '''width''' ниже).
*'''width''': Минимальное количество символов, которые будут отображены. Если отображаемая величина будет короче, чем это число, результат будет заполнен пустым пространством. Значение так же не обрежится, даже если результат будет длинее.
*'''precision''':
**'''For integers''': определяет минимальное количество цифр для отображения (или заполняет пробелами/нулями, если она меньше минимальной).
**'''For strings''': определяет максимальное количество символов для отображения.
**'''For floats''': определяет количество цифр для отображения ''после запятой''.
**'''For all other types''': нет эффекта.
*'''specifier''': символ указывающий тип данных (требуется всегда).

Для получения более подробной информации см. [http://www.cplusplus.com/reference/clibrary/cstdio/printf.html printf] из C Standard Library, хотя не Все режимы поддерживаются из C.

[[Category:Ru:SourceMod Scripting]]

Ru:Format Class Functions (SourceMod Scripting)

2008-12-28T15:28:55Z

Frenzzy: /* Испрльзование */

=Введение=
Формат классов функций, аргументов переменной - функции в [[SourceMod]] которые позволяют Вам форматировать строки. Простой пример этой <tt>Format()</tt> функции, выглядит следующим образом:

<pawn>decl String:buffer[512];
Format(buffer, sizeof(buffer), "Ваше имя: %s", userName);</pawn>

Если userName содержит "<tt>Frenzzy</tt>", содержимое <tt>buffer</tt> будет: "<tt>Ваше имя: Frenzzy</tt>". Прототип этих функций почти всегда содержит следующие параметры:
<pawn>const String:fmt[], {Handle,Float,_}:...</pawn>

Например, обратите внимание на эти два выражения:
<pawn>native Format(String:buffer[], maxlength, const String:fmt[], {Handle,Float,_}:...);
native PrintToClient(client, String:fmt[], {Handle,Float,_}:...);</pawn>

Таким образом, <tt>PrintToClient</tt> является формат-классовой функцией. Она может быть использована точно так же, как было показано ранее:
<pawn>PrintToClient(client, "Ваше имя: %s", userName);</pawn>

=Спецификаторы Формата=
Спецификаторы Формата имеют код, который позволяет указать, какие типы данных будут отображаться. Наиболее распространенными спецификаторами являются:
*'''Числовые'''
**'''d''' или '''i''': Целое число как десятичные
**'''b''': Бинарные символы в значении
**'''f''': Числа с плавающей точкой
**'''x''' or '''X''': Шестнадцатеричное представление бинарных значений (применение заглавных букв влияет на шестнадцатеричный регистр букв)
*'''Символ(ы)'''
**'''s''': Строка
**'''t''' или '''T''': Переводы фраз (см. в [[Translations (SourceMod_Scripting)#Inline_Translations|Inline Translations]])
**'''c''': Вывод одного символа (совместимо с UTF-8)
*'''Специальные'''
**'''L''': Требуется индекс клиента; расширяется до 1<2><3><>, где 1 - имя игрока, 2 - userid игрока, и 3 - Steam ID игрока. Если клиент имеет индекс 0, строка будет: <tt><nowiki>Console<0><Console><Console></nowiki></tt>
**'''N''': Требуется индекс клиента; расширяется до строки, содержащей имя игрока. Если клиент имеет индекс 0, строка будет: <tt>Console</tt>

=Испрльзование=
Спецификаторы формата обозначаются символом <tt>'%s'</tt>. Например, чтобы отобразилось число с плавающей точкой, десятичное число и строка, Вы можете использовать этот код:
<pawn>new Float:fNum = 5.0;
new iNum = 5
new String:str[] = "5"

PrintToClient(client, "Десятичное число: %d Число с плавающей точкой: %f Строка: %s", iNum, fNum, str);</pawn>

'''Примечание''': Использование неправильных типов данных спецификаторов может быть очень опасно. Всегда убедитесь, что выводится правильный тип. Например, указание строки и передача числа, может привести к падению сервера.

=Расширенное форматирование=
Format specifiers have an extended syntax for controlling various aspects of how data is printed. The full syntax is:
<tt>%[flags][width][.precision]specifier</tt>

Each bracketed section is an optional extension. Explanations of supported SourceMod format extensions:
*'''%''': Obviously, this is always required.
*'''flags''':
**'''-''': Left-justify (right-justify is set by default)
**'''0''': Pads with 0s instead of spaces when needed (see '''width''' below).
*'''width''': Minimum number of characters to be printed. If the value to be printed is shorter than this number, the result is padded with blank spaces. The value is not truncated even if the result is larger.
*'''precision''':
**'''For integers''': specifies the minimum number of digits to print (or pad with spaces/zeroes if below the minimum).
**'''For strings''': specifies the maximum number of characters to print.
**'''For floats''': specifies the number of digits to be printed ''after the decimal point''.
**'''For all other types''': no effect.
*'''specifier''': character specifying the data type (always required).

For more information, see [http://www.cplusplus.com/reference/clibrary/cstdio/printf.html printf] from the C Standard Library, although not all modes are supported from C.

[[Category:Ru:SourceMod Scripting]]

Ru:Format Class Functions (SourceMod Scripting)

2008-12-28T14:21:39Z

Frenzzy: /* Format Specifiers */

=Введение=
Формат классов функций, аргументов переменной - функции в [[SourceMod]] которые позволяют Вам форматировать строки. Простой пример этой <tt>Format()</tt> функции, выглядит следующим образом:

<pawn>decl String:buffer[512];
Format(buffer, sizeof(buffer), "Ваше имя: %s", userName);</pawn>

Если userName содержит "<tt>Frenzzy</tt>", содержимое <tt>buffer</tt> будет: "<tt>Ваше имя: Frenzzy</tt>". Прототип этих функций почти всегда содержит следующие параметры:
<pawn>const String:fmt[], {Handle,Float,_}:...</pawn>

Например, обратите внимание на эти два выражения:
<pawn>native Format(String:buffer[], maxlength, const String:fmt[], {Handle,Float,_}:...);
native PrintToClient(client, String:fmt[], {Handle,Float,_}:...);</pawn>

Таким образом, <tt>PrintToClient</tt> является формат-классовой функцией. Она может быть использована точно так же, как было показано ранее:
<pawn>PrintToClient(client, "Ваше имя: %s", userName);</pawn>

=Спецификаторы Формата=
Спецификаторы Формата имеют код, который позволяет указать, какие типы данных будут отображаться. Наиболее распространенными спецификаторами являются:
*'''Числовые'''
**'''d''' или '''i''': Целое число как десятичные
**'''b''': Бинарные символы в значении
**'''f''': Числа с плавающей точкой
**'''x''' or '''X''': Шестнадцатеричное представление бинарных значений (применение заглавных букв влияет на шестнадцатеричный регистр букв)
*'''Символ(ы)'''
**'''s''': Строка
**'''t''' или '''T''': Переводы фраз (см. в [[Translations (SourceMod_Scripting)#Inline_Translations|Inline Translations]])
**'''c''': Вывод одного символа (совместимо с UTF-8)
*'''Специальные'''
**'''L''': Требуется индекс клиента; расширяется до 1<2><3><>, где 1 - имя игрока, 2 - userid игрока, и 3 - Steam ID игрока. Если клиент имеет индекс 0, строка будет: <tt><nowiki>Console<0><Console><Console></nowiki></tt>
**'''N''': Требуется индекс клиента; расширяется до строки, содержащей имя игрока. Если клиент имеет индекс 0, строка будет: <tt>Console</tt>

=Испрльзование=
Format specifiers are denoted with a <tt>'%s'</tt> symbol. For example, to print a float, a number, and a string, you might use this code:
<pawn>new Float:fNum = 5.0;
new iNum = 5
new String:str[] = "5"

PrintToClient(client, "Number: %d Float: %f String: %s", iNum, fNum, str);</pawn>

'''Note''': Using the wrong data type with a specifier can be very dangerous. Always make sure you are printing as the right type. For example, specifying a string and passing a number can crash the server.

=Расширенное форматирование=
Format specifiers have an extended syntax for controlling various aspects of how data is printed. The full syntax is:
<tt>%[flags][width][.precision]specifier</tt>

Each bracketed section is an optional extension. Explanations of supported SourceMod format extensions:
*'''%''': Obviously, this is always required.
*'''flags''':
**'''-''': Left-justify (right-justify is set by default)
**'''0''': Pads with 0s instead of spaces when needed (see '''width''' below).
*'''width''': Minimum number of characters to be printed. If the value to be printed is shorter than this number, the result is padded with blank spaces. The value is not truncated even if the result is larger.
*'''precision''':
**'''For integers''': specifies the minimum number of digits to print (or pad with spaces/zeroes if below the minimum).
**'''For strings''': specifies the maximum number of characters to print.
**'''For floats''': specifies the number of digits to be printed ''after the decimal point''.
**'''For all other types''': no effect.
*'''specifier''': character specifying the data type (always required).

For more information, see [http://www.cplusplus.com/reference/clibrary/cstdio/printf.html printf] from the C Standard Library, although not all modes are supported from C.

[[Category:Ru:SourceMod Scripting]]

Ru:Format Class Functions (SourceMod Scripting)

2008-12-27T17:44:53Z

Frenzzy: /* Введение */

Ru:Format Class Functions (SourceMod Scripting)

2008-12-27T17:23:29Z

Frenzzy: /* Продвинутое форматирование */

=Введение=
Format-class functions are variable argument functions in [[SourceMod]] which allow you to format a string. A simple example of this is the <tt>Format()</tt> function, which looks like:

<pawn>decl String:buffer[512];
Format(buffer, sizeof(buffer), "Your name is: %s", userName);</pawn>

If userName contains "<tt>Mark</tt>," the contents of <tt>buffer</tt> will then be: "<tt>Your name is: Mark</tt>." The prototype of these functions almost always contains the following parameters:
<pawn>const String:fmt[], {Handle,Float,_}:...</pawn>

For example, observe the following two natives:
<pawn>native Format(String:buffer[], maxlength, const String:fmt[], {Handle,Float,_}:...);
native PrintToClient(client, String:fmt[], {Handle,Float,_}:...);</pawn>

Thus, <tt>PrintToClient</tt> is a format-class function. It can be used exactly as shown earlier:
<pawn>PrintToClient(client, "Your name is: %s", userName);</pawn>

=Format Specifiers=
A format specifier is a code that allows you to specify what data-type to print. The most common specifiers are:
*'''Numerical'''
**'''d''' or '''i''': Integer number as decimal
**'''b''': Binary digits in the value
**'''f''': Floating-point number
**'''x''' or '''X''': Hexadecimal representation of the binary value (capitalization affects hex letter casing)
*'''Character(s)'''
**'''s''': String
**'''t''' or '''T''': Translates a phrase (explained in [[Translations (SourceMod_Scripting)#Inline_Translations|Inline Translations]])
**'''c''': Prints one character (UTF-8 compliant)
*'''Special'''
**'''L''': Requires a client index; expands to 1<2><3><> where 1 is the player's name, 2 is the player's userid, and 3 is the player's Steam ID. If the client index is 0, the string will be: <tt><nowiki>Console<0><Console><Console></nowiki></tt>
**'''N''': Requires a client index; expands to a string containing the player's name. If the client index is 0, the string will be: <tt>Console</tt>

=Испрльзование=
Format specifiers are denoted with a <tt>'%s'</tt> symbol. For example, to print a float, a number, and a string, you might use this code:
<pawn>new Float:fNum = 5.0;
new iNum = 5
new String:str[] = "5"

PrintToClient(client, "Number: %d Float: %f String: %s", iNum, fNum, str);</pawn>

'''Note''': Using the wrong data type with a specifier can be very dangerous. Always make sure you are printing as the right type. For example, specifying a string and passing a number can crash the server.

=Расширенное форматирование=
Format specifiers have an extended syntax for controlling various aspects of how data is printed. The full syntax is:
<tt>%[flags][width][.precision]specifier</tt>

Each bracketed section is an optional extension. Explanations of supported SourceMod format extensions:
*'''%''': Obviously, this is always required.
*'''flags''':
**'''-''': Left-justify (right-justify is set by default)
**'''0''': Pads with 0s instead of spaces when needed (see '''width''' below).
*'''width''': Minimum number of characters to be printed. If the value to be printed is shorter than this number, the result is padded with blank spaces. The value is not truncated even if the result is larger.
*'''precision''':
**'''For integers''': specifies the minimum number of digits to print (or pad with spaces/zeroes if below the minimum).
**'''For strings''': specifies the maximum number of characters to print.
**'''For floats''': specifies the number of digits to be printed ''after the decimal point''.
**'''For all other types''': no effect.
*'''specifier''': character specifying the data type (always required).

For more information, see [http://www.cplusplus.com/reference/clibrary/cstdio/printf.html printf] from the C Standard Library, although not all modes are supported from C.

[[Category:Ru:SourceMod Scripting]]

Ru:Format Class Functions (SourceMod Scripting)

2008-12-27T17:21:01Z

Frenzzy:

=Введение=
Format-class functions are variable argument functions in [[SourceMod]] which allow you to format a string. A simple example of this is the <tt>Format()</tt> function, which looks like:

<pawn>decl String:buffer[512];
Format(buffer, sizeof(buffer), "Your name is: %s", userName);</pawn>

If userName contains "<tt>Mark</tt>," the contents of <tt>buffer</tt> will then be: "<tt>Your name is: Mark</tt>." The prototype of these functions almost always contains the following parameters:
<pawn>const String:fmt[], {Handle,Float,_}:...</pawn>

For example, observe the following two natives:
<pawn>native Format(String:buffer[], maxlength, const String:fmt[], {Handle,Float,_}:...);
native PrintToClient(client, String:fmt[], {Handle,Float,_}:...);</pawn>

Thus, <tt>PrintToClient</tt> is a format-class function. It can be used exactly as shown earlier:
<pawn>PrintToClient(client, "Your name is: %s", userName);</pawn>

=Format Specifiers=
A format specifier is a code that allows you to specify what data-type to print. The most common specifiers are:
*'''Numerical'''
**'''d''' or '''i''': Integer number as decimal
**'''b''': Binary digits in the value
**'''f''': Floating-point number
**'''x''' or '''X''': Hexadecimal representation of the binary value (capitalization affects hex letter casing)
*'''Character(s)'''
**'''s''': String
**'''t''' or '''T''': Translates a phrase (explained in [[Translations (SourceMod_Scripting)#Inline_Translations|Inline Translations]])
**'''c''': Prints one character (UTF-8 compliant)
*'''Special'''
**'''L''': Requires a client index; expands to 1<2><3><> where 1 is the player's name, 2 is the player's userid, and 3 is the player's Steam ID. If the client index is 0, the string will be: <tt><nowiki>Console<0><Console><Console></nowiki></tt>
**'''N''': Requires a client index; expands to a string containing the player's name. If the client index is 0, the string will be: <tt>Console</tt>

=Испрльзование=
Format specifiers are denoted with a <tt>'%s'</tt> symbol. For example, to print a float, a number, and a string, you might use this code:
<pawn>new Float:fNum = 5.0;
new iNum = 5
new String:str[] = "5"

PrintToClient(client, "Number: %d Float: %f String: %s", iNum, fNum, str);</pawn>

'''Note''': Using the wrong data type with a specifier can be very dangerous. Always make sure you are printing as the right type. For example, specifying a string and passing a number can crash the server.

=Продвинутое форматирование=
Format specifiers have an extended syntax for controlling various aspects of how data is printed. The full syntax is:
<tt>%[flags][width][.precision]specifier</tt>

Each bracketed section is an optional extension. Explanations of supported SourceMod format extensions:
*'''%''': Obviously, this is always required.
*'''flags''':
**'''-''': Left-justify (right-justify is set by default)
**'''0''': Pads with 0s instead of spaces when needed (see '''width''' below).
*'''width''': Minimum number of characters to be printed. If the value to be printed is shorter than this number, the result is padded with blank spaces. The value is not truncated even if the result is larger.
*'''precision''':
**'''For integers''': specifies the minimum number of digits to print (or pad with spaces/zeroes if below the minimum).
**'''For strings''': specifies the maximum number of characters to print.
**'''For floats''': specifies the number of digits to be printed ''after the decimal point''.
**'''For all other types''': no effect.
*'''specifier''': character specifying the data type (always required).

For more information, see [http://www.cplusplus.com/reference/clibrary/cstdio/printf.html printf] from the C Standard Library, although not all modes are supported from C.

[[Category:Ru:SourceMod Scripting]]

Ru:Format Class Functions (SourceMod Scripting)

2008-12-27T17:19:59Z

Frenzzy: /* Introduction */

=Введение=
Format-class functions are variable argument functions in [[SourceMod]] which allow you to format a string. A simple example of this is the <tt>Format()</tt> function, which looks like:

<pawn>decl String:buffer[512];
Format(buffer, sizeof(buffer), "Your name is: %s", userName);</pawn>

If userName contains "<tt>Mark</tt>," the contents of <tt>buffer</tt> will then be: "<tt>Your name is: Mark</tt>." The prototype of these functions almost always contains the following parameters:
<pawn>const String:fmt[], {Handle,Float,_}:...</pawn>

For example, observe the following two natives:
<pawn>native Format(String:buffer[], maxlength, const String:fmt[], {Handle,Float,_}:...);
native PrintToClient(client, String:fmt[], {Handle,Float,_}:...);</pawn>

Thus, <tt>PrintToClient</tt> is a format-class function. It can be used exactly as shown earlier:
<pawn>PrintToClient(client, "Your name is: %s", userName);</pawn>

=Format Specifiers=
A format specifier is a code that allows you to specify what data-type to print. The most common specifiers are:
*'''Numerical'''
**'''d''' or '''i''': Integer number as decimal
**'''b''': Binary digits in the value
**'''f''': Floating-point number
**'''x''' or '''X''': Hexadecimal representation of the binary value (capitalization affects hex letter casing)
*'''Character(s)'''
**'''s''': String
**'''t''' or '''T''': Translates a phrase (explained in [[Translations (SourceMod_Scripting)#Inline_Translations|Inline Translations]])
**'''c''': Prints one character (UTF-8 compliant)
*'''Special'''
**'''L''': Requires a client index; expands to 1<2><3><> where 1 is the player's name, 2 is the player's userid, and 3 is the player's Steam ID. If the client index is 0, the string will be: <tt><nowiki>Console<0><Console><Console></nowiki></tt>
**'''N''': Requires a client index; expands to a string containing the player's name. If the client index is 0, the string will be: <tt>Console</tt>

=Usage=
Format specifiers are denoted with a <tt>'%s'</tt> symbol. For example, to print a float, a number, and a string, you might use this code:
<pawn>new Float:fNum = 5.0;
new iNum = 5
new String:str[] = "5"

PrintToClient(client, "Number: %d Float: %f String: %s", iNum, fNum, str);</pawn>

'''Note''': Using the wrong data type with a specifier can be very dangerous. Always make sure you are printing as the right type. For example, specifying a string and passing a number can crash the server.

=Advanced Formatting=
Format specifiers have an extended syntax for controlling various aspects of how data is printed. The full syntax is:
<tt>%[flags][width][.precision]specifier</tt>

Each bracketed section is an optional extension. Explanations of supported SourceMod format extensions:
*'''%''': Obviously, this is always required.
*'''flags''':
**'''-''': Left-justify (right-justify is set by default)
**'''0''': Pads with 0s instead of spaces when needed (see '''width''' below).
*'''width''': Minimum number of characters to be printed. If the value to be printed is shorter than this number, the result is padded with blank spaces. The value is not truncated even if the result is larger.
*'''precision''':
**'''For integers''': specifies the minimum number of digits to print (or pad with spaces/zeroes if below the minimum).
**'''For strings''': specifies the maximum number of characters to print.
**'''For floats''': specifies the number of digits to be printed ''after the decimal point''.
**'''For all other types''': no effect.
*'''specifier''': character specifying the data type (always required).

For more information, see [http://www.cplusplus.com/reference/clibrary/cstdio/printf.html printf] from the C Standard Library, although not all modes are supported from C.

[[Category:Ru:SourceMod Scripting]]

Category:Ru:SourceMod Scripting

2008-12-27T17:19:12Z

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

Эта категория содержит статьи о написании скриптов под 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)|Ru:AutoConfigs]] - Автоматическое создание .cfg файлов.
*[[Ru:Commands (SourceMod Scripting)|Ru:Commands]] - Консольные команды/ввод.
*[[Ru:ConVars (SourceMod Scripting)|Ru:ConVars]] - Консольные переменные (cvars).
*[[Ru:Events (SourceMod Scripting)|Ru:Events]] - Игровые события Half-Life.
*[[Ru:KeyValues (SourceMod Scripting)|Ru:KeyValues]] - KeyValues анализ/запись файла.
*[[Ru:Menu API (SourceMod)|Ru:Menus]] - Создание и отображение меню.
*[[Ru:SQL (SourceMod Scripting)|Ru:SQL]] - Использование баз данных (MySQL, SQLite).
*[[Ru:Timers (SourceMod Scripting)|Ru:Timers]] - Вызов таймеров.
*[[Ru:Translations (SourceMod Scripting)|Ru:Translations]] - Создание локализаций.

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

===Информация===
*[[Deprecation Schedule (SourceMod Scripting)|Deprecation Schedule]] - Which functions are getting removed.
*[[Ru:Format Class Functions (SourceMod Scripting)|Ru:Format Class Functions]] - All about text formatting.
*[[Handles (SourceMod Scripting)|Handles]] - Overview of Handles and some common types.
*[[Optimizing Plugins (SourceMod Scripting)|Optimizing Plugins]] - Optimization hints.
*[[Tags (Scripting)|Tags]] - All about tags.
*[[Vectors Explained (Scripting)|Vectors Explained]] - Explanation of Vector types.

===Дополнительные средства===
*[http://docs.sourcemod.net/api API Reference] - Searchable scripting API reference.
*[[Entity Properties]] - Explanation of Source entity properties.
*[[Game Events (Source)|Game Events]] - Game events listings for popular mods.
*[[Mod TempEnt List (Source)|Temp Entity Lists]] - Temporary entities for popular mods.
*[[SourceMod Profiler]] - Performance tracking and optimizing.

Ru:Format Class Functions (SourceMod Scripting)

2008-12-27T17:18:28Z

Frenzzy: New page: =Introduction= Format-class functions are variable argument functions in SourceMod which allow you to format a string. A simple example of this is the <tt>Format()</tt> function, whic...

=Introduction=
Format-class functions are variable argument functions in [[SourceMod]] which allow you to format a string. A simple example of this is the <tt>Format()</tt> function, which looks like:

<pawn>decl String:buffer[512];
Format(buffer, sizeof(buffer), "Your name is: %s", userName);</pawn>

If userName contains "<tt>Mark</tt>," the contents of <tt>buffer</tt> will then be: "<tt>Your name is: Mark</tt>." The prototype of these functions almost always contains the following parameters:
<pawn>const String:fmt[], {Handle,Float,_}:...</pawn>

For example, observe the following two natives:
<pawn>native Format(String:buffer[], maxlength, const String:fmt[], {Handle,Float,_}:...);
native PrintToClient(client, String:fmt[], {Handle,Float,_}:...);</pawn>

Thus, <tt>PrintToClient</tt> is a format-class function. It can be used exactly as shown earlier:
<pawn>PrintToClient(client, "Your name is: %s", userName);</pawn>

=Format Specifiers=
A format specifier is a code that allows you to specify what data-type to print. The most common specifiers are:
*'''Numerical'''
**'''d''' or '''i''': Integer number as decimal
**'''b''': Binary digits in the value
**'''f''': Floating-point number
**'''x''' or '''X''': Hexadecimal representation of the binary value (capitalization affects hex letter casing)
*'''Character(s)'''
**'''s''': String
**'''t''' or '''T''': Translates a phrase (explained in [[Translations (SourceMod_Scripting)#Inline_Translations|Inline Translations]])
**'''c''': Prints one character (UTF-8 compliant)
*'''Special'''
**'''L''': Requires a client index; expands to 1<2><3><> where 1 is the player's name, 2 is the player's userid, and 3 is the player's Steam ID. If the client index is 0, the string will be: <tt><nowiki>Console<0><Console><Console></nowiki></tt>
**'''N''': Requires a client index; expands to a string containing the player's name. If the client index is 0, the string will be: <tt>Console</tt>

=Usage=
Format specifiers are denoted with a <tt>'%s'</tt> symbol. For example, to print a float, a number, and a string, you might use this code:
<pawn>new Float:fNum = 5.0;
new iNum = 5
new String:str[] = "5"

PrintToClient(client, "Number: %d Float: %f String: %s", iNum, fNum, str);</pawn>

'''Note''': Using the wrong data type with a specifier can be very dangerous. Always make sure you are printing as the right type. For example, specifying a string and passing a number can crash the server.

=Advanced Formatting=
Format specifiers have an extended syntax for controlling various aspects of how data is printed. The full syntax is:
<tt>%[flags][width][.precision]specifier</tt>

Each bracketed section is an optional extension. Explanations of supported SourceMod format extensions:
*'''%''': Obviously, this is always required.
*'''flags''':
**'''-''': Left-justify (right-justify is set by default)
**'''0''': Pads with 0s instead of spaces when needed (see '''width''' below).
*'''width''': Minimum number of characters to be printed. If the value to be printed is shorter than this number, the result is padded with blank spaces. The value is not truncated even if the result is larger.
*'''precision''':
**'''For integers''': specifies the minimum number of digits to print (or pad with spaces/zeroes if below the minimum).
**'''For strings''': specifies the maximum number of characters to print.
**'''For floats''': specifies the number of digits to be printed ''after the decimal point''.
**'''For all other types''': no effect.
*'''specifier''': character specifying the data type (always required).

For more information, see [http://www.cplusplus.com/reference/clibrary/cstdio/printf.html printf] from the C Standard Library, although not all modes are supported from C.

[[Category:Ru:SourceMod Scripting]]

Ru:Introduction to SourceMod Plugins

2008-12-27T17:12:38Z

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

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

Для получения информации о компиляции плагинов см. [[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] или любой другой текстовый редактор.

=Структура плагина=
Почти все плагины имеют три одинаковых элемента:
*'''Includes''' - Позволяет получить доступ к SourceMod API, и если Вы хотите, к API от внешних SourceMod плагинов и расширений.
*'''Info''' - Общественная информация о Вашем плагине.
*'''Startup''' - Функция, которая осуществляет запуск процедур в Вашем плагине.

Плагин скелетной структуры выглядит следующим образом:
<pawn>
#include <sourcemod>

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

public OnPluginStart()
{
// Выполнение единовременного запуска задач ...
}</pawn>

Информация часть имеет специальную синтаксическую конструкцию. Вы не можете изменить любое из ключевых слов, или объявление <tt>public Plugin:myinfo</tt>. Хорошая идея заключается в том, чтобы скопировать и вставить эту скелетную структуру и отредактировать строки, чтобы начать работу.

=Включения=
Pawn требует включать файлы '''include''', как и C требует наличие заголовка у файла. Включение списков файлов всех структур, функций, вызовы и тегов, которые имеются в наличии. Есть три типа файлов:
*'''Core''' - <tt>sourcemod.inc</tt>, и все его включения. Все представленные в SourceMod Core.
*'''Extension''' - добавляет зависимость от определенного расширения.
*'''Plugin''' - добавляет зависимость от некоторых плагинов.

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

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

==Описание==
Во-первых, давайте смотреть на то, какая команда требуется администратору. Команды администратора регистрируются с использованием функции [http://docs.sourcemod.net/api/index.php?fastload=show&id=471& RegAdminCmd]. Она требует '''название''', '''функцию обратного вызова''' и '''флаги админа по умолчанию'''.

Функция обратного вызова это то, на что ссылаться используемая команда каждый раз. [http://docs.sourcemod.net/api/index.php?fastload=show&id=469& Нажми здесь], чтобы просмотреть её прототип. Пример:

<pawn>
public OnPluginStart()
{
RegAdminCmd("sm_myslap", Command_MySlap, ADMFLAG_SLAY)
}

public Action:Command_MySlap(client, args)
{
}</pawn>

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

<pawn>public Action:Command_MySlap(client, args)
{
return Plugin_Handled;
}</pawn>

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

==Реализация==
Давайте решим, что команда будет выглядеть так. Пусть будет она действовать как команда по умолчанию <tt>sm_slap</tt>:
<pre>sm_myslap <name|#userid> [damage]</pre>

Чтобы осуществить это, Нам потребуется несколько шагов:
*Получить ввод с консоли. Для этого мы используем [http://docs.sourcemod.net/api/index.php?fastload=show&id=473& GetCmdArg()].
*Найти соответствия игрока. Для этого мы используем [http://docs.sourcemod.net/api/index.php?fastload=show&id=144& FindTarget()].
*Ударить его. Для этого мы используем [http://docs.sourcemod.net/api/index.php?fastload=show&id=42& SlapPlayer()], которая требует в том числе <tt>sdktools</tt> расширение в комплекте с SourceMod.
*Сообщить администратору. Для этого мы используем [http://docs.sourcemod.net/api/index.php?fastload=show&id=462& ReplyToCommand()].

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

<pawn>
#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;
}</pawn>

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

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

Удобная особенность ConVars заключается в том, что они легко настраиваются пользователями. Они могут быть помещены в любой .cfg файл, например <tt>server.cfg</tt> или <tt>sourcemod.cfg</tt>. Чтобы сделать удобнее их использование, SourceMod имеет [http://docs.sourcemod.net/api/index.php?fastload=show&id=607& AutoExecConfig()] функции. Эта функция автоматически создает .cfg файл по умолчанию, содержащий все Ваши переменные (cvars), снабженные комментариями для пользователей. Очень рекомендую Вам вызывать её, если у Вас есть настраиваемые ConVars.

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

<pawn>new Handle:sm_myslap_damage = INVALID_HANDLE

public OnPluginStart()
{
RegAdminCmd("sm_myslap", Command_MySlap, ADMFLAG_SLAY)

sm_myslap_damage = CreateConVar("sm_myslap_damage", "5", "Default slap damage")
AutoExecConfig(true, "plugin_myslap")
}

public Action:Command_MySlap(client, args)
{
new String:arg1[32], String:arg2[32]
new damage = GetConVarInt(sm_myslap_damage)

/* Остальное остается без изменений! */
</pawn>

=Отображение активности, логирование=
Почти все команды администратора должны логировать (записывать в лог) их активность, а некоторые команды администратора должны отобразить свою активность в игре для клиентов. Это может быть сделано через [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> переменной.

Например, давайте перепишем несколько последних строк нашей slap команды:
<pawn>
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;
}
</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.

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.

This method of target processing is used for almost every admin command in SourceMod, and in fact FindTarget() is just a simplified version.

Full, final example:
<pawn>
#include <sourcemod>
#include <sdktools>

new Handle:sm_myslap_damage = INVALID_HANDLE

public Plugin:myinfo =
{
name = "My First Plugin",
author = "Me",
description = "My first plugin ever",
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", "Default slap damage")
AutoExecConfig(true, "plugin_myslap")
}

public Action:Command_MySlap(client, args)
{
new String:arg1[32], String:arg2[32]
new damage = GetConVarInt(sm_myslap_damage)

/* Get the first argument */
GetCmdArg(1, arg1, sizeof(arg1))

/* If there are 2 or more arguments, and the second argument fetch
* is successful, convert it to an integer.
*/
if (args >= 2 && GetCmdArg(2, arg2, sizeof(arg2)))
{
damage = StringToInt(arg2)
}

/**
* target_name - stores the noun identifying the target(s)
* target_list - array to store clients
* target_count - variable to store number of clients
* tn_is_ml - stores whether the noun must be translated
*/
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, /* Only allow alive players */
target_name,
sizeof(target_name),
tn_is_ml)) <= 0)
{
/* This function replies to the admin with a failure message */
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;
}</pawn>

=Client and Entity Indexes=
One major point of confusion with Half-Life 2 is the difference between the following things:
*Client index
*Entity index
*Userid

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.

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

A userid, on the other hand, is completely different. The 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.

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

=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]].

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>
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 */
}</pawn>

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

*[http://docs.sourcemod.net/api/index.php?fastload=show&id=576& AskPluginLoad()] - Called once, immediately after the plugin is loaded from the disk.
*[http://docs.sourcemod.net/api/index.php?fastload=show&id=575& 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()'''.
*[http://docs.sourcemod.net/api/index.php?fastload=show&id=580& 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().'''
*[http://docs.sourcemod.net/api/index.php?fastload=show&id=582& OnConfigsExecuted()] - Called once per map-change after <tt>servercfgfile</tt> (usually <tt>server.cfg</tt>), <tt>sourcemod.cfg</tt>, 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).
*[http://docs.sourcemod.net/api/index.php?fastload=show&id=581& OnMapEnd()] - Called when the map is about to end. At this point, all clients are disconnected, but <tt>TIMER_NO_MAPCHANGE</tt> timers are not yet destroyed. '''This function is paired to OnMapStart().'''
*[http://docs.sourcemod.net/api/index.php?fastload=show&id=577& 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.

*[http://docs.sourcemod.net/api/index.php?fastload=show&id=388& OnClientConnect()] - Called when a player initiates a connection. '''This is paired with OnClientDisconnect() for successful connections only.'''
*[http://docs.sourcemod.net/api/index.php?fastload=show&id=394& 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().
*[http://docs.sourcemod.net/api/index.php?fastload=show&id=389& OnClientPutInServer()] - Signifies that the player is in-game and IsClientInGame() will return true.
*[http://docs.sourcemod.net/api/index.php?fastload=show&id=396& 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.
*[http://docs.sourcemod.net/api/index.php?fastload=show&id=390& 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. <tt>#include <sourcemod></tt> will give you 95% of the .incs. Similarly, <tt>#include <sdktools></tt> 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 <tt>Plugin_Stop</tt> 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.

=Further Reading=
For further reading, see the "Scripting" section at the [http://docs.sourcemod.net/ SourceMod Documentation].

[[Category:Ru:SourceMod Scripting]]

Ru:Introduction to SourceMod Plugins

2008-12-27T17:10:52Z

Frenzzy:

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

Для получения информации о компиляции плагинов см. [[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] или любой другой текстовый редактор.

=Структура плагина=
Почти все плагины имеют три одинаковых элемента:
*'''Includes''' - Позволяет получить доступ к SourceMod API, и если Вы хотите, к API от внешних SourceMod плагинов и расширений.
*'''Info''' - Общественная информация о Вашем плагине.
*'''Startup''' - Функция, которая осуществляет запуск процедур в Вашем плагине.

Плагин скелетной структуры выглядит следующим образом:
<pawn>
#include <sourcemod>

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

public OnPluginStart()
{
// Выполнение единовременного запуска задач ...
}</pawn>

Информация часть имеет специальную синтаксическую конструкцию. Вы не можете изменить любое из ключевых слов, или объявление <tt>public Plugin:myinfo</tt>. Хорошая идея заключается в том, чтобы скопировать и вставить эту скелетную структуру и отредактировать строки, чтобы начать работу.

=Включения=
Pawn требует включать файлы '''include''', как и C требует наличие заголовка у файла. Включение списков файлов всех структур, функций, вызовы и тегов, которые имеются в наличии. Есть три типа файлов:
*'''Core''' - <tt>sourcemod.inc</tt>, и все его включения. Все представленные в SourceMod Core.
*'''Extension''' - добавляет зависимость от определенного расширения.
*'''Plugin''' - добавляет зависимость от некоторых плагинов.

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

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

==Описание==
Во-первых, давайте смотреть на то, какая команда требуется администратору. Команды администратора регистрируются с использованием функции [http://docs.sourcemod.net/api/index.php?fastload=show&id=471& RegAdminCmd]. Она требует '''название''', '''функцию обратного вызова''' и '''флаги админа по умолчанию'''.

Функция обратного вызова это то, на что ссылаться используемая команда каждый раз. [http://docs.sourcemod.net/api/index.php?fastload=show&id=469& Нажми здесь], чтобы просмотреть её прототип. Пример:

<pawn>
public OnPluginStart()
{
RegAdminCmd("sm_myslap", Command_MySlap, ADMFLAG_SLAY)
}

public Action:Command_MySlap(client, args)
{
}</pawn>

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

<pawn>public Action:Command_MySlap(client, args)
{
return Plugin_Handled;
}</pawn>

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

==Реализация==
Давайте решим, что команда будет выглядеть так. Пусть будет она действовать как команда по умолчанию <tt>sm_slap</tt>:
<pre>sm_myslap <name|#userid> [damage]</pre>

Чтобы осуществить это, Нам потребуется несколько шагов:
*Получить ввод с консоли. Для этого мы используем [http://docs.sourcemod.net/api/index.php?fastload=show&id=473& GetCmdArg()].
*Найти соответствия игрока. Для этого мы используем [http://docs.sourcemod.net/api/index.php?fastload=show&id=144& FindTarget()].
*Ударить его. Для этого мы используем [http://docs.sourcemod.net/api/index.php?fastload=show&id=42& SlapPlayer()], которая требует в том числе <tt>sdktools</tt> расширение в комплекте с SourceMod.
*Сообщить администратору. Для этого мы используем [http://docs.sourcemod.net/api/index.php?fastload=show&id=462& ReplyToCommand()].

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

<pawn>
#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;
}</pawn>

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

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

Удобная особенность ConVars заключается в том, что они легко настраиваются пользователями. Они могут быть помещены в любой .cfg файл, например <tt>server.cfg</tt> или <tt>sourcemod.cfg</tt>. Чтобы сделать удобнее их использование, SourceMod имеет [http://docs.sourcemod.net/api/index.php?fastload=show&id=607& AutoExecConfig()] функции. Эта функция автоматически создает .cfg файл по умолчанию, содержащий все Ваши переменные (cvars), снабженные комментариями для пользователей. Очень рекомендую Вам вызывать её, если у Вас есть настраиваемые ConVars.

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

<pawn>new Handle:sm_myslap_damage = INVALID_HANDLE

public OnPluginStart()
{
RegAdminCmd("sm_myslap", Command_MySlap, ADMFLAG_SLAY)

sm_myslap_damage = CreateConVar("sm_myslap_damage", "5", "Default slap damage")
AutoExecConfig(true, "plugin_myslap")
}

public Action:Command_MySlap(client, args)
{
new String:arg1[32], String:arg2[32]
new damage = GetConVarInt(sm_myslap_damage)

/* Остальное остается без изменений! */
</pawn>

=Отображение активности, логирование=
Почти все команды администратора должны логировать (записывать в лог) их активность, а некоторые команды администратора должны отобразить свою активность в игре для клиентов. Это может быть сделано через [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> переменной.

Например, давайте перепишем несколько последних строк нашей slap команды:
<pawn>
SlapPlayer(target, damage)

new String:name[MAX_NAME_LENGTH]

GetClientName(target, name, sizeof(name))

ShowActivity2(client, "[SM] ", "Slapped %s for %d damage!", name, damage)
LogAction(client, target, "\"%L\" slapped \"%L\" (damage %d)", client, target, damage)

return Plugin_Handled;
}
</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.

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.

This method of target processing is used for almost every admin command in SourceMod, and in fact FindTarget() is just a simplified version.

Full, final example:
<pawn>
#include <sourcemod>
#include <sdktools>

new Handle:sm_myslap_damage = INVALID_HANDLE

public Plugin:myinfo =
{
name = "My First Plugin",
author = "Me",
description = "My first plugin ever",
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", "Default slap damage")
AutoExecConfig(true, "plugin_myslap")
}

public Action:Command_MySlap(client, args)
{
new String:arg1[32], String:arg2[32]
new damage = GetConVarInt(sm_myslap_damage)

/* Get the first argument */
GetCmdArg(1, arg1, sizeof(arg1))

/* If there are 2 or more arguments, and the second argument fetch
* is successful, convert it to an integer.
*/
if (args >= 2 && GetCmdArg(2, arg2, sizeof(arg2)))
{
damage = StringToInt(arg2)
}

/**
* target_name - stores the noun identifying the target(s)
* target_list - array to store clients
* target_count - variable to store number of clients
* tn_is_ml - stores whether the noun must be translated
*/
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, /* Only allow alive players */
target_name,
sizeof(target_name),
tn_is_ml)) <= 0)
{
/* This function replies to the admin with a failure message */
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;
}</pawn>

=Client and Entity Indexes=
One major point of confusion with Half-Life 2 is the difference between the following things:
*Client index
*Entity index
*Userid

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.

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

A userid, on the other hand, is completely different. The 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.

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

=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]].

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>
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 */
}</pawn>

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

*[http://docs.sourcemod.net/api/index.php?fastload=show&id=576& AskPluginLoad()] - Called once, immediately after the plugin is loaded from the disk.
*[http://docs.sourcemod.net/api/index.php?fastload=show&id=575& 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()'''.
*[http://docs.sourcemod.net/api/index.php?fastload=show&id=580& 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().'''
*[http://docs.sourcemod.net/api/index.php?fastload=show&id=582& OnConfigsExecuted()] - Called once per map-change after <tt>servercfgfile</tt> (usually <tt>server.cfg</tt>), <tt>sourcemod.cfg</tt>, 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).
*[http://docs.sourcemod.net/api/index.php?fastload=show&id=581& OnMapEnd()] - Called when the map is about to end. At this point, all clients are disconnected, but <tt>TIMER_NO_MAPCHANGE</tt> timers are not yet destroyed. '''This function is paired to OnMapStart().'''
*[http://docs.sourcemod.net/api/index.php?fastload=show&id=577& 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.

*[http://docs.sourcemod.net/api/index.php?fastload=show&id=388& OnClientConnect()] - Called when a player initiates a connection. '''This is paired with OnClientDisconnect() for successful connections only.'''
*[http://docs.sourcemod.net/api/index.php?fastload=show&id=394& 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().
*[http://docs.sourcemod.net/api/index.php?fastload=show&id=389& OnClientPutInServer()] - Signifies that the player is in-game and IsClientInGame() will return true.
*[http://docs.sourcemod.net/api/index.php?fastload=show&id=396& 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.
*[http://docs.sourcemod.net/api/index.php?fastload=show&id=390& 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. <tt>#include <sourcemod></tt> will give you 95% of the .incs. Similarly, <tt>#include <sdktools></tt> 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 <tt>Plugin_Stop</tt> 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.

=Further Reading=
For further reading, see the "Scripting" section at the [http://docs.sourcemod.net/ SourceMod Documentation].

[[Category:Ru:SourceMod Scripting]]

Ru:Introduction to SourceMod Plugins

2008-12-27T17:09:23Z

Frenzzy: /* Showing Activity, Logging */

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

Для получения информации о компиляции плагинов см. [[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] или любой другой текстовый редактор.

=Структура плагина=
Почти все плагины имеют три одинаковых элемента:
*'''Includes''' - Позволяет получить доступ к SourceMod API, и если Вы хотите, к API от внешних SourceMod плагинов и расширений.
*'''Info''' - Общественная информация о Вашем плагине.
*'''Startup''' - Функция, которая осуществляет запуск процедур в Вашем плагине.

Плагин скелетной структуры выглядит следующим образом:
<pawn>
#include <sourcemod>

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

public OnPluginStart()
{
// Выполнение единовременного запуска задач ...
}</pawn>

Информация часть имеет специальную синтаксическую конструкцию. Вы не можете изменить любое из ключевых слов, или объявление <tt>public Plugin:myinfo</tt>. Хорошая идея заключается в том, чтобы скопировать и вставить эту скелетную структуру и отредактировать строки, чтобы начать работу.

=Включения=
Pawn требует включать файлы '''include''', как и C требует наличие заголовка у файла. Включение списков файлов всех структур, функций, вызовы и тегов, которые имеются в наличии. Есть три типа файлов:
*'''Core''' - <tt>sourcemod.inc</tt>, и все его включения. Все представленные в SourceMod Core.
*'''Extension''' - добавляет зависимость от определенного расширения.
*'''Plugin''' - добавляет зависимость от некоторых плагинов.

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

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

==Описание==
Во-первых, давайте смотреть на то, какая команда требуется администратору. Команды администратора регистрируются с использованием функции [http://docs.sourcemod.net/api/index.php?fastload=show&id=471& RegAdminCmd]. Она требует '''название''', '''функцию обратного вызова''' и '''флаги админа по умолчанию'''.

Функция обратного вызова это то, на что ссылаться используемая команда каждый раз. [http://docs.sourcemod.net/api/index.php?fastload=show&id=469& Нажми здесь], чтобы просмотреть её прототип. Пример:

<pawn>
public OnPluginStart()
{
RegAdminCmd("sm_myslap", Command_MySlap, ADMFLAG_SLAY)
}

public Action:Command_MySlap(client, args)
{
}</pawn>

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

<pawn>public Action:Command_MySlap(client, args)
{
return Plugin_Handled;
}</pawn>

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

==Реализация==
Давайте решим, что команда будет выглядеть так. Пусть будет она действовать как команда по умолчанию <tt>sm_slap</tt>:
<pre>sm_myslap <name|#userid> [damage]</pre>

Чтобы осуществить это, Нам потребуется несколько шагов:
*Получить ввод с консоли. Для этого мы используем [http://docs.sourcemod.net/api/index.php?fastload=show&id=473& GetCmdArg()].
*Найти соответствия игрока. Для этого мы используем [http://docs.sourcemod.net/api/index.php?fastload=show&id=144& FindTarget()].
*Ударить его. Для этого мы используем [http://docs.sourcemod.net/api/index.php?fastload=show&id=42& SlapPlayer()], которая требует в том числе <tt>sdktools</tt> расширение в комплекте с SourceMod.
*Сообщить администратору. Для этого мы используем [http://docs.sourcemod.net/api/index.php?fastload=show&id=462& ReplyToCommand()].

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

<pawn>
#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;
}</pawn>

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

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

Удобная особенность ConVars заключается в том, что они легко настраиваются пользователями. Они могут быть помещены в любой .cfg файл, например <tt>server.cfg</tt> или <tt>sourcemod.cfg</tt>. Чтобы сделать удобнее их использование, SourceMod имеет [http://docs.sourcemod.net/api/index.php?fastload=show&id=607& AutoExecConfig()] функции. Эта функция автоматически создает .cfg файл по умолчанию, содержащий все Ваши переменные (cvars), снабженные комментариями для пользователей. Очень рекомендую Вам вызывать её, если у Вас есть настраиваемые ConVars.

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

<pawn>new Handle:sm_myslap_damage = INVALID_HANDLE

public OnPluginStart()
{
RegAdminCmd("sm_myslap", Command_MySlap, ADMFLAG_SLAY)

sm_myslap_damage = CreateConVar("sm_myslap_damage", "5", "Default slap damage")
AutoExecConfig(true, "plugin_myslap")
}

public Action:Command_MySlap(client, args)
{
new String:arg1[32], String:arg2[32]
new damage = GetConVarInt(sm_myslap_damage)

/* Остальное остается без изменений! */
</pawn>

=Showing Activity, Logging=
=Отображение активности, запись=
Почти все команды администратора должны записывать их активность, а некоторые команды администратора должны показать свою активность в игре для клиентов. Это может быть сделано через [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> переменной.

Например, давайте перепишем несколько последних строк нашей slap команды:
<pawn>
SlapPlayer(target, damage)

new String:name[MAX_NAME_LENGTH]

GetClientName(target, name, sizeof(name))

ShowActivity2(client, "[SM] ", "Slapped %s for %d damage!", name, damage)
LogAction(client, target, "\"%L\" slapped \"%L\" (damage %d)", client, target, damage)

return Plugin_Handled;
}
</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.

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.

This method of target processing is used for almost every admin command in SourceMod, and in fact FindTarget() is just a simplified version.

Full, final example:
<pawn>
#include <sourcemod>
#include <sdktools>

new Handle:sm_myslap_damage = INVALID_HANDLE

public Plugin:myinfo =
{
name = "My First Plugin",
author = "Me",
description = "My first plugin ever",
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", "Default slap damage")
AutoExecConfig(true, "plugin_myslap")
}

public Action:Command_MySlap(client, args)
{
new String:arg1[32], String:arg2[32]
new damage = GetConVarInt(sm_myslap_damage)

/* Get the first argument */
GetCmdArg(1, arg1, sizeof(arg1))

/* If there are 2 or more arguments, and the second argument fetch
* is successful, convert it to an integer.
*/
if (args >= 2 && GetCmdArg(2, arg2, sizeof(arg2)))
{
damage = StringToInt(arg2)
}

/**
* target_name - stores the noun identifying the target(s)
* target_list - array to store clients
* target_count - variable to store number of clients
* tn_is_ml - stores whether the noun must be translated
*/
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, /* Only allow alive players */
target_name,
sizeof(target_name),
tn_is_ml)) <= 0)
{
/* This function replies to the admin with a failure message */
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;
}</pawn>

=Client and Entity Indexes=
One major point of confusion with Half-Life 2 is the difference between the following things:
*Client index
*Entity index
*Userid

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.

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

A userid, on the other hand, is completely different. The 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.

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

=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]].

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>
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 */
}</pawn>

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

*[http://docs.sourcemod.net/api/index.php?fastload=show&id=576& AskPluginLoad()] - Called once, immediately after the plugin is loaded from the disk.
*[http://docs.sourcemod.net/api/index.php?fastload=show&id=575& 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()'''.
*[http://docs.sourcemod.net/api/index.php?fastload=show&id=580& 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().'''
*[http://docs.sourcemod.net/api/index.php?fastload=show&id=582& OnConfigsExecuted()] - Called once per map-change after <tt>servercfgfile</tt> (usually <tt>server.cfg</tt>), <tt>sourcemod.cfg</tt>, 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).
*[http://docs.sourcemod.net/api/index.php?fastload=show&id=581& OnMapEnd()] - Called when the map is about to end. At this point, all clients are disconnected, but <tt>TIMER_NO_MAPCHANGE</tt> timers are not yet destroyed. '''This function is paired to OnMapStart().'''
*[http://docs.sourcemod.net/api/index.php?fastload=show&id=577& 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.

*[http://docs.sourcemod.net/api/index.php?fastload=show&id=388& OnClientConnect()] - Called when a player initiates a connection. '''This is paired with OnClientDisconnect() for successful connections only.'''
*[http://docs.sourcemod.net/api/index.php?fastload=show&id=394& 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().
*[http://docs.sourcemod.net/api/index.php?fastload=show&id=389& OnClientPutInServer()] - Signifies that the player is in-game and IsClientInGame() will return true.
*[http://docs.sourcemod.net/api/index.php?fastload=show&id=396& 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.
*[http://docs.sourcemod.net/api/index.php?fastload=show&id=390& 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. <tt>#include <sourcemod></tt> will give you 95% of the .incs. Similarly, <tt>#include <sdktools></tt> 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 <tt>Plugin_Stop</tt> 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.

=Further Reading=
For further reading, see the "Scripting" section at the [http://docs.sourcemod.net/ SourceMod Documentation].

[[Category:Ru:SourceMod Scripting]]

Ru:Introduction to SourceMod Plugins

2008-12-27T17:04:07Z

Frenzzy: /* ConVars */

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

Для получения информации о компиляции плагинов см. [[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] или любой другой текстовый редактор.

=Структура плагина=
Почти все плагины имеют три одинаковых элемента:
*'''Includes''' - Позволяет получить доступ к SourceMod API, и если Вы хотите, к API от внешних SourceMod плагинов и расширений.
*'''Info''' - Общественная информация о Вашем плагине.
*'''Startup''' - Функция, которая осуществляет запуск процедур в Вашем плагине.

Плагин скелетной структуры выглядит следующим образом:
<pawn>
#include <sourcemod>

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

public OnPluginStart()
{
// Выполнение единовременного запуска задач ...
}</pawn>

Информация часть имеет специальную синтаксическую конструкцию. Вы не можете изменить любое из ключевых слов, или объявление <tt>public Plugin:myinfo</tt>. Хорошая идея заключается в том, чтобы скопировать и вставить эту скелетную структуру и отредактировать строки, чтобы начать работу.

=Включения=
Pawn требует включать файлы '''include''', как и C требует наличие заголовка у файла. Включение списков файлов всех структур, функций, вызовы и тегов, которые имеются в наличии. Есть три типа файлов:
*'''Core''' - <tt>sourcemod.inc</tt>, и все его включения. Все представленные в SourceMod Core.
*'''Extension''' - добавляет зависимость от определенного расширения.
*'''Plugin''' - добавляет зависимость от некоторых плагинов.

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

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

==Описание==
Во-первых, давайте смотреть на то, какая команда требуется администратору. Команды администратора регистрируются с использованием функции [http://docs.sourcemod.net/api/index.php?fastload=show&id=471& RegAdminCmd]. Она требует '''название''', '''функцию обратного вызова''' и '''флаги админа по умолчанию'''.

Функция обратного вызова это то, на что ссылаться используемая команда каждый раз. [http://docs.sourcemod.net/api/index.php?fastload=show&id=469& Нажми здесь], чтобы просмотреть её прототип. Пример:

<pawn>
public OnPluginStart()
{
RegAdminCmd("sm_myslap", Command_MySlap, ADMFLAG_SLAY)
}

public Action:Command_MySlap(client, args)
{
}</pawn>

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

<pawn>public Action:Command_MySlap(client, args)
{
return Plugin_Handled;
}</pawn>

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

==Реализация==
Давайте решим, что команда будет выглядеть так. Пусть будет она действовать как команда по умолчанию <tt>sm_slap</tt>:
<pre>sm_myslap <name|#userid> [damage]</pre>

Чтобы осуществить это, Нам потребуется несколько шагов:
*Получить ввод с консоли. Для этого мы используем [http://docs.sourcemod.net/api/index.php?fastload=show&id=473& GetCmdArg()].
*Найти соответствия игрока. Для этого мы используем [http://docs.sourcemod.net/api/index.php?fastload=show&id=144& FindTarget()].
*Ударить его. Для этого мы используем [http://docs.sourcemod.net/api/index.php?fastload=show&id=42& SlapPlayer()], которая требует в том числе <tt>sdktools</tt> расширение в комплекте с SourceMod.
*Сообщить администратору. Для этого мы используем [http://docs.sourcemod.net/api/index.php?fastload=show&id=462& ReplyToCommand()].

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

<pawn>
#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;
}</pawn>

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

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

Удобная особенность ConVars заключается в том, что они легко настраиваются пользователями. Они могут быть помещены в любой .cfg файл, например <tt>server.cfg</tt> или <tt>sourcemod.cfg</tt>. Чтобы сделать удобнее их использование, SourceMod имеет [http://docs.sourcemod.net/api/index.php?fastload=show&id=607& AutoExecConfig()] функции. Эта функция автоматически создает .cfg файл по умолчанию, содержащий все Ваши переменные (cvars), снабженные комментариями для пользователей. Очень рекомендую Вам вызывать её, если у Вас есть настраиваемые ConVars.

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

<pawn>new Handle:sm_myslap_damage = INVALID_HANDLE

public OnPluginStart()
{
RegAdminCmd("sm_myslap", Command_MySlap, ADMFLAG_SLAY)

sm_myslap_damage = CreateConVar("sm_myslap_damage", "5", "Default slap damage")
AutoExecConfig(true, "plugin_myslap")
}

public Action:Command_MySlap(client, args)
{
new String:arg1[32], String:arg2[32]
new damage = GetConVarInt(sm_myslap_damage)

/* Остальное остается без изменений! */
</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.

For example, let's rewrite the last few lines of our slap command:
<pawn>
SlapPlayer(target, damage)

new String:name[MAX_NAME_LENGTH]

GetClientName(target, name, sizeof(name))

ShowActivity2(client, "[SM] ", "Slapped %s for %d damage!", name, damage)
LogAction(client, target, "\"%L\" slapped \"%L\" (damage %d)", client, target, damage)

return Plugin_Handled;
}
</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.

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.

This method of target processing is used for almost every admin command in SourceMod, and in fact FindTarget() is just a simplified version.

Full, final example:
<pawn>
#include <sourcemod>
#include <sdktools>

new Handle:sm_myslap_damage = INVALID_HANDLE

public Plugin:myinfo =
{
name = "My First Plugin",
author = "Me",
description = "My first plugin ever",
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", "Default slap damage")
AutoExecConfig(true, "plugin_myslap")
}

public Action:Command_MySlap(client, args)
{
new String:arg1[32], String:arg2[32]
new damage = GetConVarInt(sm_myslap_damage)

/* Get the first argument */
GetCmdArg(1, arg1, sizeof(arg1))

/* If there are 2 or more arguments, and the second argument fetch
* is successful, convert it to an integer.
*/
if (args >= 2 && GetCmdArg(2, arg2, sizeof(arg2)))
{
damage = StringToInt(arg2)
}

/**
* target_name - stores the noun identifying the target(s)
* target_list - array to store clients
* target_count - variable to store number of clients
* tn_is_ml - stores whether the noun must be translated
*/
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, /* Only allow alive players */
target_name,
sizeof(target_name),
tn_is_ml)) <= 0)
{
/* This function replies to the admin with a failure message */
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;
}</pawn>

=Client and Entity Indexes=
One major point of confusion with Half-Life 2 is the difference between the following things:
*Client index
*Entity index
*Userid

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.

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

A userid, on the other hand, is completely different. The 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.

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

=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]].

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>
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 */
}</pawn>

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

*[http://docs.sourcemod.net/api/index.php?fastload=show&id=576& AskPluginLoad()] - Called once, immediately after the plugin is loaded from the disk.
*[http://docs.sourcemod.net/api/index.php?fastload=show&id=575& 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()'''.
*[http://docs.sourcemod.net/api/index.php?fastload=show&id=580& 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().'''
*[http://docs.sourcemod.net/api/index.php?fastload=show&id=582& OnConfigsExecuted()] - Called once per map-change after <tt>servercfgfile</tt> (usually <tt>server.cfg</tt>), <tt>sourcemod.cfg</tt>, 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).
*[http://docs.sourcemod.net/api/index.php?fastload=show&id=581& OnMapEnd()] - Called when the map is about to end. At this point, all clients are disconnected, but <tt>TIMER_NO_MAPCHANGE</tt> timers are not yet destroyed. '''This function is paired to OnMapStart().'''
*[http://docs.sourcemod.net/api/index.php?fastload=show&id=577& 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.

*[http://docs.sourcemod.net/api/index.php?fastload=show&id=388& OnClientConnect()] - Called when a player initiates a connection. '''This is paired with OnClientDisconnect() for successful connections only.'''
*[http://docs.sourcemod.net/api/index.php?fastload=show&id=394& 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().
*[http://docs.sourcemod.net/api/index.php?fastload=show&id=389& OnClientPutInServer()] - Signifies that the player is in-game and IsClientInGame() will return true.
*[http://docs.sourcemod.net/api/index.php?fastload=show&id=396& 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.
*[http://docs.sourcemod.net/api/index.php?fastload=show&id=390& 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. <tt>#include <sourcemod></tt> will give you 95% of the .incs. Similarly, <tt>#include <sdktools></tt> 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 <tt>Plugin_Stop</tt> 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.

=Further Reading=
For further reading, see the "Scripting" section at the [http://docs.sourcemod.net/ SourceMod Documentation].

[[Category:Ru:SourceMod Scripting]]

Ru:Introduction to SourceMod Plugins

2008-12-27T17:02:02Z

Frenzzy: /* ConVars */

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

Для получения информации о компиляции плагинов см. [[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] или любой другой текстовый редактор.

=Структура плагина=
Почти все плагины имеют три одинаковых элемента:
*'''Includes''' - Позволяет получить доступ к SourceMod API, и если Вы хотите, к API от внешних SourceMod плагинов и расширений.
*'''Info''' - Общественная информация о Вашем плагине.
*'''Startup''' - Функция, которая осуществляет запуск процедур в Вашем плагине.

Плагин скелетной структуры выглядит следующим образом:
<pawn>
#include <sourcemod>

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

public OnPluginStart()
{
// Выполнение единовременного запуска задач ...
}</pawn>

Информация часть имеет специальную синтаксическую конструкцию. Вы не можете изменить любое из ключевых слов, или объявление <tt>public Plugin:myinfo</tt>. Хорошая идея заключается в том, чтобы скопировать и вставить эту скелетную структуру и отредактировать строки, чтобы начать работу.

=Включения=
Pawn требует включать файлы '''include''', как и C требует наличие заголовка у файла. Включение списков файлов всех структур, функций, вызовы и тегов, которые имеются в наличии. Есть три типа файлов:
*'''Core''' - <tt>sourcemod.inc</tt>, и все его включения. Все представленные в SourceMod Core.
*'''Extension''' - добавляет зависимость от определенного расширения.
*'''Plugin''' - добавляет зависимость от некоторых плагинов.

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

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

==Описание==
Во-первых, давайте смотреть на то, какая команда требуется администратору. Команды администратора регистрируются с использованием функции [http://docs.sourcemod.net/api/index.php?fastload=show&id=471& RegAdminCmd]. Она требует '''название''', '''функцию обратного вызова''' и '''флаги админа по умолчанию'''.

Функция обратного вызова это то, на что ссылаться используемая команда каждый раз. [http://docs.sourcemod.net/api/index.php?fastload=show&id=469& Нажми здесь], чтобы просмотреть её прототип. Пример:

<pawn>
public OnPluginStart()
{
RegAdminCmd("sm_myslap", Command_MySlap, ADMFLAG_SLAY)
}

public Action:Command_MySlap(client, args)
{
}</pawn>

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

<pawn>public Action:Command_MySlap(client, args)
{
return Plugin_Handled;
}</pawn>

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

==Реализация==
Давайте решим, что команда будет выглядеть так. Пусть будет она действовать как команда по умолчанию <tt>sm_slap</tt>:
<pre>sm_myslap <name|#userid> [damage]</pre>

Чтобы осуществить это, Нам потребуется несколько шагов:
*Получить ввод с консоли. Для этого мы используем [http://docs.sourcemod.net/api/index.php?fastload=show&id=473& GetCmdArg()].
*Найти соответствия игрока. Для этого мы используем [http://docs.sourcemod.net/api/index.php?fastload=show&id=144& FindTarget()].
*Ударить его. Для этого мы используем [http://docs.sourcemod.net/api/index.php?fastload=show&id=42& SlapPlayer()], которая требует в том числе <tt>sdktools</tt> расширение в комплекте с SourceMod.
*Сообщить администратору. Для этого мы используем [http://docs.sourcemod.net/api/index.php?fastload=show&id=462& ReplyToCommand()].

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

<pawn>
#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;
}</pawn>

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

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

Удобная особенность ConVars заключается в том, что они легко настраиваются пользователями. Они могут быть помещены в любой .cfg файл, например <tt>server.cfg</tt> или <tt>sourcemod.cfg</tt>. Чтобы сделать удобнее их использование, SourceMod имеет [http://docs.sourcemod.net/api/index.php?fastload=show&id=607& AutoExecConfig()] функции. Эта функция автоматически создает .cfg файл по умолчанию, содержащий все Ваши переменные (cvars), снабженные комментариями для пользователей. Очень рекомендую Вам вызывать её, если у Вас есть настраиваемые ConVars.

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

<pawn>new Handle:sm_myslap_damage = INVALID_HANDLE

public OnPluginStart()
{
RegAdminCmd("sm_myslap", Command_MySlap, ADMFLAG_SLAY)

sm_myslap_damage = CreateConVar("sm_myslap_damage", "5", "Default slap damage")
AutoExecConfig(true, "plugin_myslap")
}

public Action:Command_MySlap(client, args)
{
new String:arg1[32], String:arg2[32]
new damage = GetConVarInt(sm_myslap_damage)

/* Остальное остается не тронутым! */
</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.

For example, let's rewrite the last few lines of our slap command:
<pawn>
SlapPlayer(target, damage)

new String:name[MAX_NAME_LENGTH]

GetClientName(target, name, sizeof(name))

ShowActivity2(client, "[SM] ", "Slapped %s for %d damage!", name, damage)
LogAction(client, target, "\"%L\" slapped \"%L\" (damage %d)", client, target, damage)

return Plugin_Handled;
}
</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.

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.

This method of target processing is used for almost every admin command in SourceMod, and in fact FindTarget() is just a simplified version.

Full, final example:
<pawn>
#include <sourcemod>
#include <sdktools>

new Handle:sm_myslap_damage = INVALID_HANDLE

public Plugin:myinfo =
{
name = "My First Plugin",
author = "Me",
description = "My first plugin ever",
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", "Default slap damage")
AutoExecConfig(true, "plugin_myslap")
}

public Action:Command_MySlap(client, args)
{
new String:arg1[32], String:arg2[32]
new damage = GetConVarInt(sm_myslap_damage)

/* Get the first argument */
GetCmdArg(1, arg1, sizeof(arg1))

/* If there are 2 or more arguments, and the second argument fetch
* is successful, convert it to an integer.
*/
if (args >= 2 && GetCmdArg(2, arg2, sizeof(arg2)))
{
damage = StringToInt(arg2)
}

/**
* target_name - stores the noun identifying the target(s)
* target_list - array to store clients
* target_count - variable to store number of clients
* tn_is_ml - stores whether the noun must be translated
*/
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, /* Only allow alive players */
target_name,
sizeof(target_name),
tn_is_ml)) <= 0)
{
/* This function replies to the admin with a failure message */
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;
}</pawn>

=Client and Entity Indexes=
One major point of confusion with Half-Life 2 is the difference between the following things:
*Client index
*Entity index
*Userid

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.

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

A userid, on the other hand, is completely different. The 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.

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

=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]].

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>
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 */
}</pawn>

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

*[http://docs.sourcemod.net/api/index.php?fastload=show&id=576& AskPluginLoad()] - Called once, immediately after the plugin is loaded from the disk.
*[http://docs.sourcemod.net/api/index.php?fastload=show&id=575& 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()'''.
*[http://docs.sourcemod.net/api/index.php?fastload=show&id=580& 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().'''
*[http://docs.sourcemod.net/api/index.php?fastload=show&id=582& OnConfigsExecuted()] - Called once per map-change after <tt>servercfgfile</tt> (usually <tt>server.cfg</tt>), <tt>sourcemod.cfg</tt>, 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).
*[http://docs.sourcemod.net/api/index.php?fastload=show&id=581& OnMapEnd()] - Called when the map is about to end. At this point, all clients are disconnected, but <tt>TIMER_NO_MAPCHANGE</tt> timers are not yet destroyed. '''This function is paired to OnMapStart().'''
*[http://docs.sourcemod.net/api/index.php?fastload=show&id=577& 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.

*[http://docs.sourcemod.net/api/index.php?fastload=show&id=388& OnClientConnect()] - Called when a player initiates a connection. '''This is paired with OnClientDisconnect() for successful connections only.'''
*[http://docs.sourcemod.net/api/index.php?fastload=show&id=394& 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().
*[http://docs.sourcemod.net/api/index.php?fastload=show&id=389& OnClientPutInServer()] - Signifies that the player is in-game and IsClientInGame() will return true.
*[http://docs.sourcemod.net/api/index.php?fastload=show&id=396& 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.
*[http://docs.sourcemod.net/api/index.php?fastload=show&id=390& 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. <tt>#include <sourcemod></tt> will give you 95% of the .incs. Similarly, <tt>#include <sdktools></tt> 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 <tt>Plugin_Stop</tt> 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.

=Further Reading=
For further reading, see the "Scripting" section at the [http://docs.sourcemod.net/ SourceMod Documentation].

[[Category:Ru:SourceMod Scripting]]

Ru:Introduction to SourceMod Plugins

2008-12-26T14:51:26Z

Frenzzy: /* Реализация */

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

Для получения информации о компиляции плагинов см. [[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] или любой другой текстовый редактор.

=Структура плагина=
Почти все плагины имеют три одинаковых элемента:
*'''Includes''' - Позволяет получить доступ к SourceMod API, и если Вы хотите, к API от внешних SourceMod плагинов и расширений.
*'''Info''' - Общественная информация о Вашем плагине.
*'''Startup''' - Функция, которая осуществляет запуск процедур в Вашем плагине.

Плагин скелетной структуры выглядит следующим образом:
<pawn>
#include <sourcemod>

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

public OnPluginStart()
{
// Выполнение единовременного запуска задач ...
}</pawn>

Информация часть имеет специальную синтаксическую конструкцию. Вы не можете изменить любое из ключевых слов, или объявление <tt>public Plugin:myinfo</tt>. Хорошая идея заключается в том, чтобы скопировать и вставить эту скелетную структуру и отредактировать строки, чтобы начать работу.

=Включения=
Pawn требует включать файлы '''include''', как и C требует наличие заголовка у файла. Включение списков файлов всех структур, функций, вызовы и тегов, которые имеются в наличии. Есть три типа файлов:
*'''Core''' - <tt>sourcemod.inc</tt>, и все его включения. Все представленные в SourceMod Core.
*'''Extension''' - добавляет зависимость от определенного расширения.
*'''Plugin''' - добавляет зависимость от некоторых плагинов.

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

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

==Описание==
Во-первых, давайте смотреть на то, какая команда требуется администратору. Команды администратора регистрируются с использованием функции [http://docs.sourcemod.net/api/index.php?fastload=show&id=471& RegAdminCmd]. Она требует '''название''', '''функцию обратного вызова''' и '''флаги админа по умолчанию'''.

Функция обратного вызова это то, на что ссылаться используемая команда каждый раз. [http://docs.sourcemod.net/api/index.php?fastload=show&id=469& Нажми здесь], чтобы просмотреть её прототип. Пример:

<pawn>
public OnPluginStart()
{
RegAdminCmd("sm_myslap", Command_MySlap, ADMFLAG_SLAY)
}

public Action:Command_MySlap(client, args)
{
}</pawn>

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

<pawn>public Action:Command_MySlap(client, args)
{
return Plugin_Handled;
}</pawn>

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

==Реализация==
Давайте решим, что команда будет выглядеть так. Пусть будет она действовать как команда по умолчанию <tt>sm_slap</tt>:
<pre>sm_myslap <name|#userid> [damage]</pre>

Чтобы осуществить это, Нам потребуется несколько шагов:
*Получить ввод с консоли. Для этого мы используем [http://docs.sourcemod.net/api/index.php?fastload=show&id=473& GetCmdArg()].
*Найти соответствия игрока. Для этого мы используем [http://docs.sourcemod.net/api/index.php?fastload=show&id=144& FindTarget()].
*Ударить его. Для этого мы используем [http://docs.sourcemod.net/api/index.php?fastload=show&id=42& SlapPlayer()], которая требует в том числе <tt>sdktools</tt> расширение в комплекте с SourceMod.
*Сообщить администратору. Для этого мы используем [http://docs.sourcemod.net/api/index.php?fastload=show&id=462& ReplyToCommand()].

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

<pawn>
#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;
}</pawn>

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

=ConVars=
ConVars, also known as cvars, are global console variables in the Source engine. They can have integer, float, or string values. ConVar accessing is done through [[Handles (SourceMod Scripting)|Handles]]. Since ConVars are global, you do not need to close ConVar Handles (in fact, you cannot).

The handy feature of ConVars is that they are easy for users to configure. They can be placed in any .cfg file, such as <tt>server.cfg</tt> or <tt>sourcemod.cfg</tt>. To make this easier, SourceMod has an [http://docs.sourcemod.net/api/index.php?fastload=show&id=607& AutoExecConfig()] function. This function will automatically build a default .cfg file containing all of your cvars, annotated with comments, for users. It is highly recommend that you call this if you have customizable ConVars.

Let's extend your example from earlier with a new ConVar. Our ConVar will be <tt>sm_myslap_damage</tt> and will specify the default damage someone is slapped for if no damage is specified.

<pawn>new Handle:sm_myslap_damage = INVALID_HANDLE

public OnPluginStart()
{
RegAdminCmd("sm_myslap", Command_MySlap, ADMFLAG_SLAY)

sm_myslap_damage = CreateConVar("sm_myslap_damage", "5", "Default slap damage")
AutoExecConfig(true, "plugin_myslap")
}

public Action:Command_MySlap(client, args)
{
new String:arg1[32], String:arg2[32]
new damage = GetConVarInt(sm_myslap_damage)

/* The rest remains unchanged! */
</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.

For example, let's rewrite the last few lines of our slap command:
<pawn>
SlapPlayer(target, damage)

new String:name[MAX_NAME_LENGTH]

GetClientName(target, name, sizeof(name))

ShowActivity2(client, "[SM] ", "Slapped %s for %d damage!", name, damage)
LogAction(client, target, "\"%L\" slapped \"%L\" (damage %d)", client, target, damage)

return Plugin_Handled;
}
</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.

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.

This method of target processing is used for almost every admin command in SourceMod, and in fact FindTarget() is just a simplified version.

Full, final example:
<pawn>
#include <sourcemod>
#include <sdktools>

new Handle:sm_myslap_damage = INVALID_HANDLE

public Plugin:myinfo =
{
name = "My First Plugin",
author = "Me",
description = "My first plugin ever",
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", "Default slap damage")
AutoExecConfig(true, "plugin_myslap")
}

public Action:Command_MySlap(client, args)
{
new String:arg1[32], String:arg2[32]
new damage = GetConVarInt(sm_myslap_damage)

/* Get the first argument */
GetCmdArg(1, arg1, sizeof(arg1))

/* If there are 2 or more arguments, and the second argument fetch
* is successful, convert it to an integer.
*/
if (args >= 2 && GetCmdArg(2, arg2, sizeof(arg2)))
{
damage = StringToInt(arg2)
}

/**
* target_name - stores the noun identifying the target(s)
* target_list - array to store clients
* target_count - variable to store number of clients
* tn_is_ml - stores whether the noun must be translated
*/
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, /* Only allow alive players */
target_name,
sizeof(target_name),
tn_is_ml)) <= 0)
{
/* This function replies to the admin with a failure message */
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;
}</pawn>

=Client and Entity Indexes=
One major point of confusion with Half-Life 2 is the difference between the following things:
*Client index
*Entity index
*Userid

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.

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

A userid, on the other hand, is completely different. The 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.

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

=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]].

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>
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 */
}</pawn>

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

*[http://docs.sourcemod.net/api/index.php?fastload=show&id=576& AskPluginLoad()] - Called once, immediately after the plugin is loaded from the disk.
*[http://docs.sourcemod.net/api/index.php?fastload=show&id=575& 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()'''.
*[http://docs.sourcemod.net/api/index.php?fastload=show&id=580& 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().'''
*[http://docs.sourcemod.net/api/index.php?fastload=show&id=582& OnConfigsExecuted()] - Called once per map-change after <tt>servercfgfile</tt> (usually <tt>server.cfg</tt>), <tt>sourcemod.cfg</tt>, 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).
*[http://docs.sourcemod.net/api/index.php?fastload=show&id=581& OnMapEnd()] - Called when the map is about to end. At this point, all clients are disconnected, but <tt>TIMER_NO_MAPCHANGE</tt> timers are not yet destroyed. '''This function is paired to OnMapStart().'''
*[http://docs.sourcemod.net/api/index.php?fastload=show&id=577& 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.

*[http://docs.sourcemod.net/api/index.php?fastload=show&id=388& OnClientConnect()] - Called when a player initiates a connection. '''This is paired with OnClientDisconnect() for successful connections only.'''
*[http://docs.sourcemod.net/api/index.php?fastload=show&id=394& 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().
*[http://docs.sourcemod.net/api/index.php?fastload=show&id=389& OnClientPutInServer()] - Signifies that the player is in-game and IsClientInGame() will return true.
*[http://docs.sourcemod.net/api/index.php?fastload=show&id=396& 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.
*[http://docs.sourcemod.net/api/index.php?fastload=show&id=390& 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. <tt>#include <sourcemod></tt> will give you 95% of the .incs. Similarly, <tt>#include <sdktools></tt> 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 <tt>Plugin_Stop</tt> 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.

=Further Reading=
For further reading, see the "Scripting" section at the [http://docs.sourcemod.net/ SourceMod Documentation].

[[Category:Ru:SourceMod Scripting]]

Ru:Introduction to SourceMod Plugins

2008-12-26T14:44:05Z

Frenzzy: /* Implementation */

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

Для получения информации о компиляции плагинов см. [[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] или любой другой текстовый редактор.

=Структура плагина=
Почти все плагины имеют три одинаковых элемента:
*'''Includes''' - Позволяет получить доступ к SourceMod API, и если Вы хотите, к API от внешних SourceMod плагинов и расширений.
*'''Info''' - Общественная информация о Вашем плагине.
*'''Startup''' - Функция, которая осуществляет запуск процедур в Вашем плагине.

Плагин скелетной структуры выглядит следующим образом:
<pawn>
#include <sourcemod>

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

public OnPluginStart()
{
// Выполнение единовременного запуска задач ...
}</pawn>

Информация часть имеет специальную синтаксическую конструкцию. Вы не можете изменить любое из ключевых слов, или объявление <tt>public Plugin:myinfo</tt>. Хорошая идея заключается в том, чтобы скопировать и вставить эту скелетную структуру и отредактировать строки, чтобы начать работу.

=Включения=
Pawn требует включать файлы '''include''', как и C требует наличие заголовка у файла. Включение списков файлов всех структур, функций, вызовы и тегов, которые имеются в наличии. Есть три типа файлов:
*'''Core''' - <tt>sourcemod.inc</tt>, и все его включения. Все представленные в SourceMod Core.
*'''Extension''' - добавляет зависимость от определенного расширения.
*'''Plugin''' - добавляет зависимость от некоторых плагинов.

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

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

==Описание==
Во-первых, давайте смотреть на то, какая команда требуется администратору. Команды администратора регистрируются с использованием функции [http://docs.sourcemod.net/api/index.php?fastload=show&id=471& RegAdminCmd]. Она требует '''название''', '''функцию обратного вызова''' и '''флаги админа по умолчанию'''.

Функция обратного вызова это то, на что ссылаться используемая команда каждый раз. [http://docs.sourcemod.net/api/index.php?fastload=show&id=469& Нажми здесь], чтобы просмотреть её прототип. Пример:

<pawn>
public OnPluginStart()
{
RegAdminCmd("sm_myslap", Command_MySlap, ADMFLAG_SLAY)
}

public Action:Command_MySlap(client, args)
{
}</pawn>

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

<pawn>public Action:Command_MySlap(client, args)
{
return Plugin_Handled;
}</pawn>

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

==Реализация==
Давайте решим, что команда будет выглядеть так. Пусть будет она действовать как команда по умолчанию <tt>sm_slap</tt>:
<pre>sm_myslap <name|#userid> [damage]</pre>

Чтобы осуществить это, Нам потребуется несколько шагов:
*Получить ввод с консоли. Для этого мы используем [http://docs.sourcemod.net/api/index.php?fastload=show&id=473& GetCmdArg()].
*Найти соответствия игрока. Для этого мы используем [http://docs.sourcemod.net/api/index.php?fastload=show&id=144& FindTarget()].
*Ударить его. Для этого мы используем [http://docs.sourcemod.net/api/index.php?fastload=show&id=42& SlapPlayer()], которая требует в том числе <tt>sdktools</tt> расширение в комплекте с SourceMod.
*Сообщить администратору. Для этого мы используем [http://docs.sourcemod.net/api/index.php?fastload=show&id=462& ReplyToCommand()].

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

<pawn>
#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)
}

/* Try and find a matching player */
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;
}</pawn>

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

=ConVars=
ConVars, also known as cvars, are global console variables in the Source engine. They can have integer, float, or string values. ConVar accessing is done through [[Handles (SourceMod Scripting)|Handles]]. Since ConVars are global, you do not need to close ConVar Handles (in fact, you cannot).

The handy feature of ConVars is that they are easy for users to configure. They can be placed in any .cfg file, such as <tt>server.cfg</tt> or <tt>sourcemod.cfg</tt>. To make this easier, SourceMod has an [http://docs.sourcemod.net/api/index.php?fastload=show&id=607& AutoExecConfig()] function. This function will automatically build a default .cfg file containing all of your cvars, annotated with comments, for users. It is highly recommend that you call this if you have customizable ConVars.

Let's extend your example from earlier with a new ConVar. Our ConVar will be <tt>sm_myslap_damage</tt> and will specify the default damage someone is slapped for if no damage is specified.

<pawn>new Handle:sm_myslap_damage = INVALID_HANDLE

public OnPluginStart()
{
RegAdminCmd("sm_myslap", Command_MySlap, ADMFLAG_SLAY)

sm_myslap_damage = CreateConVar("sm_myslap_damage", "5", "Default slap damage")
AutoExecConfig(true, "plugin_myslap")
}

public Action:Command_MySlap(client, args)
{
new String:arg1[32], String:arg2[32]
new damage = GetConVarInt(sm_myslap_damage)

/* The rest remains unchanged! */
</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.

For example, let's rewrite the last few lines of our slap command:
<pawn>
SlapPlayer(target, damage)

new String:name[MAX_NAME_LENGTH]

GetClientName(target, name, sizeof(name))

ShowActivity2(client, "[SM] ", "Slapped %s for %d damage!", name, damage)
LogAction(client, target, "\"%L\" slapped \"%L\" (damage %d)", client, target, damage)

return Plugin_Handled;
}
</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.

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.

This method of target processing is used for almost every admin command in SourceMod, and in fact FindTarget() is just a simplified version.

Full, final example:
<pawn>
#include <sourcemod>
#include <sdktools>

new Handle:sm_myslap_damage = INVALID_HANDLE

public Plugin:myinfo =
{
name = "My First Plugin",
author = "Me",
description = "My first plugin ever",
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", "Default slap damage")
AutoExecConfig(true, "plugin_myslap")
}

public Action:Command_MySlap(client, args)
{
new String:arg1[32], String:arg2[32]
new damage = GetConVarInt(sm_myslap_damage)

/* Get the first argument */
GetCmdArg(1, arg1, sizeof(arg1))

/* If there are 2 or more arguments, and the second argument fetch
* is successful, convert it to an integer.
*/
if (args >= 2 && GetCmdArg(2, arg2, sizeof(arg2)))
{
damage = StringToInt(arg2)
}

/**
* target_name - stores the noun identifying the target(s)
* target_list - array to store clients
* target_count - variable to store number of clients
* tn_is_ml - stores whether the noun must be translated
*/
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, /* Only allow alive players */
target_name,
sizeof(target_name),
tn_is_ml)) <= 0)
{
/* This function replies to the admin with a failure message */
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;
}</pawn>

=Client and Entity Indexes=
One major point of confusion with Half-Life 2 is the difference between the following things:
*Client index
*Entity index
*Userid

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.

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

A userid, on the other hand, is completely different. The 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.

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

=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]].

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>
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 */
}</pawn>

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

*[http://docs.sourcemod.net/api/index.php?fastload=show&id=576& AskPluginLoad()] - Called once, immediately after the plugin is loaded from the disk.
*[http://docs.sourcemod.net/api/index.php?fastload=show&id=575& 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()'''.
*[http://docs.sourcemod.net/api/index.php?fastload=show&id=580& 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().'''
*[http://docs.sourcemod.net/api/index.php?fastload=show&id=582& OnConfigsExecuted()] - Called once per map-change after <tt>servercfgfile</tt> (usually <tt>server.cfg</tt>), <tt>sourcemod.cfg</tt>, 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).
*[http://docs.sourcemod.net/api/index.php?fastload=show&id=581& OnMapEnd()] - Called when the map is about to end. At this point, all clients are disconnected, but <tt>TIMER_NO_MAPCHANGE</tt> timers are not yet destroyed. '''This function is paired to OnMapStart().'''
*[http://docs.sourcemod.net/api/index.php?fastload=show&id=577& 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.

*[http://docs.sourcemod.net/api/index.php?fastload=show&id=388& OnClientConnect()] - Called when a player initiates a connection. '''This is paired with OnClientDisconnect() for successful connections only.'''
*[http://docs.sourcemod.net/api/index.php?fastload=show&id=394& 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().
*[http://docs.sourcemod.net/api/index.php?fastload=show&id=389& OnClientPutInServer()] - Signifies that the player is in-game and IsClientInGame() will return true.
*[http://docs.sourcemod.net/api/index.php?fastload=show&id=396& 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.
*[http://docs.sourcemod.net/api/index.php?fastload=show&id=390& 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. <tt>#include <sourcemod></tt> will give you 95% of the .incs. Similarly, <tt>#include <sdktools></tt> 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 <tt>Plugin_Stop</tt> 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.

=Further Reading=
For further reading, see the "Scripting" section at the [http://docs.sourcemod.net/ SourceMod Documentation].

[[Category:Ru:SourceMod Scripting]]

Ru:Introduction to SourceMod Plugins

2008-12-26T14:25:13Z

Frenzzy: /* Declaration */

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

Для получения информации о компиляции плагинов см. [[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] или любой другой текстовый редактор.

=Структура плагина=
Почти все плагины имеют три одинаковых элемента:
*'''Includes''' - Позволяет получить доступ к SourceMod API, и если Вы хотите, к API от внешних SourceMod плагинов и расширений.
*'''Info''' - Общественная информация о Вашем плагине.
*'''Startup''' - Функция, которая осуществляет запуск процедур в Вашем плагине.

Плагин скелетной структуры выглядит следующим образом:
<pawn>
#include <sourcemod>

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

public OnPluginStart()
{
// Выполнение единовременного запуска задач ...
}</pawn>

Информация часть имеет специальную синтаксическую конструкцию. Вы не можете изменить любое из ключевых слов, или объявление <tt>public Plugin:myinfo</tt>. Хорошая идея заключается в том, чтобы скопировать и вставить эту скелетную структуру и отредактировать строки, чтобы начать работу.

=Включения=
Pawn требует включать файлы '''include''', как и C требует наличие заголовка у файла. Включение списков файлов всех структур, функций, вызовы и тегов, которые имеются в наличии. Есть три типа файлов:
*'''Core''' - <tt>sourcemod.inc</tt>, и все его включения. Все представленные в SourceMod Core.
*'''Extension''' - добавляет зависимость от определенного расширения.
*'''Plugin''' - добавляет зависимость от некоторых плагинов.

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

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

==Описание==
Во-первых, давайте смотреть на то, какая команда требуется администратору. Команды администратора регистрируются с использованием функции [http://docs.sourcemod.net/api/index.php?fastload=show&id=471& RegAdminCmd]. Она требует '''название''', '''функцию обратного вызова''' и '''флаги админа по умолчанию'''.

Функция обратного вызова это то, на что ссылаться используемая команда каждый раз. [http://docs.sourcemod.net/api/index.php?fastload=show&id=469& Нажми здесь], чтобы просмотреть её прототип. Пример:

<pawn>
public OnPluginStart()
{
RegAdminCmd("sm_myslap", Command_MySlap, ADMFLAG_SLAY)
}

public Action:Command_MySlap(client, args)
{
}</pawn>

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

<pawn>public Action:Command_MySlap(client, args)
{
return Plugin_Handled;
}</pawn>

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

==Implementation==
Let's decide what the command will look like. Let's have it act like the default <tt>sm_slap</tt> command:
<pre>sm_myslap <name|#userid> [damage]</pre>

To implement this, we'll need a few steps:
*Get the input from the console. For this we use [http://docs.sourcemod.net/api/index.php?fastload=show&id=473& GetCmdArg()].
*Find a matching player. For this we use [http://docs.sourcemod.net/api/index.php?fastload=show&id=144& FindTarget()].
*Slap them. For this we use [http://docs.sourcemod.net/api/index.php?fastload=show&id=42& SlapPlayer()], which requires including <tt>sdktools</tt>, an extension bundled with SourceMod.
*Respond to the admin. For this we use [http://docs.sourcemod.net/api/index.php?fastload=show&id=462& ReplyToCommand()].

Full example:

<pawn>
#include <sourcemod>
#include <sdktools>

public Plugin:myinfo =
{
name = "My First Plugin",
author = "Me",
description = "My first plugin ever",
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

/* Get the first argument */
GetCmdArg(1, arg1, sizeof(arg1))

/* If there are 2 or more arguments, and the second argument fetch
* is successful, convert it to an integer.
*/
if (args >= 2 && GetCmdArg(2, arg2, sizeof(arg2)))
{
damage = StringToInt(arg2)
}

/* Try and find a matching player */
new target = FindTarget(client, arg1)
if (target == -1)
{
/* FindTarget() automatically replies with the
* failure reason.
*/
return Plugin_Handled;
}

SlapPlayer(target, damage)

new String:name[MAX_NAME_LENGTH]

GetClientName(target, name, sizeof(name))
ReplyToCommand(client, "[SM] You slapped %s for %d damage!", name, damage)

return Plugin_Handled;
}</pawn>

For more information on what %s and %d are, see [[Format Class Functions (SourceMod Scripting)|Format Class Functions]]. Note that you never need to unregister or remove your admin command. When a plugin is unloaded, SourceMod cleans it up for you.

=ConVars=
ConVars, also known as cvars, are global console variables in the Source engine. They can have integer, float, or string values. ConVar accessing is done through [[Handles (SourceMod Scripting)|Handles]]. Since ConVars are global, you do not need to close ConVar Handles (in fact, you cannot).

The handy feature of ConVars is that they are easy for users to configure. They can be placed in any .cfg file, such as <tt>server.cfg</tt> or <tt>sourcemod.cfg</tt>. To make this easier, SourceMod has an [http://docs.sourcemod.net/api/index.php?fastload=show&id=607& AutoExecConfig()] function. This function will automatically build a default .cfg file containing all of your cvars, annotated with comments, for users. It is highly recommend that you call this if you have customizable ConVars.

Let's extend your example from earlier with a new ConVar. Our ConVar will be <tt>sm_myslap_damage</tt> and will specify the default damage someone is slapped for if no damage is specified.

<pawn>new Handle:sm_myslap_damage = INVALID_HANDLE

public OnPluginStart()
{
RegAdminCmd("sm_myslap", Command_MySlap, ADMFLAG_SLAY)

sm_myslap_damage = CreateConVar("sm_myslap_damage", "5", "Default slap damage")
AutoExecConfig(true, "plugin_myslap")
}

public Action:Command_MySlap(client, args)
{
new String:arg1[32], String:arg2[32]
new damage = GetConVarInt(sm_myslap_damage)

/* The rest remains unchanged! */
</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.

For example, let's rewrite the last few lines of our slap command:
<pawn>
SlapPlayer(target, damage)

new String:name[MAX_NAME_LENGTH]

GetClientName(target, name, sizeof(name))

ShowActivity2(client, "[SM] ", "Slapped %s for %d damage!", name, damage)
LogAction(client, target, "\"%L\" slapped \"%L\" (damage %d)", client, target, damage)

return Plugin_Handled;
}
</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.

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.

This method of target processing is used for almost every admin command in SourceMod, and in fact FindTarget() is just a simplified version.

Full, final example:
<pawn>
#include <sourcemod>
#include <sdktools>

new Handle:sm_myslap_damage = INVALID_HANDLE

public Plugin:myinfo =
{
name = "My First Plugin",
author = "Me",
description = "My first plugin ever",
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", "Default slap damage")
AutoExecConfig(true, "plugin_myslap")
}

public Action:Command_MySlap(client, args)
{
new String:arg1[32], String:arg2[32]
new damage = GetConVarInt(sm_myslap_damage)

/* Get the first argument */
GetCmdArg(1, arg1, sizeof(arg1))

/* If there are 2 or more arguments, and the second argument fetch
* is successful, convert it to an integer.
*/
if (args >= 2 && GetCmdArg(2, arg2, sizeof(arg2)))
{
damage = StringToInt(arg2)
}

/**
* target_name - stores the noun identifying the target(s)
* target_list - array to store clients
* target_count - variable to store number of clients
* tn_is_ml - stores whether the noun must be translated
*/
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, /* Only allow alive players */
target_name,
sizeof(target_name),
tn_is_ml)) <= 0)
{
/* This function replies to the admin with a failure message */
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;
}</pawn>

=Client and Entity Indexes=
One major point of confusion with Half-Life 2 is the difference between the following things:
*Client index
*Entity index
*Userid

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.

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

A userid, on the other hand, is completely different. The 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.

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

=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]].

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>
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 */
}</pawn>

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

*[http://docs.sourcemod.net/api/index.php?fastload=show&id=576& AskPluginLoad()] - Called once, immediately after the plugin is loaded from the disk.
*[http://docs.sourcemod.net/api/index.php?fastload=show&id=575& 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()'''.
*[http://docs.sourcemod.net/api/index.php?fastload=show&id=580& 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().'''
*[http://docs.sourcemod.net/api/index.php?fastload=show&id=582& OnConfigsExecuted()] - Called once per map-change after <tt>servercfgfile</tt> (usually <tt>server.cfg</tt>), <tt>sourcemod.cfg</tt>, 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).
*[http://docs.sourcemod.net/api/index.php?fastload=show&id=581& OnMapEnd()] - Called when the map is about to end. At this point, all clients are disconnected, but <tt>TIMER_NO_MAPCHANGE</tt> timers are not yet destroyed. '''This function is paired to OnMapStart().'''
*[http://docs.sourcemod.net/api/index.php?fastload=show&id=577& 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.

*[http://docs.sourcemod.net/api/index.php?fastload=show&id=388& OnClientConnect()] - Called when a player initiates a connection. '''This is paired with OnClientDisconnect() for successful connections only.'''
*[http://docs.sourcemod.net/api/index.php?fastload=show&id=394& 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().
*[http://docs.sourcemod.net/api/index.php?fastload=show&id=389& OnClientPutInServer()] - Signifies that the player is in-game and IsClientInGame() will return true.
*[http://docs.sourcemod.net/api/index.php?fastload=show&id=396& 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.
*[http://docs.sourcemod.net/api/index.php?fastload=show&id=390& 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. <tt>#include <sourcemod></tt> will give you 95% of the .incs. Similarly, <tt>#include <sdktools></tt> 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 <tt>Plugin_Stop</tt> 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.

=Further Reading=
For further reading, see the "Scripting" section at the [http://docs.sourcemod.net/ SourceMod Documentation].

[[Category:Ru:SourceMod Scripting]]

Ru:Introduction to SourceMod Plugins

2008-12-26T14:07:46Z

Frenzzy: /* Commands */

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

Для получения информации о компиляции плагинов см. [[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] или любой другой текстовый редактор.

=Структура плагина=
Почти все плагины имеют три одинаковых элемента:
*'''Includes''' - Позволяет получить доступ к SourceMod API, и если Вы хотите, к API от внешних SourceMod плагинов и расширений.
*'''Info''' - Общественная информация о Вашем плагине.
*'''Startup''' - Функция, которая осуществляет запуск процедур в Вашем плагине.

Плагин скелетной структуры выглядит следующим образом:
<pawn>
#include <sourcemod>

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

public OnPluginStart()
{
// Выполнение единовременного запуска задач ...
}</pawn>

Информация часть имеет специальную синтаксическую конструкцию. Вы не можете изменить любое из ключевых слов, или объявление <tt>public Plugin:myinfo</tt>. Хорошая идея заключается в том, чтобы скопировать и вставить эту скелетную структуру и отредактировать строки, чтобы начать работу.

=Включения=
Pawn требует включать файлы '''include''', как и C требует наличие заголовка у файла. Включение списков файлов всех структур, функций, вызовы и тегов, которые имеются в наличии. Есть три типа файлов:
*'''Core''' - <tt>sourcemod.inc</tt>, и все его включения. Все представленные в SourceMod Core.
*'''Extension''' - добавляет зависимость от определенного расширения.
*'''Plugin''' - добавляет зависимость от некоторых плагинов.

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

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

==Declaration==
First, let's look at what an admin command requires. Admin commands are registered using the [http://docs.sourcemod.net/api/index.php?fastload=show&id=471& RegAdminCmd] function. They require a '''name''', a '''callback function''', and '''default admin flags'''.

The callback function is what's invoked every time the command is used. [http://docs.sourcemod.net/api/index.php?fastload=show&id=469& Click here] to see its prototype. Example:

<pawn>
public OnPluginStart()
{
RegAdminCmd("sm_myslap", Command_MySlap, ADMFLAG_SLAY)
}

public Action:Command_MySlap(client, args)
{
}</pawn>

Now we've successfully implemented a command -- though it doesn't do anything yet. In fact, it will say "Unknown command" if you use it! The reason is because of the <tt>Action</tt> tag. The default functionality for entering console commands is to reply that they are unknown. To block this functionality, you must return a new action:

<pawn>public Action:Command_MySlap(client, args)
{
return Plugin_Handled;
}</pawn>

Now the command will report no error, but it still won't do anything.

==Implementation==
Let's decide what the command will look like. Let's have it act like the default <tt>sm_slap</tt> command:
<pre>sm_myslap <name|#userid> [damage]</pre>

To implement this, we'll need a few steps:
*Get the input from the console. For this we use [http://docs.sourcemod.net/api/index.php?fastload=show&id=473& GetCmdArg()].
*Find a matching player. For this we use [http://docs.sourcemod.net/api/index.php?fastload=show&id=144& FindTarget()].
*Slap them. For this we use [http://docs.sourcemod.net/api/index.php?fastload=show&id=42& SlapPlayer()], which requires including <tt>sdktools</tt>, an extension bundled with SourceMod.
*Respond to the admin. For this we use [http://docs.sourcemod.net/api/index.php?fastload=show&id=462& ReplyToCommand()].

Full example:

<pawn>
#include <sourcemod>
#include <sdktools>

public Plugin:myinfo =
{
name = "My First Plugin",
author = "Me",
description = "My first plugin ever",
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

/* Get the first argument */
GetCmdArg(1, arg1, sizeof(arg1))

/* If there are 2 or more arguments, and the second argument fetch
* is successful, convert it to an integer.
*/
if (args >= 2 && GetCmdArg(2, arg2, sizeof(arg2)))
{
damage = StringToInt(arg2)
}

/* Try and find a matching player */
new target = FindTarget(client, arg1)
if (target == -1)
{
/* FindTarget() automatically replies with the
* failure reason.
*/
return Plugin_Handled;
}

SlapPlayer(target, damage)

new String:name[MAX_NAME_LENGTH]

GetClientName(target, name, sizeof(name))
ReplyToCommand(client, "[SM] You slapped %s for %d damage!", name, damage)

return Plugin_Handled;
}</pawn>

For more information on what %s and %d are, see [[Format Class Functions (SourceMod Scripting)|Format Class Functions]]. Note that you never need to unregister or remove your admin command. When a plugin is unloaded, SourceMod cleans it up for you.

=ConVars=
ConVars, also known as cvars, are global console variables in the Source engine. They can have integer, float, or string values. ConVar accessing is done through [[Handles (SourceMod Scripting)|Handles]]. Since ConVars are global, you do not need to close ConVar Handles (in fact, you cannot).

The handy feature of ConVars is that they are easy for users to configure. They can be placed in any .cfg file, such as <tt>server.cfg</tt> or <tt>sourcemod.cfg</tt>. To make this easier, SourceMod has an [http://docs.sourcemod.net/api/index.php?fastload=show&id=607& AutoExecConfig()] function. This function will automatically build a default .cfg file containing all of your cvars, annotated with comments, for users. It is highly recommend that you call this if you have customizable ConVars.

Let's extend your example from earlier with a new ConVar. Our ConVar will be <tt>sm_myslap_damage</tt> and will specify the default damage someone is slapped for if no damage is specified.

<pawn>new Handle:sm_myslap_damage = INVALID_HANDLE

public OnPluginStart()
{
RegAdminCmd("sm_myslap", Command_MySlap, ADMFLAG_SLAY)

sm_myslap_damage = CreateConVar("sm_myslap_damage", "5", "Default slap damage")
AutoExecConfig(true, "plugin_myslap")
}

public Action:Command_MySlap(client, args)
{
new String:arg1[32], String:arg2[32]
new damage = GetConVarInt(sm_myslap_damage)

/* The rest remains unchanged! */
</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.

For example, let's rewrite the last few lines of our slap command:
<pawn>
SlapPlayer(target, damage)

new String:name[MAX_NAME_LENGTH]

GetClientName(target, name, sizeof(name))

ShowActivity2(client, "[SM] ", "Slapped %s for %d damage!", name, damage)
LogAction(client, target, "\"%L\" slapped \"%L\" (damage %d)", client, target, damage)

return Plugin_Handled;
}
</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.

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.

This method of target processing is used for almost every admin command in SourceMod, and in fact FindTarget() is just a simplified version.

Full, final example:
<pawn>
#include <sourcemod>
#include <sdktools>

new Handle:sm_myslap_damage = INVALID_HANDLE

public Plugin:myinfo =
{
name = "My First Plugin",
author = "Me",
description = "My first plugin ever",
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", "Default slap damage")
AutoExecConfig(true, "plugin_myslap")
}

public Action:Command_MySlap(client, args)
{
new String:arg1[32], String:arg2[32]
new damage = GetConVarInt(sm_myslap_damage)

/* Get the first argument */
GetCmdArg(1, arg1, sizeof(arg1))

/* If there are 2 or more arguments, and the second argument fetch
* is successful, convert it to an integer.
*/
if (args >= 2 && GetCmdArg(2, arg2, sizeof(arg2)))
{
damage = StringToInt(arg2)
}

/**
* target_name - stores the noun identifying the target(s)
* target_list - array to store clients
* target_count - variable to store number of clients
* tn_is_ml - stores whether the noun must be translated
*/
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, /* Only allow alive players */
target_name,
sizeof(target_name),
tn_is_ml)) <= 0)
{
/* This function replies to the admin with a failure message */
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;
}</pawn>

=Client and Entity Indexes=
One major point of confusion with Half-Life 2 is the difference between the following things:
*Client index
*Entity index
*Userid

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.

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

A userid, on the other hand, is completely different. The 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.

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

=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]].

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>
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 */
}</pawn>

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

*[http://docs.sourcemod.net/api/index.php?fastload=show&id=576& AskPluginLoad()] - Called once, immediately after the plugin is loaded from the disk.
*[http://docs.sourcemod.net/api/index.php?fastload=show&id=575& 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()'''.
*[http://docs.sourcemod.net/api/index.php?fastload=show&id=580& 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().'''
*[http://docs.sourcemod.net/api/index.php?fastload=show&id=582& OnConfigsExecuted()] - Called once per map-change after <tt>servercfgfile</tt> (usually <tt>server.cfg</tt>), <tt>sourcemod.cfg</tt>, 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).
*[http://docs.sourcemod.net/api/index.php?fastload=show&id=581& OnMapEnd()] - Called when the map is about to end. At this point, all clients are disconnected, but <tt>TIMER_NO_MAPCHANGE</tt> timers are not yet destroyed. '''This function is paired to OnMapStart().'''
*[http://docs.sourcemod.net/api/index.php?fastload=show&id=577& 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.

*[http://docs.sourcemod.net/api/index.php?fastload=show&id=388& OnClientConnect()] - Called when a player initiates a connection. '''This is paired with OnClientDisconnect() for successful connections only.'''
*[http://docs.sourcemod.net/api/index.php?fastload=show&id=394& 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().
*[http://docs.sourcemod.net/api/index.php?fastload=show&id=389& OnClientPutInServer()] - Signifies that the player is in-game and IsClientInGame() will return true.
*[http://docs.sourcemod.net/api/index.php?fastload=show&id=396& 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.
*[http://docs.sourcemod.net/api/index.php?fastload=show&id=390& 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. <tt>#include <sourcemod></tt> will give you 95% of the .incs. Similarly, <tt>#include <sdktools></tt> 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 <tt>Plugin_Stop</tt> 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.

=Further Reading=
For further reading, see the "Scripting" section at the [http://docs.sourcemod.net/ SourceMod Documentation].

[[Category:Ru:SourceMod Scripting]]

Ru:Introduction to SourceMod Plugins

2008-12-26T14:00:40Z

Frenzzy: /* Includes */

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

Для получения информации о компиляции плагинов см. [[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] или любой другой текстовый редактор.

=Структура плагина=
Почти все плагины имеют три одинаковых элемента:
*'''Includes''' - Позволяет получить доступ к SourceMod API, и если Вы хотите, к API от внешних SourceMod плагинов и расширений.
*'''Info''' - Общественная информация о Вашем плагине.
*'''Startup''' - Функция, которая осуществляет запуск процедур в Вашем плагине.

Плагин скелетной структуры выглядит следующим образом:
<pawn>
#include <sourcemod>

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

public OnPluginStart()
{
// Выполнение единовременного запуска задач ...
}</pawn>

Информация часть имеет специальную синтаксическую конструкцию. Вы не можете изменить любое из ключевых слов, или объявление <tt>public Plugin:myinfo</tt>. Хорошая идея заключается в том, чтобы скопировать и вставить эту скелетную структуру и отредактировать строки, чтобы начать работу.

=Включения=
Pawn требует включать файлы '''include''', как и C требует наличие заголовка у файла. Включение списков файлов всех структур, функций, вызовы и тегов, которые имеются в наличии. Есть три типа файлов:
*'''Core''' - <tt>sourcemod.inc</tt>, и все его включения. Все представленные в SourceMod Core.
*'''Extension''' - добавляет зависимость от определенного расширения.
*'''Plugin''' - добавляет зависимость от некоторых плагинов.

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

=Commands=
Our first example will be writing a simple admin command to slap a player. We'll continue to extend this example with more features until we have a final, complete result.

==Declaration==
First, let's look at what an admin command requires. Admin commands are registered using the [http://docs.sourcemod.net/api/index.php?fastload=show&id=471& RegAdminCmd] function. They require a '''name''', a '''callback function''', and '''default admin flags'''.

The callback function is what's invoked every time the command is used. [http://docs.sourcemod.net/api/index.php?fastload=show&id=469& Click here] to see its prototype. Example:

<pawn>
public OnPluginStart()
{
RegAdminCmd("sm_myslap", Command_MySlap, ADMFLAG_SLAY)
}

public Action:Command_MySlap(client, args)
{
}</pawn>

Now we've successfully implemented a command -- though it doesn't do anything yet. In fact, it will say "Unknown command" if you use it! The reason is because of the <tt>Action</tt> tag. The default functionality for entering console commands is to reply that they are unknown. To block this functionality, you must return a new action:

<pawn>public Action:Command_MySlap(client, args)
{
return Plugin_Handled;
}</pawn>

Now the command will report no error, but it still won't do anything.

==Implementation==
Let's decide what the command will look like. Let's have it act like the default <tt>sm_slap</tt> command:
<pre>sm_myslap <name|#userid> [damage]</pre>

To implement this, we'll need a few steps:
*Get the input from the console. For this we use [http://docs.sourcemod.net/api/index.php?fastload=show&id=473& GetCmdArg()].
*Find a matching player. For this we use [http://docs.sourcemod.net/api/index.php?fastload=show&id=144& FindTarget()].
*Slap them. For this we use [http://docs.sourcemod.net/api/index.php?fastload=show&id=42& SlapPlayer()], which requires including <tt>sdktools</tt>, an extension bundled with SourceMod.
*Respond to the admin. For this we use [http://docs.sourcemod.net/api/index.php?fastload=show&id=462& ReplyToCommand()].

Full example:

<pawn>
#include <sourcemod>
#include <sdktools>

public Plugin:myinfo =
{
name = "My First Plugin",
author = "Me",
description = "My first plugin ever",
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

/* Get the first argument */
GetCmdArg(1, arg1, sizeof(arg1))

/* If there are 2 or more arguments, and the second argument fetch
* is successful, convert it to an integer.
*/
if (args >= 2 && GetCmdArg(2, arg2, sizeof(arg2)))
{
damage = StringToInt(arg2)
}

/* Try and find a matching player */
new target = FindTarget(client, arg1)
if (target == -1)
{
/* FindTarget() automatically replies with the
* failure reason.
*/
return Plugin_Handled;
}

SlapPlayer(target, damage)

new String:name[MAX_NAME_LENGTH]

GetClientName(target, name, sizeof(name))
ReplyToCommand(client, "[SM] You slapped %s for %d damage!", name, damage)

return Plugin_Handled;
}</pawn>

For more information on what %s and %d are, see [[Format Class Functions (SourceMod Scripting)|Format Class Functions]]. Note that you never need to unregister or remove your admin command. When a plugin is unloaded, SourceMod cleans it up for you.

=ConVars=
ConVars, also known as cvars, are global console variables in the Source engine. They can have integer, float, or string values. ConVar accessing is done through [[Handles (SourceMod Scripting)|Handles]]. Since ConVars are global, you do not need to close ConVar Handles (in fact, you cannot).

The handy feature of ConVars is that they are easy for users to configure. They can be placed in any .cfg file, such as <tt>server.cfg</tt> or <tt>sourcemod.cfg</tt>. To make this easier, SourceMod has an [http://docs.sourcemod.net/api/index.php?fastload=show&id=607& AutoExecConfig()] function. This function will automatically build a default .cfg file containing all of your cvars, annotated with comments, for users. It is highly recommend that you call this if you have customizable ConVars.

Let's extend your example from earlier with a new ConVar. Our ConVar will be <tt>sm_myslap_damage</tt> and will specify the default damage someone is slapped for if no damage is specified.

<pawn>new Handle:sm_myslap_damage = INVALID_HANDLE

public OnPluginStart()
{
RegAdminCmd("sm_myslap", Command_MySlap, ADMFLAG_SLAY)

sm_myslap_damage = CreateConVar("sm_myslap_damage", "5", "Default slap damage")
AutoExecConfig(true, "plugin_myslap")
}

public Action:Command_MySlap(client, args)
{
new String:arg1[32], String:arg2[32]
new damage = GetConVarInt(sm_myslap_damage)

/* The rest remains unchanged! */
</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.

For example, let's rewrite the last few lines of our slap command:
<pawn>
SlapPlayer(target, damage)

new String:name[MAX_NAME_LENGTH]

GetClientName(target, name, sizeof(name))

ShowActivity2(client, "[SM] ", "Slapped %s for %d damage!", name, damage)
LogAction(client, target, "\"%L\" slapped \"%L\" (damage %d)", client, target, damage)

return Plugin_Handled;
}
</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.

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.

This method of target processing is used for almost every admin command in SourceMod, and in fact FindTarget() is just a simplified version.

Full, final example:
<pawn>
#include <sourcemod>
#include <sdktools>

new Handle:sm_myslap_damage = INVALID_HANDLE

public Plugin:myinfo =
{
name = "My First Plugin",
author = "Me",
description = "My first plugin ever",
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", "Default slap damage")
AutoExecConfig(true, "plugin_myslap")
}

public Action:Command_MySlap(client, args)
{
new String:arg1[32], String:arg2[32]
new damage = GetConVarInt(sm_myslap_damage)

/* Get the first argument */
GetCmdArg(1, arg1, sizeof(arg1))

/* If there are 2 or more arguments, and the second argument fetch
* is successful, convert it to an integer.
*/
if (args >= 2 && GetCmdArg(2, arg2, sizeof(arg2)))
{
damage = StringToInt(arg2)
}

/**
* target_name - stores the noun identifying the target(s)
* target_list - array to store clients
* target_count - variable to store number of clients
* tn_is_ml - stores whether the noun must be translated
*/
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, /* Only allow alive players */
target_name,
sizeof(target_name),
tn_is_ml)) <= 0)
{
/* This function replies to the admin with a failure message */
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;
}</pawn>

=Client and Entity Indexes=
One major point of confusion with Half-Life 2 is the difference between the following things:
*Client index
*Entity index
*Userid

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.

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

A userid, on the other hand, is completely different. The 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.

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

=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]].

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>
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 */
}</pawn>

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

*[http://docs.sourcemod.net/api/index.php?fastload=show&id=576& AskPluginLoad()] - Called once, immediately after the plugin is loaded from the disk.
*[http://docs.sourcemod.net/api/index.php?fastload=show&id=575& 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()'''.
*[http://docs.sourcemod.net/api/index.php?fastload=show&id=580& 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().'''
*[http://docs.sourcemod.net/api/index.php?fastload=show&id=582& OnConfigsExecuted()] - Called once per map-change after <tt>servercfgfile</tt> (usually <tt>server.cfg</tt>), <tt>sourcemod.cfg</tt>, 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).
*[http://docs.sourcemod.net/api/index.php?fastload=show&id=581& OnMapEnd()] - Called when the map is about to end. At this point, all clients are disconnected, but <tt>TIMER_NO_MAPCHANGE</tt> timers are not yet destroyed. '''This function is paired to OnMapStart().'''
*[http://docs.sourcemod.net/api/index.php?fastload=show&id=577& 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.

*[http://docs.sourcemod.net/api/index.php?fastload=show&id=388& OnClientConnect()] - Called when a player initiates a connection. '''This is paired with OnClientDisconnect() for successful connections only.'''
*[http://docs.sourcemod.net/api/index.php?fastload=show&id=394& 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().
*[http://docs.sourcemod.net/api/index.php?fastload=show&id=389& OnClientPutInServer()] - Signifies that the player is in-game and IsClientInGame() will return true.
*[http://docs.sourcemod.net/api/index.php?fastload=show&id=396& 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.
*[http://docs.sourcemod.net/api/index.php?fastload=show&id=390& 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. <tt>#include <sourcemod></tt> will give you 95% of the .incs. Similarly, <tt>#include <sdktools></tt> 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 <tt>Plugin_Stop</tt> 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.

=Further Reading=
For further reading, see the "Scripting" section at the [http://docs.sourcemod.net/ SourceMod Documentation].

[[Category:Ru:SourceMod Scripting]]

Ru:Introduction to SourceMod Plugins

2008-12-26T13:53:12Z

Frenzzy: /* Plugin Structure */

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

Для получения информации о компиляции плагинов см. [[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] или любой другой текстовый редактор.

=Структура плагина=
Почти все плагины имеют три одинаковых элемента:
*'''Includes''' - Позволяет получить доступ к SourceMod API, и если Вы хотите, к API от внешних SourceMod плагинов и расширений.
*'''Info''' - Общественная информация о Вашем плагине.
*'''Startup''' - Функция, которая осуществляет запуск процедур в Вашем плагине.

Плагин скелетной структуры выглядит следующим образом:
<pawn>
#include <sourcemod>

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

public OnPluginStart()
{
// Выполнение единовременного запуска задач ...
}</pawn>

Информация часть имеет специальную синтаксическую конструкцию. Вы не можете изменить любое из ключевых слов, или объявление <tt>public Plugin:myinfo</tt>. Хорошая идея заключается в том, чтобы скопировать и вставить эту скелетную структуру и отредактировать строки, чтобы начать работу.

=Includes=
Pawn requires '''include files''', much like C requires header files. Include files list all of the structures, functions, callbacks, and tags that are available. There are three types of include files:
*'''Core''' - <tt>sourcemod.inc</tt> and anything it includes. These are all provided by SourceMod's Core.
*'''Extension''' - adds a dependency against a certain extension.
*'''Plugin''' - adds a dependency against a certain plugin.

Include files are loaded using the <tt>#include</tt> compiler directive.

=Commands=
Our first example will be writing a simple admin command to slap a player. We'll continue to extend this example with more features until we have a final, complete result.

==Declaration==
First, let's look at what an admin command requires. Admin commands are registered using the [http://docs.sourcemod.net/api/index.php?fastload=show&id=471& RegAdminCmd] function. They require a '''name''', a '''callback function''', and '''default admin flags'''.

The callback function is what's invoked every time the command is used. [http://docs.sourcemod.net/api/index.php?fastload=show&id=469& Click here] to see its prototype. Example:

<pawn>
public OnPluginStart()
{
RegAdminCmd("sm_myslap", Command_MySlap, ADMFLAG_SLAY)
}

public Action:Command_MySlap(client, args)
{
}</pawn>

Now we've successfully implemented a command -- though it doesn't do anything yet. In fact, it will say "Unknown command" if you use it! The reason is because of the <tt>Action</tt> tag. The default functionality for entering console commands is to reply that they are unknown. To block this functionality, you must return a new action:

<pawn>public Action:Command_MySlap(client, args)
{
return Plugin_Handled;
}</pawn>

Now the command will report no error, but it still won't do anything.

==Implementation==
Let's decide what the command will look like. Let's have it act like the default <tt>sm_slap</tt> command:
<pre>sm_myslap <name|#userid> [damage]</pre>

To implement this, we'll need a few steps:
*Get the input from the console. For this we use [http://docs.sourcemod.net/api/index.php?fastload=show&id=473& GetCmdArg()].
*Find a matching player. For this we use [http://docs.sourcemod.net/api/index.php?fastload=show&id=144& FindTarget()].
*Slap them. For this we use [http://docs.sourcemod.net/api/index.php?fastload=show&id=42& SlapPlayer()], which requires including <tt>sdktools</tt>, an extension bundled with SourceMod.
*Respond to the admin. For this we use [http://docs.sourcemod.net/api/index.php?fastload=show&id=462& ReplyToCommand()].

Full example:

<pawn>
#include <sourcemod>
#include <sdktools>

public Plugin:myinfo =
{
name = "My First Plugin",
author = "Me",
description = "My first plugin ever",
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

/* Get the first argument */
GetCmdArg(1, arg1, sizeof(arg1))

/* If there are 2 or more arguments, and the second argument fetch
* is successful, convert it to an integer.
*/
if (args >= 2 && GetCmdArg(2, arg2, sizeof(arg2)))
{
damage = StringToInt(arg2)
}

/* Try and find a matching player */
new target = FindTarget(client, arg1)
if (target == -1)
{
/* FindTarget() automatically replies with the
* failure reason.
*/
return Plugin_Handled;
}

SlapPlayer(target, damage)

new String:name[MAX_NAME_LENGTH]

GetClientName(target, name, sizeof(name))
ReplyToCommand(client, "[SM] You slapped %s for %d damage!", name, damage)

return Plugin_Handled;
}</pawn>

For more information on what %s and %d are, see [[Format Class Functions (SourceMod Scripting)|Format Class Functions]]. Note that you never need to unregister or remove your admin command. When a plugin is unloaded, SourceMod cleans it up for you.

=ConVars=
ConVars, also known as cvars, are global console variables in the Source engine. They can have integer, float, or string values. ConVar accessing is done through [[Handles (SourceMod Scripting)|Handles]]. Since ConVars are global, you do not need to close ConVar Handles (in fact, you cannot).

The handy feature of ConVars is that they are easy for users to configure. They can be placed in any .cfg file, such as <tt>server.cfg</tt> or <tt>sourcemod.cfg</tt>. To make this easier, SourceMod has an [http://docs.sourcemod.net/api/index.php?fastload=show&id=607& AutoExecConfig()] function. This function will automatically build a default .cfg file containing all of your cvars, annotated with comments, for users. It is highly recommend that you call this if you have customizable ConVars.

Let's extend your example from earlier with a new ConVar. Our ConVar will be <tt>sm_myslap_damage</tt> and will specify the default damage someone is slapped for if no damage is specified.

<pawn>new Handle:sm_myslap_damage = INVALID_HANDLE

public OnPluginStart()
{
RegAdminCmd("sm_myslap", Command_MySlap, ADMFLAG_SLAY)

sm_myslap_damage = CreateConVar("sm_myslap_damage", "5", "Default slap damage")
AutoExecConfig(true, "plugin_myslap")
}

public Action:Command_MySlap(client, args)
{
new String:arg1[32], String:arg2[32]
new damage = GetConVarInt(sm_myslap_damage)

/* The rest remains unchanged! */
</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.

For example, let's rewrite the last few lines of our slap command:
<pawn>
SlapPlayer(target, damage)

new String:name[MAX_NAME_LENGTH]

GetClientName(target, name, sizeof(name))

ShowActivity2(client, "[SM] ", "Slapped %s for %d damage!", name, damage)
LogAction(client, target, "\"%L\" slapped \"%L\" (damage %d)", client, target, damage)

return Plugin_Handled;
}
</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.

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.

This method of target processing is used for almost every admin command in SourceMod, and in fact FindTarget() is just a simplified version.

Full, final example:
<pawn>
#include <sourcemod>
#include <sdktools>

new Handle:sm_myslap_damage = INVALID_HANDLE

public Plugin:myinfo =
{
name = "My First Plugin",
author = "Me",
description = "My first plugin ever",
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", "Default slap damage")
AutoExecConfig(true, "plugin_myslap")
}

public Action:Command_MySlap(client, args)
{
new String:arg1[32], String:arg2[32]
new damage = GetConVarInt(sm_myslap_damage)

/* Get the first argument */
GetCmdArg(1, arg1, sizeof(arg1))

/* If there are 2 or more arguments, and the second argument fetch
* is successful, convert it to an integer.
*/
if (args >= 2 && GetCmdArg(2, arg2, sizeof(arg2)))
{
damage = StringToInt(arg2)
}

/**
* target_name - stores the noun identifying the target(s)
* target_list - array to store clients
* target_count - variable to store number of clients
* tn_is_ml - stores whether the noun must be translated
*/
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, /* Only allow alive players */
target_name,
sizeof(target_name),
tn_is_ml)) <= 0)
{
/* This function replies to the admin with a failure message */
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;
}</pawn>

=Client and Entity Indexes=
One major point of confusion with Half-Life 2 is the difference between the following things:
*Client index
*Entity index
*Userid

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.

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

A userid, on the other hand, is completely different. The 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.

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

=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]].

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>
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 */
}</pawn>

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

*[http://docs.sourcemod.net/api/index.php?fastload=show&id=576& AskPluginLoad()] - Called once, immediately after the plugin is loaded from the disk.
*[http://docs.sourcemod.net/api/index.php?fastload=show&id=575& 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()'''.
*[http://docs.sourcemod.net/api/index.php?fastload=show&id=580& 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().'''
*[http://docs.sourcemod.net/api/index.php?fastload=show&id=582& OnConfigsExecuted()] - Called once per map-change after <tt>servercfgfile</tt> (usually <tt>server.cfg</tt>), <tt>sourcemod.cfg</tt>, 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).
*[http://docs.sourcemod.net/api/index.php?fastload=show&id=581& OnMapEnd()] - Called when the map is about to end. At this point, all clients are disconnected, but <tt>TIMER_NO_MAPCHANGE</tt> timers are not yet destroyed. '''This function is paired to OnMapStart().'''
*[http://docs.sourcemod.net/api/index.php?fastload=show&id=577& 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.

*[http://docs.sourcemod.net/api/index.php?fastload=show&id=388& OnClientConnect()] - Called when a player initiates a connection. '''This is paired with OnClientDisconnect() for successful connections only.'''
*[http://docs.sourcemod.net/api/index.php?fastload=show&id=394& 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().
*[http://docs.sourcemod.net/api/index.php?fastload=show&id=389& OnClientPutInServer()] - Signifies that the player is in-game and IsClientInGame() will return true.
*[http://docs.sourcemod.net/api/index.php?fastload=show&id=396& 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.
*[http://docs.sourcemod.net/api/index.php?fastload=show&id=390& 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. <tt>#include <sourcemod></tt> will give you 95% of the .incs. Similarly, <tt>#include <sdktools></tt> 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 <tt>Plugin_Stop</tt> 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.

=Further Reading=
For further reading, see the "Scripting" section at the [http://docs.sourcemod.net/ SourceMod Documentation].

[[Category:Ru:SourceMod Scripting]]

Category:Ru:SourceMod Scripting

2008-12-26T13:03:12Z

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

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

===Информация===
*[[Deprecation Schedule (SourceMod Scripting)|Deprecation Schedule]] - Which functions are getting removed.
*[[Format Class Functions (SourceMod Scripting)|Format Class Functions]] - All about text formatting.
*[[Handles (SourceMod Scripting)|Handles]] - Overview of Handles and some common types.
*[[Optimizing Plugins (SourceMod Scripting)|Optimizing Plugins]] - Optimization hints.
*[[Tags (Scripting)|Tags]] - All about tags.
*[[Vectors Explained (Scripting)|Vectors Explained]] - Explanation of Vector types.

===Дополнительные средства===
*[http://docs.sourcemod.net/api API Reference] - Searchable scripting API reference.
*[[Entity Properties]] - Explanation of Source entity properties.
*[[Game Events (Source)|Game Events]] - Game events listings for popular mods.
*[[Mod TempEnt List (Source)|Temp Entity Lists]] - Temporary entities for popular mods.
*[[SourceMod Profiler]] - Performance tracking and optimizing.

Ru:Introduction to SourcePawn

2008-12-26T12:42:50Z

Frenzzy: /* Локальный static */

Это руководство призвано дать Вам самые основные представления по основам написания сприптов в SourcePawn. [[Pawn]] это "скриптовый" язык используемый для внедрения функциональности в других программах. Это означает, что это не самостоятельный язык, как C++ или Java, и его элементы будут отличаться в различных приложениях. SourcePawn это вариация языка Pawn используемая в [[SourceMod]].

Это руководство не расскажет Вам как писать SourceMod плагины; оно предназначено для получения общих представлений о синтаксисе и семантике этого языка. Читайте отдельную статью [[Ru:Introduction to SourceMod Plugins]] (Введение в SourceMod плагины), для введения в SourceMod API.

=Введение для новичков=
Этот раздел создан не для программистов. Если Вы по прежнему в замешательстве, Вы можете прочитать книги о других языках программирования, таких как PHP, Python, или Java, чтобы получить более полное представление о программировании.

==Идентификаторы/Ключевые слова==
Идентификаторы представляет собой набор букв, цифр и/или нижнего подчеркивания, что представляет собой нечто уникальное. Идентификаторы вводятся с учетом регистра (в отличие от PHP, где иногда это не требуется). Идентификаторы не начинаются с какого-либо специального символа, но они должны начинаться с буквы.

Есть несколько зарезервированных символов, которые имеют особое значение. Например, <tt>if</tt>, <tt>for</tt>, и <tt>return</tt> специальные конструкции в языке, которые будут описаны позднее. Они не могут быть использованы в качестве названий идентификаторов.

==Переменные==
Существует несколько важных конструкций, которые Вы должны знать, прежде чем приступить к написанию сценария. Во-первых, это '''переменные'''. Переменная это идентификатор, который содержит данные. Например, переменная "a" может содержать числа "2", "16", "0", и так далее. Переменные создаются для хранения данных внутри программы. Переменные должны быть объявлены до их использования, с помощью ключевого слова "new". Данные можно присвоить переменной, используя знак равенства (=). Пример:

<pawn>new a, b, c, d;

a = 5;
b = 16;
c = 0;
d = 500;</pawn>

В SourcePawn, переменные бывают двух типов, которые будут более подробно описаны далее.
*Однострочные (могут содержать только произвольные числовые данные), как показано выше.
*Многострочные (могут содержать целый ряд текстовых символов)

==Функции==
Следующим важным понятием являются '''функции'''. Функции идентификаторов или имен, которые выполняют действия. Это означает, что когда вы их активируете, они выполняют конкретную последовательность кода. Есть несколько типов функций, но все функции активируется одинаковым образом. "Вызов функции" является термином ссылающимся на функцию действия. Функция числовых переменных строятся так:
<pawn>функция(<параметры>)</pawn>

Примеры:

<pawn>show(56); //Активирует функцию "show" и присваивает ей число 56
show(); //Активирует функцию "show" без каких-либо данных, пустую
show(a); //Активирует функцию "show" и присваивает ей переменную с данными
</pawn>

Каждый фрагмент данных передаваемый вызываемой функции, называется '''параметр'''. Функция может иметь любое количество параметров (но есть "допустимый" предел в SourceMod: 32). Параметры будут описаны далее в этой статье.

==Комментарии==
Примечания и любой текст, который пишется после "//" считается "Комментарием", а не фактическим кодом. Есть два стиля комментариев:
*<tt>//</tt> - Двойная косая черта, всё следующие после этой строки игнорируется.
*<tt>/* */</tt> - Много-строчный комментарий, весь текст, внутри звездочек игнорируются. You cannot nest these.

==Массивы==
Описание массивов. Вы можете группировать код в виде "массивов", разделенных { и }. Это фактически создает возможность работать с целым массивом как с одним оператором. Например:

<pawn>{
here;
is;
some;
code;
}</pawn>

Массивы с фигурными скобками используются достаточно широко в программировании. Массивы кода могут быть вложенными друг в друга. Это хорошая возможность адаптировать последовательность когда и сделать его удобочитаемым, благодаря отступам код не будет смотреться как одна большая и длинная макаронина.

=Особенности языка=
Pawn может показаться очень похожим на другие языки программирования, например C, но Pawn от них фундаментально отличается. Не столь важно, чтобы Вы сейчас же поняли его отличия, но они понадобятся, если Вы уже знаете один из языков программирования.
*'''Pawn не печатает''' Pawn имеет только один тип данных - '''однострочный'''. Подробнее будет описано позже. [В дальнейшем автор рассказывает, что существует два типа данных: однострочный и многострочный]
*'''Pawn не собирает мусор''' Pawn, как язык, не имеет встроенных ресурсов памяти, и потому он не мусорит. Если функция выделит память, то Вы отвечаете за её освобождение.
*'''Pawn не объектно-ориентированный язык''' Pawn является процедурным, и полагается на подпрограммы. Также у него нету C подобных структур.
*'''Pawn не функциональный.''' Pawn является процедурным, и не поддерживает функции "лямбды" (Lambda), поздние присвоения, и все то, что можно найти в языках высшего уровня, таких как Phyton и Ruby.
*'''Pawn однопоточный''' As of this writing, Pawn is not thread safe.
*'''Pawn не интерпретируемый''' Ну, почти. Он интерпретируется на очень низком уровне. Вы должны скомпилировать код, из которого получится бинарный файл. Эта программа будет работать на той платформе, которую использует хост. Это ускоряет загрузку и позволяет легче находить ошибки.

Этот язык был выпущен ITB CompuPhase. Язык разработан для устройств низкого уровня и таким образом конечные программы очень маленькие по размеру и очень быстрые.

=Переменные=
В Pawn есть всего два типа переменных: '''однострочные''' и '''многострочные'''. Однострочные могут содержать 32 бита цифровых данных. Многострочные - последовательный список из UTF-8 символов.

'''однострочные''' не имеет своего типа, однако они могут быть '''маркированы'''(tagged). Тег позволяет Вам указывать, где определенную ячейку можно использовать. Типичные теги:
*(пусто), или '''_''' - Нет тега. Обычно используют для целых чисел ([http://en.wikipedia.org/wiki/Integer Integers]).
*'''Float''' - используют для чисел с плавающей точкой (небольших).
*'''bool''' - используют для хранения значений '''true''' (истина) или '''false''' (ложь).

Со строками все по другому, они будут рассмотрены далее.

==Объявления==
Примеры разных правильных объявлений переменных.
<pawn>
new a = 5;
new Float:b = 5.0;
new bool:c = true;
new bool:d = 0; //Работает, поскольку 0 равно false (ложь)
</pawn>

Неправильные объявления переменных
<pawn>
new a = 5.0; //Несоответствие тегов. 5.0 с тегом Float
new Float:b = 5; //Несоответствие тегов. 5 без тега.
</pawn>

Если переменная не определена в объявлении то ее значения станет 0
<pawn>
new a; //значение 0
new Float:b; //значение 0.0
new bool:c; //значение false
</pawn>

==Присвоение==
Переменным могут быть присвоены данные после создания. Пример:
<pawn>new a, Float:b, bool:c;

a = 5;
b = 5.0;
c = true;
</pawn>

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

==Описание==
Массив объявляется с помощью квадратных скобок. Вот некоторые примеры массивов:
<pawn>
new players[32]; //Набор из 32 однострочных (числовых) данных
new Float:origin[3]; //Набор из 3 чисел с плавающей точкой
</pawn>

По умолчанию, массивам присваиваются нули. Вы можете присвоить им разные значения по умолчанию, однако:
<pawn>
new numbers[5] = {1, 2, 3, 4, 5}; //Набор 1, 2, 3, 4, 5 из однострочных данных.
new Float:origin[3] = {1.0, 2.0, 3.0}; //Набор 1.0, 2.0, 3.0 из однострочных данных.
</pawn>

Вы можете оставить массив без размера, если вы собираетесь заранее присвоить ему данные. Например:
<pawn>
new numbers[] = {1, 3, 5, 7, 9};
</pawn>

Компилятор будет автоматически делать вывод о том, что Вы хотите получить массив размером 5.

==Использование==
Использование массива равносильно использованию обычных переменной. Единственное отличие массива состоит в том, что он должен быть '''индексируемым'''. Индексирование массива означает присутствие возможности выбрать элемент, который Вы хотите использовать.

Вот пример кода с использованием индексов:
<pawn>
new numbers[5], Float:origin[3];

numbers[0] = 1;
numbers[1] = 2;
numbers[2] = 3;
numbers[3] = 4;
numbers[4] = 5;
origin[0] = 1.0;
origin[1] = 2.0;
origin[2] = 3.0;
</pawn>

Заметим, что '''индекс''' это текст, который находится в квадратных скобках. Индекс всегда начинается с нуля. То есть, если массив имеет N элементов, его действительный индекс от 0 до N-1. Доступ к данным с индексами работает так же, как с обычной переменной.

Использование неверного индекса вызовет ошибку. Например:
<pawn>
new numbers[5];

numbers[5] = 20;</pawn>

Это может выглядеть верно, но число 5 не является допустимым индексом. Наибольшим значением индекса является число 4.

Вы можете использовать любые выражения, как индекс. Например:
<pawn>new a, numbers[5];

a = 1; //Сделает a = 1
numbers[a] = 4; //Сделает numbers[1] = 4
numbers[numbers[a]] = 2; //Сделает numbers[4] = 2
</pawn>

Выражения будут обсуждаться подробнее в конце статьи.

=Строки=
Строки являются удобным способом хранения текста. Символы хранятся в массиве. Строка ограничивается '''нулевым символом''', или 0. Без нулевого символа, Pawn не знает, где остановить чтение строки. Все строки в SourcePawn используют кодировку UTF-8.

Отметим, что строки имеют комбинацию из массивов и однострочных переменных. В отличие от других языков, это означает, что Вы должны знать заранее, как много места будут использовать строки. Это означает, что строки не являются динамичными. Они могут лишь вырасти до размера, которым Вы их ограничили.

''Примечание для специалистов: они фактически не однострочные. SourcePawn использует 8-битный строки для хранения массивов в качестве оптимизации. Это и есть то, что делает строки типом, а не меткой.''

==Использование==
Строки были созданы почти в равной степени и для массивов. Например:
<pawn>
new String:message[] = "Hello!";
new String:clams[6] = "Clams";
</pawn>

Это равносильно следующему:
<pawn>
new String:message[7], String:clams[6];

message[0] = 'H';
message[1] = 'e';
message[2] = 'l';
message[3] = 'l';
message[4] = 'o';
message[5] = '!';
message[6] = 0;
clams[0] = 'C';
clams[1] = 'l';
clams[2] = 'a';
clams[3] = 'm';
clams[4] = 's';
clams[5] = 0;
</pawn>

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

Заметим, что строка должна быть заключена в двойных кавычках, а символ в одиночных.

==Символы==
Особенность текста может быть использована в любой строке или однострочной переменной. Например:
<pawn>new String:text[] = "Crab";
new clam;

clam = 'D'; //Устанавливает однострочной переменной значение 'D'
text[0] = 'A'; //Меняет 'C' на 'A', сейчас получилось 'Arab'
clam = text[0]; //Устанавливает однострочной переменной значение 'A'
text[1] = clam; //Меняет 'r' на 'A', сейчас получилось 'AAab'
</pawn>

То, что вы не можете сделать, это соотнести символы массивов со строками. Внутреннее хранение отличается. Например:
<pawn>
new clams[] = "Clams"; //Не верно, нужен тип String:
new clams[] = {'C', 'l', 'a', 'm', 's', 0}; //Верно, но это НЕ СТРОКА.
</pawn>

=Функции=
Функции, как отмечалось ранее, имеют отдельные составляющие кода, которые выполняют определенные действия. Функции могут быть задействованы или '''вызвоны''' с '''параметрами''', которые дают особые настройки.

Существуют два типа вызова функции:
*'''прямой вызов''' - Вы специально вызываете функцию в своем коде.
*'''обратный вызов''' - Применение вызова функций в Вашем коде, как если бы это было событием триггера (совокупность условий, инициирующих выполнение действия).

Существуют пять видов функций:
*'''native''': Прямая, внутренняя функция, предусмотренная в приложении.
*'''public''': Функция обратного вызова, что делает её видимой для приложения и других сценариев.
*'''normal''': Нормальная функция, которую Вы можете только вызвать.
*'''stock''': Нормальная функция, предусмотренная если включает в себя файл. Если не используется, то не компилируется.
*'''forward''': Эта функция представляет собой глобальное событие, предусмотренная приложением. Если Вы её привели в исполнение, она будет вызвона.

Весь код в Pawn должен существовать в функциях. Это основное отличие от языков, таких как PHP, Perl и Python, которые позволяют Вам писать глобальный код. Это происходит потому, что Pawn вызывается на основе другого языка: он реагирует на действия от родительского приложения, и функции должны быть написаны для обработки этих действий. Хотя наш пример, часто содержат свободно плавающий код, это сделано исключительно для демонстрационных целей. Свободно плавающий код в нашем примере означает, что код является частью ряда функций.

==Описание==
В отличие от переменных, функции, не нужно объявлять, прежде чем использовать их. Функции имеют две части, '''модель''' и '''тело'''. Модель содержит имя Вашей функции и параметры, которые она будет принимать. Тело является контейнером для кода.

Пример функции:
<pawn>
AddTwoNumbers(first, second)
{
new sum = first + second;

return sum;
}</pawn>

Это простая функция. Модель этой строки:
<pawn>AddTwoNumbers(first, second)</pawn>

Распишем по отдельности:
*<tt>AddTwoNumbers</tt> - Название функции.
*<tt>first</tt> - Название первого параметра, который представляет собой простой элемент.
*<tt>second</tt> - Название второго параметра, который представляет собой простой элемент.

Тело представляет собой простой блок кода. Он создает новую переменную, названную <tt>sum</tt>, и присваивает ей значение этих двух параметров, добавленных совместно (другие выражения будут позже). Важно заметить оператор <tt>return</tt>, в котором обозначается конец функции и возврат с полученными значениями из этой функции. Все функции ''возвращают значения'' после завершения. Это означает, например:

<pawn>new sum = AddTwoNumbers(4, 5);</pawn>

Приведенный выше код будет присваивать число 9 к sum. Функция получает два значения и передает новое значение sum в качестве '''возвращаемого значения'''. Если функция не имеет возвращаемого значения или не имеет значений для возврата, то возвращается 0 по умолчанию.

Функция может принимать любые типы значений. Она может вернуть любую однострочную переменную, но не массивы или строки. Пример:
<pawn>Float:AddTwoFloats(Float:a, Float:b)
{
new Float:sum = a + b;

return sum;
}</pawn>

''Заметим, что если в приведенной выше функции, Вам вернулась не Float значение, Вы получите не соответствие значений.''

Можно, конечно, передавать переменные в функции:
<pawn>new numbers[3] = {1, 2, 0};

numbers[2] = AddTwoNumbers(numbers[0], numbers[1]);</pawn>

Заметим, что однострочные переменные передаются '''по значению'''. То есть, их значение не может быть изменено функцией. Например:
<pawn>new a = 5;

ChangeValue(a);

ChangeValue(b)
{
b = 5;
}</pawn>

Этот код не будет менять значение <tt>a</tt>. Это происходит потому, что копия этого значения в <tt>a</tt> передается вместо <tt>a</tt> самостоятельно.

Больше примеров функций будут демонстрироваться и в других частях статьи.

==Publics==
Публичные функции используются для осуществления обратных вызовов. Вы не должны создавать какую-либо публичную функцию, если это вынудит выполнение обратного вызова. Например, вот два обратных вызова из <tt>sourcemod.inc</tt>:

<pawn>forward OnPluginStart();
forward OnClientDisconnected(client);</pawn>

Чтобы выполнить и получить эти два события, Вы должны написать такие функции как:

<pawn>public OnPluginStart()
{
/* Код здесь */
}

public OnClientDisconnected(client)
{
/* Код здесь */
}</pawn>

Ключевое слово '''public''' делает функцию публичной, а также позволяет родительскому приложению непосредственно вызывать функцию.

==Natives==
Natives имеют встроенные функции, предоставляемые приложением. Вы можете вызвать их, как если бы они были normal функциями. Например, SourceMod имеет следующие функции:

<pawn>native FloatRound(Float:num);</pawn>

Её можно вызвать таким образом:
<pawn>new num = FloatRound(5.2); //Результат в num = 5</pawn>

==Параметры массива==
Вы можете передавать массивы или строки в качестве параметров. Важно отметить, что они идут '''как ссылка'''. То есть не делать копию данных, а отдавать непосредственно ссылки на данные. Существует простой способ объяснить это более конкретно.

<pawn>
new example[] = {1, 2, 3, 4, 5};

ChangeArray(example, 2, 29);

ChangeArray(array[], index, value)
{
array[index] = value;
}</pawn>

Эта функция устанавливает заданный индекс в массиве с учетом значений. Когда она запускается на примере нашего массива, она меняет индекс 2 для значения 3 на 29. То есть:
<pawn>example[2] = 29;</pawn>

Это возможно лишь потому, что массив может быть непосредственно изменён. Чтобы предотвратить массив от изменения, можно пометить его как постоянную <tt>const</tt>. Это позволит понизить риск на ошибку в коде от её изменения. Например:

<pawn>CantChangeArray(const array[], index, value)
{
array[index] = value; //Не компилируется
}</pawn>

Это хорошая идея использовать <tt>const</tt> в параметрах массивов и Вы будете точно знать, что массив не будет изменен; это может предотвратить ошибки кодирования.

=Выражения=
Выражения являются точно такими же, какими они существуют в математике. Это группы операторов/символов, которые приходятся на один фрагмент данных. Они часто заключены в скобках (внутри скобок). Они содержат строгий "порядок операций". Они могут содержать переменные, функции, цифры и выражения сами могут быть вложенные внутрь других выражений, и даже приняты в качестве параметров.

Приведем пример простейшего выражения:
<pawn>
0; //Возвращает число 0
(0); //Так же возвращает число 0
</pawn>

Хотя выражения могут возвращать значения, они также могут ответить какое значение содержит ответ ''ноль или не ноль''. В этом смысле, ''ноль'' является ''ложью'' (false), а ''не нулевое'' значение ''истиной'' (true). Например, -1 ''истина'' в Pawn, поскольку она не является нулем. Не думайте, что отрицательные числа являются ложными.

Порядок операций выражения аналогичен языку C. PMDAS: Parenthesis, Multiplication, Division, Addition, Subtraction. Вот несколько примеров выражений:
<pawn>
5 + 6; //Вычисляет как 11
5 * 6 + 3; //Вычисляет как 33
5 * (6 + 3); //Вычисляет как 45
5.0 + 2.3; //Вычисляет как 7.3
(5 * 6) % 7; //Modulo operator, вычисляет как 2
(5 + 3) / 2 * 4 - 9; //Вычисляет как 7
</pawn>

Как уже отмечалось, выражения могут содержать переменные, или даже функции:
<pawn>
new a = 5 * 6;
new b = a * 3; //Вычисляет как 90
new c = AddTwoNumbers(a, b) + (a * b);
</pawn>

==Операторы==
Есть несколько полезных дополнительных операторов в Pawn. Первый набор упрощает аутоагрегацию выражения. Например:
<pawn>new a = 5;

a = a + 5;</pawn>

Может быть переписан, как:
<pawn>new a = 5;
a += 5;</pawn>

Это верно в отношении следующих операторов в Pawn:
*Four-function: *, /, -, +
*Bit-wise: |, &, ^, ~, <<, >>

Кроме того, существуют инкремент/декремент операторы:
<pawn>a = a + 1;
a = a - 1;</pawn>

Может быть упрощено, как:
<pawn>a++;
a--;</pawn>

Дополнительно отметим, что ++ или -- может быть представлен до переменной (до-инкремент, до-декремент) или после переменной (пост-инкремент, пост-декремент). Разница заключается в том, как остальная часть выражения содержащие их, видит результат.

* ''До:'' Переменная увеличивается до определения и остальная часть выражения видит новое значение.
* ''Пост:'' Переменная увеличивается после определения и остальная часть выражения видит старое значение.

Иными словами, <tt>a++</tt> определяет значение как <tt>a</tt> в то время как <tt>++a</tt> определяет значение как <tt>a + 1</tt>. В обоих случаях <tt>a</tt> увеличивается на <tt>1</tt>.

Например:

<pawn>new a = 5;
new b = a++; // b = 5, a = 6 (1)
new c = ++a; // a = 7, c = 7 (2)
</pawn>

(1) <tt>b</tt> присваивается <tt>a</tt> со ''старым'' значением, ''до'' того, как он будет увеличено до <tt>6</tt>. (2) <tt>c</tt> присваивается <tt>a</tt> с ''новым'' значением, ''после'' того, как он увеличивается до <tt>7</tt>.

==Операторы сравнения==
Существуют шесть операторов для сравнения двух числовых значений, а результат является либо истиной (не ноль) или ложью (ноль):
*<tt>a == b</tt> - Действительно, если и b имеет то же значение.
*<tt>a != b</tt> - Действительно, если b имеет другое значение.
*<tt>a > b</tt> - Действительно, если оно больше b
*<tt>a >= b</tt> - Действительно, если оно больше или равно b
*<tt>a < b</tt> - Действительно, если оно меньше b
*<tt>a <= b</tt> - Действительно, если оно меньше или равно b

Например:
<pawn>
(1 != 3); //Определяется как истина, поскольку 1 не равно 3.
(3 + 3 == 6); //Определяется как истина, поскольку 3+3 равно 6.
(5 - 2 >= 4); //Определяется как ложь, поскольку 3 меньше 4.
</pawn>

Заметим, что эти операторы не работают с массивами и строками. То есть, вы не можете сравнить их с помощью <tt>==</tt>.

==Действительные операторы==
Действительные операторы могут быть скомбинированы тремя булевыми (boolean) операторами:
*<tt>a && b</tt> - Истина, если a и b истинные. Ложь, если a и (или) b ложные.
{| border="1" cellpadding="2" cellspacing="0" align="center"
! <tt>&&</tt> !! 0 !! 1
|-
! 0
| 0 || 0
|-
! 1
| 0 || 1
|}
*<tt>a || b</tt> - Истина, если a или b (или обе переменные) истинные. Ложь, если обе переменные a и b ложные.
{| border="1" cellpadding="2" cellspacing="0" align="center"
! <tt><nowiki>||</nowiki></tt> !! 0 !! 1
|-
! 0
| 0 || 1
|-
! 1
| 1 || 1
|}
*<tt>!a</tt> - Истина, если a ложь. Ложь, если a истина.
{| border="1" cellpadding="2" cellspacing="0" align="center"
! <tt>!</tt> !! 0 !! 1
|-
!
| 1 || 0
|}

Например:
<pawn>
(1 || 0); //Определяется как истина, так как выражение 1 истинное
(1 && 0); //Определяется как ложь, так как выражение 0 ложное
(!1 || 0); //Определяется как ложь, так как выражение !1 ложное.
</pawn>

==Левое/правое значения==
Два важных понятия левого и правого значений, или левостороннее и правостороннее значения. Левостороннее значение имеет то, что появляется на левой стороне выражения, а правостороннее значение - появляется на правой стороне выражения.

Например:
<pawn>
new a = 5;</pawn>

В этом примере <tt>a</tt> является левосторонним значением и <tt>5</tt> является правосторонним значением.

Правила:
*'''Выражения никогда не будут левосторонними значениями'''.
*'''Переменные являются двумя, левосторонними и правосторонними значениями'''.

=Условия=
Условия позволяют Вам запускать код, определенное условие выполнено.

==Если соответствует==
Если соответствует одно или более условий. Например:

<pawn>
if (a == 5)
{
/* Код будет запущен, если условие будет истинным */
}</pawn>

Они могут быть расширены для более сложных случаев:
<pawn>
if (a == 5)
{
/* Код */
}
else if (a == 6)
{
/* Код */
}
else if (a == 7)
{
/* Код */
}</pawn>

Вы так же можете обрабатывать случаи, даже если выражение не верно. Например:
<pawn>
if (a == 5)
{
/* Код */
}
else
{
/* Код, который будет запущен если нет истинного выражения */
}</pawn>

==Оператор выбора==
Оператор выбора будет ограничен условием. Он необходим для выражения, выполняющего код для целого ряда возможных значений. Например:

<pawn>
switch (a)
{
case 5:
{
/* Код */
}
case 6:
{
/* Код */
}
case 7:
{
/* Код */
}
case 8, 9, 10:
{
/* Код */
}
default:
{
/* будет запущен, если не одно условие не соответствует */
}
}</pawn>

В отличие от некоторых других языков, оператор выбора не проваливается. То есть существуют случаи, когда код не будет запущен. При случае совпадения его код выполняется, а ключ является местом для немедленного прекращения.

=Циклы=
Циклы позволяют Вам без труда повторять выполнение кода, пока условие станет истинным.

==For циклы==
For циклы, это циклы, которые состоят из четырех частей:
*Оператор '''инициализации''' - запускается один раз перед первым циклом.
*Оператор '''условия''' - проверяет условие и запускает следующий цикл, в том числе первый. Цикл прекращается, когда это выражение становится ложным.
*Оператор '''итерации''' - запускается после каждого цикла.
* '''тело''' цикла - запускается каждый раз, пока оператор '''условия''' вычисляется как истинный.

<pawn>
for ( /* инициализация */ ; /* условие */ ; /* итерация */ )
{
/* тело */
}
</pawn>

Простым примером является функция сложения массива:
<pawn>
new array[10] = {1, 2, 3, 4, 5, 6, 7, 8, 9, 10};
new sum = SumArray(array, 10);

SumArray(const array[], count)
{
new total;

for (new i = 0; i < count; i++)
{
total += array[i];
}

return total;
}</pawn>

По отдельности:
*<tt>new i = 0</tt> - Создает новую переменную для цикла, и устанавливает её в 0.
*<tt>i < count</tt> - Только запускает цикл, если <tt>i</tt> меньше, чем <tt>count</tt>. Это гарантирует, что чтение цикла прекращается в определенный момент. В этом случае, мы не хотим читать недействительные индексы в массиве.
*<tt>i++</tt> - Увеличивает <tt>i</tt> на единицу после каждого цикла. Это гарантирует, что цикл не будет запущен вечно; в конце концов <tt>i</tt> станет слишком большим, и цикл завершится.

Таким образом, функция <tt>SumArray</tt> будет циклом каждого действительного индекса массива, каждый раз добавляя это значение в sum. Для циклов очень распространены массивы такие, как в нашем примере.

==While циклы==
While циклы являются менее распространенными, чем for циклы, но на самом деле это более простые циклы. Они имеют только две части:
*Оператор '''условия''' - проверяется перед началом каждого цикла. Цикл прекращается, когда условие становится ложным.
*'''тело''' цикла - запускается каждый раз пока цикл выполняется.

<pawn>
while ( /* условие */ )
{
/* тело */
}
</pawn>

До тех пор, пока условие выражения остается истинным, цикл будет выполняться. Каждый for цикл может быть переписан, как while цикл:

<pawn>
/* инициализация */
while ( /* условие */ )
{
/* тело */
/* итерация */
}
</pawn>

Вот предыдущий for цикл переписан как while цикл:
<pawn>
SumArray(const array[], count)
{
new total, i;

while (i < count)
{
total += array[i];
i++;
}

return total;
}</pawn>

Существуют также '''do...while''' циклы, которые используются еще реже. Они работают как и while циклы, но проверяют условие ПОСЛЕ каждого цикла, а не перед ним. Это означает, что цикл всегда будет запущен, по крайней мере один раз. Например:

<pawn>
do
{
/* тело */
}
while ( /* условие */ );
</pawn>

==Управление циклами==
Существуют два случая, в которых Мы хотели бы контролировать цикл:
*'''пропустить''' одну итерацию или цикл и продолжить выполнение цикла как обычно, или;
*'''разорвать''' цикл целиком, прежде чем он закончится.

Допустим у вас есть функция, которая принимает массив и ищет соответствия цифр. Вы хотите его остановить, когда число будет найдено:
<pawn>
/**
* Возвращает массив, если индекс значения, или -1, не найдены.
*/
SearchInArray(const array[], count, value)
{
new index = -1;

for (new i = 0; i < count; i++)
{
if (array[i] == value)
{
index = i;
break;
}
}

return index;
}</pawn>

Конечно, эту функцию можно вернуть и способом <tt>return i</tt>, но пример показывает, как <tt>break</tt> может остановить цикл.

Кроме того, ключевое слово <tt>continue</tt> пропускает итерации цикла. Например, Мы хотим суммировать все четные числа:

<pawn>
SumEvenNumbers(const array[], count)
{
new sum;

for (new i = 0; i < count; i++)
{
/* If divisibility by 2 is 1, we know it's odd */
if (array[i] % 2 == 1)
{
/* Пропускаем оставшуюся часть итерации цикла */
continue;
}
sum += array[i];
}

return sum;
}</pawn>

=Область действия=
Область действия относится к '''удобочитаемости''' кода. Это означает, что код одного уровня не может быть "виден" в коде другого уровня. Пример:

<pawn>
new A, B, C;

Function1()
{
new B;

Function2();
}

Function2()
{
new C;
}</pawn>

В этом примере, <tt>A</tt>, <tt>B</tt>, и <tt>C</tt> имеют '''глобальную область действия'''. Их можно увидеть в любой функции. Вместе с тем, <tt>B</tt> в функции <tt>Function1</tt> не является той же переменной, как <tt>B</tt> на глобальном уровне. Вместо этого она находится в '''локальной области действия''', и поэтому является '''локально изменяемой'''.

Кроме того, функции <tt>Function1</tt> и <tt>Function2</tt> ничего не знают о существовании других переменных.

Она так же является не только локальной переменной функции <tt>Function1</tt>, но и создается заново каждый раз, когда функция вызывается. Попробуйте представить это:
<pawn>
Function1()
{
new B;

Function1();
}</pawn>

В приведенном выше примере, функция <tt>Function1</tt> вызывает сама себя. Конечно, это бесконечной рекурсии (а это очень плохо), но идея заключается в том, что каждый раз, когда функция срабатывает, то создается новая копия <tt>B</tt>. Когда функция завершается, <tt>B</tt> уничтожается, и её значение теряется.

Это свойство можно объяснить проще тем, что область действия переменной равна уровню её вложенности. То есть, переменная на глобальной области действия видна для всех функций. Переменная в локальной области действия видна всему блоку кода расположенному "ниже" этого уровня. Например:

<pawn>Function1()
{
new A;

if (A)
{
A = 5;
}
}</pawn>

Приведенный выше код является действительным, поскольку в область действия распространяется по всей функции. Однако этот код, работать не будет:
<pawn>
Function1()
{
new A;

if (A)
{
new B = 5;
}

B = 5;
}</pawn>

Отметим, что <tt>B</tt> объявляется в новом блоке кода. Это означает, что <tt>B</tt> доступна только в том блоке кода, в котором была создана (и всем под-блокам вложенных внутри него). Как только блок кода прекращается, <tt>B</tt> становится не действительной.

=Динамические массивы=
Динамические массивы это массивы, которые не имеют фиксированного размера. Например:

<pawn>Function1(size)
{
new array[size];

/* Код */
}</pawn>

Динамические массивы могут иметь любое выражение, соответствующее их размеру до тех пор, пока выражение вычисляется, как число большее чем 0. Как и для обычных массивов, SourcePawn не сможет узнать размер массива после того, как он будет создан; Вы должны задать его, если хотите использовать массив позднее.

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

=Расширенное объявление переменных=
Переменные могут быть объявлены более длинным путем чем просто <tt>new</tt>.

==decl==
===Назначение===
По умолчанию, все переменные в Pawn будут инициализированы как нуль. Если есть явная инициализация, переменная инициализируется для выражения <tt>=</tt> определенным символам. В локальной области действия, это может потребовать время на выполнение. Ключевое слово <tt>decl</tt> (которое действительно только в локальной области действия) было введено, чтобы позволить решать пользователю, хочит ли он инициализировать переменную или нет.

Примечание: <tt>decl</tt> не должно быть использовано на одну однострочную переменную. Это почти никогда не будет выгодно.

===Объяснение===
Например:

<pawn>
new c = 5;
new d;
new String:blah[512];

Format(blah, sizeof(blah), "%d %d", c, d);
</pawn>

В этом коде, <tt>c</tt> равна 5 и <tt>d</tt> равна 0. Во время выполнения этого кода затраты на инициализацию незначительные. Вместе с тем, <tt>blah</tt> является большим массивом, и затраты на инициализацию всего массива могут быть больше 0 сек. и иметь плохие последствия в определенных ситуациях.

Заметим, что <tt>blah</tt> не должен быть нулевой. В период времени с объявления <tt>new</tt> и и перемещения в <tt>Format()</tt>, массив <tt>blah</tt> никогда не будет загружен или прочитан. Данный код будет более эффективен, если будет написанный следующим образом:

<pawn>
new c = 5;
new d;
decl String:blah[512];

Format(blah, sizeof(blah), "%d %d", c, d);
</pawn>

===Предостережения===
Обратная сторона <tt>decl</tt> состоит в том, что его переменные будут начинаться с "ненужного" содержания. Например, если мы будем использовать:

<pawn>
new c = 5;
new d;
decl String:blah[512];

PrintToServer("%s", blah);

Format(blah, sizeof(blah), "%d %d", c, d);
</pawn>

Этот код может привести к падению сервера, так как массив <tt>blah</tt> может быть полностью испорчен (строки требуют нулевой символ, который может отсутствовать). Точно так же, если мы сделаем:

<pawn>
new c = 5;
decl d;
decl String:blah[512];

Format(blah, sizeof(blah), "%d %d", c, d);
</pawn>

Значение <tt>d</tt> в настоящее время не определенно. Оно может быть любым значением, отрицательным или положительным.

Заметим, что это легко и эффективно обезопасит строки. Пример ниже показывает, как предотвратить строки от мусора:
<pawn>
decl String:blah[512];

blah[0] = '\0';
</pawn>

===Золотые правила===
*'''Используйте decl только, если в период объявления и загрузки/чтения значения, Вы абсолютно уверены, что есть по крайней мере одно хранилище/операция, которая отдает переменной действительные данные.'''
*'''Не оптимизируйте преждевременно.''' Кроме того, нет необходимости использовать <tt>decl</tt> на не-массивы, поскольку нет никаких дополнительных затрат на инициализацию однго однострочного значения.

===Примечания===
Этот пример НЕ является столь эффективным, как <tt>decl</tt>:
<pawn>
new String:blah[512] = "a";
</pawn>

Даже несмотря на то, что строка имеет только один символ, оператор <tt>new</tt> гарантирует, что остальная часть массива будет нулевой.

Также обратите внимание, он является неправильным для явной инициализации <tt>decl</tt>:
<pawn>decl String:blah[512] = "a";</pawn>

Приведенный выше код не будет компилироваться, потому что цель <tt>decl</tt> состоит в том, чтобы избежать каких-либо инициализаций.

==static==
Ключевое слово <tt>static</tt> входит в глобальную и локальную область действия. Оно имеет различные значения в каждой из них.

===Глобальный static===
Глобальные static переменные могут быть доступны только в рамках того же файла. Например:

<pawn>//file1.inc
static Float:g_value1 = 0.15f;

//file2.inc
static Float:g_value2 = 0.15f;</pawn>

Если плагин включает в себя оба этих файла, он не сможет использовать <tt>g_value1</tt> или <tt>g_value2</tt>. Это простой механизм сокрытия информации, и аналогичен элементам объявления переменных, например <tt>private</tt> в таких языках, как C++, Java, или C#.

===Локальный static===
Локальная static переменная является глобальной переменной, которая является видимой лишь из её местной области действия. Например:

<pawn>
MyFunction(inc)
{
static counter = -1;

counter += inc;

return counter;
}</pawn>

В этом примере, <tt>counter</tt> технически глобальная переменная -- она инициализируется один раз как -1 и никогда не инициализируется заново. Оно не существует в наборе. Это означает, что при каждом запуске функции <tt>MyFunction</tt>, переменная <tt>counter</tt> и ее хранение в памяти одно и тоже.

Возьмем следающий пример:
<pawn>MyFunction(5);
MyFunction(6);
MyFunction(10);</pawn>

В этом примере, <tt>counter</tt> может быть <tt>-1 +5 +6 +10</tt>, или <tt>20</tt>, поскольку она сохраняется за рамками этой функции. Это может создавать проблемы для рекурсивной функции: если ваша функция может быть рекурсивной, то <tt>static</tt>, как правило, не является хорошей идеей, если только Ваш код не реентерабельный.

Преимуществом локальных static переменных является то, что Вам не придется загромождать свой сценарий глобальными переменными. До тех пор, пока переменной не нужно читать другую функцию, Вы можете его пихать внутрь функции и её сохранение будет гарантировано.

Заметим, что statics может существовать в любой локальной области действия:

<pawn>
MyFunction(inc)
{
if (inc > 0)
{
static counter;
return (counter += inc);
}
return -1;
}</pawn>

[[Category:Ru:SourceMod Scripting]]

Ru:Introduction to SourcePawn

2008-12-26T12:42:00Z

Frenzzy: /* Local static */

Это руководство призвано дать Вам самые основные представления по основам написания сприптов в SourcePawn. [[Pawn]] это "скриптовый" язык используемый для внедрения функциональности в других программах. Это означает, что это не самостоятельный язык, как C++ или Java, и его элементы будут отличаться в различных приложениях. SourcePawn это вариация языка Pawn используемая в [[SourceMod]].

Это руководство не расскажет Вам как писать SourceMod плагины; оно предназначено для получения общих представлений о синтаксисе и семантике этого языка. Читайте отдельную статью [[Ru:Introduction to SourceMod Plugins]] (Введение в SourceMod плагины), для введения в SourceMod API.

=Введение для новичков=
Этот раздел создан не для программистов. Если Вы по прежнему в замешательстве, Вы можете прочитать книги о других языках программирования, таких как PHP, Python, или Java, чтобы получить более полное представление о программировании.

==Идентификаторы/Ключевые слова==
Идентификаторы представляет собой набор букв, цифр и/или нижнего подчеркивания, что представляет собой нечто уникальное. Идентификаторы вводятся с учетом регистра (в отличие от PHP, где иногда это не требуется). Идентификаторы не начинаются с какого-либо специального символа, но они должны начинаться с буквы.

Есть несколько зарезервированных символов, которые имеют особое значение. Например, <tt>if</tt>, <tt>for</tt>, и <tt>return</tt> специальные конструкции в языке, которые будут описаны позднее. Они не могут быть использованы в качестве названий идентификаторов.

==Переменные==
Существует несколько важных конструкций, которые Вы должны знать, прежде чем приступить к написанию сценария. Во-первых, это '''переменные'''. Переменная это идентификатор, который содержит данные. Например, переменная "a" может содержать числа "2", "16", "0", и так далее. Переменные создаются для хранения данных внутри программы. Переменные должны быть объявлены до их использования, с помощью ключевого слова "new". Данные можно присвоить переменной, используя знак равенства (=). Пример:

<pawn>new a, b, c, d;

a = 5;
b = 16;
c = 0;
d = 500;</pawn>

В SourcePawn, переменные бывают двух типов, которые будут более подробно описаны далее.
*Однострочные (могут содержать только произвольные числовые данные), как показано выше.
*Многострочные (могут содержать целый ряд текстовых символов)

==Функции==
Следующим важным понятием являются '''функции'''. Функции идентификаторов или имен, которые выполняют действия. Это означает, что когда вы их активируете, они выполняют конкретную последовательность кода. Есть несколько типов функций, но все функции активируется одинаковым образом. "Вызов функции" является термином ссылающимся на функцию действия. Функция числовых переменных строятся так:
<pawn>функция(<параметры>)</pawn>

Примеры:

<pawn>show(56); //Активирует функцию "show" и присваивает ей число 56
show(); //Активирует функцию "show" без каких-либо данных, пустую
show(a); //Активирует функцию "show" и присваивает ей переменную с данными
</pawn>

Каждый фрагмент данных передаваемый вызываемой функции, называется '''параметр'''. Функция может иметь любое количество параметров (но есть "допустимый" предел в SourceMod: 32). Параметры будут описаны далее в этой статье.

==Комментарии==
Примечания и любой текст, который пишется после "//" считается "Комментарием", а не фактическим кодом. Есть два стиля комментариев:
*<tt>//</tt> - Двойная косая черта, всё следующие после этой строки игнорируется.
*<tt>/* */</tt> - Много-строчный комментарий, весь текст, внутри звездочек игнорируются. You cannot nest these.

==Массивы==
Описание массивов. Вы можете группировать код в виде "массивов", разделенных { и }. Это фактически создает возможность работать с целым массивом как с одним оператором. Например:

<pawn>{
here;
is;
some;
code;
}</pawn>

Массивы с фигурными скобками используются достаточно широко в программировании. Массивы кода могут быть вложенными друг в друга. Это хорошая возможность адаптировать последовательность когда и сделать его удобочитаемым, благодаря отступам код не будет смотреться как одна большая и длинная макаронина.

=Особенности языка=
Pawn может показаться очень похожим на другие языки программирования, например C, но Pawn от них фундаментально отличается. Не столь важно, чтобы Вы сейчас же поняли его отличия, но они понадобятся, если Вы уже знаете один из языков программирования.
*'''Pawn не печатает''' Pawn имеет только один тип данных - '''однострочный'''. Подробнее будет описано позже. [В дальнейшем автор рассказывает, что существует два типа данных: однострочный и многострочный]
*'''Pawn не собирает мусор''' Pawn, как язык, не имеет встроенных ресурсов памяти, и потому он не мусорит. Если функция выделит память, то Вы отвечаете за её освобождение.
*'''Pawn не объектно-ориентированный язык''' Pawn является процедурным, и полагается на подпрограммы. Также у него нету C подобных структур.
*'''Pawn не функциональный.''' Pawn является процедурным, и не поддерживает функции "лямбды" (Lambda), поздние присвоения, и все то, что можно найти в языках высшего уровня, таких как Phyton и Ruby.
*'''Pawn однопоточный''' As of this writing, Pawn is not thread safe.
*'''Pawn не интерпретируемый''' Ну, почти. Он интерпретируется на очень низком уровне. Вы должны скомпилировать код, из которого получится бинарный файл. Эта программа будет работать на той платформе, которую использует хост. Это ускоряет загрузку и позволяет легче находить ошибки.

Этот язык был выпущен ITB CompuPhase. Язык разработан для устройств низкого уровня и таким образом конечные программы очень маленькие по размеру и очень быстрые.

=Переменные=
В Pawn есть всего два типа переменных: '''однострочные''' и '''многострочные'''. Однострочные могут содержать 32 бита цифровых данных. Многострочные - последовательный список из UTF-8 символов.

'''однострочные''' не имеет своего типа, однако они могут быть '''маркированы'''(tagged). Тег позволяет Вам указывать, где определенную ячейку можно использовать. Типичные теги:
*(пусто), или '''_''' - Нет тега. Обычно используют для целых чисел ([http://en.wikipedia.org/wiki/Integer Integers]).
*'''Float''' - используют для чисел с плавающей точкой (небольших).
*'''bool''' - используют для хранения значений '''true''' (истина) или '''false''' (ложь).

Со строками все по другому, они будут рассмотрены далее.

==Объявления==
Примеры разных правильных объявлений переменных.
<pawn>
new a = 5;
new Float:b = 5.0;
new bool:c = true;
new bool:d = 0; //Работает, поскольку 0 равно false (ложь)
</pawn>

Неправильные объявления переменных
<pawn>
new a = 5.0; //Несоответствие тегов. 5.0 с тегом Float
new Float:b = 5; //Несоответствие тегов. 5 без тега.
</pawn>

Если переменная не определена в объявлении то ее значения станет 0
<pawn>
new a; //значение 0
new Float:b; //значение 0.0
new bool:c; //значение false
</pawn>

==Присвоение==
Переменным могут быть присвоены данные после создания. Пример:
<pawn>new a, Float:b, bool:c;

a = 5;
b = 5.0;
c = true;
</pawn>

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

==Описание==
Массив объявляется с помощью квадратных скобок. Вот некоторые примеры массивов:
<pawn>
new players[32]; //Набор из 32 однострочных (числовых) данных
new Float:origin[3]; //Набор из 3 чисел с плавающей точкой
</pawn>

По умолчанию, массивам присваиваются нули. Вы можете присвоить им разные значения по умолчанию, однако:
<pawn>
new numbers[5] = {1, 2, 3, 4, 5}; //Набор 1, 2, 3, 4, 5 из однострочных данных.
new Float:origin[3] = {1.0, 2.0, 3.0}; //Набор 1.0, 2.0, 3.0 из однострочных данных.
</pawn>

Вы можете оставить массив без размера, если вы собираетесь заранее присвоить ему данные. Например:
<pawn>
new numbers[] = {1, 3, 5, 7, 9};
</pawn>

Компилятор будет автоматически делать вывод о том, что Вы хотите получить массив размером 5.

==Использование==
Использование массива равносильно использованию обычных переменной. Единственное отличие массива состоит в том, что он должен быть '''индексируемым'''. Индексирование массива означает присутствие возможности выбрать элемент, который Вы хотите использовать.

Вот пример кода с использованием индексов:
<pawn>
new numbers[5], Float:origin[3];

numbers[0] = 1;
numbers[1] = 2;
numbers[2] = 3;
numbers[3] = 4;
numbers[4] = 5;
origin[0] = 1.0;
origin[1] = 2.0;
origin[2] = 3.0;
</pawn>

Заметим, что '''индекс''' это текст, который находится в квадратных скобках. Индекс всегда начинается с нуля. То есть, если массив имеет N элементов, его действительный индекс от 0 до N-1. Доступ к данным с индексами работает так же, как с обычной переменной.

Использование неверного индекса вызовет ошибку. Например:
<pawn>
new numbers[5];

numbers[5] = 20;</pawn>

Это может выглядеть верно, но число 5 не является допустимым индексом. Наибольшим значением индекса является число 4.

Вы можете использовать любые выражения, как индекс. Например:
<pawn>new a, numbers[5];

a = 1; //Сделает a = 1
numbers[a] = 4; //Сделает numbers[1] = 4
numbers[numbers[a]] = 2; //Сделает numbers[4] = 2
</pawn>

Выражения будут обсуждаться подробнее в конце статьи.

=Строки=
Строки являются удобным способом хранения текста. Символы хранятся в массиве. Строка ограничивается '''нулевым символом''', или 0. Без нулевого символа, Pawn не знает, где остановить чтение строки. Все строки в SourcePawn используют кодировку UTF-8.

Отметим, что строки имеют комбинацию из массивов и однострочных переменных. В отличие от других языков, это означает, что Вы должны знать заранее, как много места будут использовать строки. Это означает, что строки не являются динамичными. Они могут лишь вырасти до размера, которым Вы их ограничили.

''Примечание для специалистов: они фактически не однострочные. SourcePawn использует 8-битный строки для хранения массивов в качестве оптимизации. Это и есть то, что делает строки типом, а не меткой.''

==Использование==
Строки были созданы почти в равной степени и для массивов. Например:
<pawn>
new String:message[] = "Hello!";
new String:clams[6] = "Clams";
</pawn>

Это равносильно следующему:
<pawn>
new String:message[7], String:clams[6];

message[0] = 'H';
message[1] = 'e';
message[2] = 'l';
message[3] = 'l';
message[4] = 'o';
message[5] = '!';
message[6] = 0;
clams[0] = 'C';
clams[1] = 'l';
clams[2] = 'a';
clams[3] = 'm';
clams[4] = 's';
clams[5] = 0;
</pawn>

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

Заметим, что строка должна быть заключена в двойных кавычках, а символ в одиночных.

==Символы==
Особенность текста может быть использована в любой строке или однострочной переменной. Например:
<pawn>new String:text[] = "Crab";
new clam;

clam = 'D'; //Устанавливает однострочной переменной значение 'D'
text[0] = 'A'; //Меняет 'C' на 'A', сейчас получилось 'Arab'
clam = text[0]; //Устанавливает однострочной переменной значение 'A'
text[1] = clam; //Меняет 'r' на 'A', сейчас получилось 'AAab'
</pawn>

То, что вы не можете сделать, это соотнести символы массивов со строками. Внутреннее хранение отличается. Например:
<pawn>
new clams[] = "Clams"; //Не верно, нужен тип String:
new clams[] = {'C', 'l', 'a', 'm', 's', 0}; //Верно, но это НЕ СТРОКА.
</pawn>

=Функции=
Функции, как отмечалось ранее, имеют отдельные составляющие кода, которые выполняют определенные действия. Функции могут быть задействованы или '''вызвоны''' с '''параметрами''', которые дают особые настройки.

Существуют два типа вызова функции:
*'''прямой вызов''' - Вы специально вызываете функцию в своем коде.
*'''обратный вызов''' - Применение вызова функций в Вашем коде, как если бы это было событием триггера (совокупность условий, инициирующих выполнение действия).

Существуют пять видов функций:
*'''native''': Прямая, внутренняя функция, предусмотренная в приложении.
*'''public''': Функция обратного вызова, что делает её видимой для приложения и других сценариев.
*'''normal''': Нормальная функция, которую Вы можете только вызвать.
*'''stock''': Нормальная функция, предусмотренная если включает в себя файл. Если не используется, то не компилируется.
*'''forward''': Эта функция представляет собой глобальное событие, предусмотренная приложением. Если Вы её привели в исполнение, она будет вызвона.

Весь код в Pawn должен существовать в функциях. Это основное отличие от языков, таких как PHP, Perl и Python, которые позволяют Вам писать глобальный код. Это происходит потому, что Pawn вызывается на основе другого языка: он реагирует на действия от родительского приложения, и функции должны быть написаны для обработки этих действий. Хотя наш пример, часто содержат свободно плавающий код, это сделано исключительно для демонстрационных целей. Свободно плавающий код в нашем примере означает, что код является частью ряда функций.

==Описание==
В отличие от переменных, функции, не нужно объявлять, прежде чем использовать их. Функции имеют две части, '''модель''' и '''тело'''. Модель содержит имя Вашей функции и параметры, которые она будет принимать. Тело является контейнером для кода.

Пример функции:
<pawn>
AddTwoNumbers(first, second)
{
new sum = first + second;

return sum;
}</pawn>

Это простая функция. Модель этой строки:
<pawn>AddTwoNumbers(first, second)</pawn>

Распишем по отдельности:
*<tt>AddTwoNumbers</tt> - Название функции.
*<tt>first</tt> - Название первого параметра, который представляет собой простой элемент.
*<tt>second</tt> - Название второго параметра, который представляет собой простой элемент.

Тело представляет собой простой блок кода. Он создает новую переменную, названную <tt>sum</tt>, и присваивает ей значение этих двух параметров, добавленных совместно (другие выражения будут позже). Важно заметить оператор <tt>return</tt>, в котором обозначается конец функции и возврат с полученными значениями из этой функции. Все функции ''возвращают значения'' после завершения. Это означает, например:

<pawn>new sum = AddTwoNumbers(4, 5);</pawn>

Приведенный выше код будет присваивать число 9 к sum. Функция получает два значения и передает новое значение sum в качестве '''возвращаемого значения'''. Если функция не имеет возвращаемого значения или не имеет значений для возврата, то возвращается 0 по умолчанию.

Функция может принимать любые типы значений. Она может вернуть любую однострочную переменную, но не массивы или строки. Пример:
<pawn>Float:AddTwoFloats(Float:a, Float:b)
{
new Float:sum = a + b;

return sum;
}</pawn>

''Заметим, что если в приведенной выше функции, Вам вернулась не Float значение, Вы получите не соответствие значений.''

Можно, конечно, передавать переменные в функции:
<pawn>new numbers[3] = {1, 2, 0};

numbers[2] = AddTwoNumbers(numbers[0], numbers[1]);</pawn>

Заметим, что однострочные переменные передаются '''по значению'''. То есть, их значение не может быть изменено функцией. Например:
<pawn>new a = 5;

ChangeValue(a);

ChangeValue(b)
{
b = 5;
}</pawn>

Этот код не будет менять значение <tt>a</tt>. Это происходит потому, что копия этого значения в <tt>a</tt> передается вместо <tt>a</tt> самостоятельно.

Больше примеров функций будут демонстрироваться и в других частях статьи.

==Publics==
Публичные функции используются для осуществления обратных вызовов. Вы не должны создавать какую-либо публичную функцию, если это вынудит выполнение обратного вызова. Например, вот два обратных вызова из <tt>sourcemod.inc</tt>:

<pawn>forward OnPluginStart();
forward OnClientDisconnected(client);</pawn>

Чтобы выполнить и получить эти два события, Вы должны написать такие функции как:

<pawn>public OnPluginStart()
{
/* Код здесь */
}

public OnClientDisconnected(client)
{
/* Код здесь */
}</pawn>

Ключевое слово '''public''' делает функцию публичной, а также позволяет родительскому приложению непосредственно вызывать функцию.

==Natives==
Natives имеют встроенные функции, предоставляемые приложением. Вы можете вызвать их, как если бы они были normal функциями. Например, SourceMod имеет следующие функции:

<pawn>native FloatRound(Float:num);</pawn>

Её можно вызвать таким образом:
<pawn>new num = FloatRound(5.2); //Результат в num = 5</pawn>

==Параметры массива==
Вы можете передавать массивы или строки в качестве параметров. Важно отметить, что они идут '''как ссылка'''. То есть не делать копию данных, а отдавать непосредственно ссылки на данные. Существует простой способ объяснить это более конкретно.

<pawn>
new example[] = {1, 2, 3, 4, 5};

ChangeArray(example, 2, 29);

ChangeArray(array[], index, value)
{
array[index] = value;
}</pawn>

Эта функция устанавливает заданный индекс в массиве с учетом значений. Когда она запускается на примере нашего массива, она меняет индекс 2 для значения 3 на 29. То есть:
<pawn>example[2] = 29;</pawn>

Это возможно лишь потому, что массив может быть непосредственно изменён. Чтобы предотвратить массив от изменения, можно пометить его как постоянную <tt>const</tt>. Это позволит понизить риск на ошибку в коде от её изменения. Например:

<pawn>CantChangeArray(const array[], index, value)
{
array[index] = value; //Не компилируется
}</pawn>

Это хорошая идея использовать <tt>const</tt> в параметрах массивов и Вы будете точно знать, что массив не будет изменен; это может предотвратить ошибки кодирования.

=Выражения=
Выражения являются точно такими же, какими они существуют в математике. Это группы операторов/символов, которые приходятся на один фрагмент данных. Они часто заключены в скобках (внутри скобок). Они содержат строгий "порядок операций". Они могут содержать переменные, функции, цифры и выражения сами могут быть вложенные внутрь других выражений, и даже приняты в качестве параметров.

Приведем пример простейшего выражения:
<pawn>
0; //Возвращает число 0
(0); //Так же возвращает число 0
</pawn>

Хотя выражения могут возвращать значения, они также могут ответить какое значение содержит ответ ''ноль или не ноль''. В этом смысле, ''ноль'' является ''ложью'' (false), а ''не нулевое'' значение ''истиной'' (true). Например, -1 ''истина'' в Pawn, поскольку она не является нулем. Не думайте, что отрицательные числа являются ложными.

Порядок операций выражения аналогичен языку C. PMDAS: Parenthesis, Multiplication, Division, Addition, Subtraction. Вот несколько примеров выражений:
<pawn>
5 + 6; //Вычисляет как 11
5 * 6 + 3; //Вычисляет как 33
5 * (6 + 3); //Вычисляет как 45
5.0 + 2.3; //Вычисляет как 7.3
(5 * 6) % 7; //Modulo operator, вычисляет как 2
(5 + 3) / 2 * 4 - 9; //Вычисляет как 7
</pawn>

Как уже отмечалось, выражения могут содержать переменные, или даже функции:
<pawn>
new a = 5 * 6;
new b = a * 3; //Вычисляет как 90
new c = AddTwoNumbers(a, b) + (a * b);
</pawn>

==Операторы==
Есть несколько полезных дополнительных операторов в Pawn. Первый набор упрощает аутоагрегацию выражения. Например:
<pawn>new a = 5;

a = a + 5;</pawn>

Может быть переписан, как:
<pawn>new a = 5;
a += 5;</pawn>

Это верно в отношении следующих операторов в Pawn:
*Four-function: *, /, -, +
*Bit-wise: |, &, ^, ~, <<, >>

Кроме того, существуют инкремент/декремент операторы:
<pawn>a = a + 1;
a = a - 1;</pawn>

Может быть упрощено, как:
<pawn>a++;
a--;</pawn>

Дополнительно отметим, что ++ или -- может быть представлен до переменной (до-инкремент, до-декремент) или после переменной (пост-инкремент, пост-декремент). Разница заключается в том, как остальная часть выражения содержащие их, видит результат.

* ''До:'' Переменная увеличивается до определения и остальная часть выражения видит новое значение.
* ''Пост:'' Переменная увеличивается после определения и остальная часть выражения видит старое значение.

Иными словами, <tt>a++</tt> определяет значение как <tt>a</tt> в то время как <tt>++a</tt> определяет значение как <tt>a + 1</tt>. В обоих случаях <tt>a</tt> увеличивается на <tt>1</tt>.

Например:

<pawn>new a = 5;
new b = a++; // b = 5, a = 6 (1)
new c = ++a; // a = 7, c = 7 (2)
</pawn>

(1) <tt>b</tt> присваивается <tt>a</tt> со ''старым'' значением, ''до'' того, как он будет увеличено до <tt>6</tt>. (2) <tt>c</tt> присваивается <tt>a</tt> с ''новым'' значением, ''после'' того, как он увеличивается до <tt>7</tt>.

==Операторы сравнения==
Существуют шесть операторов для сравнения двух числовых значений, а результат является либо истиной (не ноль) или ложью (ноль):
*<tt>a == b</tt> - Действительно, если и b имеет то же значение.
*<tt>a != b</tt> - Действительно, если b имеет другое значение.
*<tt>a > b</tt> - Действительно, если оно больше b
*<tt>a >= b</tt> - Действительно, если оно больше или равно b
*<tt>a < b</tt> - Действительно, если оно меньше b
*<tt>a <= b</tt> - Действительно, если оно меньше или равно b

Например:
<pawn>
(1 != 3); //Определяется как истина, поскольку 1 не равно 3.
(3 + 3 == 6); //Определяется как истина, поскольку 3+3 равно 6.
(5 - 2 >= 4); //Определяется как ложь, поскольку 3 меньше 4.
</pawn>

Заметим, что эти операторы не работают с массивами и строками. То есть, вы не можете сравнить их с помощью <tt>==</tt>.

==Действительные операторы==
Действительные операторы могут быть скомбинированы тремя булевыми (boolean) операторами:
*<tt>a && b</tt> - Истина, если a и b истинные. Ложь, если a и (или) b ложные.
{| border="1" cellpadding="2" cellspacing="0" align="center"
! <tt>&&</tt> !! 0 !! 1
|-
! 0
| 0 || 0
|-
! 1
| 0 || 1
|}
*<tt>a || b</tt> - Истина, если a или b (или обе переменные) истинные. Ложь, если обе переменные a и b ложные.
{| border="1" cellpadding="2" cellspacing="0" align="center"
! <tt><nowiki>||</nowiki></tt> !! 0 !! 1
|-
! 0
| 0 || 1
|-
! 1
| 1 || 1
|}
*<tt>!a</tt> - Истина, если a ложь. Ложь, если a истина.
{| border="1" cellpadding="2" cellspacing="0" align="center"
! <tt>!</tt> !! 0 !! 1
|-
!
| 1 || 0
|}

Например:
<pawn>
(1 || 0); //Определяется как истина, так как выражение 1 истинное
(1 && 0); //Определяется как ложь, так как выражение 0 ложное
(!1 || 0); //Определяется как ложь, так как выражение !1 ложное.
</pawn>

==Левое/правое значения==
Два важных понятия левого и правого значений, или левостороннее и правостороннее значения. Левостороннее значение имеет то, что появляется на левой стороне выражения, а правостороннее значение - появляется на правой стороне выражения.

Например:
<pawn>
new a = 5;</pawn>

В этом примере <tt>a</tt> является левосторонним значением и <tt>5</tt> является правосторонним значением.

Правила:
*'''Выражения никогда не будут левосторонними значениями'''.
*'''Переменные являются двумя, левосторонними и правосторонними значениями'''.

=Условия=
Условия позволяют Вам запускать код, определенное условие выполнено.

==Если соответствует==
Если соответствует одно или более условий. Например:

<pawn>
if (a == 5)
{
/* Код будет запущен, если условие будет истинным */
}</pawn>

Они могут быть расширены для более сложных случаев:
<pawn>
if (a == 5)
{
/* Код */
}
else if (a == 6)
{
/* Код */
}
else if (a == 7)
{
/* Код */
}</pawn>

Вы так же можете обрабатывать случаи, даже если выражение не верно. Например:
<pawn>
if (a == 5)
{
/* Код */
}
else
{
/* Код, который будет запущен если нет истинного выражения */
}</pawn>

==Оператор выбора==
Оператор выбора будет ограничен условием. Он необходим для выражения, выполняющего код для целого ряда возможных значений. Например:

<pawn>
switch (a)
{
case 5:
{
/* Код */
}
case 6:
{
/* Код */
}
case 7:
{
/* Код */
}
case 8, 9, 10:
{
/* Код */
}
default:
{
/* будет запущен, если не одно условие не соответствует */
}
}</pawn>

В отличие от некоторых других языков, оператор выбора не проваливается. То есть существуют случаи, когда код не будет запущен. При случае совпадения его код выполняется, а ключ является местом для немедленного прекращения.

=Циклы=
Циклы позволяют Вам без труда повторять выполнение кода, пока условие станет истинным.

==For циклы==
For циклы, это циклы, которые состоят из четырех частей:
*Оператор '''инициализации''' - запускается один раз перед первым циклом.
*Оператор '''условия''' - проверяет условие и запускает следующий цикл, в том числе первый. Цикл прекращается, когда это выражение становится ложным.
*Оператор '''итерации''' - запускается после каждого цикла.
* '''тело''' цикла - запускается каждый раз, пока оператор '''условия''' вычисляется как истинный.

<pawn>
for ( /* инициализация */ ; /* условие */ ; /* итерация */ )
{
/* тело */
}
</pawn>

Простым примером является функция сложения массива:
<pawn>
new array[10] = {1, 2, 3, 4, 5, 6, 7, 8, 9, 10};
new sum = SumArray(array, 10);

SumArray(const array[], count)
{
new total;

for (new i = 0; i < count; i++)
{
total += array[i];
}

return total;
}</pawn>

По отдельности:
*<tt>new i = 0</tt> - Создает новую переменную для цикла, и устанавливает её в 0.
*<tt>i < count</tt> - Только запускает цикл, если <tt>i</tt> меньше, чем <tt>count</tt>. Это гарантирует, что чтение цикла прекращается в определенный момент. В этом случае, мы не хотим читать недействительные индексы в массиве.
*<tt>i++</tt> - Увеличивает <tt>i</tt> на единицу после каждого цикла. Это гарантирует, что цикл не будет запущен вечно; в конце концов <tt>i</tt> станет слишком большим, и цикл завершится.

Таким образом, функция <tt>SumArray</tt> будет циклом каждого действительного индекса массива, каждый раз добавляя это значение в sum. Для циклов очень распространены массивы такие, как в нашем примере.

==While циклы==
While циклы являются менее распространенными, чем for циклы, но на самом деле это более простые циклы. Они имеют только две части:
*Оператор '''условия''' - проверяется перед началом каждого цикла. Цикл прекращается, когда условие становится ложным.
*'''тело''' цикла - запускается каждый раз пока цикл выполняется.

<pawn>
while ( /* условие */ )
{
/* тело */
}
</pawn>

До тех пор, пока условие выражения остается истинным, цикл будет выполняться. Каждый for цикл может быть переписан, как while цикл:

<pawn>
/* инициализация */
while ( /* условие */ )
{
/* тело */
/* итерация */
}
</pawn>

Вот предыдущий for цикл переписан как while цикл:
<pawn>
SumArray(const array[], count)
{
new total, i;

while (i < count)
{
total += array[i];
i++;
}

return total;
}</pawn>

Существуют также '''do...while''' циклы, которые используются еще реже. Они работают как и while циклы, но проверяют условие ПОСЛЕ каждого цикла, а не перед ним. Это означает, что цикл всегда будет запущен, по крайней мере один раз. Например:

<pawn>
do
{
/* тело */
}
while ( /* условие */ );
</pawn>

==Управление циклами==
Существуют два случая, в которых Мы хотели бы контролировать цикл:
*'''пропустить''' одну итерацию или цикл и продолжить выполнение цикла как обычно, или;
*'''разорвать''' цикл целиком, прежде чем он закончится.

Допустим у вас есть функция, которая принимает массив и ищет соответствия цифр. Вы хотите его остановить, когда число будет найдено:
<pawn>
/**
* Возвращает массив, если индекс значения, или -1, не найдены.
*/
SearchInArray(const array[], count, value)
{
new index = -1;

for (new i = 0; i < count; i++)
{
if (array[i] == value)
{
index = i;
break;
}
}

return index;
}</pawn>

Конечно, эту функцию можно вернуть и способом <tt>return i</tt>, но пример показывает, как <tt>break</tt> может остановить цикл.

Кроме того, ключевое слово <tt>continue</tt> пропускает итерации цикла. Например, Мы хотим суммировать все четные числа:

<pawn>
SumEvenNumbers(const array[], count)
{
new sum;

for (new i = 0; i < count; i++)
{
/* If divisibility by 2 is 1, we know it's odd */
if (array[i] % 2 == 1)
{
/* Пропускаем оставшуюся часть итерации цикла */
continue;
}
sum += array[i];
}

return sum;
}</pawn>

=Область действия=
Область действия относится к '''удобочитаемости''' кода. Это означает, что код одного уровня не может быть "виден" в коде другого уровня. Пример:

<pawn>
new A, B, C;

Function1()
{
new B;

Function2();
}

Function2()
{
new C;
}</pawn>

В этом примере, <tt>A</tt>, <tt>B</tt>, и <tt>C</tt> имеют '''глобальную область действия'''. Их можно увидеть в любой функции. Вместе с тем, <tt>B</tt> в функции <tt>Function1</tt> не является той же переменной, как <tt>B</tt> на глобальном уровне. Вместо этого она находится в '''локальной области действия''', и поэтому является '''локально изменяемой'''.

Кроме того, функции <tt>Function1</tt> и <tt>Function2</tt> ничего не знают о существовании других переменных.

Она так же является не только локальной переменной функции <tt>Function1</tt>, но и создается заново каждый раз, когда функция вызывается. Попробуйте представить это:
<pawn>
Function1()
{
new B;

Function1();
}</pawn>

В приведенном выше примере, функция <tt>Function1</tt> вызывает сама себя. Конечно, это бесконечной рекурсии (а это очень плохо), но идея заключается в том, что каждый раз, когда функция срабатывает, то создается новая копия <tt>B</tt>. Когда функция завершается, <tt>B</tt> уничтожается, и её значение теряется.

Это свойство можно объяснить проще тем, что область действия переменной равна уровню её вложенности. То есть, переменная на глобальной области действия видна для всех функций. Переменная в локальной области действия видна всему блоку кода расположенному "ниже" этого уровня. Например:

<pawn>Function1()
{
new A;

if (A)
{
A = 5;
}
}</pawn>

Приведенный выше код является действительным, поскольку в область действия распространяется по всей функции. Однако этот код, работать не будет:
<pawn>
Function1()
{
new A;

if (A)
{
new B = 5;
}

B = 5;
}</pawn>

Отметим, что <tt>B</tt> объявляется в новом блоке кода. Это означает, что <tt>B</tt> доступна только в том блоке кода, в котором была создана (и всем под-блокам вложенных внутри него). Как только блок кода прекращается, <tt>B</tt> становится не действительной.

=Динамические массивы=
Динамические массивы это массивы, которые не имеют фиксированного размера. Например:

<pawn>Function1(size)
{
new array[size];

/* Код */
}</pawn>

Динамические массивы могут иметь любое выражение, соответствующее их размеру до тех пор, пока выражение вычисляется, как число большее чем 0. Как и для обычных массивов, SourcePawn не сможет узнать размер массива после того, как он будет создан; Вы должны задать его, если хотите использовать массив позднее.

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

=Расширенное объявление переменных=
Переменные могут быть объявлены более длинным путем чем просто <tt>new</tt>.

==decl==
===Назначение===
По умолчанию, все переменные в Pawn будут инициализированы как нуль. Если есть явная инициализация, переменная инициализируется для выражения <tt>=</tt> определенным символам. В локальной области действия, это может потребовать время на выполнение. Ключевое слово <tt>decl</tt> (которое действительно только в локальной области действия) было введено, чтобы позволить решать пользователю, хочит ли он инициализировать переменную или нет.

Примечание: <tt>decl</tt> не должно быть использовано на одну однострочную переменную. Это почти никогда не будет выгодно.

===Объяснение===
Например:

<pawn>
new c = 5;
new d;
new String:blah[512];

Format(blah, sizeof(blah), "%d %d", c, d);
</pawn>

В этом коде, <tt>c</tt> равна 5 и <tt>d</tt> равна 0. Во время выполнения этого кода затраты на инициализацию незначительные. Вместе с тем, <tt>blah</tt> является большим массивом, и затраты на инициализацию всего массива могут быть больше 0 сек. и иметь плохие последствия в определенных ситуациях.

Заметим, что <tt>blah</tt> не должен быть нулевой. В период времени с объявления <tt>new</tt> и и перемещения в <tt>Format()</tt>, массив <tt>blah</tt> никогда не будет загружен или прочитан. Данный код будет более эффективен, если будет написанный следующим образом:

<pawn>
new c = 5;
new d;
decl String:blah[512];

Format(blah, sizeof(blah), "%d %d", c, d);
</pawn>

===Предостережения===
Обратная сторона <tt>decl</tt> состоит в том, что его переменные будут начинаться с "ненужного" содержания. Например, если мы будем использовать:

<pawn>
new c = 5;
new d;
decl String:blah[512];

PrintToServer("%s", blah);

Format(blah, sizeof(blah), "%d %d", c, d);
</pawn>

Этот код может привести к падению сервера, так как массив <tt>blah</tt> может быть полностью испорчен (строки требуют нулевой символ, который может отсутствовать). Точно так же, если мы сделаем:

<pawn>
new c = 5;
decl d;
decl String:blah[512];

Format(blah, sizeof(blah), "%d %d", c, d);
</pawn>

Значение <tt>d</tt> в настоящее время не определенно. Оно может быть любым значением, отрицательным или положительным.

Заметим, что это легко и эффективно обезопасит строки. Пример ниже показывает, как предотвратить строки от мусора:
<pawn>
decl String:blah[512];

blah[0] = '\0';
</pawn>

===Золотые правила===
*'''Используйте decl только, если в период объявления и загрузки/чтения значения, Вы абсолютно уверены, что есть по крайней мере одно хранилище/операция, которая отдает переменной действительные данные.'''
*'''Не оптимизируйте преждевременно.''' Кроме того, нет необходимости использовать <tt>decl</tt> на не-массивы, поскольку нет никаких дополнительных затрат на инициализацию однго однострочного значения.

===Примечания===
Этот пример НЕ является столь эффективным, как <tt>decl</tt>:
<pawn>
new String:blah[512] = "a";
</pawn>

Даже несмотря на то, что строка имеет только один символ, оператор <tt>new</tt> гарантирует, что остальная часть массива будет нулевой.

Также обратите внимание, он является неправильным для явной инициализации <tt>decl</tt>:
<pawn>decl String:blah[512] = "a";</pawn>

Приведенный выше код не будет компилироваться, потому что цель <tt>decl</tt> состоит в том, чтобы избежать каких-либо инициализаций.

==static==
Ключевое слово <tt>static</tt> входит в глобальную и локальную область действия. Оно имеет различные значения в каждой из них.

===Глобальный static===
Глобальные static переменные могут быть доступны только в рамках того же файла. Например:

<pawn>//file1.inc
static Float:g_value1 = 0.15f;

//file2.inc
static Float:g_value2 = 0.15f;</pawn>

Если плагин включает в себя оба этих файла, он не сможет использовать <tt>g_value1</tt> или <tt>g_value2</tt>. Это простой механизм сокрытия информации, и аналогичен элементам объявления переменных, например <tt>private</tt> в таких языках, как C++, Java, или C#.

===Локальный static===
Локальная static переменная является глобальной переменной, которая является видимой лишь из её местной области действия. Например:

<pawn>
MyFunction(inc)
{
static counter = -1;

counter += inc;

return counter;
}</pawn>

В этом примере, <tt>counter</tt> технически глобальная переменная -- она инициализируется один раз как -1 и никогда не инициализируется заново. Оно не существует в наборе. Это означает, что при каждом запуске функции <tt>MyFunction</tt>, переменная <tt>counter</tt> и ее хранение в памяти одно и тоже.

Возьмем следающий пример:
<pawn>MyFunction(5);
MyFunction(6);
MyFunction(10);</pawn>

В этом примере, <tt>counter</tt> может быть <tt>-1 + 5 + 6 + 10</tt>, или <tt>20</tt>, поскольку она сохраняется за рамки этой функции. Это может создавать проблемы для рекурсивной функции: если ваша функция может быть рекурсивной, то <tt>static</tt>, как правило, не является хорошей идеей, если только Ваш код не реентерабельный.

Преимуществом локальных static переменных является то, что Вам не придется загромождать свой сценарий глобальными переменными. До тех пор, пока переменной не нужно читать другую функцию, Вы можете его пихать внутрь функции и её сохранение будет гарантировано.

Заметим, что statics может существовать в любой локальной области действия:

<pawn>
MyFunction(inc)
{
if (inc > 0)
{
static counter;
return (counter += inc);
}
return -1;
}</pawn>

[[Category:Ru:SourceMod Scripting]]

Ru:Introduction to SourcePawn

2008-12-26T12:27:53Z

Frenzzy: /* Global static */

Это руководство призвано дать Вам самые основные представления по основам написания сприптов в SourcePawn. [[Pawn]] это "скриптовый" язык используемый для внедрения функциональности в других программах. Это означает, что это не самостоятельный язык, как C++ или Java, и его элементы будут отличаться в различных приложениях. SourcePawn это вариация языка Pawn используемая в [[SourceMod]].

Это руководство не расскажет Вам как писать SourceMod плагины; оно предназначено для получения общих представлений о синтаксисе и семантике этого языка. Читайте отдельную статью [[Ru:Introduction to SourceMod Plugins]] (Введение в SourceMod плагины), для введения в SourceMod API.

=Введение для новичков=
Этот раздел создан не для программистов. Если Вы по прежнему в замешательстве, Вы можете прочитать книги о других языках программирования, таких как PHP, Python, или Java, чтобы получить более полное представление о программировании.

==Идентификаторы/Ключевые слова==
Идентификаторы представляет собой набор букв, цифр и/или нижнего подчеркивания, что представляет собой нечто уникальное. Идентификаторы вводятся с учетом регистра (в отличие от PHP, где иногда это не требуется). Идентификаторы не начинаются с какого-либо специального символа, но они должны начинаться с буквы.

Есть несколько зарезервированных символов, которые имеют особое значение. Например, <tt>if</tt>, <tt>for</tt>, и <tt>return</tt> специальные конструкции в языке, которые будут описаны позднее. Они не могут быть использованы в качестве названий идентификаторов.

==Переменные==
Существует несколько важных конструкций, которые Вы должны знать, прежде чем приступить к написанию сценария. Во-первых, это '''переменные'''. Переменная это идентификатор, который содержит данные. Например, переменная "a" может содержать числа "2", "16", "0", и так далее. Переменные создаются для хранения данных внутри программы. Переменные должны быть объявлены до их использования, с помощью ключевого слова "new". Данные можно присвоить переменной, используя знак равенства (=). Пример:

<pawn>new a, b, c, d;

a = 5;
b = 16;
c = 0;
d = 500;</pawn>

В SourcePawn, переменные бывают двух типов, которые будут более подробно описаны далее.
*Однострочные (могут содержать только произвольные числовые данные), как показано выше.
*Многострочные (могут содержать целый ряд текстовых символов)

==Функции==
Следующим важным понятием являются '''функции'''. Функции идентификаторов или имен, которые выполняют действия. Это означает, что когда вы их активируете, они выполняют конкретную последовательность кода. Есть несколько типов функций, но все функции активируется одинаковым образом. "Вызов функции" является термином ссылающимся на функцию действия. Функция числовых переменных строятся так:
<pawn>функция(<параметры>)</pawn>

Примеры:

<pawn>show(56); //Активирует функцию "show" и присваивает ей число 56
show(); //Активирует функцию "show" без каких-либо данных, пустую
show(a); //Активирует функцию "show" и присваивает ей переменную с данными
</pawn>

Каждый фрагмент данных передаваемый вызываемой функции, называется '''параметр'''. Функция может иметь любое количество параметров (но есть "допустимый" предел в SourceMod: 32). Параметры будут описаны далее в этой статье.

==Комментарии==
Примечания и любой текст, который пишется после "//" считается "Комментарием", а не фактическим кодом. Есть два стиля комментариев:
*<tt>//</tt> - Двойная косая черта, всё следующие после этой строки игнорируется.
*<tt>/* */</tt> - Много-строчный комментарий, весь текст, внутри звездочек игнорируются. You cannot nest these.

==Массивы==
Описание массивов. Вы можете группировать код в виде "массивов", разделенных { и }. Это фактически создает возможность работать с целым массивом как с одним оператором. Например:

<pawn>{
here;
is;
some;
code;
}</pawn>

Массивы с фигурными скобками используются достаточно широко в программировании. Массивы кода могут быть вложенными друг в друга. Это хорошая возможность адаптировать последовательность когда и сделать его удобочитаемым, благодаря отступам код не будет смотреться как одна большая и длинная макаронина.

=Особенности языка=
Pawn может показаться очень похожим на другие языки программирования, например C, но Pawn от них фундаментально отличается. Не столь важно, чтобы Вы сейчас же поняли его отличия, но они понадобятся, если Вы уже знаете один из языков программирования.
*'''Pawn не печатает''' Pawn имеет только один тип данных - '''однострочный'''. Подробнее будет описано позже. [В дальнейшем автор рассказывает, что существует два типа данных: однострочный и многострочный]
*'''Pawn не собирает мусор''' Pawn, как язык, не имеет встроенных ресурсов памяти, и потому он не мусорит. Если функция выделит память, то Вы отвечаете за её освобождение.
*'''Pawn не объектно-ориентированный язык''' Pawn является процедурным, и полагается на подпрограммы. Также у него нету C подобных структур.
*'''Pawn не функциональный.''' Pawn является процедурным, и не поддерживает функции "лямбды" (Lambda), поздние присвоения, и все то, что можно найти в языках высшего уровня, таких как Phyton и Ruby.
*'''Pawn однопоточный''' As of this writing, Pawn is not thread safe.
*'''Pawn не интерпретируемый''' Ну, почти. Он интерпретируется на очень низком уровне. Вы должны скомпилировать код, из которого получится бинарный файл. Эта программа будет работать на той платформе, которую использует хост. Это ускоряет загрузку и позволяет легче находить ошибки.

Этот язык был выпущен ITB CompuPhase. Язык разработан для устройств низкого уровня и таким образом конечные программы очень маленькие по размеру и очень быстрые.

=Переменные=
В Pawn есть всего два типа переменных: '''однострочные''' и '''многострочные'''. Однострочные могут содержать 32 бита цифровых данных. Многострочные - последовательный список из UTF-8 символов.

'''однострочные''' не имеет своего типа, однако они могут быть '''маркированы'''(tagged). Тег позволяет Вам указывать, где определенную ячейку можно использовать. Типичные теги:
*(пусто), или '''_''' - Нет тега. Обычно используют для целых чисел ([http://en.wikipedia.org/wiki/Integer Integers]).
*'''Float''' - используют для чисел с плавающей точкой (небольших).
*'''bool''' - используют для хранения значений '''true''' (истина) или '''false''' (ложь).

Со строками все по другому, они будут рассмотрены далее.

==Объявления==
Примеры разных правильных объявлений переменных.
<pawn>
new a = 5;
new Float:b = 5.0;
new bool:c = true;
new bool:d = 0; //Работает, поскольку 0 равно false (ложь)
</pawn>

Неправильные объявления переменных
<pawn>
new a = 5.0; //Несоответствие тегов. 5.0 с тегом Float
new Float:b = 5; //Несоответствие тегов. 5 без тега.
</pawn>

Если переменная не определена в объявлении то ее значения станет 0
<pawn>
new a; //значение 0
new Float:b; //значение 0.0
new bool:c; //значение false
</pawn>

==Присвоение==
Переменным могут быть присвоены данные после создания. Пример:
<pawn>new a, Float:b, bool:c;

a = 5;
b = 5.0;
c = true;
</pawn>

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

==Описание==
Массив объявляется с помощью квадратных скобок. Вот некоторые примеры массивов:
<pawn>
new players[32]; //Набор из 32 однострочных (числовых) данных
new Float:origin[3]; //Набор из 3 чисел с плавающей точкой
</pawn>

По умолчанию, массивам присваиваются нули. Вы можете присвоить им разные значения по умолчанию, однако:
<pawn>
new numbers[5] = {1, 2, 3, 4, 5}; //Набор 1, 2, 3, 4, 5 из однострочных данных.
new Float:origin[3] = {1.0, 2.0, 3.0}; //Набор 1.0, 2.0, 3.0 из однострочных данных.
</pawn>

Вы можете оставить массив без размера, если вы собираетесь заранее присвоить ему данные. Например:
<pawn>
new numbers[] = {1, 3, 5, 7, 9};
</pawn>

Компилятор будет автоматически делать вывод о том, что Вы хотите получить массив размером 5.

==Использование==
Использование массива равносильно использованию обычных переменной. Единственное отличие массива состоит в том, что он должен быть '''индексируемым'''. Индексирование массива означает присутствие возможности выбрать элемент, который Вы хотите использовать.

Вот пример кода с использованием индексов:
<pawn>
new numbers[5], Float:origin[3];

numbers[0] = 1;
numbers[1] = 2;
numbers[2] = 3;
numbers[3] = 4;
numbers[4] = 5;
origin[0] = 1.0;
origin[1] = 2.0;
origin[2] = 3.0;
</pawn>

Заметим, что '''индекс''' это текст, который находится в квадратных скобках. Индекс всегда начинается с нуля. То есть, если массив имеет N элементов, его действительный индекс от 0 до N-1. Доступ к данным с индексами работает так же, как с обычной переменной.

Использование неверного индекса вызовет ошибку. Например:
<pawn>
new numbers[5];

numbers[5] = 20;</pawn>

Это может выглядеть верно, но число 5 не является допустимым индексом. Наибольшим значением индекса является число 4.

Вы можете использовать любые выражения, как индекс. Например:
<pawn>new a, numbers[5];

a = 1; //Сделает a = 1
numbers[a] = 4; //Сделает numbers[1] = 4
numbers[numbers[a]] = 2; //Сделает numbers[4] = 2
</pawn>

Выражения будут обсуждаться подробнее в конце статьи.

=Строки=
Строки являются удобным способом хранения текста. Символы хранятся в массиве. Строка ограничивается '''нулевым символом''', или 0. Без нулевого символа, Pawn не знает, где остановить чтение строки. Все строки в SourcePawn используют кодировку UTF-8.

Отметим, что строки имеют комбинацию из массивов и однострочных переменных. В отличие от других языков, это означает, что Вы должны знать заранее, как много места будут использовать строки. Это означает, что строки не являются динамичными. Они могут лишь вырасти до размера, которым Вы их ограничили.

''Примечание для специалистов: они фактически не однострочные. SourcePawn использует 8-битный строки для хранения массивов в качестве оптимизации. Это и есть то, что делает строки типом, а не меткой.''

==Использование==
Строки были созданы почти в равной степени и для массивов. Например:
<pawn>
new String:message[] = "Hello!";
new String:clams[6] = "Clams";
</pawn>

Это равносильно следующему:
<pawn>
new String:message[7], String:clams[6];

message[0] = 'H';
message[1] = 'e';
message[2] = 'l';
message[3] = 'l';
message[4] = 'o';
message[5] = '!';
message[6] = 0;
clams[0] = 'C';
clams[1] = 'l';
clams[2] = 'a';
clams[3] = 'm';
clams[4] = 's';
clams[5] = 0;
</pawn>

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

Заметим, что строка должна быть заключена в двойных кавычках, а символ в одиночных.

==Символы==
Особенность текста может быть использована в любой строке или однострочной переменной. Например:
<pawn>new String:text[] = "Crab";
new clam;

clam = 'D'; //Устанавливает однострочной переменной значение 'D'
text[0] = 'A'; //Меняет 'C' на 'A', сейчас получилось 'Arab'
clam = text[0]; //Устанавливает однострочной переменной значение 'A'
text[1] = clam; //Меняет 'r' на 'A', сейчас получилось 'AAab'
</pawn>

То, что вы не можете сделать, это соотнести символы массивов со строками. Внутреннее хранение отличается. Например:
<pawn>
new clams[] = "Clams"; //Не верно, нужен тип String:
new clams[] = {'C', 'l', 'a', 'm', 's', 0}; //Верно, но это НЕ СТРОКА.
</pawn>

=Функции=
Функции, как отмечалось ранее, имеют отдельные составляющие кода, которые выполняют определенные действия. Функции могут быть задействованы или '''вызвоны''' с '''параметрами''', которые дают особые настройки.

Существуют два типа вызова функции:
*'''прямой вызов''' - Вы специально вызываете функцию в своем коде.
*'''обратный вызов''' - Применение вызова функций в Вашем коде, как если бы это было событием триггера (совокупность условий, инициирующих выполнение действия).

Существуют пять видов функций:
*'''native''': Прямая, внутренняя функция, предусмотренная в приложении.
*'''public''': Функция обратного вызова, что делает её видимой для приложения и других сценариев.
*'''normal''': Нормальная функция, которую Вы можете только вызвать.
*'''stock''': Нормальная функция, предусмотренная если включает в себя файл. Если не используется, то не компилируется.
*'''forward''': Эта функция представляет собой глобальное событие, предусмотренная приложением. Если Вы её привели в исполнение, она будет вызвона.

Весь код в Pawn должен существовать в функциях. Это основное отличие от языков, таких как PHP, Perl и Python, которые позволяют Вам писать глобальный код. Это происходит потому, что Pawn вызывается на основе другого языка: он реагирует на действия от родительского приложения, и функции должны быть написаны для обработки этих действий. Хотя наш пример, часто содержат свободно плавающий код, это сделано исключительно для демонстрационных целей. Свободно плавающий код в нашем примере означает, что код является частью ряда функций.

==Описание==
В отличие от переменных, функции, не нужно объявлять, прежде чем использовать их. Функции имеют две части, '''модель''' и '''тело'''. Модель содержит имя Вашей функции и параметры, которые она будет принимать. Тело является контейнером для кода.

Пример функции:
<pawn>
AddTwoNumbers(first, second)
{
new sum = first + second;

return sum;
}</pawn>

Это простая функция. Модель этой строки:
<pawn>AddTwoNumbers(first, second)</pawn>

Распишем по отдельности:
*<tt>AddTwoNumbers</tt> - Название функции.
*<tt>first</tt> - Название первого параметра, который представляет собой простой элемент.
*<tt>second</tt> - Название второго параметра, который представляет собой простой элемент.

Тело представляет собой простой блок кода. Он создает новую переменную, названную <tt>sum</tt>, и присваивает ей значение этих двух параметров, добавленных совместно (другие выражения будут позже). Важно заметить оператор <tt>return</tt>, в котором обозначается конец функции и возврат с полученными значениями из этой функции. Все функции ''возвращают значения'' после завершения. Это означает, например:

<pawn>new sum = AddTwoNumbers(4, 5);</pawn>

Приведенный выше код будет присваивать число 9 к sum. Функция получает два значения и передает новое значение sum в качестве '''возвращаемого значения'''. Если функция не имеет возвращаемого значения или не имеет значений для возврата, то возвращается 0 по умолчанию.

Функция может принимать любые типы значений. Она может вернуть любую однострочную переменную, но не массивы или строки. Пример:
<pawn>Float:AddTwoFloats(Float:a, Float:b)
{
new Float:sum = a + b;

return sum;
}</pawn>

''Заметим, что если в приведенной выше функции, Вам вернулась не Float значение, Вы получите не соответствие значений.''

Можно, конечно, передавать переменные в функции:
<pawn>new numbers[3] = {1, 2, 0};

numbers[2] = AddTwoNumbers(numbers[0], numbers[1]);</pawn>

Заметим, что однострочные переменные передаются '''по значению'''. То есть, их значение не может быть изменено функцией. Например:
<pawn>new a = 5;

ChangeValue(a);

ChangeValue(b)
{
b = 5;
}</pawn>

Этот код не будет менять значение <tt>a</tt>. Это происходит потому, что копия этого значения в <tt>a</tt> передается вместо <tt>a</tt> самостоятельно.

Больше примеров функций будут демонстрироваться и в других частях статьи.

==Publics==
Публичные функции используются для осуществления обратных вызовов. Вы не должны создавать какую-либо публичную функцию, если это вынудит выполнение обратного вызова. Например, вот два обратных вызова из <tt>sourcemod.inc</tt>:

<pawn>forward OnPluginStart();
forward OnClientDisconnected(client);</pawn>

Чтобы выполнить и получить эти два события, Вы должны написать такие функции как:

<pawn>public OnPluginStart()
{
/* Код здесь */
}

public OnClientDisconnected(client)
{
/* Код здесь */
}</pawn>

Ключевое слово '''public''' делает функцию публичной, а также позволяет родительскому приложению непосредственно вызывать функцию.

==Natives==
Natives имеют встроенные функции, предоставляемые приложением. Вы можете вызвать их, как если бы они были normal функциями. Например, SourceMod имеет следующие функции:

<pawn>native FloatRound(Float:num);</pawn>

Её можно вызвать таким образом:
<pawn>new num = FloatRound(5.2); //Результат в num = 5</pawn>

==Параметры массива==
Вы можете передавать массивы или строки в качестве параметров. Важно отметить, что они идут '''как ссылка'''. То есть не делать копию данных, а отдавать непосредственно ссылки на данные. Существует простой способ объяснить это более конкретно.

<pawn>
new example[] = {1, 2, 3, 4, 5};

ChangeArray(example, 2, 29);

ChangeArray(array[], index, value)
{
array[index] = value;
}</pawn>

Эта функция устанавливает заданный индекс в массиве с учетом значений. Когда она запускается на примере нашего массива, она меняет индекс 2 для значения 3 на 29. То есть:
<pawn>example[2] = 29;</pawn>

Это возможно лишь потому, что массив может быть непосредственно изменён. Чтобы предотвратить массив от изменения, можно пометить его как постоянную <tt>const</tt>. Это позволит понизить риск на ошибку в коде от её изменения. Например:

<pawn>CantChangeArray(const array[], index, value)
{
array[index] = value; //Не компилируется
}</pawn>

Это хорошая идея использовать <tt>const</tt> в параметрах массивов и Вы будете точно знать, что массив не будет изменен; это может предотвратить ошибки кодирования.

=Выражения=
Выражения являются точно такими же, какими они существуют в математике. Это группы операторов/символов, которые приходятся на один фрагмент данных. Они часто заключены в скобках (внутри скобок). Они содержат строгий "порядок операций". Они могут содержать переменные, функции, цифры и выражения сами могут быть вложенные внутрь других выражений, и даже приняты в качестве параметров.

Приведем пример простейшего выражения:
<pawn>
0; //Возвращает число 0
(0); //Так же возвращает число 0
</pawn>

Хотя выражения могут возвращать значения, они также могут ответить какое значение содержит ответ ''ноль или не ноль''. В этом смысле, ''ноль'' является ''ложью'' (false), а ''не нулевое'' значение ''истиной'' (true). Например, -1 ''истина'' в Pawn, поскольку она не является нулем. Не думайте, что отрицательные числа являются ложными.

Порядок операций выражения аналогичен языку C. PMDAS: Parenthesis, Multiplication, Division, Addition, Subtraction. Вот несколько примеров выражений:
<pawn>
5 + 6; //Вычисляет как 11
5 * 6 + 3; //Вычисляет как 33
5 * (6 + 3); //Вычисляет как 45
5.0 + 2.3; //Вычисляет как 7.3
(5 * 6) % 7; //Modulo operator, вычисляет как 2
(5 + 3) / 2 * 4 - 9; //Вычисляет как 7
</pawn>

Как уже отмечалось, выражения могут содержать переменные, или даже функции:
<pawn>
new a = 5 * 6;
new b = a * 3; //Вычисляет как 90
new c = AddTwoNumbers(a, b) + (a * b);
</pawn>

==Операторы==
Есть несколько полезных дополнительных операторов в Pawn. Первый набор упрощает аутоагрегацию выражения. Например:
<pawn>new a = 5;

a = a + 5;</pawn>

Может быть переписан, как:
<pawn>new a = 5;
a += 5;</pawn>

Это верно в отношении следующих операторов в Pawn:
*Four-function: *, /, -, +
*Bit-wise: |, &, ^, ~, <<, >>

Кроме того, существуют инкремент/декремент операторы:
<pawn>a = a + 1;
a = a - 1;</pawn>

Может быть упрощено, как:
<pawn>a++;
a--;</pawn>

Дополнительно отметим, что ++ или -- может быть представлен до переменной (до-инкремент, до-декремент) или после переменной (пост-инкремент, пост-декремент). Разница заключается в том, как остальная часть выражения содержащие их, видит результат.

* ''До:'' Переменная увеличивается до определения и остальная часть выражения видит новое значение.
* ''Пост:'' Переменная увеличивается после определения и остальная часть выражения видит старое значение.

Иными словами, <tt>a++</tt> определяет значение как <tt>a</tt> в то время как <tt>++a</tt> определяет значение как <tt>a + 1</tt>. В обоих случаях <tt>a</tt> увеличивается на <tt>1</tt>.

Например:

<pawn>new a = 5;
new b = a++; // b = 5, a = 6 (1)
new c = ++a; // a = 7, c = 7 (2)
</pawn>

(1) <tt>b</tt> присваивается <tt>a</tt> со ''старым'' значением, ''до'' того, как он будет увеличено до <tt>6</tt>. (2) <tt>c</tt> присваивается <tt>a</tt> с ''новым'' значением, ''после'' того, как он увеличивается до <tt>7</tt>.

==Операторы сравнения==
Существуют шесть операторов для сравнения двух числовых значений, а результат является либо истиной (не ноль) или ложью (ноль):
*<tt>a == b</tt> - Действительно, если и b имеет то же значение.
*<tt>a != b</tt> - Действительно, если b имеет другое значение.
*<tt>a > b</tt> - Действительно, если оно больше b
*<tt>a >= b</tt> - Действительно, если оно больше или равно b
*<tt>a < b</tt> - Действительно, если оно меньше b
*<tt>a <= b</tt> - Действительно, если оно меньше или равно b

Например:
<pawn>
(1 != 3); //Определяется как истина, поскольку 1 не равно 3.
(3 + 3 == 6); //Определяется как истина, поскольку 3+3 равно 6.
(5 - 2 >= 4); //Определяется как ложь, поскольку 3 меньше 4.
</pawn>

Заметим, что эти операторы не работают с массивами и строками. То есть, вы не можете сравнить их с помощью <tt>==</tt>.

==Действительные операторы==
Действительные операторы могут быть скомбинированы тремя булевыми (boolean) операторами:
*<tt>a && b</tt> - Истина, если a и b истинные. Ложь, если a и (или) b ложные.
{| border="1" cellpadding="2" cellspacing="0" align="center"
! <tt>&&</tt> !! 0 !! 1
|-
! 0
| 0 || 0
|-
! 1
| 0 || 1
|}
*<tt>a || b</tt> - Истина, если a или b (или обе переменные) истинные. Ложь, если обе переменные a и b ложные.
{| border="1" cellpadding="2" cellspacing="0" align="center"
! <tt><nowiki>||</nowiki></tt> !! 0 !! 1
|-
! 0
| 0 || 1
|-
! 1
| 1 || 1
|}
*<tt>!a</tt> - Истина, если a ложь. Ложь, если a истина.
{| border="1" cellpadding="2" cellspacing="0" align="center"
! <tt>!</tt> !! 0 !! 1
|-
!
| 1 || 0
|}

Например:
<pawn>
(1 || 0); //Определяется как истина, так как выражение 1 истинное
(1 && 0); //Определяется как ложь, так как выражение 0 ложное
(!1 || 0); //Определяется как ложь, так как выражение !1 ложное.
</pawn>

==Левое/правое значения==
Два важных понятия левого и правого значений, или левостороннее и правостороннее значения. Левостороннее значение имеет то, что появляется на левой стороне выражения, а правостороннее значение - появляется на правой стороне выражения.

Например:
<pawn>
new a = 5;</pawn>

В этом примере <tt>a</tt> является левосторонним значением и <tt>5</tt> является правосторонним значением.

Правила:
*'''Выражения никогда не будут левосторонними значениями'''.
*'''Переменные являются двумя, левосторонними и правосторонними значениями'''.

=Условия=
Условия позволяют Вам запускать код, определенное условие выполнено.

==Если соответствует==
Если соответствует одно или более условий. Например:

<pawn>
if (a == 5)
{
/* Код будет запущен, если условие будет истинным */
}</pawn>

Они могут быть расширены для более сложных случаев:
<pawn>
if (a == 5)
{
/* Код */
}
else if (a == 6)
{
/* Код */
}
else if (a == 7)
{
/* Код */
}</pawn>

Вы так же можете обрабатывать случаи, даже если выражение не верно. Например:
<pawn>
if (a == 5)
{
/* Код */
}
else
{
/* Код, который будет запущен если нет истинного выражения */
}</pawn>

==Оператор выбора==
Оператор выбора будет ограничен условием. Он необходим для выражения, выполняющего код для целого ряда возможных значений. Например:

<pawn>
switch (a)
{
case 5:
{
/* Код */
}
case 6:
{
/* Код */
}
case 7:
{
/* Код */
}
case 8, 9, 10:
{
/* Код */
}
default:
{
/* будет запущен, если не одно условие не соответствует */
}
}</pawn>

В отличие от некоторых других языков, оператор выбора не проваливается. То есть существуют случаи, когда код не будет запущен. При случае совпадения его код выполняется, а ключ является местом для немедленного прекращения.

=Циклы=
Циклы позволяют Вам без труда повторять выполнение кода, пока условие станет истинным.

==For циклы==
For циклы, это циклы, которые состоят из четырех частей:
*Оператор '''инициализации''' - запускается один раз перед первым циклом.
*Оператор '''условия''' - проверяет условие и запускает следующий цикл, в том числе первый. Цикл прекращается, когда это выражение становится ложным.
*Оператор '''итерации''' - запускается после каждого цикла.
* '''тело''' цикла - запускается каждый раз, пока оператор '''условия''' вычисляется как истинный.

<pawn>
for ( /* инициализация */ ; /* условие */ ; /* итерация */ )
{
/* тело */
}
</pawn>

Простым примером является функция сложения массива:
<pawn>
new array[10] = {1, 2, 3, 4, 5, 6, 7, 8, 9, 10};
new sum = SumArray(array, 10);

SumArray(const array[], count)
{
new total;

for (new i = 0; i < count; i++)
{
total += array[i];
}

return total;
}</pawn>

По отдельности:
*<tt>new i = 0</tt> - Создает новую переменную для цикла, и устанавливает её в 0.
*<tt>i < count</tt> - Только запускает цикл, если <tt>i</tt> меньше, чем <tt>count</tt>. Это гарантирует, что чтение цикла прекращается в определенный момент. В этом случае, мы не хотим читать недействительные индексы в массиве.
*<tt>i++</tt> - Увеличивает <tt>i</tt> на единицу после каждого цикла. Это гарантирует, что цикл не будет запущен вечно; в конце концов <tt>i</tt> станет слишком большим, и цикл завершится.

Таким образом, функция <tt>SumArray</tt> будет циклом каждого действительного индекса массива, каждый раз добавляя это значение в sum. Для циклов очень распространены массивы такие, как в нашем примере.

==While циклы==
While циклы являются менее распространенными, чем for циклы, но на самом деле это более простые циклы. Они имеют только две части:
*Оператор '''условия''' - проверяется перед началом каждого цикла. Цикл прекращается, когда условие становится ложным.
*'''тело''' цикла - запускается каждый раз пока цикл выполняется.

<pawn>
while ( /* условие */ )
{
/* тело */
}
</pawn>

До тех пор, пока условие выражения остается истинным, цикл будет выполняться. Каждый for цикл может быть переписан, как while цикл:

<pawn>
/* инициализация */
while ( /* условие */ )
{
/* тело */
/* итерация */
}
</pawn>

Вот предыдущий for цикл переписан как while цикл:
<pawn>
SumArray(const array[], count)
{
new total, i;

while (i < count)
{
total += array[i];
i++;
}

return total;
}</pawn>

Существуют также '''do...while''' циклы, которые используются еще реже. Они работают как и while циклы, но проверяют условие ПОСЛЕ каждого цикла, а не перед ним. Это означает, что цикл всегда будет запущен, по крайней мере один раз. Например:

<pawn>
do
{
/* тело */
}
while ( /* условие */ );
</pawn>

==Управление циклами==
Существуют два случая, в которых Мы хотели бы контролировать цикл:
*'''пропустить''' одну итерацию или цикл и продолжить выполнение цикла как обычно, или;
*'''разорвать''' цикл целиком, прежде чем он закончится.

Допустим у вас есть функция, которая принимает массив и ищет соответствия цифр. Вы хотите его остановить, когда число будет найдено:
<pawn>
/**
* Возвращает массив, если индекс значения, или -1, не найдены.
*/
SearchInArray(const array[], count, value)
{
new index = -1;

for (new i = 0; i < count; i++)
{
if (array[i] == value)
{
index = i;
break;
}
}

return index;
}</pawn>

Конечно, эту функцию можно вернуть и способом <tt>return i</tt>, но пример показывает, как <tt>break</tt> может остановить цикл.

Кроме того, ключевое слово <tt>continue</tt> пропускает итерации цикла. Например, Мы хотим суммировать все четные числа:

<pawn>
SumEvenNumbers(const array[], count)
{
new sum;

for (new i = 0; i < count; i++)
{
/* If divisibility by 2 is 1, we know it's odd */
if (array[i] % 2 == 1)
{
/* Пропускаем оставшуюся часть итерации цикла */
continue;
}
sum += array[i];
}

return sum;
}</pawn>

=Область действия=
Область действия относится к '''удобочитаемости''' кода. Это означает, что код одного уровня не может быть "виден" в коде другого уровня. Пример:

<pawn>
new A, B, C;

Function1()
{
new B;

Function2();
}

Function2()
{
new C;
}</pawn>

В этом примере, <tt>A</tt>, <tt>B</tt>, и <tt>C</tt> имеют '''глобальную область действия'''. Их можно увидеть в любой функции. Вместе с тем, <tt>B</tt> в функции <tt>Function1</tt> не является той же переменной, как <tt>B</tt> на глобальном уровне. Вместо этого она находится в '''локальной области действия''', и поэтому является '''локально изменяемой'''.

Кроме того, функции <tt>Function1</tt> и <tt>Function2</tt> ничего не знают о существовании других переменных.

Она так же является не только локальной переменной функции <tt>Function1</tt>, но и создается заново каждый раз, когда функция вызывается. Попробуйте представить это:
<pawn>
Function1()
{
new B;

Function1();
}</pawn>

В приведенном выше примере, функция <tt>Function1</tt> вызывает сама себя. Конечно, это бесконечной рекурсии (а это очень плохо), но идея заключается в том, что каждый раз, когда функция срабатывает, то создается новая копия <tt>B</tt>. Когда функция завершается, <tt>B</tt> уничтожается, и её значение теряется.

Это свойство можно объяснить проще тем, что область действия переменной равна уровню её вложенности. То есть, переменная на глобальной области действия видна для всех функций. Переменная в локальной области действия видна всему блоку кода расположенному "ниже" этого уровня. Например:

<pawn>Function1()
{
new A;

if (A)
{
A = 5;
}
}</pawn>

Приведенный выше код является действительным, поскольку в область действия распространяется по всей функции. Однако этот код, работать не будет:
<pawn>
Function1()
{
new A;

if (A)
{
new B = 5;
}

B = 5;
}</pawn>

Отметим, что <tt>B</tt> объявляется в новом блоке кода. Это означает, что <tt>B</tt> доступна только в том блоке кода, в котором была создана (и всем под-блокам вложенных внутри него). Как только блок кода прекращается, <tt>B</tt> становится не действительной.

=Динамические массивы=
Динамические массивы это массивы, которые не имеют фиксированного размера. Например:

<pawn>Function1(size)
{
new array[size];

/* Код */
}</pawn>

Динамические массивы могут иметь любое выражение, соответствующее их размеру до тех пор, пока выражение вычисляется, как число большее чем 0. Как и для обычных массивов, SourcePawn не сможет узнать размер массива после того, как он будет создан; Вы должны задать его, если хотите использовать массив позднее.

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

=Расширенное объявление переменных=
Переменные могут быть объявлены более длинным путем чем просто <tt>new</tt>.

==decl==
===Назначение===
По умолчанию, все переменные в Pawn будут инициализированы как нуль. Если есть явная инициализация, переменная инициализируется для выражения <tt>=</tt> определенным символам. В локальной области действия, это может потребовать время на выполнение. Ключевое слово <tt>decl</tt> (которое действительно только в локальной области действия) было введено, чтобы позволить решать пользователю, хочит ли он инициализировать переменную или нет.

Примечание: <tt>decl</tt> не должно быть использовано на одну однострочную переменную. Это почти никогда не будет выгодно.

===Объяснение===
Например:

<pawn>
new c = 5;
new d;
new String:blah[512];

Format(blah, sizeof(blah), "%d %d", c, d);
</pawn>

В этом коде, <tt>c</tt> равна 5 и <tt>d</tt> равна 0. Во время выполнения этого кода затраты на инициализацию незначительные. Вместе с тем, <tt>blah</tt> является большим массивом, и затраты на инициализацию всего массива могут быть больше 0 сек. и иметь плохие последствия в определенных ситуациях.

Заметим, что <tt>blah</tt> не должен быть нулевой. В период времени с объявления <tt>new</tt> и и перемещения в <tt>Format()</tt>, массив <tt>blah</tt> никогда не будет загружен или прочитан. Данный код будет более эффективен, если будет написанный следующим образом:

<pawn>
new c = 5;
new d;
decl String:blah[512];

Format(blah, sizeof(blah), "%d %d", c, d);
</pawn>

===Предостережения===
Обратная сторона <tt>decl</tt> состоит в том, что его переменные будут начинаться с "ненужного" содержания. Например, если мы будем использовать:

<pawn>
new c = 5;
new d;
decl String:blah[512];

PrintToServer("%s", blah);

Format(blah, sizeof(blah), "%d %d", c, d);
</pawn>

Этот код может привести к падению сервера, так как массив <tt>blah</tt> может быть полностью испорчен (строки требуют нулевой символ, который может отсутствовать). Точно так же, если мы сделаем:

<pawn>
new c = 5;
decl d;
decl String:blah[512];

Format(blah, sizeof(blah), "%d %d", c, d);
</pawn>

Значение <tt>d</tt> в настоящее время не определенно. Оно может быть любым значением, отрицательным или положительным.

Заметим, что это легко и эффективно обезопасит строки. Пример ниже показывает, как предотвратить строки от мусора:
<pawn>
decl String:blah[512];

blah[0] = '\0';
</pawn>

===Золотые правила===
*'''Используйте decl только, если в период объявления и загрузки/чтения значения, Вы абсолютно уверены, что есть по крайней мере одно хранилище/операция, которая отдает переменной действительные данные.'''
*'''Не оптимизируйте преждевременно.''' Кроме того, нет необходимости использовать <tt>decl</tt> на не-массивы, поскольку нет никаких дополнительных затрат на инициализацию однго однострочного значения.

===Примечания===
Этот пример НЕ является столь эффективным, как <tt>decl</tt>:
<pawn>
new String:blah[512] = "a";
</pawn>

Даже несмотря на то, что строка имеет только один символ, оператор <tt>new</tt> гарантирует, что остальная часть массива будет нулевой.

Также обратите внимание, он является неправильным для явной инициализации <tt>decl</tt>:
<pawn>decl String:blah[512] = "a";</pawn>

Приведенный выше код не будет компилироваться, потому что цель <tt>decl</tt> состоит в том, чтобы избежать каких-либо инициализаций.

==static==
Ключевое слово <tt>static</tt> входит в глобальную и локальную область действия. Оно имеет различные значения в каждой из них.

===Глобальный static===
Глобальные static переменные могут быть доступны только в рамках того же файла. Например:

<pawn>//file1.inc
static Float:g_value1 = 0.15f;

//file2.inc
static Float:g_value2 = 0.15f;</pawn>

Если плагин включает в себя оба этих файла, он не сможет использовать <tt>g_value1</tt> или <tt>g_value2</tt>. Это простой механизм сокрытия информации, и аналогичен элементам объявления переменных, например <tt>private</tt> в таких языках, как C++, Java, или C#.

===Local static===
A local static variable is a global variable that is only visible from its local lexical scope. For example:

<pawn>
MyFunction(inc)
{
static counter = -1;

counter += inc;

return counter;
}</pawn>

In this example, <tt>counter</tt> is technically a global variable -- it is initialized once to -1 and is never initialized again. It does not exist on the stack. That means each time <tt>MyFunction</tt> runs, the <tt>counter</tt> variable and its storage in memory is the same.

Take this example:
<pawn>MyFunction(5);
MyFunction(6);
MyFunction(10);</pawn>

In this example, <tt>counter</tt> will be <tt>-1 + 5 + 6 + 10</tt>, or <tt>20</tt>, because it persists beyond the frame of the function. Note this may pose problems for recursive functions: if your function may be recursive, then <tt>static</tt> is usually not a good idea unless your code is re-entrant.

The benefit of a local static variable is that you don't have to clutter your script with global variables. As long as the variable doesn't need to be read by another function, you can squirrel it inside the function and its persistence will be guaranteed.

Note that statics can exist in any local scope:

<pawn>
MyFunction(inc)
{
if (inc > 0)
{
static counter;
return (counter += inc);
}
return -1;
}</pawn>

[[Category:Ru:SourceMod Scripting]]

Ru:Introduction to SourcePawn

2008-12-26T12:27:36Z

Frenzzy: /* Global static */

Это руководство призвано дать Вам самые основные представления по основам написания сприптов в SourcePawn. [[Pawn]] это "скриптовый" язык используемый для внедрения функциональности в других программах. Это означает, что это не самостоятельный язык, как C++ или Java, и его элементы будут отличаться в различных приложениях. SourcePawn это вариация языка Pawn используемая в [[SourceMod]].

Это руководство не расскажет Вам как писать SourceMod плагины; оно предназначено для получения общих представлений о синтаксисе и семантике этого языка. Читайте отдельную статью [[Ru:Introduction to SourceMod Plugins]] (Введение в SourceMod плагины), для введения в SourceMod API.

=Введение для новичков=
Этот раздел создан не для программистов. Если Вы по прежнему в замешательстве, Вы можете прочитать книги о других языках программирования, таких как PHP, Python, или Java, чтобы получить более полное представление о программировании.

==Идентификаторы/Ключевые слова==
Идентификаторы представляет собой набор букв, цифр и/или нижнего подчеркивания, что представляет собой нечто уникальное. Идентификаторы вводятся с учетом регистра (в отличие от PHP, где иногда это не требуется). Идентификаторы не начинаются с какого-либо специального символа, но они должны начинаться с буквы.

Есть несколько зарезервированных символов, которые имеют особое значение. Например, <tt>if</tt>, <tt>for</tt>, и <tt>return</tt> специальные конструкции в языке, которые будут описаны позднее. Они не могут быть использованы в качестве названий идентификаторов.

==Переменные==
Существует несколько важных конструкций, которые Вы должны знать, прежде чем приступить к написанию сценария. Во-первых, это '''переменные'''. Переменная это идентификатор, который содержит данные. Например, переменная "a" может содержать числа "2", "16", "0", и так далее. Переменные создаются для хранения данных внутри программы. Переменные должны быть объявлены до их использования, с помощью ключевого слова "new". Данные можно присвоить переменной, используя знак равенства (=). Пример:

<pawn>new a, b, c, d;

a = 5;
b = 16;
c = 0;
d = 500;</pawn>

В SourcePawn, переменные бывают двух типов, которые будут более подробно описаны далее.
*Однострочные (могут содержать только произвольные числовые данные), как показано выше.
*Многострочные (могут содержать целый ряд текстовых символов)

==Функции==
Следующим важным понятием являются '''функции'''. Функции идентификаторов или имен, которые выполняют действия. Это означает, что когда вы их активируете, они выполняют конкретную последовательность кода. Есть несколько типов функций, но все функции активируется одинаковым образом. "Вызов функции" является термином ссылающимся на функцию действия. Функция числовых переменных строятся так:
<pawn>функция(<параметры>)</pawn>

Примеры:

<pawn>show(56); //Активирует функцию "show" и присваивает ей число 56
show(); //Активирует функцию "show" без каких-либо данных, пустую
show(a); //Активирует функцию "show" и присваивает ей переменную с данными
</pawn>

Каждый фрагмент данных передаваемый вызываемой функции, называется '''параметр'''. Функция может иметь любое количество параметров (но есть "допустимый" предел в SourceMod: 32). Параметры будут описаны далее в этой статье.

==Комментарии==
Примечания и любой текст, который пишется после "//" считается "Комментарием", а не фактическим кодом. Есть два стиля комментариев:
*<tt>//</tt> - Двойная косая черта, всё следующие после этой строки игнорируется.
*<tt>/* */</tt> - Много-строчный комментарий, весь текст, внутри звездочек игнорируются. You cannot nest these.

==Массивы==
Описание массивов. Вы можете группировать код в виде "массивов", разделенных { и }. Это фактически создает возможность работать с целым массивом как с одним оператором. Например:

<pawn>{
here;
is;
some;
code;
}</pawn>

Массивы с фигурными скобками используются достаточно широко в программировании. Массивы кода могут быть вложенными друг в друга. Это хорошая возможность адаптировать последовательность когда и сделать его удобочитаемым, благодаря отступам код не будет смотреться как одна большая и длинная макаронина.

=Особенности языка=
Pawn может показаться очень похожим на другие языки программирования, например C, но Pawn от них фундаментально отличается. Не столь важно, чтобы Вы сейчас же поняли его отличия, но они понадобятся, если Вы уже знаете один из языков программирования.
*'''Pawn не печатает''' Pawn имеет только один тип данных - '''однострочный'''. Подробнее будет описано позже. [В дальнейшем автор рассказывает, что существует два типа данных: однострочный и многострочный]
*'''Pawn не собирает мусор''' Pawn, как язык, не имеет встроенных ресурсов памяти, и потому он не мусорит. Если функция выделит память, то Вы отвечаете за её освобождение.
*'''Pawn не объектно-ориентированный язык''' Pawn является процедурным, и полагается на подпрограммы. Также у него нету C подобных структур.
*'''Pawn не функциональный.''' Pawn является процедурным, и не поддерживает функции "лямбды" (Lambda), поздние присвоения, и все то, что можно найти в языках высшего уровня, таких как Phyton и Ruby.
*'''Pawn однопоточный''' As of this writing, Pawn is not thread safe.
*'''Pawn не интерпретируемый''' Ну, почти. Он интерпретируется на очень низком уровне. Вы должны скомпилировать код, из которого получится бинарный файл. Эта программа будет работать на той платформе, которую использует хост. Это ускоряет загрузку и позволяет легче находить ошибки.

Этот язык был выпущен ITB CompuPhase. Язык разработан для устройств низкого уровня и таким образом конечные программы очень маленькие по размеру и очень быстрые.

=Переменные=
В Pawn есть всего два типа переменных: '''однострочные''' и '''многострочные'''. Однострочные могут содержать 32 бита цифровых данных. Многострочные - последовательный список из UTF-8 символов.

'''однострочные''' не имеет своего типа, однако они могут быть '''маркированы'''(tagged). Тег позволяет Вам указывать, где определенную ячейку можно использовать. Типичные теги:
*(пусто), или '''_''' - Нет тега. Обычно используют для целых чисел ([http://en.wikipedia.org/wiki/Integer Integers]).
*'''Float''' - используют для чисел с плавающей точкой (небольших).
*'''bool''' - используют для хранения значений '''true''' (истина) или '''false''' (ложь).

Со строками все по другому, они будут рассмотрены далее.

==Объявления==
Примеры разных правильных объявлений переменных.
<pawn>
new a = 5;
new Float:b = 5.0;
new bool:c = true;
new bool:d = 0; //Работает, поскольку 0 равно false (ложь)
</pawn>

Неправильные объявления переменных
<pawn>
new a = 5.0; //Несоответствие тегов. 5.0 с тегом Float
new Float:b = 5; //Несоответствие тегов. 5 без тега.
</pawn>

Если переменная не определена в объявлении то ее значения станет 0
<pawn>
new a; //значение 0
new Float:b; //значение 0.0
new bool:c; //значение false
</pawn>

==Присвоение==
Переменным могут быть присвоены данные после создания. Пример:
<pawn>new a, Float:b, bool:c;

a = 5;
b = 5.0;
c = true;
</pawn>

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

==Описание==
Массив объявляется с помощью квадратных скобок. Вот некоторые примеры массивов:
<pawn>
new players[32]; //Набор из 32 однострочных (числовых) данных
new Float:origin[3]; //Набор из 3 чисел с плавающей точкой
</pawn>

По умолчанию, массивам присваиваются нули. Вы можете присвоить им разные значения по умолчанию, однако:
<pawn>
new numbers[5] = {1, 2, 3, 4, 5}; //Набор 1, 2, 3, 4, 5 из однострочных данных.
new Float:origin[3] = {1.0, 2.0, 3.0}; //Набор 1.0, 2.0, 3.0 из однострочных данных.
</pawn>

Вы можете оставить массив без размера, если вы собираетесь заранее присвоить ему данные. Например:
<pawn>
new numbers[] = {1, 3, 5, 7, 9};
</pawn>

Компилятор будет автоматически делать вывод о том, что Вы хотите получить массив размером 5.

==Использование==
Использование массива равносильно использованию обычных переменной. Единственное отличие массива состоит в том, что он должен быть '''индексируемым'''. Индексирование массива означает присутствие возможности выбрать элемент, который Вы хотите использовать.

Вот пример кода с использованием индексов:
<pawn>
new numbers[5], Float:origin[3];

numbers[0] = 1;
numbers[1] = 2;
numbers[2] = 3;
numbers[3] = 4;
numbers[4] = 5;
origin[0] = 1.0;
origin[1] = 2.0;
origin[2] = 3.0;
</pawn>

Заметим, что '''индекс''' это текст, который находится в квадратных скобках. Индекс всегда начинается с нуля. То есть, если массив имеет N элементов, его действительный индекс от 0 до N-1. Доступ к данным с индексами работает так же, как с обычной переменной.

Использование неверного индекса вызовет ошибку. Например:
<pawn>
new numbers[5];

numbers[5] = 20;</pawn>

Это может выглядеть верно, но число 5 не является допустимым индексом. Наибольшим значением индекса является число 4.

Вы можете использовать любые выражения, как индекс. Например:
<pawn>new a, numbers[5];

a = 1; //Сделает a = 1
numbers[a] = 4; //Сделает numbers[1] = 4
numbers[numbers[a]] = 2; //Сделает numbers[4] = 2
</pawn>

Выражения будут обсуждаться подробнее в конце статьи.

=Строки=
Строки являются удобным способом хранения текста. Символы хранятся в массиве. Строка ограничивается '''нулевым символом''', или 0. Без нулевого символа, Pawn не знает, где остановить чтение строки. Все строки в SourcePawn используют кодировку UTF-8.

Отметим, что строки имеют комбинацию из массивов и однострочных переменных. В отличие от других языков, это означает, что Вы должны знать заранее, как много места будут использовать строки. Это означает, что строки не являются динамичными. Они могут лишь вырасти до размера, которым Вы их ограничили.

''Примечание для специалистов: они фактически не однострочные. SourcePawn использует 8-битный строки для хранения массивов в качестве оптимизации. Это и есть то, что делает строки типом, а не меткой.''

==Использование==
Строки были созданы почти в равной степени и для массивов. Например:
<pawn>
new String:message[] = "Hello!";
new String:clams[6] = "Clams";
</pawn>

Это равносильно следующему:
<pawn>
new String:message[7], String:clams[6];

message[0] = 'H';
message[1] = 'e';
message[2] = 'l';
message[3] = 'l';
message[4] = 'o';
message[5] = '!';
message[6] = 0;
clams[0] = 'C';
clams[1] = 'l';
clams[2] = 'a';
clams[3] = 'm';
clams[4] = 's';
clams[5] = 0;
</pawn>

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

Заметим, что строка должна быть заключена в двойных кавычках, а символ в одиночных.

==Символы==
Особенность текста может быть использована в любой строке или однострочной переменной. Например:
<pawn>new String:text[] = "Crab";
new clam;

clam = 'D'; //Устанавливает однострочной переменной значение 'D'
text[0] = 'A'; //Меняет 'C' на 'A', сейчас получилось 'Arab'
clam = text[0]; //Устанавливает однострочной переменной значение 'A'
text[1] = clam; //Меняет 'r' на 'A', сейчас получилось 'AAab'
</pawn>

То, что вы не можете сделать, это соотнести символы массивов со строками. Внутреннее хранение отличается. Например:
<pawn>
new clams[] = "Clams"; //Не верно, нужен тип String:
new clams[] = {'C', 'l', 'a', 'm', 's', 0}; //Верно, но это НЕ СТРОКА.
</pawn>

=Функции=
Функции, как отмечалось ранее, имеют отдельные составляющие кода, которые выполняют определенные действия. Функции могут быть задействованы или '''вызвоны''' с '''параметрами''', которые дают особые настройки.

Существуют два типа вызова функции:
*'''прямой вызов''' - Вы специально вызываете функцию в своем коде.
*'''обратный вызов''' - Применение вызова функций в Вашем коде, как если бы это было событием триггера (совокупность условий, инициирующих выполнение действия).

Существуют пять видов функций:
*'''native''': Прямая, внутренняя функция, предусмотренная в приложении.
*'''public''': Функция обратного вызова, что делает её видимой для приложения и других сценариев.
*'''normal''': Нормальная функция, которую Вы можете только вызвать.
*'''stock''': Нормальная функция, предусмотренная если включает в себя файл. Если не используется, то не компилируется.
*'''forward''': Эта функция представляет собой глобальное событие, предусмотренная приложением. Если Вы её привели в исполнение, она будет вызвона.

Весь код в Pawn должен существовать в функциях. Это основное отличие от языков, таких как PHP, Perl и Python, которые позволяют Вам писать глобальный код. Это происходит потому, что Pawn вызывается на основе другого языка: он реагирует на действия от родительского приложения, и функции должны быть написаны для обработки этих действий. Хотя наш пример, часто содержат свободно плавающий код, это сделано исключительно для демонстрационных целей. Свободно плавающий код в нашем примере означает, что код является частью ряда функций.

==Описание==
В отличие от переменных, функции, не нужно объявлять, прежде чем использовать их. Функции имеют две части, '''модель''' и '''тело'''. Модель содержит имя Вашей функции и параметры, которые она будет принимать. Тело является контейнером для кода.

Пример функции:
<pawn>
AddTwoNumbers(first, second)
{
new sum = first + second;

return sum;
}</pawn>

Это простая функция. Модель этой строки:
<pawn>AddTwoNumbers(first, second)</pawn>

Распишем по отдельности:
*<tt>AddTwoNumbers</tt> - Название функции.
*<tt>first</tt> - Название первого параметра, который представляет собой простой элемент.
*<tt>second</tt> - Название второго параметра, который представляет собой простой элемент.

Тело представляет собой простой блок кода. Он создает новую переменную, названную <tt>sum</tt>, и присваивает ей значение этих двух параметров, добавленных совместно (другие выражения будут позже). Важно заметить оператор <tt>return</tt>, в котором обозначается конец функции и возврат с полученными значениями из этой функции. Все функции ''возвращают значения'' после завершения. Это означает, например:

<pawn>new sum = AddTwoNumbers(4, 5);</pawn>

Приведенный выше код будет присваивать число 9 к sum. Функция получает два значения и передает новое значение sum в качестве '''возвращаемого значения'''. Если функция не имеет возвращаемого значения или не имеет значений для возврата, то возвращается 0 по умолчанию.

Функция может принимать любые типы значений. Она может вернуть любую однострочную переменную, но не массивы или строки. Пример:
<pawn>Float:AddTwoFloats(Float:a, Float:b)
{
new Float:sum = a + b;

return sum;
}</pawn>

''Заметим, что если в приведенной выше функции, Вам вернулась не Float значение, Вы получите не соответствие значений.''

Можно, конечно, передавать переменные в функции:
<pawn>new numbers[3] = {1, 2, 0};

numbers[2] = AddTwoNumbers(numbers[0], numbers[1]);</pawn>

Заметим, что однострочные переменные передаются '''по значению'''. То есть, их значение не может быть изменено функцией. Например:
<pawn>new a = 5;

ChangeValue(a);

ChangeValue(b)
{
b = 5;
}</pawn>

Этот код не будет менять значение <tt>a</tt>. Это происходит потому, что копия этого значения в <tt>a</tt> передается вместо <tt>a</tt> самостоятельно.

Больше примеров функций будут демонстрироваться и в других частях статьи.

==Publics==
Публичные функции используются для осуществления обратных вызовов. Вы не должны создавать какую-либо публичную функцию, если это вынудит выполнение обратного вызова. Например, вот два обратных вызова из <tt>sourcemod.inc</tt>:

<pawn>forward OnPluginStart();
forward OnClientDisconnected(client);</pawn>

Чтобы выполнить и получить эти два события, Вы должны написать такие функции как:

<pawn>public OnPluginStart()
{
/* Код здесь */
}

public OnClientDisconnected(client)
{
/* Код здесь */
}</pawn>

Ключевое слово '''public''' делает функцию публичной, а также позволяет родительскому приложению непосредственно вызывать функцию.

==Natives==
Natives имеют встроенные функции, предоставляемые приложением. Вы можете вызвать их, как если бы они были normal функциями. Например, SourceMod имеет следующие функции:

<pawn>native FloatRound(Float:num);</pawn>

Её можно вызвать таким образом:
<pawn>new num = FloatRound(5.2); //Результат в num = 5</pawn>

==Параметры массива==
Вы можете передавать массивы или строки в качестве параметров. Важно отметить, что они идут '''как ссылка'''. То есть не делать копию данных, а отдавать непосредственно ссылки на данные. Существует простой способ объяснить это более конкретно.

<pawn>
new example[] = {1, 2, 3, 4, 5};

ChangeArray(example, 2, 29);

ChangeArray(array[], index, value)
{
array[index] = value;
}</pawn>

Эта функция устанавливает заданный индекс в массиве с учетом значений. Когда она запускается на примере нашего массива, она меняет индекс 2 для значения 3 на 29. То есть:
<pawn>example[2] = 29;</pawn>

Это возможно лишь потому, что массив может быть непосредственно изменён. Чтобы предотвратить массив от изменения, можно пометить его как постоянную <tt>const</tt>. Это позволит понизить риск на ошибку в коде от её изменения. Например:

<pawn>CantChangeArray(const array[], index, value)
{
array[index] = value; //Не компилируется
}</pawn>

Это хорошая идея использовать <tt>const</tt> в параметрах массивов и Вы будете точно знать, что массив не будет изменен; это может предотвратить ошибки кодирования.

=Выражения=
Выражения являются точно такими же, какими они существуют в математике. Это группы операторов/символов, которые приходятся на один фрагмент данных. Они часто заключены в скобках (внутри скобок). Они содержат строгий "порядок операций". Они могут содержать переменные, функции, цифры и выражения сами могут быть вложенные внутрь других выражений, и даже приняты в качестве параметров.

Приведем пример простейшего выражения:
<pawn>
0; //Возвращает число 0
(0); //Так же возвращает число 0
</pawn>

Хотя выражения могут возвращать значения, они также могут ответить какое значение содержит ответ ''ноль или не ноль''. В этом смысле, ''ноль'' является ''ложью'' (false), а ''не нулевое'' значение ''истиной'' (true). Например, -1 ''истина'' в Pawn, поскольку она не является нулем. Не думайте, что отрицательные числа являются ложными.

Порядок операций выражения аналогичен языку C. PMDAS: Parenthesis, Multiplication, Division, Addition, Subtraction. Вот несколько примеров выражений:
<pawn>
5 + 6; //Вычисляет как 11
5 * 6 + 3; //Вычисляет как 33
5 * (6 + 3); //Вычисляет как 45
5.0 + 2.3; //Вычисляет как 7.3
(5 * 6) % 7; //Modulo operator, вычисляет как 2
(5 + 3) / 2 * 4 - 9; //Вычисляет как 7
</pawn>

Как уже отмечалось, выражения могут содержать переменные, или даже функции:
<pawn>
new a = 5 * 6;
new b = a * 3; //Вычисляет как 90
new c = AddTwoNumbers(a, b) + (a * b);
</pawn>

==Операторы==
Есть несколько полезных дополнительных операторов в Pawn. Первый набор упрощает аутоагрегацию выражения. Например:
<pawn>new a = 5;

a = a + 5;</pawn>

Может быть переписан, как:
<pawn>new a = 5;
a += 5;</pawn>

Это верно в отношении следующих операторов в Pawn:
*Four-function: *, /, -, +
*Bit-wise: |, &, ^, ~, <<, >>

Кроме того, существуют инкремент/декремент операторы:
<pawn>a = a + 1;
a = a - 1;</pawn>

Может быть упрощено, как:
<pawn>a++;
a--;</pawn>

Дополнительно отметим, что ++ или -- может быть представлен до переменной (до-инкремент, до-декремент) или после переменной (пост-инкремент, пост-декремент). Разница заключается в том, как остальная часть выражения содержащие их, видит результат.

* ''До:'' Переменная увеличивается до определения и остальная часть выражения видит новое значение.
* ''Пост:'' Переменная увеличивается после определения и остальная часть выражения видит старое значение.

Иными словами, <tt>a++</tt> определяет значение как <tt>a</tt> в то время как <tt>++a</tt> определяет значение как <tt>a + 1</tt>. В обоих случаях <tt>a</tt> увеличивается на <tt>1</tt>.

Например:

<pawn>new a = 5;
new b = a++; // b = 5, a = 6 (1)
new c = ++a; // a = 7, c = 7 (2)
</pawn>

(1) <tt>b</tt> присваивается <tt>a</tt> со ''старым'' значением, ''до'' того, как он будет увеличено до <tt>6</tt>. (2) <tt>c</tt> присваивается <tt>a</tt> с ''новым'' значением, ''после'' того, как он увеличивается до <tt>7</tt>.

==Операторы сравнения==
Существуют шесть операторов для сравнения двух числовых значений, а результат является либо истиной (не ноль) или ложью (ноль):
*<tt>a == b</tt> - Действительно, если и b имеет то же значение.
*<tt>a != b</tt> - Действительно, если b имеет другое значение.
*<tt>a > b</tt> - Действительно, если оно больше b
*<tt>a >= b</tt> - Действительно, если оно больше или равно b
*<tt>a < b</tt> - Действительно, если оно меньше b
*<tt>a <= b</tt> - Действительно, если оно меньше или равно b

Например:
<pawn>
(1 != 3); //Определяется как истина, поскольку 1 не равно 3.
(3 + 3 == 6); //Определяется как истина, поскольку 3+3 равно 6.
(5 - 2 >= 4); //Определяется как ложь, поскольку 3 меньше 4.
</pawn>

Заметим, что эти операторы не работают с массивами и строками. То есть, вы не можете сравнить их с помощью <tt>==</tt>.

==Действительные операторы==
Действительные операторы могут быть скомбинированы тремя булевыми (boolean) операторами:
*<tt>a && b</tt> - Истина, если a и b истинные. Ложь, если a и (или) b ложные.
{| border="1" cellpadding="2" cellspacing="0" align="center"
! <tt>&&</tt> !! 0 !! 1
|-
! 0
| 0 || 0
|-
! 1
| 0 || 1
|}
*<tt>a || b</tt> - Истина, если a или b (или обе переменные) истинные. Ложь, если обе переменные a и b ложные.
{| border="1" cellpadding="2" cellspacing="0" align="center"
! <tt><nowiki>||</nowiki></tt> !! 0 !! 1
|-
! 0
| 0 || 1
|-
! 1
| 1 || 1
|}
*<tt>!a</tt> - Истина, если a ложь. Ложь, если a истина.
{| border="1" cellpadding="2" cellspacing="0" align="center"
! <tt>!</tt> !! 0 !! 1
|-
!
| 1 || 0
|}

Например:
<pawn>
(1 || 0); //Определяется как истина, так как выражение 1 истинное
(1 && 0); //Определяется как ложь, так как выражение 0 ложное
(!1 || 0); //Определяется как ложь, так как выражение !1 ложное.
</pawn>

==Левое/правое значения==
Два важных понятия левого и правого значений, или левостороннее и правостороннее значения. Левостороннее значение имеет то, что появляется на левой стороне выражения, а правостороннее значение - появляется на правой стороне выражения.

Например:
<pawn>
new a = 5;</pawn>

В этом примере <tt>a</tt> является левосторонним значением и <tt>5</tt> является правосторонним значением.

Правила:
*'''Выражения никогда не будут левосторонними значениями'''.
*'''Переменные являются двумя, левосторонними и правосторонними значениями'''.

=Условия=
Условия позволяют Вам запускать код, определенное условие выполнено.

==Если соответствует==
Если соответствует одно или более условий. Например:

<pawn>
if (a == 5)
{
/* Код будет запущен, если условие будет истинным */
}</pawn>

Они могут быть расширены для более сложных случаев:
<pawn>
if (a == 5)
{
/* Код */
}
else if (a == 6)
{
/* Код */
}
else if (a == 7)
{
/* Код */
}</pawn>

Вы так же можете обрабатывать случаи, даже если выражение не верно. Например:
<pawn>
if (a == 5)
{
/* Код */
}
else
{
/* Код, который будет запущен если нет истинного выражения */
}</pawn>

==Оператор выбора==
Оператор выбора будет ограничен условием. Он необходим для выражения, выполняющего код для целого ряда возможных значений. Например:

<pawn>
switch (a)
{
case 5:
{
/* Код */
}
case 6:
{
/* Код */
}
case 7:
{
/* Код */
}
case 8, 9, 10:
{
/* Код */
}
default:
{
/* будет запущен, если не одно условие не соответствует */
}
}</pawn>

В отличие от некоторых других языков, оператор выбора не проваливается. То есть существуют случаи, когда код не будет запущен. При случае совпадения его код выполняется, а ключ является местом для немедленного прекращения.

=Циклы=
Циклы позволяют Вам без труда повторять выполнение кода, пока условие станет истинным.

==For циклы==
For циклы, это циклы, которые состоят из четырех частей:
*Оператор '''инициализации''' - запускается один раз перед первым циклом.
*Оператор '''условия''' - проверяет условие и запускает следующий цикл, в том числе первый. Цикл прекращается, когда это выражение становится ложным.
*Оператор '''итерации''' - запускается после каждого цикла.
* '''тело''' цикла - запускается каждый раз, пока оператор '''условия''' вычисляется как истинный.

<pawn>
for ( /* инициализация */ ; /* условие */ ; /* итерация */ )
{
/* тело */
}
</pawn>

Простым примером является функция сложения массива:
<pawn>
new array[10] = {1, 2, 3, 4, 5, 6, 7, 8, 9, 10};
new sum = SumArray(array, 10);

SumArray(const array[], count)
{
new total;

for (new i = 0; i < count; i++)
{
total += array[i];
}

return total;
}</pawn>

По отдельности:
*<tt>new i = 0</tt> - Создает новую переменную для цикла, и устанавливает её в 0.
*<tt>i < count</tt> - Только запускает цикл, если <tt>i</tt> меньше, чем <tt>count</tt>. Это гарантирует, что чтение цикла прекращается в определенный момент. В этом случае, мы не хотим читать недействительные индексы в массиве.
*<tt>i++</tt> - Увеличивает <tt>i</tt> на единицу после каждого цикла. Это гарантирует, что цикл не будет запущен вечно; в конце концов <tt>i</tt> станет слишком большим, и цикл завершится.

Таким образом, функция <tt>SumArray</tt> будет циклом каждого действительного индекса массива, каждый раз добавляя это значение в sum. Для циклов очень распространены массивы такие, как в нашем примере.

==While циклы==
While циклы являются менее распространенными, чем for циклы, но на самом деле это более простые циклы. Они имеют только две части:
*Оператор '''условия''' - проверяется перед началом каждого цикла. Цикл прекращается, когда условие становится ложным.
*'''тело''' цикла - запускается каждый раз пока цикл выполняется.

<pawn>
while ( /* условие */ )
{
/* тело */
}
</pawn>

До тех пор, пока условие выражения остается истинным, цикл будет выполняться. Каждый for цикл может быть переписан, как while цикл:

<pawn>
/* инициализация */
while ( /* условие */ )
{
/* тело */
/* итерация */
}
</pawn>

Вот предыдущий for цикл переписан как while цикл:
<pawn>
SumArray(const array[], count)
{
new total, i;

while (i < count)
{
total += array[i];
i++;
}

return total;
}</pawn>

Существуют также '''do...while''' циклы, которые используются еще реже. Они работают как и while циклы, но проверяют условие ПОСЛЕ каждого цикла, а не перед ним. Это означает, что цикл всегда будет запущен, по крайней мере один раз. Например:

<pawn>
do
{
/* тело */
}
while ( /* условие */ );
</pawn>

==Управление циклами==
Существуют два случая, в которых Мы хотели бы контролировать цикл:
*'''пропустить''' одну итерацию или цикл и продолжить выполнение цикла как обычно, или;
*'''разорвать''' цикл целиком, прежде чем он закончится.

Допустим у вас есть функция, которая принимает массив и ищет соответствия цифр. Вы хотите его остановить, когда число будет найдено:
<pawn>
/**
* Возвращает массив, если индекс значения, или -1, не найдены.
*/
SearchInArray(const array[], count, value)
{
new index = -1;

for (new i = 0; i < count; i++)
{
if (array[i] == value)
{
index = i;
break;
}
}

return index;
}</pawn>

Конечно, эту функцию можно вернуть и способом <tt>return i</tt>, но пример показывает, как <tt>break</tt> может остановить цикл.

Кроме того, ключевое слово <tt>continue</tt> пропускает итерации цикла. Например, Мы хотим суммировать все четные числа:

<pawn>
SumEvenNumbers(const array[], count)
{
new sum;

for (new i = 0; i < count; i++)
{
/* If divisibility by 2 is 1, we know it's odd */
if (array[i] % 2 == 1)
{
/* Пропускаем оставшуюся часть итерации цикла */
continue;
}
sum += array[i];
}

return sum;
}</pawn>

=Область действия=
Область действия относится к '''удобочитаемости''' кода. Это означает, что код одного уровня не может быть "виден" в коде другого уровня. Пример:

<pawn>
new A, B, C;

Function1()
{
new B;

Function2();
}

Function2()
{
new C;
}</pawn>

В этом примере, <tt>A</tt>, <tt>B</tt>, и <tt>C</tt> имеют '''глобальную область действия'''. Их можно увидеть в любой функции. Вместе с тем, <tt>B</tt> в функции <tt>Function1</tt> не является той же переменной, как <tt>B</tt> на глобальном уровне. Вместо этого она находится в '''локальной области действия''', и поэтому является '''локально изменяемой'''.

Кроме того, функции <tt>Function1</tt> и <tt>Function2</tt> ничего не знают о существовании других переменных.

Она так же является не только локальной переменной функции <tt>Function1</tt>, но и создается заново каждый раз, когда функция вызывается. Попробуйте представить это:
<pawn>
Function1()
{
new B;

Function1();
}</pawn>

В приведенном выше примере, функция <tt>Function1</tt> вызывает сама себя. Конечно, это бесконечной рекурсии (а это очень плохо), но идея заключается в том, что каждый раз, когда функция срабатывает, то создается новая копия <tt>B</tt>. Когда функция завершается, <tt>B</tt> уничтожается, и её значение теряется.

Это свойство можно объяснить проще тем, что область действия переменной равна уровню её вложенности. То есть, переменная на глобальной области действия видна для всех функций. Переменная в локальной области действия видна всему блоку кода расположенному "ниже" этого уровня. Например:

<pawn>Function1()
{
new A;

if (A)
{
A = 5;
}
}</pawn>

Приведенный выше код является действительным, поскольку в область действия распространяется по всей функции. Однако этот код, работать не будет:
<pawn>
Function1()
{
new A;

if (A)
{
new B = 5;
}

B = 5;
}</pawn>

Отметим, что <tt>B</tt> объявляется в новом блоке кода. Это означает, что <tt>B</tt> доступна только в том блоке кода, в котором была создана (и всем под-блокам вложенных внутри него). Как только блок кода прекращается, <tt>B</tt> становится не действительной.

=Динамические массивы=
Динамические массивы это массивы, которые не имеют фиксированного размера. Например:

<pawn>Function1(size)
{
new array[size];

/* Код */
}</pawn>

Динамические массивы могут иметь любое выражение, соответствующее их размеру до тех пор, пока выражение вычисляется, как число большее чем 0. Как и для обычных массивов, SourcePawn не сможет узнать размер массива после того, как он будет создан; Вы должны задать его, если хотите использовать массив позднее.

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

=Расширенное объявление переменных=
Переменные могут быть объявлены более длинным путем чем просто <tt>new</tt>.

==decl==
===Назначение===
По умолчанию, все переменные в Pawn будут инициализированы как нуль. Если есть явная инициализация, переменная инициализируется для выражения <tt>=</tt> определенным символам. В локальной области действия, это может потребовать время на выполнение. Ключевое слово <tt>decl</tt> (которое действительно только в локальной области действия) было введено, чтобы позволить решать пользователю, хочит ли он инициализировать переменную или нет.

Примечание: <tt>decl</tt> не должно быть использовано на одну однострочную переменную. Это почти никогда не будет выгодно.

===Объяснение===
Например:

<pawn>
new c = 5;
new d;
new String:blah[512];

Format(blah, sizeof(blah), "%d %d", c, d);
</pawn>

В этом коде, <tt>c</tt> равна 5 и <tt>d</tt> равна 0. Во время выполнения этого кода затраты на инициализацию незначительные. Вместе с тем, <tt>blah</tt> является большим массивом, и затраты на инициализацию всего массива могут быть больше 0 сек. и иметь плохие последствия в определенных ситуациях.

Заметим, что <tt>blah</tt> не должен быть нулевой. В период времени с объявления <tt>new</tt> и и перемещения в <tt>Format()</tt>, массив <tt>blah</tt> никогда не будет загружен или прочитан. Данный код будет более эффективен, если будет написанный следующим образом:

<pawn>
new c = 5;
new d;
decl String:blah[512];

Format(blah, sizeof(blah), "%d %d", c, d);
</pawn>

===Предостережения===
Обратная сторона <tt>decl</tt> состоит в том, что его переменные будут начинаться с "ненужного" содержания. Например, если мы будем использовать:

<pawn>
new c = 5;
new d;
decl String:blah[512];

PrintToServer("%s", blah);

Format(blah, sizeof(blah), "%d %d", c, d);
</pawn>

Этот код может привести к падению сервера, так как массив <tt>blah</tt> может быть полностью испорчен (строки требуют нулевой символ, который может отсутствовать). Точно так же, если мы сделаем:

<pawn>
new c = 5;
decl d;
decl String:blah[512];

Format(blah, sizeof(blah), "%d %d", c, d);
</pawn>

Значение <tt>d</tt> в настоящее время не определенно. Оно может быть любым значением, отрицательным или положительным.

Заметим, что это легко и эффективно обезопасит строки. Пример ниже показывает, как предотвратить строки от мусора:
<pawn>
decl String:blah[512];

blah[0] = '\0';
</pawn>

===Золотые правила===
*'''Используйте decl только, если в период объявления и загрузки/чтения значения, Вы абсолютно уверены, что есть по крайней мере одно хранилище/операция, которая отдает переменной действительные данные.'''
*'''Не оптимизируйте преждевременно.''' Кроме того, нет необходимости использовать <tt>decl</tt> на не-массивы, поскольку нет никаких дополнительных затрат на инициализацию однго однострочного значения.

===Примечания===
Этот пример НЕ является столь эффективным, как <tt>decl</tt>:
<pawn>
new String:blah[512] = "a";
</pawn>

Даже несмотря на то, что строка имеет только один символ, оператор <tt>new</tt> гарантирует, что остальная часть массива будет нулевой.

Также обратите внимание, он является неправильным для явной инициализации <tt>decl</tt>:
<pawn>decl String:blah[512] = "a";</pawn>

Приведенный выше код не будет компилироваться, потому что цель <tt>decl</tt> состоит в том, чтобы избежать каких-либо инициализаций.

==static==
Ключевое слово <tt>static</tt> входит в глобальную и локальную область действия. Оно имеет различные значения в каждой из них.

===Global static===
Глобальные static переменные могут быть доступны только в рамках того же файла. Например:

<pawn>//file1.inc
static Float:g_value1 = 0.15f;

//file2.inc
static Float:g_value2 = 0.15f;</pawn>

Если плагин включает в себя оба этих файла, он не сможет использовать <tt>g_value1</tt> или <tt>g_value2</tt>. Это простой механизм сокрытия информации, и аналогичен элементам объявления переменных, например <tt>private</tt> в таких языках, как C++, Java, или C#.

===Local static===
A local static variable is a global variable that is only visible from its local lexical scope. For example:

<pawn>
MyFunction(inc)
{
static counter = -1;

counter += inc;

return counter;
}</pawn>

In this example, <tt>counter</tt> is technically a global variable -- it is initialized once to -1 and is never initialized again. It does not exist on the stack. That means each time <tt>MyFunction</tt> runs, the <tt>counter</tt> variable and its storage in memory is the same.

Take this example:
<pawn>MyFunction(5);
MyFunction(6);
MyFunction(10);</pawn>

In this example, <tt>counter</tt> will be <tt>-1 + 5 + 6 + 10</tt>, or <tt>20</tt>, because it persists beyond the frame of the function. Note this may pose problems for recursive functions: if your function may be recursive, then <tt>static</tt> is usually not a good idea unless your code is re-entrant.

The benefit of a local static variable is that you don't have to clutter your script with global variables. As long as the variable doesn't need to be read by another function, you can squirrel it inside the function and its persistence will be guaranteed.

Note that statics can exist in any local scope:

<pawn>
MyFunction(inc)
{
if (inc > 0)
{
static counter;
return (counter += inc);
}
return -1;
}</pawn>

[[Category:Ru:SourceMod Scripting]]

Ru:Introduction to SourcePawn

2008-12-26T12:21:13Z

Frenzzy: /* static */

Это руководство призвано дать Вам самые основные представления по основам написания сприптов в SourcePawn. [[Pawn]] это "скриптовый" язык используемый для внедрения функциональности в других программах. Это означает, что это не самостоятельный язык, как C++ или Java, и его элементы будут отличаться в различных приложениях. SourcePawn это вариация языка Pawn используемая в [[SourceMod]].

Это руководство не расскажет Вам как писать SourceMod плагины; оно предназначено для получения общих представлений о синтаксисе и семантике этого языка. Читайте отдельную статью [[Ru:Introduction to SourceMod Plugins]] (Введение в SourceMod плагины), для введения в SourceMod API.

=Введение для новичков=
Этот раздел создан не для программистов. Если Вы по прежнему в замешательстве, Вы можете прочитать книги о других языках программирования, таких как PHP, Python, или Java, чтобы получить более полное представление о программировании.

==Идентификаторы/Ключевые слова==
Идентификаторы представляет собой набор букв, цифр и/или нижнего подчеркивания, что представляет собой нечто уникальное. Идентификаторы вводятся с учетом регистра (в отличие от PHP, где иногда это не требуется). Идентификаторы не начинаются с какого-либо специального символа, но они должны начинаться с буквы.

Есть несколько зарезервированных символов, которые имеют особое значение. Например, <tt>if</tt>, <tt>for</tt>, и <tt>return</tt> специальные конструкции в языке, которые будут описаны позднее. Они не могут быть использованы в качестве названий идентификаторов.

==Переменные==
Существует несколько важных конструкций, которые Вы должны знать, прежде чем приступить к написанию сценария. Во-первых, это '''переменные'''. Переменная это идентификатор, который содержит данные. Например, переменная "a" может содержать числа "2", "16", "0", и так далее. Переменные создаются для хранения данных внутри программы. Переменные должны быть объявлены до их использования, с помощью ключевого слова "new". Данные можно присвоить переменной, используя знак равенства (=). Пример:

<pawn>new a, b, c, d;

a = 5;
b = 16;
c = 0;
d = 500;</pawn>

В SourcePawn, переменные бывают двух типов, которые будут более подробно описаны далее.
*Однострочные (могут содержать только произвольные числовые данные), как показано выше.
*Многострочные (могут содержать целый ряд текстовых символов)

==Функции==
Следующим важным понятием являются '''функции'''. Функции идентификаторов или имен, которые выполняют действия. Это означает, что когда вы их активируете, они выполняют конкретную последовательность кода. Есть несколько типов функций, но все функции активируется одинаковым образом. "Вызов функции" является термином ссылающимся на функцию действия. Функция числовых переменных строятся так:
<pawn>функция(<параметры>)</pawn>

Примеры:

<pawn>show(56); //Активирует функцию "show" и присваивает ей число 56
show(); //Активирует функцию "show" без каких-либо данных, пустую
show(a); //Активирует функцию "show" и присваивает ей переменную с данными
</pawn>

Каждый фрагмент данных передаваемый вызываемой функции, называется '''параметр'''. Функция может иметь любое количество параметров (но есть "допустимый" предел в SourceMod: 32). Параметры будут описаны далее в этой статье.

==Комментарии==
Примечания и любой текст, который пишется после "//" считается "Комментарием", а не фактическим кодом. Есть два стиля комментариев:
*<tt>//</tt> - Двойная косая черта, всё следующие после этой строки игнорируется.
*<tt>/* */</tt> - Много-строчный комментарий, весь текст, внутри звездочек игнорируются. You cannot nest these.

==Массивы==
Описание массивов. Вы можете группировать код в виде "массивов", разделенных { и }. Это фактически создает возможность работать с целым массивом как с одним оператором. Например:

<pawn>{
here;
is;
some;
code;
}</pawn>

Массивы с фигурными скобками используются достаточно широко в программировании. Массивы кода могут быть вложенными друг в друга. Это хорошая возможность адаптировать последовательность когда и сделать его удобочитаемым, благодаря отступам код не будет смотреться как одна большая и длинная макаронина.

=Особенности языка=
Pawn может показаться очень похожим на другие языки программирования, например C, но Pawn от них фундаментально отличается. Не столь важно, чтобы Вы сейчас же поняли его отличия, но они понадобятся, если Вы уже знаете один из языков программирования.
*'''Pawn не печатает''' Pawn имеет только один тип данных - '''однострочный'''. Подробнее будет описано позже. [В дальнейшем автор рассказывает, что существует два типа данных: однострочный и многострочный]
*'''Pawn не собирает мусор''' Pawn, как язык, не имеет встроенных ресурсов памяти, и потому он не мусорит. Если функция выделит память, то Вы отвечаете за её освобождение.
*'''Pawn не объектно-ориентированный язык''' Pawn является процедурным, и полагается на подпрограммы. Также у него нету C подобных структур.
*'''Pawn не функциональный.''' Pawn является процедурным, и не поддерживает функции "лямбды" (Lambda), поздние присвоения, и все то, что можно найти в языках высшего уровня, таких как Phyton и Ruby.
*'''Pawn однопоточный''' As of this writing, Pawn is not thread safe.
*'''Pawn не интерпретируемый''' Ну, почти. Он интерпретируется на очень низком уровне. Вы должны скомпилировать код, из которого получится бинарный файл. Эта программа будет работать на той платформе, которую использует хост. Это ускоряет загрузку и позволяет легче находить ошибки.

Этот язык был выпущен ITB CompuPhase. Язык разработан для устройств низкого уровня и таким образом конечные программы очень маленькие по размеру и очень быстрые.

=Переменные=
В Pawn есть всего два типа переменных: '''однострочные''' и '''многострочные'''. Однострочные могут содержать 32 бита цифровых данных. Многострочные - последовательный список из UTF-8 символов.

'''однострочные''' не имеет своего типа, однако они могут быть '''маркированы'''(tagged). Тег позволяет Вам указывать, где определенную ячейку можно использовать. Типичные теги:
*(пусто), или '''_''' - Нет тега. Обычно используют для целых чисел ([http://en.wikipedia.org/wiki/Integer Integers]).
*'''Float''' - используют для чисел с плавающей точкой (небольших).
*'''bool''' - используют для хранения значений '''true''' (истина) или '''false''' (ложь).

Со строками все по другому, они будут рассмотрены далее.

==Объявления==
Примеры разных правильных объявлений переменных.
<pawn>
new a = 5;
new Float:b = 5.0;
new bool:c = true;
new bool:d = 0; //Работает, поскольку 0 равно false (ложь)
</pawn>

Неправильные объявления переменных
<pawn>
new a = 5.0; //Несоответствие тегов. 5.0 с тегом Float
new Float:b = 5; //Несоответствие тегов. 5 без тега.
</pawn>

Если переменная не определена в объявлении то ее значения станет 0
<pawn>
new a; //значение 0
new Float:b; //значение 0.0
new bool:c; //значение false
</pawn>

==Присвоение==
Переменным могут быть присвоены данные после создания. Пример:
<pawn>new a, Float:b, bool:c;

a = 5;
b = 5.0;
c = true;
</pawn>

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

==Описание==
Массив объявляется с помощью квадратных скобок. Вот некоторые примеры массивов:
<pawn>
new players[32]; //Набор из 32 однострочных (числовых) данных
new Float:origin[3]; //Набор из 3 чисел с плавающей точкой
</pawn>

По умолчанию, массивам присваиваются нули. Вы можете присвоить им разные значения по умолчанию, однако:
<pawn>
new numbers[5] = {1, 2, 3, 4, 5}; //Набор 1, 2, 3, 4, 5 из однострочных данных.
new Float:origin[3] = {1.0, 2.0, 3.0}; //Набор 1.0, 2.0, 3.0 из однострочных данных.
</pawn>

Вы можете оставить массив без размера, если вы собираетесь заранее присвоить ему данные. Например:
<pawn>
new numbers[] = {1, 3, 5, 7, 9};
</pawn>

Компилятор будет автоматически делать вывод о том, что Вы хотите получить массив размером 5.

==Использование==
Использование массива равносильно использованию обычных переменной. Единственное отличие массива состоит в том, что он должен быть '''индексируемым'''. Индексирование массива означает присутствие возможности выбрать элемент, который Вы хотите использовать.

Вот пример кода с использованием индексов:
<pawn>
new numbers[5], Float:origin[3];

numbers[0] = 1;
numbers[1] = 2;
numbers[2] = 3;
numbers[3] = 4;
numbers[4] = 5;
origin[0] = 1.0;
origin[1] = 2.0;
origin[2] = 3.0;
</pawn>

Заметим, что '''индекс''' это текст, который находится в квадратных скобках. Индекс всегда начинается с нуля. То есть, если массив имеет N элементов, его действительный индекс от 0 до N-1. Доступ к данным с индексами работает так же, как с обычной переменной.

Использование неверного индекса вызовет ошибку. Например:
<pawn>
new numbers[5];

numbers[5] = 20;</pawn>

Это может выглядеть верно, но число 5 не является допустимым индексом. Наибольшим значением индекса является число 4.

Вы можете использовать любые выражения, как индекс. Например:
<pawn>new a, numbers[5];

a = 1; //Сделает a = 1
numbers[a] = 4; //Сделает numbers[1] = 4
numbers[numbers[a]] = 2; //Сделает numbers[4] = 2
</pawn>

Выражения будут обсуждаться подробнее в конце статьи.

=Строки=
Строки являются удобным способом хранения текста. Символы хранятся в массиве. Строка ограничивается '''нулевым символом''', или 0. Без нулевого символа, Pawn не знает, где остановить чтение строки. Все строки в SourcePawn используют кодировку UTF-8.

Отметим, что строки имеют комбинацию из массивов и однострочных переменных. В отличие от других языков, это означает, что Вы должны знать заранее, как много места будут использовать строки. Это означает, что строки не являются динамичными. Они могут лишь вырасти до размера, которым Вы их ограничили.

''Примечание для специалистов: они фактически не однострочные. SourcePawn использует 8-битный строки для хранения массивов в качестве оптимизации. Это и есть то, что делает строки типом, а не меткой.''

==Использование==
Строки были созданы почти в равной степени и для массивов. Например:
<pawn>
new String:message[] = "Hello!";
new String:clams[6] = "Clams";
</pawn>

Это равносильно следующему:
<pawn>
new String:message[7], String:clams[6];

message[0] = 'H';
message[1] = 'e';
message[2] = 'l';
message[3] = 'l';
message[4] = 'o';
message[5] = '!';
message[6] = 0;
clams[0] = 'C';
clams[1] = 'l';
clams[2] = 'a';
clams[3] = 'm';
clams[4] = 's';
clams[5] = 0;
</pawn>

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

Заметим, что строка должна быть заключена в двойных кавычках, а символ в одиночных.

==Символы==
Особенность текста может быть использована в любой строке или однострочной переменной. Например:
<pawn>new String:text[] = "Crab";
new clam;

clam = 'D'; //Устанавливает однострочной переменной значение 'D'
text[0] = 'A'; //Меняет 'C' на 'A', сейчас получилось 'Arab'
clam = text[0]; //Устанавливает однострочной переменной значение 'A'
text[1] = clam; //Меняет 'r' на 'A', сейчас получилось 'AAab'
</pawn>

То, что вы не можете сделать, это соотнести символы массивов со строками. Внутреннее хранение отличается. Например:
<pawn>
new clams[] = "Clams"; //Не верно, нужен тип String:
new clams[] = {'C', 'l', 'a', 'm', 's', 0}; //Верно, но это НЕ СТРОКА.
</pawn>

=Функции=
Функции, как отмечалось ранее, имеют отдельные составляющие кода, которые выполняют определенные действия. Функции могут быть задействованы или '''вызвоны''' с '''параметрами''', которые дают особые настройки.

Существуют два типа вызова функции:
*'''прямой вызов''' - Вы специально вызываете функцию в своем коде.
*'''обратный вызов''' - Применение вызова функций в Вашем коде, как если бы это было событием триггера (совокупность условий, инициирующих выполнение действия).

Существуют пять видов функций:
*'''native''': Прямая, внутренняя функция, предусмотренная в приложении.
*'''public''': Функция обратного вызова, что делает её видимой для приложения и других сценариев.
*'''normal''': Нормальная функция, которую Вы можете только вызвать.
*'''stock''': Нормальная функция, предусмотренная если включает в себя файл. Если не используется, то не компилируется.
*'''forward''': Эта функция представляет собой глобальное событие, предусмотренная приложением. Если Вы её привели в исполнение, она будет вызвона.

Весь код в Pawn должен существовать в функциях. Это основное отличие от языков, таких как PHP, Perl и Python, которые позволяют Вам писать глобальный код. Это происходит потому, что Pawn вызывается на основе другого языка: он реагирует на действия от родительского приложения, и функции должны быть написаны для обработки этих действий. Хотя наш пример, часто содержат свободно плавающий код, это сделано исключительно для демонстрационных целей. Свободно плавающий код в нашем примере означает, что код является частью ряда функций.

==Описание==
В отличие от переменных, функции, не нужно объявлять, прежде чем использовать их. Функции имеют две части, '''модель''' и '''тело'''. Модель содержит имя Вашей функции и параметры, которые она будет принимать. Тело является контейнером для кода.

Пример функции:
<pawn>
AddTwoNumbers(first, second)
{
new sum = first + second;

return sum;
}</pawn>

Это простая функция. Модель этой строки:
<pawn>AddTwoNumbers(first, second)</pawn>

Распишем по отдельности:
*<tt>AddTwoNumbers</tt> - Название функции.
*<tt>first</tt> - Название первого параметра, который представляет собой простой элемент.
*<tt>second</tt> - Название второго параметра, который представляет собой простой элемент.

Тело представляет собой простой блок кода. Он создает новую переменную, названную <tt>sum</tt>, и присваивает ей значение этих двух параметров, добавленных совместно (другие выражения будут позже). Важно заметить оператор <tt>return</tt>, в котором обозначается конец функции и возврат с полученными значениями из этой функции. Все функции ''возвращают значения'' после завершения. Это означает, например:

<pawn>new sum = AddTwoNumbers(4, 5);</pawn>

Приведенный выше код будет присваивать число 9 к sum. Функция получает два значения и передает новое значение sum в качестве '''возвращаемого значения'''. Если функция не имеет возвращаемого значения или не имеет значений для возврата, то возвращается 0 по умолчанию.

Функция может принимать любые типы значений. Она может вернуть любую однострочную переменную, но не массивы или строки. Пример:
<pawn>Float:AddTwoFloats(Float:a, Float:b)
{
new Float:sum = a + b;

return sum;
}</pawn>

''Заметим, что если в приведенной выше функции, Вам вернулась не Float значение, Вы получите не соответствие значений.''

Можно, конечно, передавать переменные в функции:
<pawn>new numbers[3] = {1, 2, 0};

numbers[2] = AddTwoNumbers(numbers[0], numbers[1]);</pawn>

Заметим, что однострочные переменные передаются '''по значению'''. То есть, их значение не может быть изменено функцией. Например:
<pawn>new a = 5;

ChangeValue(a);

ChangeValue(b)
{
b = 5;
}</pawn>

Этот код не будет менять значение <tt>a</tt>. Это происходит потому, что копия этого значения в <tt>a</tt> передается вместо <tt>a</tt> самостоятельно.

Больше примеров функций будут демонстрироваться и в других частях статьи.

==Publics==
Публичные функции используются для осуществления обратных вызовов. Вы не должны создавать какую-либо публичную функцию, если это вынудит выполнение обратного вызова. Например, вот два обратных вызова из <tt>sourcemod.inc</tt>:

<pawn>forward OnPluginStart();
forward OnClientDisconnected(client);</pawn>

Чтобы выполнить и получить эти два события, Вы должны написать такие функции как:

<pawn>public OnPluginStart()
{
/* Код здесь */
}

public OnClientDisconnected(client)
{
/* Код здесь */
}</pawn>

Ключевое слово '''public''' делает функцию публичной, а также позволяет родительскому приложению непосредственно вызывать функцию.

==Natives==
Natives имеют встроенные функции, предоставляемые приложением. Вы можете вызвать их, как если бы они были normal функциями. Например, SourceMod имеет следующие функции:

<pawn>native FloatRound(Float:num);</pawn>

Её можно вызвать таким образом:
<pawn>new num = FloatRound(5.2); //Результат в num = 5</pawn>

==Параметры массива==
Вы можете передавать массивы или строки в качестве параметров. Важно отметить, что они идут '''как ссылка'''. То есть не делать копию данных, а отдавать непосредственно ссылки на данные. Существует простой способ объяснить это более конкретно.

<pawn>
new example[] = {1, 2, 3, 4, 5};

ChangeArray(example, 2, 29);

ChangeArray(array[], index, value)
{
array[index] = value;
}</pawn>

Эта функция устанавливает заданный индекс в массиве с учетом значений. Когда она запускается на примере нашего массива, она меняет индекс 2 для значения 3 на 29. То есть:
<pawn>example[2] = 29;</pawn>

Это возможно лишь потому, что массив может быть непосредственно изменён. Чтобы предотвратить массив от изменения, можно пометить его как постоянную <tt>const</tt>. Это позволит понизить риск на ошибку в коде от её изменения. Например:

<pawn>CantChangeArray(const array[], index, value)
{
array[index] = value; //Не компилируется
}</pawn>

Это хорошая идея использовать <tt>const</tt> в параметрах массивов и Вы будете точно знать, что массив не будет изменен; это может предотвратить ошибки кодирования.

=Выражения=
Выражения являются точно такими же, какими они существуют в математике. Это группы операторов/символов, которые приходятся на один фрагмент данных. Они часто заключены в скобках (внутри скобок). Они содержат строгий "порядок операций". Они могут содержать переменные, функции, цифры и выражения сами могут быть вложенные внутрь других выражений, и даже приняты в качестве параметров.

Приведем пример простейшего выражения:
<pawn>
0; //Возвращает число 0
(0); //Так же возвращает число 0
</pawn>

Хотя выражения могут возвращать значения, они также могут ответить какое значение содержит ответ ''ноль или не ноль''. В этом смысле, ''ноль'' является ''ложью'' (false), а ''не нулевое'' значение ''истиной'' (true). Например, -1 ''истина'' в Pawn, поскольку она не является нулем. Не думайте, что отрицательные числа являются ложными.

Порядок операций выражения аналогичен языку C. PMDAS: Parenthesis, Multiplication, Division, Addition, Subtraction. Вот несколько примеров выражений:
<pawn>
5 + 6; //Вычисляет как 11
5 * 6 + 3; //Вычисляет как 33
5 * (6 + 3); //Вычисляет как 45
5.0 + 2.3; //Вычисляет как 7.3
(5 * 6) % 7; //Modulo operator, вычисляет как 2
(5 + 3) / 2 * 4 - 9; //Вычисляет как 7
</pawn>

Как уже отмечалось, выражения могут содержать переменные, или даже функции:
<pawn>
new a = 5 * 6;
new b = a * 3; //Вычисляет как 90
new c = AddTwoNumbers(a, b) + (a * b);
</pawn>

==Операторы==
Есть несколько полезных дополнительных операторов в Pawn. Первый набор упрощает аутоагрегацию выражения. Например:
<pawn>new a = 5;

a = a + 5;</pawn>

Может быть переписан, как:
<pawn>new a = 5;
a += 5;</pawn>

Это верно в отношении следующих операторов в Pawn:
*Four-function: *, /, -, +
*Bit-wise: |, &, ^, ~, <<, >>

Кроме того, существуют инкремент/декремент операторы:
<pawn>a = a + 1;
a = a - 1;</pawn>

Может быть упрощено, как:
<pawn>a++;
a--;</pawn>

Дополнительно отметим, что ++ или -- может быть представлен до переменной (до-инкремент, до-декремент) или после переменной (пост-инкремент, пост-декремент). Разница заключается в том, как остальная часть выражения содержащие их, видит результат.

* ''До:'' Переменная увеличивается до определения и остальная часть выражения видит новое значение.
* ''Пост:'' Переменная увеличивается после определения и остальная часть выражения видит старое значение.

Иными словами, <tt>a++</tt> определяет значение как <tt>a</tt> в то время как <tt>++a</tt> определяет значение как <tt>a + 1</tt>. В обоих случаях <tt>a</tt> увеличивается на <tt>1</tt>.

Например:

<pawn>new a = 5;
new b = a++; // b = 5, a = 6 (1)
new c = ++a; // a = 7, c = 7 (2)
</pawn>

(1) <tt>b</tt> присваивается <tt>a</tt> со ''старым'' значением, ''до'' того, как он будет увеличено до <tt>6</tt>. (2) <tt>c</tt> присваивается <tt>a</tt> с ''новым'' значением, ''после'' того, как он увеличивается до <tt>7</tt>.

==Операторы сравнения==
Существуют шесть операторов для сравнения двух числовых значений, а результат является либо истиной (не ноль) или ложью (ноль):
*<tt>a == b</tt> - Действительно, если и b имеет то же значение.
*<tt>a != b</tt> - Действительно, если b имеет другое значение.
*<tt>a > b</tt> - Действительно, если оно больше b
*<tt>a >= b</tt> - Действительно, если оно больше или равно b
*<tt>a < b</tt> - Действительно, если оно меньше b
*<tt>a <= b</tt> - Действительно, если оно меньше или равно b

Например:
<pawn>
(1 != 3); //Определяется как истина, поскольку 1 не равно 3.
(3 + 3 == 6); //Определяется как истина, поскольку 3+3 равно 6.
(5 - 2 >= 4); //Определяется как ложь, поскольку 3 меньше 4.
</pawn>

Заметим, что эти операторы не работают с массивами и строками. То есть, вы не можете сравнить их с помощью <tt>==</tt>.

==Действительные операторы==
Действительные операторы могут быть скомбинированы тремя булевыми (boolean) операторами:
*<tt>a && b</tt> - Истина, если a и b истинные. Ложь, если a и (или) b ложные.
{| border="1" cellpadding="2" cellspacing="0" align="center"
! <tt>&&</tt> !! 0 !! 1
|-
! 0
| 0 || 0
|-
! 1
| 0 || 1
|}
*<tt>a || b</tt> - Истина, если a или b (или обе переменные) истинные. Ложь, если обе переменные a и b ложные.
{| border="1" cellpadding="2" cellspacing="0" align="center"
! <tt><nowiki>||</nowiki></tt> !! 0 !! 1
|-
! 0
| 0 || 1
|-
! 1
| 1 || 1
|}
*<tt>!a</tt> - Истина, если a ложь. Ложь, если a истина.
{| border="1" cellpadding="2" cellspacing="0" align="center"
! <tt>!</tt> !! 0 !! 1
|-
!
| 1 || 0
|}

Например:
<pawn>
(1 || 0); //Определяется как истина, так как выражение 1 истинное
(1 && 0); //Определяется как ложь, так как выражение 0 ложное
(!1 || 0); //Определяется как ложь, так как выражение !1 ложное.
</pawn>

==Левое/правое значения==
Два важных понятия левого и правого значений, или левостороннее и правостороннее значения. Левостороннее значение имеет то, что появляется на левой стороне выражения, а правостороннее значение - появляется на правой стороне выражения.

Например:
<pawn>
new a = 5;</pawn>

В этом примере <tt>a</tt> является левосторонним значением и <tt>5</tt> является правосторонним значением.

Правила:
*'''Выражения никогда не будут левосторонними значениями'''.
*'''Переменные являются двумя, левосторонними и правосторонними значениями'''.

=Условия=
Условия позволяют Вам запускать код, определенное условие выполнено.

==Если соответствует==
Если соответствует одно или более условий. Например:

<pawn>
if (a == 5)
{
/* Код будет запущен, если условие будет истинным */
}</pawn>

Они могут быть расширены для более сложных случаев:
<pawn>
if (a == 5)
{
/* Код */
}
else if (a == 6)
{
/* Код */
}
else if (a == 7)
{
/* Код */
}</pawn>

Вы так же можете обрабатывать случаи, даже если выражение не верно. Например:
<pawn>
if (a == 5)
{
/* Код */
}
else
{
/* Код, который будет запущен если нет истинного выражения */
}</pawn>

==Оператор выбора==
Оператор выбора будет ограничен условием. Он необходим для выражения, выполняющего код для целого ряда возможных значений. Например:

<pawn>
switch (a)
{
case 5:
{
/* Код */
}
case 6:
{
/* Код */
}
case 7:
{
/* Код */
}
case 8, 9, 10:
{
/* Код */
}
default:
{
/* будет запущен, если не одно условие не соответствует */
}
}</pawn>

В отличие от некоторых других языков, оператор выбора не проваливается. То есть существуют случаи, когда код не будет запущен. При случае совпадения его код выполняется, а ключ является местом для немедленного прекращения.

=Циклы=
Циклы позволяют Вам без труда повторять выполнение кода, пока условие станет истинным.

==For циклы==
For циклы, это циклы, которые состоят из четырех частей:
*Оператор '''инициализации''' - запускается один раз перед первым циклом.
*Оператор '''условия''' - проверяет условие и запускает следующий цикл, в том числе первый. Цикл прекращается, когда это выражение становится ложным.
*Оператор '''итерации''' - запускается после каждого цикла.
* '''тело''' цикла - запускается каждый раз, пока оператор '''условия''' вычисляется как истинный.

<pawn>
for ( /* инициализация */ ; /* условие */ ; /* итерация */ )
{
/* тело */
}
</pawn>

Простым примером является функция сложения массива:
<pawn>
new array[10] = {1, 2, 3, 4, 5, 6, 7, 8, 9, 10};
new sum = SumArray(array, 10);

SumArray(const array[], count)
{
new total;

for (new i = 0; i < count; i++)
{
total += array[i];
}

return total;
}</pawn>

По отдельности:
*<tt>new i = 0</tt> - Создает новую переменную для цикла, и устанавливает её в 0.
*<tt>i < count</tt> - Только запускает цикл, если <tt>i</tt> меньше, чем <tt>count</tt>. Это гарантирует, что чтение цикла прекращается в определенный момент. В этом случае, мы не хотим читать недействительные индексы в массиве.
*<tt>i++</tt> - Увеличивает <tt>i</tt> на единицу после каждого цикла. Это гарантирует, что цикл не будет запущен вечно; в конце концов <tt>i</tt> станет слишком большим, и цикл завершится.

Таким образом, функция <tt>SumArray</tt> будет циклом каждого действительного индекса массива, каждый раз добавляя это значение в sum. Для циклов очень распространены массивы такие, как в нашем примере.

==While циклы==
While циклы являются менее распространенными, чем for циклы, но на самом деле это более простые циклы. Они имеют только две части:
*Оператор '''условия''' - проверяется перед началом каждого цикла. Цикл прекращается, когда условие становится ложным.
*'''тело''' цикла - запускается каждый раз пока цикл выполняется.

<pawn>
while ( /* условие */ )
{
/* тело */
}
</pawn>

До тех пор, пока условие выражения остается истинным, цикл будет выполняться. Каждый for цикл может быть переписан, как while цикл:

<pawn>
/* инициализация */
while ( /* условие */ )
{
/* тело */
/* итерация */
}
</pawn>

Вот предыдущий for цикл переписан как while цикл:
<pawn>
SumArray(const array[], count)
{
new total, i;

while (i < count)
{
total += array[i];
i++;
}

return total;
}</pawn>

Существуют также '''do...while''' циклы, которые используются еще реже. Они работают как и while циклы, но проверяют условие ПОСЛЕ каждого цикла, а не перед ним. Это означает, что цикл всегда будет запущен, по крайней мере один раз. Например:

<pawn>
do
{
/* тело */
}
while ( /* условие */ );
</pawn>

==Управление циклами==
Существуют два случая, в которых Мы хотели бы контролировать цикл:
*'''пропустить''' одну итерацию или цикл и продолжить выполнение цикла как обычно, или;
*'''разорвать''' цикл целиком, прежде чем он закончится.

Допустим у вас есть функция, которая принимает массив и ищет соответствия цифр. Вы хотите его остановить, когда число будет найдено:
<pawn>
/**
* Возвращает массив, если индекс значения, или -1, не найдены.
*/
SearchInArray(const array[], count, value)
{
new index = -1;

for (new i = 0; i < count; i++)
{
if (array[i] == value)
{
index = i;
break;
}
}

return index;
}</pawn>

Конечно, эту функцию можно вернуть и способом <tt>return i</tt>, но пример показывает, как <tt>break</tt> может остановить цикл.

Кроме того, ключевое слово <tt>continue</tt> пропускает итерации цикла. Например, Мы хотим суммировать все четные числа:

<pawn>
SumEvenNumbers(const array[], count)
{
new sum;

for (new i = 0; i < count; i++)
{
/* If divisibility by 2 is 1, we know it's odd */
if (array[i] % 2 == 1)
{
/* Пропускаем оставшуюся часть итерации цикла */
continue;
}
sum += array[i];
}

return sum;
}</pawn>

=Область действия=
Область действия относится к '''удобочитаемости''' кода. Это означает, что код одного уровня не может быть "виден" в коде другого уровня. Пример:

<pawn>
new A, B, C;

Function1()
{
new B;

Function2();
}

Function2()
{
new C;
}</pawn>

В этом примере, <tt>A</tt>, <tt>B</tt>, и <tt>C</tt> имеют '''глобальную область действия'''. Их можно увидеть в любой функции. Вместе с тем, <tt>B</tt> в функции <tt>Function1</tt> не является той же переменной, как <tt>B</tt> на глобальном уровне. Вместо этого она находится в '''локальной области действия''', и поэтому является '''локально изменяемой'''.

Кроме того, функции <tt>Function1</tt> и <tt>Function2</tt> ничего не знают о существовании других переменных.

Она так же является не только локальной переменной функции <tt>Function1</tt>, но и создается заново каждый раз, когда функция вызывается. Попробуйте представить это:
<pawn>
Function1()
{
new B;

Function1();
}</pawn>

В приведенном выше примере, функция <tt>Function1</tt> вызывает сама себя. Конечно, это бесконечной рекурсии (а это очень плохо), но идея заключается в том, что каждый раз, когда функция срабатывает, то создается новая копия <tt>B</tt>. Когда функция завершается, <tt>B</tt> уничтожается, и её значение теряется.

Это свойство можно объяснить проще тем, что область действия переменной равна уровню её вложенности. То есть, переменная на глобальной области действия видна для всех функций. Переменная в локальной области действия видна всему блоку кода расположенному "ниже" этого уровня. Например:

<pawn>Function1()
{
new A;

if (A)
{
A = 5;
}
}</pawn>

Приведенный выше код является действительным, поскольку в область действия распространяется по всей функции. Однако этот код, работать не будет:
<pawn>
Function1()
{
new A;

if (A)
{
new B = 5;
}

B = 5;
}</pawn>

Отметим, что <tt>B</tt> объявляется в новом блоке кода. Это означает, что <tt>B</tt> доступна только в том блоке кода, в котором была создана (и всем под-блокам вложенных внутри него). Как только блок кода прекращается, <tt>B</tt> становится не действительной.

=Динамические массивы=
Динамические массивы это массивы, которые не имеют фиксированного размера. Например:

<pawn>Function1(size)
{
new array[size];

/* Код */
}</pawn>

Динамические массивы могут иметь любое выражение, соответствующее их размеру до тех пор, пока выражение вычисляется, как число большее чем 0. Как и для обычных массивов, SourcePawn не сможет узнать размер массива после того, как он будет создан; Вы должны задать его, если хотите использовать массив позднее.

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

=Расширенное объявление переменных=
Переменные могут быть объявлены более длинным путем чем просто <tt>new</tt>.

==decl==
===Назначение===
По умолчанию, все переменные в Pawn будут инициализированы как нуль. Если есть явная инициализация, переменная инициализируется для выражения <tt>=</tt> определенным символам. В локальной области действия, это может потребовать время на выполнение. Ключевое слово <tt>decl</tt> (которое действительно только в локальной области действия) было введено, чтобы позволить решать пользователю, хочит ли он инициализировать переменную или нет.

Примечание: <tt>decl</tt> не должно быть использовано на одну однострочную переменную. Это почти никогда не будет выгодно.

===Объяснение===
Например:

<pawn>
new c = 5;
new d;
new String:blah[512];

Format(blah, sizeof(blah), "%d %d", c, d);
</pawn>

В этом коде, <tt>c</tt> равна 5 и <tt>d</tt> равна 0. Во время выполнения этого кода затраты на инициализацию незначительные. Вместе с тем, <tt>blah</tt> является большим массивом, и затраты на инициализацию всего массива могут быть больше 0 сек. и иметь плохие последствия в определенных ситуациях.

Заметим, что <tt>blah</tt> не должен быть нулевой. В период времени с объявления <tt>new</tt> и и перемещения в <tt>Format()</tt>, массив <tt>blah</tt> никогда не будет загружен или прочитан. Данный код будет более эффективен, если будет написанный следующим образом:

<pawn>
new c = 5;
new d;
decl String:blah[512];

Format(blah, sizeof(blah), "%d %d", c, d);
</pawn>

===Предостережения===
Обратная сторона <tt>decl</tt> состоит в том, что его переменные будут начинаться с "ненужного" содержания. Например, если мы будем использовать:

<pawn>
new c = 5;
new d;
decl String:blah[512];

PrintToServer("%s", blah);

Format(blah, sizeof(blah), "%d %d", c, d);
</pawn>

Этот код может привести к падению сервера, так как массив <tt>blah</tt> может быть полностью испорчен (строки требуют нулевой символ, который может отсутствовать). Точно так же, если мы сделаем:

<pawn>
new c = 5;
decl d;
decl String:blah[512];

Format(blah, sizeof(blah), "%d %d", c, d);
</pawn>

Значение <tt>d</tt> в настоящее время не определенно. Оно может быть любым значением, отрицательным или положительным.

Заметим, что это легко и эффективно обезопасит строки. Пример ниже показывает, как предотвратить строки от мусора:
<pawn>
decl String:blah[512];

blah[0] = '\0';
</pawn>

===Золотые правила===
*'''Используйте decl только, если в период объявления и загрузки/чтения значения, Вы абсолютно уверены, что есть по крайней мере одно хранилище/операция, которая отдает переменной действительные данные.'''
*'''Не оптимизируйте преждевременно.''' Кроме того, нет необходимости использовать <tt>decl</tt> на не-массивы, поскольку нет никаких дополнительных затрат на инициализацию однго однострочного значения.

===Примечания===
Этот пример НЕ является столь эффективным, как <tt>decl</tt>:
<pawn>
new String:blah[512] = "a";
</pawn>

Даже несмотря на то, что строка имеет только один символ, оператор <tt>new</tt> гарантирует, что остальная часть массива будет нулевой.

Также обратите внимание, он является неправильным для явной инициализации <tt>decl</tt>:
<pawn>decl String:blah[512] = "a";</pawn>

Приведенный выше код не будет компилироваться, потому что цель <tt>decl</tt> состоит в том, чтобы избежать каких-либо инициализаций.

==static==
Ключевое слово <tt>static</tt> входит в глобальную и локальную область действия. Оно имеет различные значения в каждой из них.

===Global static===
A global static variable can only be accessed from within the same file. For example:

<pawn>//file1.inc
static Float:g_value1 = 0.15f;

//file2.inc
static Float:g_value2 = 0.15f;</pawn>

If a plugin includes both of these files, it will not be able to use either <tt>g_value1</tt> or <tt>g_value2</tt>. This is a simple information hiding mechanism, and is similar to declaring member variables as <tt>private</tt> in languages like C++, Java, or C#.

===Local static===
A local static variable is a global variable that is only visible from its local lexical scope. For example:

<pawn>
MyFunction(inc)
{
static counter = -1;

counter += inc;

return counter;
}</pawn>

In this example, <tt>counter</tt> is technically a global variable -- it is initialized once to -1 and is never initialized again. It does not exist on the stack. That means each time <tt>MyFunction</tt> runs, the <tt>counter</tt> variable and its storage in memory is the same.

Take this example:
<pawn>MyFunction(5);
MyFunction(6);
MyFunction(10);</pawn>

In this example, <tt>counter</tt> will be <tt>-1 + 5 + 6 + 10</tt>, or <tt>20</tt>, because it persists beyond the frame of the function. Note this may pose problems for recursive functions: if your function may be recursive, then <tt>static</tt> is usually not a good idea unless your code is re-entrant.

The benefit of a local static variable is that you don't have to clutter your script with global variables. As long as the variable doesn't need to be read by another function, you can squirrel it inside the function and its persistence will be guaranteed.

Note that statics can exist in any local scope:

<pawn>
MyFunction(inc)
{
if (inc > 0)
{
static counter;
return (counter += inc);
}
return -1;
}</pawn>

[[Category:Ru:SourceMod Scripting]]

Ru:Introduction to SourcePawn

2008-12-26T12:18:45Z

Frenzzy: /* Notes */

Это руководство призвано дать Вам самые основные представления по основам написания сприптов в SourcePawn. [[Pawn]] это "скриптовый" язык используемый для внедрения функциональности в других программах. Это означает, что это не самостоятельный язык, как C++ или Java, и его элементы будут отличаться в различных приложениях. SourcePawn это вариация языка Pawn используемая в [[SourceMod]].

Это руководство не расскажет Вам как писать SourceMod плагины; оно предназначено для получения общих представлений о синтаксисе и семантике этого языка. Читайте отдельную статью [[Ru:Introduction to SourceMod Plugins]] (Введение в SourceMod плагины), для введения в SourceMod API.

=Введение для новичков=
Этот раздел создан не для программистов. Если Вы по прежнему в замешательстве, Вы можете прочитать книги о других языках программирования, таких как PHP, Python, или Java, чтобы получить более полное представление о программировании.

==Идентификаторы/Ключевые слова==
Идентификаторы представляет собой набор букв, цифр и/или нижнего подчеркивания, что представляет собой нечто уникальное. Идентификаторы вводятся с учетом регистра (в отличие от PHP, где иногда это не требуется). Идентификаторы не начинаются с какого-либо специального символа, но они должны начинаться с буквы.

Есть несколько зарезервированных символов, которые имеют особое значение. Например, <tt>if</tt>, <tt>for</tt>, и <tt>return</tt> специальные конструкции в языке, которые будут описаны позднее. Они не могут быть использованы в качестве названий идентификаторов.

==Переменные==
Существует несколько важных конструкций, которые Вы должны знать, прежде чем приступить к написанию сценария. Во-первых, это '''переменные'''. Переменная это идентификатор, который содержит данные. Например, переменная "a" может содержать числа "2", "16", "0", и так далее. Переменные создаются для хранения данных внутри программы. Переменные должны быть объявлены до их использования, с помощью ключевого слова "new". Данные можно присвоить переменной, используя знак равенства (=). Пример:

<pawn>new a, b, c, d;

a = 5;
b = 16;
c = 0;
d = 500;</pawn>

В SourcePawn, переменные бывают двух типов, которые будут более подробно описаны далее.
*Однострочные (могут содержать только произвольные числовые данные), как показано выше.
*Многострочные (могут содержать целый ряд текстовых символов)

==Функции==
Следующим важным понятием являются '''функции'''. Функции идентификаторов или имен, которые выполняют действия. Это означает, что когда вы их активируете, они выполняют конкретную последовательность кода. Есть несколько типов функций, но все функции активируется одинаковым образом. "Вызов функции" является термином ссылающимся на функцию действия. Функция числовых переменных строятся так:
<pawn>функция(<параметры>)</pawn>

Примеры:

<pawn>show(56); //Активирует функцию "show" и присваивает ей число 56
show(); //Активирует функцию "show" без каких-либо данных, пустую
show(a); //Активирует функцию "show" и присваивает ей переменную с данными
</pawn>

Каждый фрагмент данных передаваемый вызываемой функции, называется '''параметр'''. Функция может иметь любое количество параметров (но есть "допустимый" предел в SourceMod: 32). Параметры будут описаны далее в этой статье.

==Комментарии==
Примечания и любой текст, который пишется после "//" считается "Комментарием", а не фактическим кодом. Есть два стиля комментариев:
*<tt>//</tt> - Двойная косая черта, всё следующие после этой строки игнорируется.
*<tt>/* */</tt> - Много-строчный комментарий, весь текст, внутри звездочек игнорируются. You cannot nest these.

==Массивы==
Описание массивов. Вы можете группировать код в виде "массивов", разделенных { и }. Это фактически создает возможность работать с целым массивом как с одним оператором. Например:

<pawn>{
here;
is;
some;
code;
}</pawn>

Массивы с фигурными скобками используются достаточно широко в программировании. Массивы кода могут быть вложенными друг в друга. Это хорошая возможность адаптировать последовательность когда и сделать его удобочитаемым, благодаря отступам код не будет смотреться как одна большая и длинная макаронина.

=Особенности языка=
Pawn может показаться очень похожим на другие языки программирования, например C, но Pawn от них фундаментально отличается. Не столь важно, чтобы Вы сейчас же поняли его отличия, но они понадобятся, если Вы уже знаете один из языков программирования.
*'''Pawn не печатает''' Pawn имеет только один тип данных - '''однострочный'''. Подробнее будет описано позже. [В дальнейшем автор рассказывает, что существует два типа данных: однострочный и многострочный]
*'''Pawn не собирает мусор''' Pawn, как язык, не имеет встроенных ресурсов памяти, и потому он не мусорит. Если функция выделит память, то Вы отвечаете за её освобождение.
*'''Pawn не объектно-ориентированный язык''' Pawn является процедурным, и полагается на подпрограммы. Также у него нету C подобных структур.
*'''Pawn не функциональный.''' Pawn является процедурным, и не поддерживает функции "лямбды" (Lambda), поздние присвоения, и все то, что можно найти в языках высшего уровня, таких как Phyton и Ruby.
*'''Pawn однопоточный''' As of this writing, Pawn is not thread safe.
*'''Pawn не интерпретируемый''' Ну, почти. Он интерпретируется на очень низком уровне. Вы должны скомпилировать код, из которого получится бинарный файл. Эта программа будет работать на той платформе, которую использует хост. Это ускоряет загрузку и позволяет легче находить ошибки.

Этот язык был выпущен ITB CompuPhase. Язык разработан для устройств низкого уровня и таким образом конечные программы очень маленькие по размеру и очень быстрые.

=Переменные=
В Pawn есть всего два типа переменных: '''однострочные''' и '''многострочные'''. Однострочные могут содержать 32 бита цифровых данных. Многострочные - последовательный список из UTF-8 символов.

'''однострочные''' не имеет своего типа, однако они могут быть '''маркированы'''(tagged). Тег позволяет Вам указывать, где определенную ячейку можно использовать. Типичные теги:
*(пусто), или '''_''' - Нет тега. Обычно используют для целых чисел ([http://en.wikipedia.org/wiki/Integer Integers]).
*'''Float''' - используют для чисел с плавающей точкой (небольших).
*'''bool''' - используют для хранения значений '''true''' (истина) или '''false''' (ложь).

Со строками все по другому, они будут рассмотрены далее.

==Объявления==
Примеры разных правильных объявлений переменных.
<pawn>
new a = 5;
new Float:b = 5.0;
new bool:c = true;
new bool:d = 0; //Работает, поскольку 0 равно false (ложь)
</pawn>

Неправильные объявления переменных
<pawn>
new a = 5.0; //Несоответствие тегов. 5.0 с тегом Float
new Float:b = 5; //Несоответствие тегов. 5 без тега.
</pawn>

Если переменная не определена в объявлении то ее значения станет 0
<pawn>
new a; //значение 0
new Float:b; //значение 0.0
new bool:c; //значение false
</pawn>

==Присвоение==
Переменным могут быть присвоены данные после создания. Пример:
<pawn>new a, Float:b, bool:c;

a = 5;
b = 5.0;
c = true;
</pawn>

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

==Описание==
Массив объявляется с помощью квадратных скобок. Вот некоторые примеры массивов:
<pawn>
new players[32]; //Набор из 32 однострочных (числовых) данных
new Float:origin[3]; //Набор из 3 чисел с плавающей точкой
</pawn>

По умолчанию, массивам присваиваются нули. Вы можете присвоить им разные значения по умолчанию, однако:
<pawn>
new numbers[5] = {1, 2, 3, 4, 5}; //Набор 1, 2, 3, 4, 5 из однострочных данных.
new Float:origin[3] = {1.0, 2.0, 3.0}; //Набор 1.0, 2.0, 3.0 из однострочных данных.
</pawn>

Вы можете оставить массив без размера, если вы собираетесь заранее присвоить ему данные. Например:
<pawn>
new numbers[] = {1, 3, 5, 7, 9};
</pawn>

Компилятор будет автоматически делать вывод о том, что Вы хотите получить массив размером 5.

==Использование==
Использование массива равносильно использованию обычных переменной. Единственное отличие массива состоит в том, что он должен быть '''индексируемым'''. Индексирование массива означает присутствие возможности выбрать элемент, который Вы хотите использовать.

Вот пример кода с использованием индексов:
<pawn>
new numbers[5], Float:origin[3];

numbers[0] = 1;
numbers[1] = 2;
numbers[2] = 3;
numbers[3] = 4;
numbers[4] = 5;
origin[0] = 1.0;
origin[1] = 2.0;
origin[2] = 3.0;
</pawn>

Заметим, что '''индекс''' это текст, который находится в квадратных скобках. Индекс всегда начинается с нуля. То есть, если массив имеет N элементов, его действительный индекс от 0 до N-1. Доступ к данным с индексами работает так же, как с обычной переменной.

Использование неверного индекса вызовет ошибку. Например:
<pawn>
new numbers[5];

numbers[5] = 20;</pawn>

Это может выглядеть верно, но число 5 не является допустимым индексом. Наибольшим значением индекса является число 4.

Вы можете использовать любые выражения, как индекс. Например:
<pawn>new a, numbers[5];

a = 1; //Сделает a = 1
numbers[a] = 4; //Сделает numbers[1] = 4
numbers[numbers[a]] = 2; //Сделает numbers[4] = 2
</pawn>

Выражения будут обсуждаться подробнее в конце статьи.

=Строки=
Строки являются удобным способом хранения текста. Символы хранятся в массиве. Строка ограничивается '''нулевым символом''', или 0. Без нулевого символа, Pawn не знает, где остановить чтение строки. Все строки в SourcePawn используют кодировку UTF-8.

Отметим, что строки имеют комбинацию из массивов и однострочных переменных. В отличие от других языков, это означает, что Вы должны знать заранее, как много места будут использовать строки. Это означает, что строки не являются динамичными. Они могут лишь вырасти до размера, которым Вы их ограничили.

''Примечание для специалистов: они фактически не однострочные. SourcePawn использует 8-битный строки для хранения массивов в качестве оптимизации. Это и есть то, что делает строки типом, а не меткой.''

==Использование==
Строки были созданы почти в равной степени и для массивов. Например:
<pawn>
new String:message[] = "Hello!";
new String:clams[6] = "Clams";
</pawn>

Это равносильно следующему:
<pawn>
new String:message[7], String:clams[6];

message[0] = 'H';
message[1] = 'e';
message[2] = 'l';
message[3] = 'l';
message[4] = 'o';
message[5] = '!';
message[6] = 0;
clams[0] = 'C';
clams[1] = 'l';
clams[2] = 'a';
clams[3] = 'm';
clams[4] = 's';
clams[5] = 0;
</pawn>

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

Заметим, что строка должна быть заключена в двойных кавычках, а символ в одиночных.

==Символы==
Особенность текста может быть использована в любой строке или однострочной переменной. Например:
<pawn>new String:text[] = "Crab";
new clam;

clam = 'D'; //Устанавливает однострочной переменной значение 'D'
text[0] = 'A'; //Меняет 'C' на 'A', сейчас получилось 'Arab'
clam = text[0]; //Устанавливает однострочной переменной значение 'A'
text[1] = clam; //Меняет 'r' на 'A', сейчас получилось 'AAab'
</pawn>

То, что вы не можете сделать, это соотнести символы массивов со строками. Внутреннее хранение отличается. Например:
<pawn>
new clams[] = "Clams"; //Не верно, нужен тип String:
new clams[] = {'C', 'l', 'a', 'm', 's', 0}; //Верно, но это НЕ СТРОКА.
</pawn>

=Функции=
Функции, как отмечалось ранее, имеют отдельные составляющие кода, которые выполняют определенные действия. Функции могут быть задействованы или '''вызвоны''' с '''параметрами''', которые дают особые настройки.

Существуют два типа вызова функции:
*'''прямой вызов''' - Вы специально вызываете функцию в своем коде.
*'''обратный вызов''' - Применение вызова функций в Вашем коде, как если бы это было событием триггера (совокупность условий, инициирующих выполнение действия).

Существуют пять видов функций:
*'''native''': Прямая, внутренняя функция, предусмотренная в приложении.
*'''public''': Функция обратного вызова, что делает её видимой для приложения и других сценариев.
*'''normal''': Нормальная функция, которую Вы можете только вызвать.
*'''stock''': Нормальная функция, предусмотренная если включает в себя файл. Если не используется, то не компилируется.
*'''forward''': Эта функция представляет собой глобальное событие, предусмотренная приложением. Если Вы её привели в исполнение, она будет вызвона.

Весь код в Pawn должен существовать в функциях. Это основное отличие от языков, таких как PHP, Perl и Python, которые позволяют Вам писать глобальный код. Это происходит потому, что Pawn вызывается на основе другого языка: он реагирует на действия от родительского приложения, и функции должны быть написаны для обработки этих действий. Хотя наш пример, часто содержат свободно плавающий код, это сделано исключительно для демонстрационных целей. Свободно плавающий код в нашем примере означает, что код является частью ряда функций.

==Описание==
В отличие от переменных, функции, не нужно объявлять, прежде чем использовать их. Функции имеют две части, '''модель''' и '''тело'''. Модель содержит имя Вашей функции и параметры, которые она будет принимать. Тело является контейнером для кода.

Пример функции:
<pawn>
AddTwoNumbers(first, second)
{
new sum = first + second;

return sum;
}</pawn>

Это простая функция. Модель этой строки:
<pawn>AddTwoNumbers(first, second)</pawn>

Распишем по отдельности:
*<tt>AddTwoNumbers</tt> - Название функции.
*<tt>first</tt> - Название первого параметра, который представляет собой простой элемент.
*<tt>second</tt> - Название второго параметра, который представляет собой простой элемент.

Тело представляет собой простой блок кода. Он создает новую переменную, названную <tt>sum</tt>, и присваивает ей значение этих двух параметров, добавленных совместно (другие выражения будут позже). Важно заметить оператор <tt>return</tt>, в котором обозначается конец функции и возврат с полученными значениями из этой функции. Все функции ''возвращают значения'' после завершения. Это означает, например:

<pawn>new sum = AddTwoNumbers(4, 5);</pawn>

Приведенный выше код будет присваивать число 9 к sum. Функция получает два значения и передает новое значение sum в качестве '''возвращаемого значения'''. Если функция не имеет возвращаемого значения или не имеет значений для возврата, то возвращается 0 по умолчанию.

Функция может принимать любые типы значений. Она может вернуть любую однострочную переменную, но не массивы или строки. Пример:
<pawn>Float:AddTwoFloats(Float:a, Float:b)
{
new Float:sum = a + b;

return sum;
}</pawn>

''Заметим, что если в приведенной выше функции, Вам вернулась не Float значение, Вы получите не соответствие значений.''

Можно, конечно, передавать переменные в функции:
<pawn>new numbers[3] = {1, 2, 0};

numbers[2] = AddTwoNumbers(numbers[0], numbers[1]);</pawn>

Заметим, что однострочные переменные передаются '''по значению'''. То есть, их значение не может быть изменено функцией. Например:
<pawn>new a = 5;

ChangeValue(a);

ChangeValue(b)
{
b = 5;
}</pawn>

Этот код не будет менять значение <tt>a</tt>. Это происходит потому, что копия этого значения в <tt>a</tt> передается вместо <tt>a</tt> самостоятельно.

Больше примеров функций будут демонстрироваться и в других частях статьи.

==Publics==
Публичные функции используются для осуществления обратных вызовов. Вы не должны создавать какую-либо публичную функцию, если это вынудит выполнение обратного вызова. Например, вот два обратных вызова из <tt>sourcemod.inc</tt>:

<pawn>forward OnPluginStart();
forward OnClientDisconnected(client);</pawn>

Чтобы выполнить и получить эти два события, Вы должны написать такие функции как:

<pawn>public OnPluginStart()
{
/* Код здесь */
}

public OnClientDisconnected(client)
{
/* Код здесь */
}</pawn>

Ключевое слово '''public''' делает функцию публичной, а также позволяет родительскому приложению непосредственно вызывать функцию.

==Natives==
Natives имеют встроенные функции, предоставляемые приложением. Вы можете вызвать их, как если бы они были normal функциями. Например, SourceMod имеет следующие функции:

<pawn>native FloatRound(Float:num);</pawn>

Её можно вызвать таким образом:
<pawn>new num = FloatRound(5.2); //Результат в num = 5</pawn>

==Параметры массива==
Вы можете передавать массивы или строки в качестве параметров. Важно отметить, что они идут '''как ссылка'''. То есть не делать копию данных, а отдавать непосредственно ссылки на данные. Существует простой способ объяснить это более конкретно.

<pawn>
new example[] = {1, 2, 3, 4, 5};

ChangeArray(example, 2, 29);

ChangeArray(array[], index, value)
{
array[index] = value;
}</pawn>

Эта функция устанавливает заданный индекс в массиве с учетом значений. Когда она запускается на примере нашего массива, она меняет индекс 2 для значения 3 на 29. То есть:
<pawn>example[2] = 29;</pawn>

Это возможно лишь потому, что массив может быть непосредственно изменён. Чтобы предотвратить массив от изменения, можно пометить его как постоянную <tt>const</tt>. Это позволит понизить риск на ошибку в коде от её изменения. Например:

<pawn>CantChangeArray(const array[], index, value)
{
array[index] = value; //Не компилируется
}</pawn>

Это хорошая идея использовать <tt>const</tt> в параметрах массивов и Вы будете точно знать, что массив не будет изменен; это может предотвратить ошибки кодирования.

=Выражения=
Выражения являются точно такими же, какими они существуют в математике. Это группы операторов/символов, которые приходятся на один фрагмент данных. Они часто заключены в скобках (внутри скобок). Они содержат строгий "порядок операций". Они могут содержать переменные, функции, цифры и выражения сами могут быть вложенные внутрь других выражений, и даже приняты в качестве параметров.

Приведем пример простейшего выражения:
<pawn>
0; //Возвращает число 0
(0); //Так же возвращает число 0
</pawn>

Хотя выражения могут возвращать значения, они также могут ответить какое значение содержит ответ ''ноль или не ноль''. В этом смысле, ''ноль'' является ''ложью'' (false), а ''не нулевое'' значение ''истиной'' (true). Например, -1 ''истина'' в Pawn, поскольку она не является нулем. Не думайте, что отрицательные числа являются ложными.

Порядок операций выражения аналогичен языку C. PMDAS: Parenthesis, Multiplication, Division, Addition, Subtraction. Вот несколько примеров выражений:
<pawn>
5 + 6; //Вычисляет как 11
5 * 6 + 3; //Вычисляет как 33
5 * (6 + 3); //Вычисляет как 45
5.0 + 2.3; //Вычисляет как 7.3
(5 * 6) % 7; //Modulo operator, вычисляет как 2
(5 + 3) / 2 * 4 - 9; //Вычисляет как 7
</pawn>

Как уже отмечалось, выражения могут содержать переменные, или даже функции:
<pawn>
new a = 5 * 6;
new b = a * 3; //Вычисляет как 90
new c = AddTwoNumbers(a, b) + (a * b);
</pawn>

==Операторы==
Есть несколько полезных дополнительных операторов в Pawn. Первый набор упрощает аутоагрегацию выражения. Например:
<pawn>new a = 5;

a = a + 5;</pawn>

Может быть переписан, как:
<pawn>new a = 5;
a += 5;</pawn>

Это верно в отношении следующих операторов в Pawn:
*Four-function: *, /, -, +
*Bit-wise: |, &, ^, ~, <<, >>

Кроме того, существуют инкремент/декремент операторы:
<pawn>a = a + 1;
a = a - 1;</pawn>

Может быть упрощено, как:
<pawn>a++;
a--;</pawn>

Дополнительно отметим, что ++ или -- может быть представлен до переменной (до-инкремент, до-декремент) или после переменной (пост-инкремент, пост-декремент). Разница заключается в том, как остальная часть выражения содержащие их, видит результат.

* ''До:'' Переменная увеличивается до определения и остальная часть выражения видит новое значение.
* ''Пост:'' Переменная увеличивается после определения и остальная часть выражения видит старое значение.

Иными словами, <tt>a++</tt> определяет значение как <tt>a</tt> в то время как <tt>++a</tt> определяет значение как <tt>a + 1</tt>. В обоих случаях <tt>a</tt> увеличивается на <tt>1</tt>.

Например:

<pawn>new a = 5;
new b = a++; // b = 5, a = 6 (1)
new c = ++a; // a = 7, c = 7 (2)
</pawn>

(1) <tt>b</tt> присваивается <tt>a</tt> со ''старым'' значением, ''до'' того, как он будет увеличено до <tt>6</tt>. (2) <tt>c</tt> присваивается <tt>a</tt> с ''новым'' значением, ''после'' того, как он увеличивается до <tt>7</tt>.

==Операторы сравнения==
Существуют шесть операторов для сравнения двух числовых значений, а результат является либо истиной (не ноль) или ложью (ноль):
*<tt>a == b</tt> - Действительно, если и b имеет то же значение.
*<tt>a != b</tt> - Действительно, если b имеет другое значение.
*<tt>a > b</tt> - Действительно, если оно больше b
*<tt>a >= b</tt> - Действительно, если оно больше или равно b
*<tt>a < b</tt> - Действительно, если оно меньше b
*<tt>a <= b</tt> - Действительно, если оно меньше или равно b

Например:
<pawn>
(1 != 3); //Определяется как истина, поскольку 1 не равно 3.
(3 + 3 == 6); //Определяется как истина, поскольку 3+3 равно 6.
(5 - 2 >= 4); //Определяется как ложь, поскольку 3 меньше 4.
</pawn>

Заметим, что эти операторы не работают с массивами и строками. То есть, вы не можете сравнить их с помощью <tt>==</tt>.

==Действительные операторы==
Действительные операторы могут быть скомбинированы тремя булевыми (boolean) операторами:
*<tt>a && b</tt> - Истина, если a и b истинные. Ложь, если a и (или) b ложные.
{| border="1" cellpadding="2" cellspacing="0" align="center"
! <tt>&&</tt> !! 0 !! 1
|-
! 0
| 0 || 0
|-
! 1
| 0 || 1
|}
*<tt>a || b</tt> - Истина, если a или b (или обе переменные) истинные. Ложь, если обе переменные a и b ложные.
{| border="1" cellpadding="2" cellspacing="0" align="center"
! <tt><nowiki>||</nowiki></tt> !! 0 !! 1
|-
! 0
| 0 || 1
|-
! 1
| 1 || 1
|}
*<tt>!a</tt> - Истина, если a ложь. Ложь, если a истина.
{| border="1" cellpadding="2" cellspacing="0" align="center"
! <tt>!</tt> !! 0 !! 1
|-
!
| 1 || 0
|}

Например:
<pawn>
(1 || 0); //Определяется как истина, так как выражение 1 истинное
(1 && 0); //Определяется как ложь, так как выражение 0 ложное
(!1 || 0); //Определяется как ложь, так как выражение !1 ложное.
</pawn>

==Левое/правое значения==
Два важных понятия левого и правого значений, или левостороннее и правостороннее значения. Левостороннее значение имеет то, что появляется на левой стороне выражения, а правостороннее значение - появляется на правой стороне выражения.

Например:
<pawn>
new a = 5;</pawn>

В этом примере <tt>a</tt> является левосторонним значением и <tt>5</tt> является правосторонним значением.

Правила:
*'''Выражения никогда не будут левосторонними значениями'''.
*'''Переменные являются двумя, левосторонними и правосторонними значениями'''.

=Условия=
Условия позволяют Вам запускать код, определенное условие выполнено.

==Если соответствует==
Если соответствует одно или более условий. Например:

<pawn>
if (a == 5)
{
/* Код будет запущен, если условие будет истинным */
}</pawn>

Они могут быть расширены для более сложных случаев:
<pawn>
if (a == 5)
{
/* Код */
}
else if (a == 6)
{
/* Код */
}
else if (a == 7)
{
/* Код */
}</pawn>

Вы так же можете обрабатывать случаи, даже если выражение не верно. Например:
<pawn>
if (a == 5)
{
/* Код */
}
else
{
/* Код, который будет запущен если нет истинного выражения */
}</pawn>

==Оператор выбора==
Оператор выбора будет ограничен условием. Он необходим для выражения, выполняющего код для целого ряда возможных значений. Например:

<pawn>
switch (a)
{
case 5:
{
/* Код */
}
case 6:
{
/* Код */
}
case 7:
{
/* Код */
}
case 8, 9, 10:
{
/* Код */
}
default:
{
/* будет запущен, если не одно условие не соответствует */
}
}</pawn>

В отличие от некоторых других языков, оператор выбора не проваливается. То есть существуют случаи, когда код не будет запущен. При случае совпадения его код выполняется, а ключ является местом для немедленного прекращения.

=Циклы=
Циклы позволяют Вам без труда повторять выполнение кода, пока условие станет истинным.

==For циклы==
For циклы, это циклы, которые состоят из четырех частей:
*Оператор '''инициализации''' - запускается один раз перед первым циклом.
*Оператор '''условия''' - проверяет условие и запускает следующий цикл, в том числе первый. Цикл прекращается, когда это выражение становится ложным.
*Оператор '''итерации''' - запускается после каждого цикла.
* '''тело''' цикла - запускается каждый раз, пока оператор '''условия''' вычисляется как истинный.

<pawn>
for ( /* инициализация */ ; /* условие */ ; /* итерация */ )
{
/* тело */
}
</pawn>

Простым примером является функция сложения массива:
<pawn>
new array[10] = {1, 2, 3, 4, 5, 6, 7, 8, 9, 10};
new sum = SumArray(array, 10);

SumArray(const array[], count)
{
new total;

for (new i = 0; i < count; i++)
{
total += array[i];
}

return total;
}</pawn>

По отдельности:
*<tt>new i = 0</tt> - Создает новую переменную для цикла, и устанавливает её в 0.
*<tt>i < count</tt> - Только запускает цикл, если <tt>i</tt> меньше, чем <tt>count</tt>. Это гарантирует, что чтение цикла прекращается в определенный момент. В этом случае, мы не хотим читать недействительные индексы в массиве.
*<tt>i++</tt> - Увеличивает <tt>i</tt> на единицу после каждого цикла. Это гарантирует, что цикл не будет запущен вечно; в конце концов <tt>i</tt> станет слишком большим, и цикл завершится.

Таким образом, функция <tt>SumArray</tt> будет циклом каждого действительного индекса массива, каждый раз добавляя это значение в sum. Для циклов очень распространены массивы такие, как в нашем примере.

==While циклы==
While циклы являются менее распространенными, чем for циклы, но на самом деле это более простые циклы. Они имеют только две части:
*Оператор '''условия''' - проверяется перед началом каждого цикла. Цикл прекращается, когда условие становится ложным.
*'''тело''' цикла - запускается каждый раз пока цикл выполняется.

<pawn>
while ( /* условие */ )
{
/* тело */
}
</pawn>

До тех пор, пока условие выражения остается истинным, цикл будет выполняться. Каждый for цикл может быть переписан, как while цикл:

<pawn>
/* инициализация */
while ( /* условие */ )
{
/* тело */
/* итерация */
}
</pawn>

Вот предыдущий for цикл переписан как while цикл:
<pawn>
SumArray(const array[], count)
{
new total, i;

while (i < count)
{
total += array[i];
i++;
}

return total;
}</pawn>

Существуют также '''do...while''' циклы, которые используются еще реже. Они работают как и while циклы, но проверяют условие ПОСЛЕ каждого цикла, а не перед ним. Это означает, что цикл всегда будет запущен, по крайней мере один раз. Например:

<pawn>
do
{
/* тело */
}
while ( /* условие */ );
</pawn>

==Управление циклами==
Существуют два случая, в которых Мы хотели бы контролировать цикл:
*'''пропустить''' одну итерацию или цикл и продолжить выполнение цикла как обычно, или;
*'''разорвать''' цикл целиком, прежде чем он закончится.

Допустим у вас есть функция, которая принимает массив и ищет соответствия цифр. Вы хотите его остановить, когда число будет найдено:
<pawn>
/**
* Возвращает массив, если индекс значения, или -1, не найдены.
*/
SearchInArray(const array[], count, value)
{
new index = -1;

for (new i = 0; i < count; i++)
{
if (array[i] == value)
{
index = i;
break;
}
}

return index;
}</pawn>

Конечно, эту функцию можно вернуть и способом <tt>return i</tt>, но пример показывает, как <tt>break</tt> может остановить цикл.

Кроме того, ключевое слово <tt>continue</tt> пропускает итерации цикла. Например, Мы хотим суммировать все четные числа:

<pawn>
SumEvenNumbers(const array[], count)
{
new sum;

for (new i = 0; i < count; i++)
{
/* If divisibility by 2 is 1, we know it's odd */
if (array[i] % 2 == 1)
{
/* Пропускаем оставшуюся часть итерации цикла */
continue;
}
sum += array[i];
}

return sum;
}</pawn>

=Область действия=
Область действия относится к '''удобочитаемости''' кода. Это означает, что код одного уровня не может быть "виден" в коде другого уровня. Пример:

<pawn>
new A, B, C;

Function1()
{
new B;

Function2();
}

Function2()
{
new C;
}</pawn>

В этом примере, <tt>A</tt>, <tt>B</tt>, и <tt>C</tt> имеют '''глобальную область действия'''. Их можно увидеть в любой функции. Вместе с тем, <tt>B</tt> в функции <tt>Function1</tt> не является той же переменной, как <tt>B</tt> на глобальном уровне. Вместо этого она находится в '''локальной области действия''', и поэтому является '''локально изменяемой'''.

Кроме того, функции <tt>Function1</tt> и <tt>Function2</tt> ничего не знают о существовании других переменных.

Она так же является не только локальной переменной функции <tt>Function1</tt>, но и создается заново каждый раз, когда функция вызывается. Попробуйте представить это:
<pawn>
Function1()
{
new B;

Function1();
}</pawn>

В приведенном выше примере, функция <tt>Function1</tt> вызывает сама себя. Конечно, это бесконечной рекурсии (а это очень плохо), но идея заключается в том, что каждый раз, когда функция срабатывает, то создается новая копия <tt>B</tt>. Когда функция завершается, <tt>B</tt> уничтожается, и её значение теряется.

Это свойство можно объяснить проще тем, что область действия переменной равна уровню её вложенности. То есть, переменная на глобальной области действия видна для всех функций. Переменная в локальной области действия видна всему блоку кода расположенному "ниже" этого уровня. Например:

<pawn>Function1()
{
new A;

if (A)
{
A = 5;
}
}</pawn>

Приведенный выше код является действительным, поскольку в область действия распространяется по всей функции. Однако этот код, работать не будет:
<pawn>
Function1()
{
new A;

if (A)
{
new B = 5;
}

B = 5;
}</pawn>

Отметим, что <tt>B</tt> объявляется в новом блоке кода. Это означает, что <tt>B</tt> доступна только в том блоке кода, в котором была создана (и всем под-блокам вложенных внутри него). Как только блок кода прекращается, <tt>B</tt> становится не действительной.

=Динамические массивы=
Динамические массивы это массивы, которые не имеют фиксированного размера. Например:

<pawn>Function1(size)
{
new array[size];

/* Код */
}</pawn>

Динамические массивы могут иметь любое выражение, соответствующее их размеру до тех пор, пока выражение вычисляется, как число большее чем 0. Как и для обычных массивов, SourcePawn не сможет узнать размер массива после того, как он будет создан; Вы должны задать его, если хотите использовать массив позднее.

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

=Расширенное объявление переменных=
Переменные могут быть объявлены более длинным путем чем просто <tt>new</tt>.

==decl==
===Назначение===
По умолчанию, все переменные в Pawn будут инициализированы как нуль. Если есть явная инициализация, переменная инициализируется для выражения <tt>=</tt> определенным символам. В локальной области действия, это может потребовать время на выполнение. Ключевое слово <tt>decl</tt> (которое действительно только в локальной области действия) было введено, чтобы позволить решать пользователю, хочит ли он инициализировать переменную или нет.

Примечание: <tt>decl</tt> не должно быть использовано на одну однострочную переменную. Это почти никогда не будет выгодно.

===Объяснение===
Например:

<pawn>
new c = 5;
new d;
new String:blah[512];

Format(blah, sizeof(blah), "%d %d", c, d);
</pawn>

В этом коде, <tt>c</tt> равна 5 и <tt>d</tt> равна 0. Во время выполнения этого кода затраты на инициализацию незначительные. Вместе с тем, <tt>blah</tt> является большим массивом, и затраты на инициализацию всего массива могут быть больше 0 сек. и иметь плохие последствия в определенных ситуациях.

Заметим, что <tt>blah</tt> не должен быть нулевой. В период времени с объявления <tt>new</tt> и и перемещения в <tt>Format()</tt>, массив <tt>blah</tt> никогда не будет загружен или прочитан. Данный код будет более эффективен, если будет написанный следующим образом:

<pawn>
new c = 5;
new d;
decl String:blah[512];

Format(blah, sizeof(blah), "%d %d", c, d);
</pawn>

===Предостережения===
Обратная сторона <tt>decl</tt> состоит в том, что его переменные будут начинаться с "ненужного" содержания. Например, если мы будем использовать:

<pawn>
new c = 5;
new d;
decl String:blah[512];

PrintToServer("%s", blah);

Format(blah, sizeof(blah), "%d %d", c, d);
</pawn>

Этот код может привести к падению сервера, так как массив <tt>blah</tt> может быть полностью испорчен (строки требуют нулевой символ, который может отсутствовать). Точно так же, если мы сделаем:

<pawn>
new c = 5;
decl d;
decl String:blah[512];

Format(blah, sizeof(blah), "%d %d", c, d);
</pawn>

Значение <tt>d</tt> в настоящее время не определенно. Оно может быть любым значением, отрицательным или положительным.

Заметим, что это легко и эффективно обезопасит строки. Пример ниже показывает, как предотвратить строки от мусора:
<pawn>
decl String:blah[512];

blah[0] = '\0';
</pawn>

===Золотые правила===
*'''Используйте decl только, если в период объявления и загрузки/чтения значения, Вы абсолютно уверены, что есть по крайней мере одно хранилище/операция, которая отдает переменной действительные данные.'''
*'''Не оптимизируйте преждевременно.''' Кроме того, нет необходимости использовать <tt>decl</tt> на не-массивы, поскольку нет никаких дополнительных затрат на инициализацию однго однострочного значения.

===Примечания===
Этот пример НЕ является столь эффективным, как <tt>decl</tt>:
<pawn>
new String:blah[512] = "a";
</pawn>

Даже несмотря на то, что строка имеет только один символ, оператор <tt>new</tt> гарантирует, что остальная часть массива будет нулевой.

Также обратите внимание, он является неправильным для явной инициализации <tt>decl</tt>:
<pawn>decl String:blah[512] = "a";</pawn>

Приведенный выше код не будет компилироваться, потому что цель <tt>decl</tt> состоит в том, чтобы избежать каких-либо инициализаций.

==static==
The <tt>static</tt> keyword is available at global and local scope. It has different meanings in each.

===Global static===
A global static variable can only be accessed from within the same file. For example:

<pawn>//file1.inc
static Float:g_value1 = 0.15f;

//file2.inc
static Float:g_value2 = 0.15f;</pawn>

If a plugin includes both of these files, it will not be able to use either <tt>g_value1</tt> or <tt>g_value2</tt>. This is a simple information hiding mechanism, and is similar to declaring member variables as <tt>private</tt> in languages like C++, Java, or C#.

===Local static===
A local static variable is a global variable that is only visible from its local lexical scope. For example:

<pawn>
MyFunction(inc)
{
static counter = -1;

counter += inc;

return counter;
}</pawn>

In this example, <tt>counter</tt> is technically a global variable -- it is initialized once to -1 and is never initialized again. It does not exist on the stack. That means each time <tt>MyFunction</tt> runs, the <tt>counter</tt> variable and its storage in memory is the same.

Take this example:
<pawn>MyFunction(5);
MyFunction(6);
MyFunction(10);</pawn>

In this example, <tt>counter</tt> will be <tt>-1 + 5 + 6 + 10</tt>, or <tt>20</tt>, because it persists beyond the frame of the function. Note this may pose problems for recursive functions: if your function may be recursive, then <tt>static</tt> is usually not a good idea unless your code is re-entrant.

The benefit of a local static variable is that you don't have to clutter your script with global variables. As long as the variable doesn't need to be read by another function, you can squirrel it inside the function and its persistence will be guaranteed.

Note that statics can exist in any local scope:

<pawn>
MyFunction(inc)
{
if (inc > 0)
{
static counter;
return (counter += inc);
}
return -1;
}</pawn>

[[Category:Ru:SourceMod Scripting]]

Ru:Introduction to SourcePawn

2008-12-26T12:10:41Z

Frenzzy: /* Golden Rules */

Это руководство призвано дать Вам самые основные представления по основам написания сприптов в SourcePawn. [[Pawn]] это "скриптовый" язык используемый для внедрения функциональности в других программах. Это означает, что это не самостоятельный язык, как C++ или Java, и его элементы будут отличаться в различных приложениях. SourcePawn это вариация языка Pawn используемая в [[SourceMod]].

Это руководство не расскажет Вам как писать SourceMod плагины; оно предназначено для получения общих представлений о синтаксисе и семантике этого языка. Читайте отдельную статью [[Ru:Introduction to SourceMod Plugins]] (Введение в SourceMod плагины), для введения в SourceMod API.

=Введение для новичков=
Этот раздел создан не для программистов. Если Вы по прежнему в замешательстве, Вы можете прочитать книги о других языках программирования, таких как PHP, Python, или Java, чтобы получить более полное представление о программировании.

==Идентификаторы/Ключевые слова==
Идентификаторы представляет собой набор букв, цифр и/или нижнего подчеркивания, что представляет собой нечто уникальное. Идентификаторы вводятся с учетом регистра (в отличие от PHP, где иногда это не требуется). Идентификаторы не начинаются с какого-либо специального символа, но они должны начинаться с буквы.

Есть несколько зарезервированных символов, которые имеют особое значение. Например, <tt>if</tt>, <tt>for</tt>, и <tt>return</tt> специальные конструкции в языке, которые будут описаны позднее. Они не могут быть использованы в качестве названий идентификаторов.

==Переменные==
Существует несколько важных конструкций, которые Вы должны знать, прежде чем приступить к написанию сценария. Во-первых, это '''переменные'''. Переменная это идентификатор, который содержит данные. Например, переменная "a" может содержать числа "2", "16", "0", и так далее. Переменные создаются для хранения данных внутри программы. Переменные должны быть объявлены до их использования, с помощью ключевого слова "new". Данные можно присвоить переменной, используя знак равенства (=). Пример:

<pawn>new a, b, c, d;

a = 5;
b = 16;
c = 0;
d = 500;</pawn>

В SourcePawn, переменные бывают двух типов, которые будут более подробно описаны далее.
*Однострочные (могут содержать только произвольные числовые данные), как показано выше.
*Многострочные (могут содержать целый ряд текстовых символов)

==Функции==
Следующим важным понятием являются '''функции'''. Функции идентификаторов или имен, которые выполняют действия. Это означает, что когда вы их активируете, они выполняют конкретную последовательность кода. Есть несколько типов функций, но все функции активируется одинаковым образом. "Вызов функции" является термином ссылающимся на функцию действия. Функция числовых переменных строятся так:
<pawn>функция(<параметры>)</pawn>

Примеры:

<pawn>show(56); //Активирует функцию "show" и присваивает ей число 56
show(); //Активирует функцию "show" без каких-либо данных, пустую
show(a); //Активирует функцию "show" и присваивает ей переменную с данными
</pawn>

Каждый фрагмент данных передаваемый вызываемой функции, называется '''параметр'''. Функция может иметь любое количество параметров (но есть "допустимый" предел в SourceMod: 32). Параметры будут описаны далее в этой статье.

==Комментарии==
Примечания и любой текст, который пишется после "//" считается "Комментарием", а не фактическим кодом. Есть два стиля комментариев:
*<tt>//</tt> - Двойная косая черта, всё следующие после этой строки игнорируется.
*<tt>/* */</tt> - Много-строчный комментарий, весь текст, внутри звездочек игнорируются. You cannot nest these.

==Массивы==
Описание массивов. Вы можете группировать код в виде "массивов", разделенных { и }. Это фактически создает возможность работать с целым массивом как с одним оператором. Например:

<pawn>{
here;
is;
some;
code;
}</pawn>

Массивы с фигурными скобками используются достаточно широко в программировании. Массивы кода могут быть вложенными друг в друга. Это хорошая возможность адаптировать последовательность когда и сделать его удобочитаемым, благодаря отступам код не будет смотреться как одна большая и длинная макаронина.

=Особенности языка=
Pawn может показаться очень похожим на другие языки программирования, например C, но Pawn от них фундаментально отличается. Не столь важно, чтобы Вы сейчас же поняли его отличия, но они понадобятся, если Вы уже знаете один из языков программирования.
*'''Pawn не печатает''' Pawn имеет только один тип данных - '''однострочный'''. Подробнее будет описано позже. [В дальнейшем автор рассказывает, что существует два типа данных: однострочный и многострочный]
*'''Pawn не собирает мусор''' Pawn, как язык, не имеет встроенных ресурсов памяти, и потому он не мусорит. Если функция выделит память, то Вы отвечаете за её освобождение.
*'''Pawn не объектно-ориентированный язык''' Pawn является процедурным, и полагается на подпрограммы. Также у него нету C подобных структур.
*'''Pawn не функциональный.''' Pawn является процедурным, и не поддерживает функции "лямбды" (Lambda), поздние присвоения, и все то, что можно найти в языках высшего уровня, таких как Phyton и Ruby.
*'''Pawn однопоточный''' As of this writing, Pawn is not thread safe.
*'''Pawn не интерпретируемый''' Ну, почти. Он интерпретируется на очень низком уровне. Вы должны скомпилировать код, из которого получится бинарный файл. Эта программа будет работать на той платформе, которую использует хост. Это ускоряет загрузку и позволяет легче находить ошибки.

Этот язык был выпущен ITB CompuPhase. Язык разработан для устройств низкого уровня и таким образом конечные программы очень маленькие по размеру и очень быстрые.

=Переменные=
В Pawn есть всего два типа переменных: '''однострочные''' и '''многострочные'''. Однострочные могут содержать 32 бита цифровых данных. Многострочные - последовательный список из UTF-8 символов.

'''однострочные''' не имеет своего типа, однако они могут быть '''маркированы'''(tagged). Тег позволяет Вам указывать, где определенную ячейку можно использовать. Типичные теги:
*(пусто), или '''_''' - Нет тега. Обычно используют для целых чисел ([http://en.wikipedia.org/wiki/Integer Integers]).
*'''Float''' - используют для чисел с плавающей точкой (небольших).
*'''bool''' - используют для хранения значений '''true''' (истина) или '''false''' (ложь).

Со строками все по другому, они будут рассмотрены далее.

==Объявления==
Примеры разных правильных объявлений переменных.
<pawn>
new a = 5;
new Float:b = 5.0;
new bool:c = true;
new bool:d = 0; //Работает, поскольку 0 равно false (ложь)
</pawn>

Неправильные объявления переменных
<pawn>
new a = 5.0; //Несоответствие тегов. 5.0 с тегом Float
new Float:b = 5; //Несоответствие тегов. 5 без тега.
</pawn>

Если переменная не определена в объявлении то ее значения станет 0
<pawn>
new a; //значение 0
new Float:b; //значение 0.0
new bool:c; //значение false
</pawn>

==Присвоение==
Переменным могут быть присвоены данные после создания. Пример:
<pawn>new a, Float:b, bool:c;

a = 5;
b = 5.0;
c = true;
</pawn>

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

==Описание==
Массив объявляется с помощью квадратных скобок. Вот некоторые примеры массивов:
<pawn>
new players[32]; //Набор из 32 однострочных (числовых) данных
new Float:origin[3]; //Набор из 3 чисел с плавающей точкой
</pawn>

По умолчанию, массивам присваиваются нули. Вы можете присвоить им разные значения по умолчанию, однако:
<pawn>
new numbers[5] = {1, 2, 3, 4, 5}; //Набор 1, 2, 3, 4, 5 из однострочных данных.
new Float:origin[3] = {1.0, 2.0, 3.0}; //Набор 1.0, 2.0, 3.0 из однострочных данных.
</pawn>

Вы можете оставить массив без размера, если вы собираетесь заранее присвоить ему данные. Например:
<pawn>
new numbers[] = {1, 3, 5, 7, 9};
</pawn>

Компилятор будет автоматически делать вывод о том, что Вы хотите получить массив размером 5.

==Использование==
Использование массива равносильно использованию обычных переменной. Единственное отличие массива состоит в том, что он должен быть '''индексируемым'''. Индексирование массива означает присутствие возможности выбрать элемент, который Вы хотите использовать.

Вот пример кода с использованием индексов:
<pawn>
new numbers[5], Float:origin[3];

numbers[0] = 1;
numbers[1] = 2;
numbers[2] = 3;
numbers[3] = 4;
numbers[4] = 5;
origin[0] = 1.0;
origin[1] = 2.0;
origin[2] = 3.0;
</pawn>

Заметим, что '''индекс''' это текст, который находится в квадратных скобках. Индекс всегда начинается с нуля. То есть, если массив имеет N элементов, его действительный индекс от 0 до N-1. Доступ к данным с индексами работает так же, как с обычной переменной.

Использование неверного индекса вызовет ошибку. Например:
<pawn>
new numbers[5];

numbers[5] = 20;</pawn>

Это может выглядеть верно, но число 5 не является допустимым индексом. Наибольшим значением индекса является число 4.

Вы можете использовать любые выражения, как индекс. Например:
<pawn>new a, numbers[5];

a = 1; //Сделает a = 1
numbers[a] = 4; //Сделает numbers[1] = 4
numbers[numbers[a]] = 2; //Сделает numbers[4] = 2
</pawn>

Выражения будут обсуждаться подробнее в конце статьи.

=Строки=
Строки являются удобным способом хранения текста. Символы хранятся в массиве. Строка ограничивается '''нулевым символом''', или 0. Без нулевого символа, Pawn не знает, где остановить чтение строки. Все строки в SourcePawn используют кодировку UTF-8.

Отметим, что строки имеют комбинацию из массивов и однострочных переменных. В отличие от других языков, это означает, что Вы должны знать заранее, как много места будут использовать строки. Это означает, что строки не являются динамичными. Они могут лишь вырасти до размера, которым Вы их ограничили.

''Примечание для специалистов: они фактически не однострочные. SourcePawn использует 8-битный строки для хранения массивов в качестве оптимизации. Это и есть то, что делает строки типом, а не меткой.''

==Использование==
Строки были созданы почти в равной степени и для массивов. Например:
<pawn>
new String:message[] = "Hello!";
new String:clams[6] = "Clams";
</pawn>

Это равносильно следующему:
<pawn>
new String:message[7], String:clams[6];

message[0] = 'H';
message[1] = 'e';
message[2] = 'l';
message[3] = 'l';
message[4] = 'o';
message[5] = '!';
message[6] = 0;
clams[0] = 'C';
clams[1] = 'l';
clams[2] = 'a';
clams[3] = 'm';
clams[4] = 's';
clams[5] = 0;
</pawn>

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

Заметим, что строка должна быть заключена в двойных кавычках, а символ в одиночных.

==Символы==
Особенность текста может быть использована в любой строке или однострочной переменной. Например:
<pawn>new String:text[] = "Crab";
new clam;

clam = 'D'; //Устанавливает однострочной переменной значение 'D'
text[0] = 'A'; //Меняет 'C' на 'A', сейчас получилось 'Arab'
clam = text[0]; //Устанавливает однострочной переменной значение 'A'
text[1] = clam; //Меняет 'r' на 'A', сейчас получилось 'AAab'
</pawn>

То, что вы не можете сделать, это соотнести символы массивов со строками. Внутреннее хранение отличается. Например:
<pawn>
new clams[] = "Clams"; //Не верно, нужен тип String:
new clams[] = {'C', 'l', 'a', 'm', 's', 0}; //Верно, но это НЕ СТРОКА.
</pawn>

=Функции=
Функции, как отмечалось ранее, имеют отдельные составляющие кода, которые выполняют определенные действия. Функции могут быть задействованы или '''вызвоны''' с '''параметрами''', которые дают особые настройки.

Существуют два типа вызова функции:
*'''прямой вызов''' - Вы специально вызываете функцию в своем коде.
*'''обратный вызов''' - Применение вызова функций в Вашем коде, как если бы это было событием триггера (совокупность условий, инициирующих выполнение действия).

Существуют пять видов функций:
*'''native''': Прямая, внутренняя функция, предусмотренная в приложении.
*'''public''': Функция обратного вызова, что делает её видимой для приложения и других сценариев.
*'''normal''': Нормальная функция, которую Вы можете только вызвать.
*'''stock''': Нормальная функция, предусмотренная если включает в себя файл. Если не используется, то не компилируется.
*'''forward''': Эта функция представляет собой глобальное событие, предусмотренная приложением. Если Вы её привели в исполнение, она будет вызвона.

Весь код в Pawn должен существовать в функциях. Это основное отличие от языков, таких как PHP, Perl и Python, которые позволяют Вам писать глобальный код. Это происходит потому, что Pawn вызывается на основе другого языка: он реагирует на действия от родительского приложения, и функции должны быть написаны для обработки этих действий. Хотя наш пример, часто содержат свободно плавающий код, это сделано исключительно для демонстрационных целей. Свободно плавающий код в нашем примере означает, что код является частью ряда функций.

==Описание==
В отличие от переменных, функции, не нужно объявлять, прежде чем использовать их. Функции имеют две части, '''модель''' и '''тело'''. Модель содержит имя Вашей функции и параметры, которые она будет принимать. Тело является контейнером для кода.

Пример функции:
<pawn>
AddTwoNumbers(first, second)
{
new sum = first + second;

return sum;
}</pawn>

Это простая функция. Модель этой строки:
<pawn>AddTwoNumbers(first, second)</pawn>

Распишем по отдельности:
*<tt>AddTwoNumbers</tt> - Название функции.
*<tt>first</tt> - Название первого параметра, который представляет собой простой элемент.
*<tt>second</tt> - Название второго параметра, который представляет собой простой элемент.

Тело представляет собой простой блок кода. Он создает новую переменную, названную <tt>sum</tt>, и присваивает ей значение этих двух параметров, добавленных совместно (другие выражения будут позже). Важно заметить оператор <tt>return</tt>, в котором обозначается конец функции и возврат с полученными значениями из этой функции. Все функции ''возвращают значения'' после завершения. Это означает, например:

<pawn>new sum = AddTwoNumbers(4, 5);</pawn>

Приведенный выше код будет присваивать число 9 к sum. Функция получает два значения и передает новое значение sum в качестве '''возвращаемого значения'''. Если функция не имеет возвращаемого значения или не имеет значений для возврата, то возвращается 0 по умолчанию.

Функция может принимать любые типы значений. Она может вернуть любую однострочную переменную, но не массивы или строки. Пример:
<pawn>Float:AddTwoFloats(Float:a, Float:b)
{
new Float:sum = a + b;

return sum;
}</pawn>

''Заметим, что если в приведенной выше функции, Вам вернулась не Float значение, Вы получите не соответствие значений.''

Можно, конечно, передавать переменные в функции:
<pawn>new numbers[3] = {1, 2, 0};

numbers[2] = AddTwoNumbers(numbers[0], numbers[1]);</pawn>

Заметим, что однострочные переменные передаются '''по значению'''. То есть, их значение не может быть изменено функцией. Например:
<pawn>new a = 5;

ChangeValue(a);

ChangeValue(b)
{
b = 5;
}</pawn>

Этот код не будет менять значение <tt>a</tt>. Это происходит потому, что копия этого значения в <tt>a</tt> передается вместо <tt>a</tt> самостоятельно.

Больше примеров функций будут демонстрироваться и в других частях статьи.

==Publics==
Публичные функции используются для осуществления обратных вызовов. Вы не должны создавать какую-либо публичную функцию, если это вынудит выполнение обратного вызова. Например, вот два обратных вызова из <tt>sourcemod.inc</tt>:

<pawn>forward OnPluginStart();
forward OnClientDisconnected(client);</pawn>

Чтобы выполнить и получить эти два события, Вы должны написать такие функции как:

<pawn>public OnPluginStart()
{
/* Код здесь */
}

public OnClientDisconnected(client)
{
/* Код здесь */
}</pawn>

Ключевое слово '''public''' делает функцию публичной, а также позволяет родительскому приложению непосредственно вызывать функцию.

==Natives==
Natives имеют встроенные функции, предоставляемые приложением. Вы можете вызвать их, как если бы они были normal функциями. Например, SourceMod имеет следующие функции:

<pawn>native FloatRound(Float:num);</pawn>

Её можно вызвать таким образом:
<pawn>new num = FloatRound(5.2); //Результат в num = 5</pawn>

==Параметры массива==
Вы можете передавать массивы или строки в качестве параметров. Важно отметить, что они идут '''как ссылка'''. То есть не делать копию данных, а отдавать непосредственно ссылки на данные. Существует простой способ объяснить это более конкретно.

<pawn>
new example[] = {1, 2, 3, 4, 5};

ChangeArray(example, 2, 29);

ChangeArray(array[], index, value)
{
array[index] = value;
}</pawn>

Эта функция устанавливает заданный индекс в массиве с учетом значений. Когда она запускается на примере нашего массива, она меняет индекс 2 для значения 3 на 29. То есть:
<pawn>example[2] = 29;</pawn>

Это возможно лишь потому, что массив может быть непосредственно изменён. Чтобы предотвратить массив от изменения, можно пометить его как постоянную <tt>const</tt>. Это позволит понизить риск на ошибку в коде от её изменения. Например:

<pawn>CantChangeArray(const array[], index, value)
{
array[index] = value; //Не компилируется
}</pawn>

Это хорошая идея использовать <tt>const</tt> в параметрах массивов и Вы будете точно знать, что массив не будет изменен; это может предотвратить ошибки кодирования.

=Выражения=
Выражения являются точно такими же, какими они существуют в математике. Это группы операторов/символов, которые приходятся на один фрагмент данных. Они часто заключены в скобках (внутри скобок). Они содержат строгий "порядок операций". Они могут содержать переменные, функции, цифры и выражения сами могут быть вложенные внутрь других выражений, и даже приняты в качестве параметров.

Приведем пример простейшего выражения:
<pawn>
0; //Возвращает число 0
(0); //Так же возвращает число 0
</pawn>

Хотя выражения могут возвращать значения, они также могут ответить какое значение содержит ответ ''ноль или не ноль''. В этом смысле, ''ноль'' является ''ложью'' (false), а ''не нулевое'' значение ''истиной'' (true). Например, -1 ''истина'' в Pawn, поскольку она не является нулем. Не думайте, что отрицательные числа являются ложными.

Порядок операций выражения аналогичен языку C. PMDAS: Parenthesis, Multiplication, Division, Addition, Subtraction. Вот несколько примеров выражений:
<pawn>
5 + 6; //Вычисляет как 11
5 * 6 + 3; //Вычисляет как 33
5 * (6 + 3); //Вычисляет как 45
5.0 + 2.3; //Вычисляет как 7.3
(5 * 6) % 7; //Modulo operator, вычисляет как 2
(5 + 3) / 2 * 4 - 9; //Вычисляет как 7
</pawn>

Как уже отмечалось, выражения могут содержать переменные, или даже функции:
<pawn>
new a = 5 * 6;
new b = a * 3; //Вычисляет как 90
new c = AddTwoNumbers(a, b) + (a * b);
</pawn>

==Операторы==
Есть несколько полезных дополнительных операторов в Pawn. Первый набор упрощает аутоагрегацию выражения. Например:
<pawn>new a = 5;

a = a + 5;</pawn>

Может быть переписан, как:
<pawn>new a = 5;
a += 5;</pawn>

Это верно в отношении следующих операторов в Pawn:
*Four-function: *, /, -, +
*Bit-wise: |, &, ^, ~, <<, >>

Кроме того, существуют инкремент/декремент операторы:
<pawn>a = a + 1;
a = a - 1;</pawn>

Может быть упрощено, как:
<pawn>a++;
a--;</pawn>

Дополнительно отметим, что ++ или -- может быть представлен до переменной (до-инкремент, до-декремент) или после переменной (пост-инкремент, пост-декремент). Разница заключается в том, как остальная часть выражения содержащие их, видит результат.

* ''До:'' Переменная увеличивается до определения и остальная часть выражения видит новое значение.
* ''Пост:'' Переменная увеличивается после определения и остальная часть выражения видит старое значение.

Иными словами, <tt>a++</tt> определяет значение как <tt>a</tt> в то время как <tt>++a</tt> определяет значение как <tt>a + 1</tt>. В обоих случаях <tt>a</tt> увеличивается на <tt>1</tt>.

Например:

<pawn>new a = 5;
new b = a++; // b = 5, a = 6 (1)
new c = ++a; // a = 7, c = 7 (2)
</pawn>

(1) <tt>b</tt> присваивается <tt>a</tt> со ''старым'' значением, ''до'' того, как он будет увеличено до <tt>6</tt>. (2) <tt>c</tt> присваивается <tt>a</tt> с ''новым'' значением, ''после'' того, как он увеличивается до <tt>7</tt>.

==Операторы сравнения==
Существуют шесть операторов для сравнения двух числовых значений, а результат является либо истиной (не ноль) или ложью (ноль):
*<tt>a == b</tt> - Действительно, если и b имеет то же значение.
*<tt>a != b</tt> - Действительно, если b имеет другое значение.
*<tt>a > b</tt> - Действительно, если оно больше b
*<tt>a >= b</tt> - Действительно, если оно больше или равно b
*<tt>a < b</tt> - Действительно, если оно меньше b
*<tt>a <= b</tt> - Действительно, если оно меньше или равно b

Например:
<pawn>
(1 != 3); //Определяется как истина, поскольку 1 не равно 3.
(3 + 3 == 6); //Определяется как истина, поскольку 3+3 равно 6.
(5 - 2 >= 4); //Определяется как ложь, поскольку 3 меньше 4.
</pawn>

Заметим, что эти операторы не работают с массивами и строками. То есть, вы не можете сравнить их с помощью <tt>==</tt>.

==Действительные операторы==
Действительные операторы могут быть скомбинированы тремя булевыми (boolean) операторами:
*<tt>a && b</tt> - Истина, если a и b истинные. Ложь, если a и (или) b ложные.
{| border="1" cellpadding="2" cellspacing="0" align="center"
! <tt>&&</tt> !! 0 !! 1
|-
! 0
| 0 || 0
|-
! 1
| 0 || 1
|}
*<tt>a || b</tt> - Истина, если a или b (или обе переменные) истинные. Ложь, если обе переменные a и b ложные.
{| border="1" cellpadding="2" cellspacing="0" align="center"
! <tt><nowiki>||</nowiki></tt> !! 0 !! 1
|-
! 0
| 0 || 1
|-
! 1
| 1 || 1
|}
*<tt>!a</tt> - Истина, если a ложь. Ложь, если a истина.
{| border="1" cellpadding="2" cellspacing="0" align="center"
! <tt>!</tt> !! 0 !! 1
|-
!
| 1 || 0
|}

Например:
<pawn>
(1 || 0); //Определяется как истина, так как выражение 1 истинное
(1 && 0); //Определяется как ложь, так как выражение 0 ложное
(!1 || 0); //Определяется как ложь, так как выражение !1 ложное.
</pawn>

==Левое/правое значения==
Два важных понятия левого и правого значений, или левостороннее и правостороннее значения. Левостороннее значение имеет то, что появляется на левой стороне выражения, а правостороннее значение - появляется на правой стороне выражения.

Например:
<pawn>
new a = 5;</pawn>

В этом примере <tt>a</tt> является левосторонним значением и <tt>5</tt> является правосторонним значением.

Правила:
*'''Выражения никогда не будут левосторонними значениями'''.
*'''Переменные являются двумя, левосторонними и правосторонними значениями'''.

=Условия=
Условия позволяют Вам запускать код, определенное условие выполнено.

==Если соответствует==
Если соответствует одно или более условий. Например:

<pawn>
if (a == 5)
{
/* Код будет запущен, если условие будет истинным */
}</pawn>

Они могут быть расширены для более сложных случаев:
<pawn>
if (a == 5)
{
/* Код */
}
else if (a == 6)
{
/* Код */
}
else if (a == 7)
{
/* Код */
}</pawn>

Вы так же можете обрабатывать случаи, даже если выражение не верно. Например:
<pawn>
if (a == 5)
{
/* Код */
}
else
{
/* Код, который будет запущен если нет истинного выражения */
}</pawn>

==Оператор выбора==
Оператор выбора будет ограничен условием. Он необходим для выражения, выполняющего код для целого ряда возможных значений. Например:

<pawn>
switch (a)
{
case 5:
{
/* Код */
}
case 6:
{
/* Код */
}
case 7:
{
/* Код */
}
case 8, 9, 10:
{
/* Код */
}
default:
{
/* будет запущен, если не одно условие не соответствует */
}
}</pawn>

В отличие от некоторых других языков, оператор выбора не проваливается. То есть существуют случаи, когда код не будет запущен. При случае совпадения его код выполняется, а ключ является местом для немедленного прекращения.

=Циклы=
Циклы позволяют Вам без труда повторять выполнение кода, пока условие станет истинным.

==For циклы==
For циклы, это циклы, которые состоят из четырех частей:
*Оператор '''инициализации''' - запускается один раз перед первым циклом.
*Оператор '''условия''' - проверяет условие и запускает следующий цикл, в том числе первый. Цикл прекращается, когда это выражение становится ложным.
*Оператор '''итерации''' - запускается после каждого цикла.
* '''тело''' цикла - запускается каждый раз, пока оператор '''условия''' вычисляется как истинный.

<pawn>
for ( /* инициализация */ ; /* условие */ ; /* итерация */ )
{
/* тело */
}
</pawn>

Простым примером является функция сложения массива:
<pawn>
new array[10] = {1, 2, 3, 4, 5, 6, 7, 8, 9, 10};
new sum = SumArray(array, 10);

SumArray(const array[], count)
{
new total;

for (new i = 0; i < count; i++)
{
total += array[i];
}

return total;
}</pawn>

По отдельности:
*<tt>new i = 0</tt> - Создает новую переменную для цикла, и устанавливает её в 0.
*<tt>i < count</tt> - Только запускает цикл, если <tt>i</tt> меньше, чем <tt>count</tt>. Это гарантирует, что чтение цикла прекращается в определенный момент. В этом случае, мы не хотим читать недействительные индексы в массиве.
*<tt>i++</tt> - Увеличивает <tt>i</tt> на единицу после каждого цикла. Это гарантирует, что цикл не будет запущен вечно; в конце концов <tt>i</tt> станет слишком большим, и цикл завершится.

Таким образом, функция <tt>SumArray</tt> будет циклом каждого действительного индекса массива, каждый раз добавляя это значение в sum. Для циклов очень распространены массивы такие, как в нашем примере.

==While циклы==
While циклы являются менее распространенными, чем for циклы, но на самом деле это более простые циклы. Они имеют только две части:
*Оператор '''условия''' - проверяется перед началом каждого цикла. Цикл прекращается, когда условие становится ложным.
*'''тело''' цикла - запускается каждый раз пока цикл выполняется.

<pawn>
while ( /* условие */ )
{
/* тело */
}
</pawn>

До тех пор, пока условие выражения остается истинным, цикл будет выполняться. Каждый for цикл может быть переписан, как while цикл:

<pawn>
/* инициализация */
while ( /* условие */ )
{
/* тело */
/* итерация */
}
</pawn>

Вот предыдущий for цикл переписан как while цикл:
<pawn>
SumArray(const array[], count)
{
new total, i;

while (i < count)
{
total += array[i];
i++;
}

return total;
}</pawn>

Существуют также '''do...while''' циклы, которые используются еще реже. Они работают как и while циклы, но проверяют условие ПОСЛЕ каждого цикла, а не перед ним. Это означает, что цикл всегда будет запущен, по крайней мере один раз. Например:

<pawn>
do
{
/* тело */
}
while ( /* условие */ );
</pawn>

==Управление циклами==
Существуют два случая, в которых Мы хотели бы контролировать цикл:
*'''пропустить''' одну итерацию или цикл и продолжить выполнение цикла как обычно, или;
*'''разорвать''' цикл целиком, прежде чем он закончится.

Допустим у вас есть функция, которая принимает массив и ищет соответствия цифр. Вы хотите его остановить, когда число будет найдено:
<pawn>
/**
* Возвращает массив, если индекс значения, или -1, не найдены.
*/
SearchInArray(const array[], count, value)
{
new index = -1;

for (new i = 0; i < count; i++)
{
if (array[i] == value)
{
index = i;
break;
}
}

return index;
}</pawn>

Конечно, эту функцию можно вернуть и способом <tt>return i</tt>, но пример показывает, как <tt>break</tt> может остановить цикл.

Кроме того, ключевое слово <tt>continue</tt> пропускает итерации цикла. Например, Мы хотим суммировать все четные числа:

<pawn>
SumEvenNumbers(const array[], count)
{
new sum;

for (new i = 0; i < count; i++)
{
/* If divisibility by 2 is 1, we know it's odd */
if (array[i] % 2 == 1)
{
/* Пропускаем оставшуюся часть итерации цикла */
continue;
}
sum += array[i];
}

return sum;
}</pawn>

=Область действия=
Область действия относится к '''удобочитаемости''' кода. Это означает, что код одного уровня не может быть "виден" в коде другого уровня. Пример:

<pawn>
new A, B, C;

Function1()
{
new B;

Function2();
}

Function2()
{
new C;
}</pawn>

В этом примере, <tt>A</tt>, <tt>B</tt>, и <tt>C</tt> имеют '''глобальную область действия'''. Их можно увидеть в любой функции. Вместе с тем, <tt>B</tt> в функции <tt>Function1</tt> не является той же переменной, как <tt>B</tt> на глобальном уровне. Вместо этого она находится в '''локальной области действия''', и поэтому является '''локально изменяемой'''.

Кроме того, функции <tt>Function1</tt> и <tt>Function2</tt> ничего не знают о существовании других переменных.

Она так же является не только локальной переменной функции <tt>Function1</tt>, но и создается заново каждый раз, когда функция вызывается. Попробуйте представить это:
<pawn>
Function1()
{
new B;

Function1();
}</pawn>

В приведенном выше примере, функция <tt>Function1</tt> вызывает сама себя. Конечно, это бесконечной рекурсии (а это очень плохо), но идея заключается в том, что каждый раз, когда функция срабатывает, то создается новая копия <tt>B</tt>. Когда функция завершается, <tt>B</tt> уничтожается, и её значение теряется.

Это свойство можно объяснить проще тем, что область действия переменной равна уровню её вложенности. То есть, переменная на глобальной области действия видна для всех функций. Переменная в локальной области действия видна всему блоку кода расположенному "ниже" этого уровня. Например:

<pawn>Function1()
{
new A;

if (A)
{
A = 5;
}
}</pawn>

Приведенный выше код является действительным, поскольку в область действия распространяется по всей функции. Однако этот код, работать не будет:
<pawn>
Function1()
{
new A;

if (A)
{
new B = 5;
}

B = 5;
}</pawn>

Отметим, что <tt>B</tt> объявляется в новом блоке кода. Это означает, что <tt>B</tt> доступна только в том блоке кода, в котором была создана (и всем под-блокам вложенных внутри него). Как только блок кода прекращается, <tt>B</tt> становится не действительной.

=Динамические массивы=
Динамические массивы это массивы, которые не имеют фиксированного размера. Например:

<pawn>Function1(size)
{
new array[size];

/* Код */
}</pawn>

Динамические массивы могут иметь любое выражение, соответствующее их размеру до тех пор, пока выражение вычисляется, как число большее чем 0. Как и для обычных массивов, SourcePawn не сможет узнать размер массива после того, как он будет создан; Вы должны задать его, если хотите использовать массив позднее.

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

=Расширенное объявление переменных=
Переменные могут быть объявлены более длинным путем чем просто <tt>new</tt>.

==decl==
===Назначение===
По умолчанию, все переменные в Pawn будут инициализированы как нуль. Если есть явная инициализация, переменная инициализируется для выражения <tt>=</tt> определенным символам. В локальной области действия, это может потребовать время на выполнение. Ключевое слово <tt>decl</tt> (которое действительно только в локальной области действия) было введено, чтобы позволить решать пользователю, хочит ли он инициализировать переменную или нет.

Примечание: <tt>decl</tt> не должно быть использовано на одну однострочную переменную. Это почти никогда не будет выгодно.

===Объяснение===
Например:

<pawn>
new c = 5;
new d;
new String:blah[512];

Format(blah, sizeof(blah), "%d %d", c, d);
</pawn>

В этом коде, <tt>c</tt> равна 5 и <tt>d</tt> равна 0. Во время выполнения этого кода затраты на инициализацию незначительные. Вместе с тем, <tt>blah</tt> является большим массивом, и затраты на инициализацию всего массива могут быть больше 0 сек. и иметь плохие последствия в определенных ситуациях.

Заметим, что <tt>blah</tt> не должен быть нулевой. В период времени с объявления <tt>new</tt> и и перемещения в <tt>Format()</tt>, массив <tt>blah</tt> никогда не будет загружен или прочитан. Данный код будет более эффективен, если будет написанный следующим образом:

<pawn>
new c = 5;
new d;
decl String:blah[512];

Format(blah, sizeof(blah), "%d %d", c, d);
</pawn>

===Предостережения===
Обратная сторона <tt>decl</tt> состоит в том, что его переменные будут начинаться с "ненужного" содержания. Например, если мы будем использовать:

<pawn>
new c = 5;
new d;
decl String:blah[512];

PrintToServer("%s", blah);

Format(blah, sizeof(blah), "%d %d", c, d);
</pawn>

Этот код может привести к падению сервера, так как массив <tt>blah</tt> может быть полностью испорчен (строки требуют нулевой символ, который может отсутствовать). Точно так же, если мы сделаем:

<pawn>
new c = 5;
decl d;
decl String:blah[512];

Format(blah, sizeof(blah), "%d %d", c, d);
</pawn>

Значение <tt>d</tt> в настоящее время не определенно. Оно может быть любым значением, отрицательным или положительным.

Заметим, что это легко и эффективно обезопасит строки. Пример ниже показывает, как предотвратить строки от мусора:
<pawn>
decl String:blah[512];

blah[0] = '\0';
</pawn>

===Золотые правила===
*'''Используйте decl только, если в период объявления и загрузки/чтения значения, Вы абсолютно уверены, что есть по крайней мере одно хранилище/операция, которая отдает переменной действительные данные.'''
*'''Не оптимизируйте преждевременно.''' Кроме того, нет необходимости использовать <tt>decl</tt> на не-массивы, поскольку нет никаких дополнительных затрат на инициализацию однго однострочного значения.

===Notes===
This example is NOT as efficient as a <tt>decl</tt>:
<pawn>
new String:blah[512] = "a";
</pawn>

Even though the string is only one character, the <tt>new</tt> operator guarantees the rest of the array will be zeroed as well.

Also note, it is invalid to explicitly initialize a <tt>decl</tt>:
<pawn>decl String:blah[512] = "a";</pawn>

The above code will not compile, because the purpose of <tt>decl</tt> is to avoid any initialization.

==static==
The <tt>static</tt> keyword is available at global and local scope. It has different meanings in each.

===Global static===
A global static variable can only be accessed from within the same file. For example:

<pawn>//file1.inc
static Float:g_value1 = 0.15f;

//file2.inc
static Float:g_value2 = 0.15f;</pawn>

If a plugin includes both of these files, it will not be able to use either <tt>g_value1</tt> or <tt>g_value2</tt>. This is a simple information hiding mechanism, and is similar to declaring member variables as <tt>private</tt> in languages like C++, Java, or C#.

===Local static===
A local static variable is a global variable that is only visible from its local lexical scope. For example:

<pawn>
MyFunction(inc)
{
static counter = -1;

counter += inc;

return counter;
}</pawn>

In this example, <tt>counter</tt> is technically a global variable -- it is initialized once to -1 and is never initialized again. It does not exist on the stack. That means each time <tt>MyFunction</tt> runs, the <tt>counter</tt> variable and its storage in memory is the same.

Take this example:
<pawn>MyFunction(5);
MyFunction(6);
MyFunction(10);</pawn>

In this example, <tt>counter</tt> will be <tt>-1 + 5 + 6 + 10</tt>, or <tt>20</tt>, because it persists beyond the frame of the function. Note this may pose problems for recursive functions: if your function may be recursive, then <tt>static</tt> is usually not a good idea unless your code is re-entrant.

The benefit of a local static variable is that you don't have to clutter your script with global variables. As long as the variable doesn't need to be read by another function, you can squirrel it inside the function and its persistence will be guaranteed.

Note that statics can exist in any local scope:

<pawn>
MyFunction(inc)
{
if (inc > 0)
{
static counter;
return (counter += inc);
}
return -1;
}</pawn>

[[Category:Ru:SourceMod Scripting]]

Ru:Introduction to SourcePawn

2008-12-26T12:03:32Z

Frenzzy: /* Caveats */

Это руководство призвано дать Вам самые основные представления по основам написания сприптов в SourcePawn. [[Pawn]] это "скриптовый" язык используемый для внедрения функциональности в других программах. Это означает, что это не самостоятельный язык, как C++ или Java, и его элементы будут отличаться в различных приложениях. SourcePawn это вариация языка Pawn используемая в [[SourceMod]].

Это руководство не расскажет Вам как писать SourceMod плагины; оно предназначено для получения общих представлений о синтаксисе и семантике этого языка. Читайте отдельную статью [[Ru:Introduction to SourceMod Plugins]] (Введение в SourceMod плагины), для введения в SourceMod API.

=Введение для новичков=
Этот раздел создан не для программистов. Если Вы по прежнему в замешательстве, Вы можете прочитать книги о других языках программирования, таких как PHP, Python, или Java, чтобы получить более полное представление о программировании.

==Идентификаторы/Ключевые слова==
Идентификаторы представляет собой набор букв, цифр и/или нижнего подчеркивания, что представляет собой нечто уникальное. Идентификаторы вводятся с учетом регистра (в отличие от PHP, где иногда это не требуется). Идентификаторы не начинаются с какого-либо специального символа, но они должны начинаться с буквы.

Есть несколько зарезервированных символов, которые имеют особое значение. Например, <tt>if</tt>, <tt>for</tt>, и <tt>return</tt> специальные конструкции в языке, которые будут описаны позднее. Они не могут быть использованы в качестве названий идентификаторов.

==Переменные==
Существует несколько важных конструкций, которые Вы должны знать, прежде чем приступить к написанию сценария. Во-первых, это '''переменные'''. Переменная это идентификатор, который содержит данные. Например, переменная "a" может содержать числа "2", "16", "0", и так далее. Переменные создаются для хранения данных внутри программы. Переменные должны быть объявлены до их использования, с помощью ключевого слова "new". Данные можно присвоить переменной, используя знак равенства (=). Пример:

<pawn>new a, b, c, d;

a = 5;
b = 16;
c = 0;
d = 500;</pawn>

В SourcePawn, переменные бывают двух типов, которые будут более подробно описаны далее.
*Однострочные (могут содержать только произвольные числовые данные), как показано выше.
*Многострочные (могут содержать целый ряд текстовых символов)

==Функции==
Следующим важным понятием являются '''функции'''. Функции идентификаторов или имен, которые выполняют действия. Это означает, что когда вы их активируете, они выполняют конкретную последовательность кода. Есть несколько типов функций, но все функции активируется одинаковым образом. "Вызов функции" является термином ссылающимся на функцию действия. Функция числовых переменных строятся так:
<pawn>функция(<параметры>)</pawn>

Примеры:

<pawn>show(56); //Активирует функцию "show" и присваивает ей число 56
show(); //Активирует функцию "show" без каких-либо данных, пустую
show(a); //Активирует функцию "show" и присваивает ей переменную с данными
</pawn>

Каждый фрагмент данных передаваемый вызываемой функции, называется '''параметр'''. Функция может иметь любое количество параметров (но есть "допустимый" предел в SourceMod: 32). Параметры будут описаны далее в этой статье.

==Комментарии==
Примечания и любой текст, который пишется после "//" считается "Комментарием", а не фактическим кодом. Есть два стиля комментариев:
*<tt>//</tt> - Двойная косая черта, всё следующие после этой строки игнорируется.
*<tt>/* */</tt> - Много-строчный комментарий, весь текст, внутри звездочек игнорируются. You cannot nest these.

==Массивы==
Описание массивов. Вы можете группировать код в виде "массивов", разделенных { и }. Это фактически создает возможность работать с целым массивом как с одним оператором. Например:

<pawn>{
here;
is;
some;
code;
}</pawn>

Массивы с фигурными скобками используются достаточно широко в программировании. Массивы кода могут быть вложенными друг в друга. Это хорошая возможность адаптировать последовательность когда и сделать его удобочитаемым, благодаря отступам код не будет смотреться как одна большая и длинная макаронина.

=Особенности языка=
Pawn может показаться очень похожим на другие языки программирования, например C, но Pawn от них фундаментально отличается. Не столь важно, чтобы Вы сейчас же поняли его отличия, но они понадобятся, если Вы уже знаете один из языков программирования.
*'''Pawn не печатает''' Pawn имеет только один тип данных - '''однострочный'''. Подробнее будет описано позже. [В дальнейшем автор рассказывает, что существует два типа данных: однострочный и многострочный]
*'''Pawn не собирает мусор''' Pawn, как язык, не имеет встроенных ресурсов памяти, и потому он не мусорит. Если функция выделит память, то Вы отвечаете за её освобождение.
*'''Pawn не объектно-ориентированный язык''' Pawn является процедурным, и полагается на подпрограммы. Также у него нету C подобных структур.
*'''Pawn не функциональный.''' Pawn является процедурным, и не поддерживает функции "лямбды" (Lambda), поздние присвоения, и все то, что можно найти в языках высшего уровня, таких как Phyton и Ruby.
*'''Pawn однопоточный''' As of this writing, Pawn is not thread safe.
*'''Pawn не интерпретируемый''' Ну, почти. Он интерпретируется на очень низком уровне. Вы должны скомпилировать код, из которого получится бинарный файл. Эта программа будет работать на той платформе, которую использует хост. Это ускоряет загрузку и позволяет легче находить ошибки.

Этот язык был выпущен ITB CompuPhase. Язык разработан для устройств низкого уровня и таким образом конечные программы очень маленькие по размеру и очень быстрые.

=Переменные=
В Pawn есть всего два типа переменных: '''однострочные''' и '''многострочные'''. Однострочные могут содержать 32 бита цифровых данных. Многострочные - последовательный список из UTF-8 символов.

'''однострочные''' не имеет своего типа, однако они могут быть '''маркированы'''(tagged). Тег позволяет Вам указывать, где определенную ячейку можно использовать. Типичные теги:
*(пусто), или '''_''' - Нет тега. Обычно используют для целых чисел ([http://en.wikipedia.org/wiki/Integer Integers]).
*'''Float''' - используют для чисел с плавающей точкой (небольших).
*'''bool''' - используют для хранения значений '''true''' (истина) или '''false''' (ложь).

Со строками все по другому, они будут рассмотрены далее.

==Объявления==
Примеры разных правильных объявлений переменных.
<pawn>
new a = 5;
new Float:b = 5.0;
new bool:c = true;
new bool:d = 0; //Работает, поскольку 0 равно false (ложь)
</pawn>

Неправильные объявления переменных
<pawn>
new a = 5.0; //Несоответствие тегов. 5.0 с тегом Float
new Float:b = 5; //Несоответствие тегов. 5 без тега.
</pawn>

Если переменная не определена в объявлении то ее значения станет 0
<pawn>
new a; //значение 0
new Float:b; //значение 0.0
new bool:c; //значение false
</pawn>

==Присвоение==
Переменным могут быть присвоены данные после создания. Пример:
<pawn>new a, Float:b, bool:c;

a = 5;
b = 5.0;
c = true;
</pawn>

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

==Описание==
Массив объявляется с помощью квадратных скобок. Вот некоторые примеры массивов:
<pawn>
new players[32]; //Набор из 32 однострочных (числовых) данных
new Float:origin[3]; //Набор из 3 чисел с плавающей точкой
</pawn>

По умолчанию, массивам присваиваются нули. Вы можете присвоить им разные значения по умолчанию, однако:
<pawn>
new numbers[5] = {1, 2, 3, 4, 5}; //Набор 1, 2, 3, 4, 5 из однострочных данных.
new Float:origin[3] = {1.0, 2.0, 3.0}; //Набор 1.0, 2.0, 3.0 из однострочных данных.
</pawn>

Вы можете оставить массив без размера, если вы собираетесь заранее присвоить ему данные. Например:
<pawn>
new numbers[] = {1, 3, 5, 7, 9};
</pawn>

Компилятор будет автоматически делать вывод о том, что Вы хотите получить массив размером 5.

==Использование==
Использование массива равносильно использованию обычных переменной. Единственное отличие массива состоит в том, что он должен быть '''индексируемым'''. Индексирование массива означает присутствие возможности выбрать элемент, который Вы хотите использовать.

Вот пример кода с использованием индексов:
<pawn>
new numbers[5], Float:origin[3];

numbers[0] = 1;
numbers[1] = 2;
numbers[2] = 3;
numbers[3] = 4;
numbers[4] = 5;
origin[0] = 1.0;
origin[1] = 2.0;
origin[2] = 3.0;
</pawn>

Заметим, что '''индекс''' это текст, который находится в квадратных скобках. Индекс всегда начинается с нуля. То есть, если массив имеет N элементов, его действительный индекс от 0 до N-1. Доступ к данным с индексами работает так же, как с обычной переменной.

Использование неверного индекса вызовет ошибку. Например:
<pawn>
new numbers[5];

numbers[5] = 20;</pawn>

Это может выглядеть верно, но число 5 не является допустимым индексом. Наибольшим значением индекса является число 4.

Вы можете использовать любые выражения, как индекс. Например:
<pawn>new a, numbers[5];

a = 1; //Сделает a = 1
numbers[a] = 4; //Сделает numbers[1] = 4
numbers[numbers[a]] = 2; //Сделает numbers[4] = 2
</pawn>

Выражения будут обсуждаться подробнее в конце статьи.

=Строки=
Строки являются удобным способом хранения текста. Символы хранятся в массиве. Строка ограничивается '''нулевым символом''', или 0. Без нулевого символа, Pawn не знает, где остановить чтение строки. Все строки в SourcePawn используют кодировку UTF-8.

Отметим, что строки имеют комбинацию из массивов и однострочных переменных. В отличие от других языков, это означает, что Вы должны знать заранее, как много места будут использовать строки. Это означает, что строки не являются динамичными. Они могут лишь вырасти до размера, которым Вы их ограничили.

''Примечание для специалистов: они фактически не однострочные. SourcePawn использует 8-битный строки для хранения массивов в качестве оптимизации. Это и есть то, что делает строки типом, а не меткой.''

==Использование==
Строки были созданы почти в равной степени и для массивов. Например:
<pawn>
new String:message[] = "Hello!";
new String:clams[6] = "Clams";
</pawn>

Это равносильно следующему:
<pawn>
new String:message[7], String:clams[6];

message[0] = 'H';
message[1] = 'e';
message[2] = 'l';
message[3] = 'l';
message[4] = 'o';
message[5] = '!';
message[6] = 0;
clams[0] = 'C';
clams[1] = 'l';
clams[2] = 'a';
clams[3] = 'm';
clams[4] = 's';
clams[5] = 0;
</pawn>

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

Заметим, что строка должна быть заключена в двойных кавычках, а символ в одиночных.

==Символы==
Особенность текста может быть использована в любой строке или однострочной переменной. Например:
<pawn>new String:text[] = "Crab";
new clam;

clam = 'D'; //Устанавливает однострочной переменной значение 'D'
text[0] = 'A'; //Меняет 'C' на 'A', сейчас получилось 'Arab'
clam = text[0]; //Устанавливает однострочной переменной значение 'A'
text[1] = clam; //Меняет 'r' на 'A', сейчас получилось 'AAab'
</pawn>

То, что вы не можете сделать, это соотнести символы массивов со строками. Внутреннее хранение отличается. Например:
<pawn>
new clams[] = "Clams"; //Не верно, нужен тип String:
new clams[] = {'C', 'l', 'a', 'm', 's', 0}; //Верно, но это НЕ СТРОКА.
</pawn>

=Функции=
Функции, как отмечалось ранее, имеют отдельные составляющие кода, которые выполняют определенные действия. Функции могут быть задействованы или '''вызвоны''' с '''параметрами''', которые дают особые настройки.

Существуют два типа вызова функции:
*'''прямой вызов''' - Вы специально вызываете функцию в своем коде.
*'''обратный вызов''' - Применение вызова функций в Вашем коде, как если бы это было событием триггера (совокупность условий, инициирующих выполнение действия).

Существуют пять видов функций:
*'''native''': Прямая, внутренняя функция, предусмотренная в приложении.
*'''public''': Функция обратного вызова, что делает её видимой для приложения и других сценариев.
*'''normal''': Нормальная функция, которую Вы можете только вызвать.
*'''stock''': Нормальная функция, предусмотренная если включает в себя файл. Если не используется, то не компилируется.
*'''forward''': Эта функция представляет собой глобальное событие, предусмотренная приложением. Если Вы её привели в исполнение, она будет вызвона.

Весь код в Pawn должен существовать в функциях. Это основное отличие от языков, таких как PHP, Perl и Python, которые позволяют Вам писать глобальный код. Это происходит потому, что Pawn вызывается на основе другого языка: он реагирует на действия от родительского приложения, и функции должны быть написаны для обработки этих действий. Хотя наш пример, часто содержат свободно плавающий код, это сделано исключительно для демонстрационных целей. Свободно плавающий код в нашем примере означает, что код является частью ряда функций.

==Описание==
В отличие от переменных, функции, не нужно объявлять, прежде чем использовать их. Функции имеют две части, '''модель''' и '''тело'''. Модель содержит имя Вашей функции и параметры, которые она будет принимать. Тело является контейнером для кода.

Пример функции:
<pawn>
AddTwoNumbers(first, second)
{
new sum = first + second;

return sum;
}</pawn>

Это простая функция. Модель этой строки:
<pawn>AddTwoNumbers(first, second)</pawn>

Распишем по отдельности:
*<tt>AddTwoNumbers</tt> - Название функции.
*<tt>first</tt> - Название первого параметра, который представляет собой простой элемент.
*<tt>second</tt> - Название второго параметра, который представляет собой простой элемент.

Тело представляет собой простой блок кода. Он создает новую переменную, названную <tt>sum</tt>, и присваивает ей значение этих двух параметров, добавленных совместно (другие выражения будут позже). Важно заметить оператор <tt>return</tt>, в котором обозначается конец функции и возврат с полученными значениями из этой функции. Все функции ''возвращают значения'' после завершения. Это означает, например:

<pawn>new sum = AddTwoNumbers(4, 5);</pawn>

Приведенный выше код будет присваивать число 9 к sum. Функция получает два значения и передает новое значение sum в качестве '''возвращаемого значения'''. Если функция не имеет возвращаемого значения или не имеет значений для возврата, то возвращается 0 по умолчанию.

Функция может принимать любые типы значений. Она может вернуть любую однострочную переменную, но не массивы или строки. Пример:
<pawn>Float:AddTwoFloats(Float:a, Float:b)
{
new Float:sum = a + b;

return sum;
}</pawn>

''Заметим, что если в приведенной выше функции, Вам вернулась не Float значение, Вы получите не соответствие значений.''

Можно, конечно, передавать переменные в функции:
<pawn>new numbers[3] = {1, 2, 0};

numbers[2] = AddTwoNumbers(numbers[0], numbers[1]);</pawn>

Заметим, что однострочные переменные передаются '''по значению'''. То есть, их значение не может быть изменено функцией. Например:
<pawn>new a = 5;

ChangeValue(a);

ChangeValue(b)
{
b = 5;
}</pawn>

Этот код не будет менять значение <tt>a</tt>. Это происходит потому, что копия этого значения в <tt>a</tt> передается вместо <tt>a</tt> самостоятельно.

Больше примеров функций будут демонстрироваться и в других частях статьи.

==Publics==
Публичные функции используются для осуществления обратных вызовов. Вы не должны создавать какую-либо публичную функцию, если это вынудит выполнение обратного вызова. Например, вот два обратных вызова из <tt>sourcemod.inc</tt>:

<pawn>forward OnPluginStart();
forward OnClientDisconnected(client);</pawn>

Чтобы выполнить и получить эти два события, Вы должны написать такие функции как:

<pawn>public OnPluginStart()
{
/* Код здесь */
}

public OnClientDisconnected(client)
{
/* Код здесь */
}</pawn>

Ключевое слово '''public''' делает функцию публичной, а также позволяет родительскому приложению непосредственно вызывать функцию.

==Natives==
Natives имеют встроенные функции, предоставляемые приложением. Вы можете вызвать их, как если бы они были normal функциями. Например, SourceMod имеет следующие функции:

<pawn>native FloatRound(Float:num);</pawn>

Её можно вызвать таким образом:
<pawn>new num = FloatRound(5.2); //Результат в num = 5</pawn>

==Параметры массива==
Вы можете передавать массивы или строки в качестве параметров. Важно отметить, что они идут '''как ссылка'''. То есть не делать копию данных, а отдавать непосредственно ссылки на данные. Существует простой способ объяснить это более конкретно.

<pawn>
new example[] = {1, 2, 3, 4, 5};

ChangeArray(example, 2, 29);

ChangeArray(array[], index, value)
{
array[index] = value;
}</pawn>

Эта функция устанавливает заданный индекс в массиве с учетом значений. Когда она запускается на примере нашего массива, она меняет индекс 2 для значения 3 на 29. То есть:
<pawn>example[2] = 29;</pawn>

Это возможно лишь потому, что массив может быть непосредственно изменён. Чтобы предотвратить массив от изменения, можно пометить его как постоянную <tt>const</tt>. Это позволит понизить риск на ошибку в коде от её изменения. Например:

<pawn>CantChangeArray(const array[], index, value)
{
array[index] = value; //Не компилируется
}</pawn>

Это хорошая идея использовать <tt>const</tt> в параметрах массивов и Вы будете точно знать, что массив не будет изменен; это может предотвратить ошибки кодирования.

=Выражения=
Выражения являются точно такими же, какими они существуют в математике. Это группы операторов/символов, которые приходятся на один фрагмент данных. Они часто заключены в скобках (внутри скобок). Они содержат строгий "порядок операций". Они могут содержать переменные, функции, цифры и выражения сами могут быть вложенные внутрь других выражений, и даже приняты в качестве параметров.

Приведем пример простейшего выражения:
<pawn>
0; //Возвращает число 0
(0); //Так же возвращает число 0
</pawn>

Хотя выражения могут возвращать значения, они также могут ответить какое значение содержит ответ ''ноль или не ноль''. В этом смысле, ''ноль'' является ''ложью'' (false), а ''не нулевое'' значение ''истиной'' (true). Например, -1 ''истина'' в Pawn, поскольку она не является нулем. Не думайте, что отрицательные числа являются ложными.

Порядок операций выражения аналогичен языку C. PMDAS: Parenthesis, Multiplication, Division, Addition, Subtraction. Вот несколько примеров выражений:
<pawn>
5 + 6; //Вычисляет как 11
5 * 6 + 3; //Вычисляет как 33
5 * (6 + 3); //Вычисляет как 45
5.0 + 2.3; //Вычисляет как 7.3
(5 * 6) % 7; //Modulo operator, вычисляет как 2
(5 + 3) / 2 * 4 - 9; //Вычисляет как 7
</pawn>

Как уже отмечалось, выражения могут содержать переменные, или даже функции:
<pawn>
new a = 5 * 6;
new b = a * 3; //Вычисляет как 90
new c = AddTwoNumbers(a, b) + (a * b);
</pawn>

==Операторы==
Есть несколько полезных дополнительных операторов в Pawn. Первый набор упрощает аутоагрегацию выражения. Например:
<pawn>new a = 5;

a = a + 5;</pawn>

Может быть переписан, как:
<pawn>new a = 5;
a += 5;</pawn>

Это верно в отношении следующих операторов в Pawn:
*Four-function: *, /, -, +
*Bit-wise: |, &, ^, ~, <<, >>

Кроме того, существуют инкремент/декремент операторы:
<pawn>a = a + 1;
a = a - 1;</pawn>

Может быть упрощено, как:
<pawn>a++;
a--;</pawn>

Дополнительно отметим, что ++ или -- может быть представлен до переменной (до-инкремент, до-декремент) или после переменной (пост-инкремент, пост-декремент). Разница заключается в том, как остальная часть выражения содержащие их, видит результат.

* ''До:'' Переменная увеличивается до определения и остальная часть выражения видит новое значение.
* ''Пост:'' Переменная увеличивается после определения и остальная часть выражения видит старое значение.

Иными словами, <tt>a++</tt> определяет значение как <tt>a</tt> в то время как <tt>++a</tt> определяет значение как <tt>a + 1</tt>. В обоих случаях <tt>a</tt> увеличивается на <tt>1</tt>.

Например:

<pawn>new a = 5;
new b = a++; // b = 5, a = 6 (1)
new c = ++a; // a = 7, c = 7 (2)
</pawn>

(1) <tt>b</tt> присваивается <tt>a</tt> со ''старым'' значением, ''до'' того, как он будет увеличено до <tt>6</tt>. (2) <tt>c</tt> присваивается <tt>a</tt> с ''новым'' значением, ''после'' того, как он увеличивается до <tt>7</tt>.

==Операторы сравнения==
Существуют шесть операторов для сравнения двух числовых значений, а результат является либо истиной (не ноль) или ложью (ноль):
*<tt>a == b</tt> - Действительно, если и b имеет то же значение.
*<tt>a != b</tt> - Действительно, если b имеет другое значение.
*<tt>a > b</tt> - Действительно, если оно больше b
*<tt>a >= b</tt> - Действительно, если оно больше или равно b
*<tt>a < b</tt> - Действительно, если оно меньше b
*<tt>a <= b</tt> - Действительно, если оно меньше или равно b

Например:
<pawn>
(1 != 3); //Определяется как истина, поскольку 1 не равно 3.
(3 + 3 == 6); //Определяется как истина, поскольку 3+3 равно 6.
(5 - 2 >= 4); //Определяется как ложь, поскольку 3 меньше 4.
</pawn>

Заметим, что эти операторы не работают с массивами и строками. То есть, вы не можете сравнить их с помощью <tt>==</tt>.

==Действительные операторы==
Действительные операторы могут быть скомбинированы тремя булевыми (boolean) операторами:
*<tt>a && b</tt> - Истина, если a и b истинные. Ложь, если a и (или) b ложные.
{| border="1" cellpadding="2" cellspacing="0" align="center"
! <tt>&&</tt> !! 0 !! 1
|-
! 0
| 0 || 0
|-
! 1
| 0 || 1
|}
*<tt>a || b</tt> - Истина, если a или b (или обе переменные) истинные. Ложь, если обе переменные a и b ложные.
{| border="1" cellpadding="2" cellspacing="0" align="center"
! <tt><nowiki>||</nowiki></tt> !! 0 !! 1
|-
! 0
| 0 || 1
|-
! 1
| 1 || 1
|}
*<tt>!a</tt> - Истина, если a ложь. Ложь, если a истина.
{| border="1" cellpadding="2" cellspacing="0" align="center"
! <tt>!</tt> !! 0 !! 1
|-
!
| 1 || 0
|}

Например:
<pawn>
(1 || 0); //Определяется как истина, так как выражение 1 истинное
(1 && 0); //Определяется как ложь, так как выражение 0 ложное
(!1 || 0); //Определяется как ложь, так как выражение !1 ложное.
</pawn>

==Левое/правое значения==
Два важных понятия левого и правого значений, или левостороннее и правостороннее значения. Левостороннее значение имеет то, что появляется на левой стороне выражения, а правостороннее значение - появляется на правой стороне выражения.

Например:
<pawn>
new a = 5;</pawn>

В этом примере <tt>a</tt> является левосторонним значением и <tt>5</tt> является правосторонним значением.

Правила:
*'''Выражения никогда не будут левосторонними значениями'''.
*'''Переменные являются двумя, левосторонними и правосторонними значениями'''.

=Условия=
Условия позволяют Вам запускать код, определенное условие выполнено.

==Если соответствует==
Если соответствует одно или более условий. Например:

<pawn>
if (a == 5)
{
/* Код будет запущен, если условие будет истинным */
}</pawn>

Они могут быть расширены для более сложных случаев:
<pawn>
if (a == 5)
{
/* Код */
}
else if (a == 6)
{
/* Код */
}
else if (a == 7)
{
/* Код */
}</pawn>

Вы так же можете обрабатывать случаи, даже если выражение не верно. Например:
<pawn>
if (a == 5)
{
/* Код */
}
else
{
/* Код, который будет запущен если нет истинного выражения */
}</pawn>

==Оператор выбора==
Оператор выбора будет ограничен условием. Он необходим для выражения, выполняющего код для целого ряда возможных значений. Например:

<pawn>
switch (a)
{
case 5:
{
/* Код */
}
case 6:
{
/* Код */
}
case 7:
{
/* Код */
}
case 8, 9, 10:
{
/* Код */
}
default:
{
/* будет запущен, если не одно условие не соответствует */
}
}</pawn>

В отличие от некоторых других языков, оператор выбора не проваливается. То есть существуют случаи, когда код не будет запущен. При случае совпадения его код выполняется, а ключ является местом для немедленного прекращения.

=Циклы=
Циклы позволяют Вам без труда повторять выполнение кода, пока условие станет истинным.

==For циклы==
For циклы, это циклы, которые состоят из четырех частей:
*Оператор '''инициализации''' - запускается один раз перед первым циклом.
*Оператор '''условия''' - проверяет условие и запускает следующий цикл, в том числе первый. Цикл прекращается, когда это выражение становится ложным.
*Оператор '''итерации''' - запускается после каждого цикла.
* '''тело''' цикла - запускается каждый раз, пока оператор '''условия''' вычисляется как истинный.

<pawn>
for ( /* инициализация */ ; /* условие */ ; /* итерация */ )
{
/* тело */
}
</pawn>

Простым примером является функция сложения массива:
<pawn>
new array[10] = {1, 2, 3, 4, 5, 6, 7, 8, 9, 10};
new sum = SumArray(array, 10);

SumArray(const array[], count)
{
new total;

for (new i = 0; i < count; i++)
{
total += array[i];
}

return total;
}</pawn>

По отдельности:
*<tt>new i = 0</tt> - Создает новую переменную для цикла, и устанавливает её в 0.
*<tt>i < count</tt> - Только запускает цикл, если <tt>i</tt> меньше, чем <tt>count</tt>. Это гарантирует, что чтение цикла прекращается в определенный момент. В этом случае, мы не хотим читать недействительные индексы в массиве.
*<tt>i++</tt> - Увеличивает <tt>i</tt> на единицу после каждого цикла. Это гарантирует, что цикл не будет запущен вечно; в конце концов <tt>i</tt> станет слишком большим, и цикл завершится.

Таким образом, функция <tt>SumArray</tt> будет циклом каждого действительного индекса массива, каждый раз добавляя это значение в sum. Для циклов очень распространены массивы такие, как в нашем примере.

==While циклы==
While циклы являются менее распространенными, чем for циклы, но на самом деле это более простые циклы. Они имеют только две части:
*Оператор '''условия''' - проверяется перед началом каждого цикла. Цикл прекращается, когда условие становится ложным.
*'''тело''' цикла - запускается каждый раз пока цикл выполняется.

<pawn>
while ( /* условие */ )
{
/* тело */
}
</pawn>

До тех пор, пока условие выражения остается истинным, цикл будет выполняться. Каждый for цикл может быть переписан, как while цикл:

<pawn>
/* инициализация */
while ( /* условие */ )
{
/* тело */
/* итерация */
}
</pawn>

Вот предыдущий for цикл переписан как while цикл:
<pawn>
SumArray(const array[], count)
{
new total, i;

while (i < count)
{
total += array[i];
i++;
}

return total;
}</pawn>

Существуют также '''do...while''' циклы, которые используются еще реже. Они работают как и while циклы, но проверяют условие ПОСЛЕ каждого цикла, а не перед ним. Это означает, что цикл всегда будет запущен, по крайней мере один раз. Например:

<pawn>
do
{
/* тело */
}
while ( /* условие */ );
</pawn>

==Управление циклами==
Существуют два случая, в которых Мы хотели бы контролировать цикл:
*'''пропустить''' одну итерацию или цикл и продолжить выполнение цикла как обычно, или;
*'''разорвать''' цикл целиком, прежде чем он закончится.

Допустим у вас есть функция, которая принимает массив и ищет соответствия цифр. Вы хотите его остановить, когда число будет найдено:
<pawn>
/**
* Возвращает массив, если индекс значения, или -1, не найдены.
*/
SearchInArray(const array[], count, value)
{
new index = -1;

for (new i = 0; i < count; i++)
{
if (array[i] == value)
{
index = i;
break;
}
}

return index;
}</pawn>

Конечно, эту функцию можно вернуть и способом <tt>return i</tt>, но пример показывает, как <tt>break</tt> может остановить цикл.

Кроме того, ключевое слово <tt>continue</tt> пропускает итерации цикла. Например, Мы хотим суммировать все четные числа:

<pawn>
SumEvenNumbers(const array[], count)
{
new sum;

for (new i = 0; i < count; i++)
{
/* If divisibility by 2 is 1, we know it's odd */
if (array[i] % 2 == 1)
{
/* Пропускаем оставшуюся часть итерации цикла */
continue;
}
sum += array[i];
}

return sum;
}</pawn>

=Область действия=
Область действия относится к '''удобочитаемости''' кода. Это означает, что код одного уровня не может быть "виден" в коде другого уровня. Пример:

<pawn>
new A, B, C;

Function1()
{
new B;

Function2();
}

Function2()
{
new C;
}</pawn>

В этом примере, <tt>A</tt>, <tt>B</tt>, и <tt>C</tt> имеют '''глобальную область действия'''. Их можно увидеть в любой функции. Вместе с тем, <tt>B</tt> в функции <tt>Function1</tt> не является той же переменной, как <tt>B</tt> на глобальном уровне. Вместо этого она находится в '''локальной области действия''', и поэтому является '''локально изменяемой'''.

Кроме того, функции <tt>Function1</tt> и <tt>Function2</tt> ничего не знают о существовании других переменных.

Она так же является не только локальной переменной функции <tt>Function1</tt>, но и создается заново каждый раз, когда функция вызывается. Попробуйте представить это:
<pawn>
Function1()
{
new B;

Function1();
}</pawn>

В приведенном выше примере, функция <tt>Function1</tt> вызывает сама себя. Конечно, это бесконечной рекурсии (а это очень плохо), но идея заключается в том, что каждый раз, когда функция срабатывает, то создается новая копия <tt>B</tt>. Когда функция завершается, <tt>B</tt> уничтожается, и её значение теряется.

Это свойство можно объяснить проще тем, что область действия переменной равна уровню её вложенности. То есть, переменная на глобальной области действия видна для всех функций. Переменная в локальной области действия видна всему блоку кода расположенному "ниже" этого уровня. Например:

<pawn>Function1()
{
new A;

if (A)
{
A = 5;
}
}</pawn>

Приведенный выше код является действительным, поскольку в область действия распространяется по всей функции. Однако этот код, работать не будет:
<pawn>
Function1()
{
new A;

if (A)
{
new B = 5;
}

B = 5;
}</pawn>

Отметим, что <tt>B</tt> объявляется в новом блоке кода. Это означает, что <tt>B</tt> доступна только в том блоке кода, в котором была создана (и всем под-блокам вложенных внутри него). Как только блок кода прекращается, <tt>B</tt> становится не действительной.

=Динамические массивы=
Динамические массивы это массивы, которые не имеют фиксированного размера. Например:

<pawn>Function1(size)
{
new array[size];

/* Код */
}</pawn>

Динамические массивы могут иметь любое выражение, соответствующее их размеру до тех пор, пока выражение вычисляется, как число большее чем 0. Как и для обычных массивов, SourcePawn не сможет узнать размер массива после того, как он будет создан; Вы должны задать его, если хотите использовать массив позднее.

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

=Расширенное объявление переменных=
Переменные могут быть объявлены более длинным путем чем просто <tt>new</tt>.

==decl==
===Назначение===
По умолчанию, все переменные в Pawn будут инициализированы как нуль. Если есть явная инициализация, переменная инициализируется для выражения <tt>=</tt> определенным символам. В локальной области действия, это может потребовать время на выполнение. Ключевое слово <tt>decl</tt> (которое действительно только в локальной области действия) было введено, чтобы позволить решать пользователю, хочит ли он инициализировать переменную или нет.

Примечание: <tt>decl</tt> не должно быть использовано на одну однострочную переменную. Это почти никогда не будет выгодно.

===Объяснение===
Например:

<pawn>
new c = 5;
new d;
new String:blah[512];

Format(blah, sizeof(blah), "%d %d", c, d);
</pawn>

В этом коде, <tt>c</tt> равна 5 и <tt>d</tt> равна 0. Во время выполнения этого кода затраты на инициализацию незначительные. Вместе с тем, <tt>blah</tt> является большим массивом, и затраты на инициализацию всего массива могут быть больше 0 сек. и иметь плохие последствия в определенных ситуациях.

Заметим, что <tt>blah</tt> не должен быть нулевой. В период времени с объявления <tt>new</tt> и и перемещения в <tt>Format()</tt>, массив <tt>blah</tt> никогда не будет загружен или прочитан. Данный код будет более эффективен, если будет написанный следующим образом:

<pawn>
new c = 5;
new d;
decl String:blah[512];

Format(blah, sizeof(blah), "%d %d", c, d);
</pawn>

===Предостережения===
Обратная сторона <tt>decl</tt> состоит в том, что его переменные будут начинаться с "ненужного" содержания. Например, если мы будем использовать:

<pawn>
new c = 5;
new d;
decl String:blah[512];

PrintToServer("%s", blah);

Format(blah, sizeof(blah), "%d %d", c, d);
</pawn>

Этот код может привести к падению сервера, так как массив <tt>blah</tt> может быть полностью испорчен (строки требуют нулевой символ, который может отсутствовать). Точно так же, если мы сделаем:

<pawn>
new c = 5;
decl d;
decl String:blah[512];

Format(blah, sizeof(blah), "%d %d", c, d);
</pawn>

Значение <tt>d</tt> в настоящее время не определенно. Оно может быть любым значением, отрицательным или положительным.

Заметим, что это легко и эффективно обезопасит строки. Пример ниже показывает, как предотвратить строки от мусора:
<pawn>
decl String:blah[512];

blah[0] = '\0';
</pawn>

===Golden Rules===
*'''Only use decl if in between declaring and loading/reading the value, you are absolutely sure there is at least one store/set operation that gives the variable valid data.'''
*'''Do not prematurely optimize.''' Likewise, there is no need to use <tt>decl</tt> on non-arrays, because there is no added expense for initializing a single cell value.

===Notes===
This example is NOT as efficient as a <tt>decl</tt>:
<pawn>
new String:blah[512] = "a";
</pawn>

Even though the string is only one character, the <tt>new</tt> operator guarantees the rest of the array will be zeroed as well.

Also note, it is invalid to explicitly initialize a <tt>decl</tt>:
<pawn>decl String:blah[512] = "a";</pawn>

The above code will not compile, because the purpose of <tt>decl</tt> is to avoid any initialization.

==static==
The <tt>static</tt> keyword is available at global and local scope. It has different meanings in each.

===Global static===
A global static variable can only be accessed from within the same file. For example:

<pawn>//file1.inc
static Float:g_value1 = 0.15f;

//file2.inc
static Float:g_value2 = 0.15f;</pawn>

If a plugin includes both of these files, it will not be able to use either <tt>g_value1</tt> or <tt>g_value2</tt>. This is a simple information hiding mechanism, and is similar to declaring member variables as <tt>private</tt> in languages like C++, Java, or C#.

===Local static===
A local static variable is a global variable that is only visible from its local lexical scope. For example:

<pawn>
MyFunction(inc)
{
static counter = -1;

counter += inc;

return counter;
}</pawn>

In this example, <tt>counter</tt> is technically a global variable -- it is initialized once to -1 and is never initialized again. It does not exist on the stack. That means each time <tt>MyFunction</tt> runs, the <tt>counter</tt> variable and its storage in memory is the same.

Take this example:
<pawn>MyFunction(5);
MyFunction(6);
MyFunction(10);</pawn>

In this example, <tt>counter</tt> will be <tt>-1 + 5 + 6 + 10</tt>, or <tt>20</tt>, because it persists beyond the frame of the function. Note this may pose problems for recursive functions: if your function may be recursive, then <tt>static</tt> is usually not a good idea unless your code is re-entrant.

The benefit of a local static variable is that you don't have to clutter your script with global variables. As long as the variable doesn't need to be read by another function, you can squirrel it inside the function and its persistence will be guaranteed.

Note that statics can exist in any local scope:

<pawn>
MyFunction(inc)
{
if (inc > 0)
{
static counter;
return (counter += inc);
}
return -1;
}</pawn>

[[Category:Ru:SourceMod Scripting]]

Ru:Introduction to SourcePawn

2008-12-26T11:51:51Z

Frenzzy: /* Explanation */

Это руководство призвано дать Вам самые основные представления по основам написания сприптов в SourcePawn. [[Pawn]] это "скриптовый" язык используемый для внедрения функциональности в других программах. Это означает, что это не самостоятельный язык, как C++ или Java, и его элементы будут отличаться в различных приложениях. SourcePawn это вариация языка Pawn используемая в [[SourceMod]].

Это руководство не расскажет Вам как писать SourceMod плагины; оно предназначено для получения общих представлений о синтаксисе и семантике этого языка. Читайте отдельную статью [[Ru:Introduction to SourceMod Plugins]] (Введение в SourceMod плагины), для введения в SourceMod API.

=Введение для новичков=
Этот раздел создан не для программистов. Если Вы по прежнему в замешательстве, Вы можете прочитать книги о других языках программирования, таких как PHP, Python, или Java, чтобы получить более полное представление о программировании.

==Идентификаторы/Ключевые слова==
Идентификаторы представляет собой набор букв, цифр и/или нижнего подчеркивания, что представляет собой нечто уникальное. Идентификаторы вводятся с учетом регистра (в отличие от PHP, где иногда это не требуется). Идентификаторы не начинаются с какого-либо специального символа, но они должны начинаться с буквы.

Есть несколько зарезервированных символов, которые имеют особое значение. Например, <tt>if</tt>, <tt>for</tt>, и <tt>return</tt> специальные конструкции в языке, которые будут описаны позднее. Они не могут быть использованы в качестве названий идентификаторов.

==Переменные==
Существует несколько важных конструкций, которые Вы должны знать, прежде чем приступить к написанию сценария. Во-первых, это '''переменные'''. Переменная это идентификатор, который содержит данные. Например, переменная "a" может содержать числа "2", "16", "0", и так далее. Переменные создаются для хранения данных внутри программы. Переменные должны быть объявлены до их использования, с помощью ключевого слова "new". Данные можно присвоить переменной, используя знак равенства (=). Пример:

<pawn>new a, b, c, d;

a = 5;
b = 16;
c = 0;
d = 500;</pawn>

В SourcePawn, переменные бывают двух типов, которые будут более подробно описаны далее.
*Однострочные (могут содержать только произвольные числовые данные), как показано выше.
*Многострочные (могут содержать целый ряд текстовых символов)

==Функции==
Следующим важным понятием являются '''функции'''. Функции идентификаторов или имен, которые выполняют действия. Это означает, что когда вы их активируете, они выполняют конкретную последовательность кода. Есть несколько типов функций, но все функции активируется одинаковым образом. "Вызов функции" является термином ссылающимся на функцию действия. Функция числовых переменных строятся так:
<pawn>функция(<параметры>)</pawn>

Примеры:

<pawn>show(56); //Активирует функцию "show" и присваивает ей число 56
show(); //Активирует функцию "show" без каких-либо данных, пустую
show(a); //Активирует функцию "show" и присваивает ей переменную с данными
</pawn>

Каждый фрагмент данных передаваемый вызываемой функции, называется '''параметр'''. Функция может иметь любое количество параметров (но есть "допустимый" предел в SourceMod: 32). Параметры будут описаны далее в этой статье.

==Комментарии==
Примечания и любой текст, который пишется после "//" считается "Комментарием", а не фактическим кодом. Есть два стиля комментариев:
*<tt>//</tt> - Двойная косая черта, всё следующие после этой строки игнорируется.
*<tt>/* */</tt> - Много-строчный комментарий, весь текст, внутри звездочек игнорируются. You cannot nest these.

==Массивы==
Описание массивов. Вы можете группировать код в виде "массивов", разделенных { и }. Это фактически создает возможность работать с целым массивом как с одним оператором. Например:

<pawn>{
here;
is;
some;
code;
}</pawn>

Массивы с фигурными скобками используются достаточно широко в программировании. Массивы кода могут быть вложенными друг в друга. Это хорошая возможность адаптировать последовательность когда и сделать его удобочитаемым, благодаря отступам код не будет смотреться как одна большая и длинная макаронина.

=Особенности языка=
Pawn может показаться очень похожим на другие языки программирования, например C, но Pawn от них фундаментально отличается. Не столь важно, чтобы Вы сейчас же поняли его отличия, но они понадобятся, если Вы уже знаете один из языков программирования.
*'''Pawn не печатает''' Pawn имеет только один тип данных - '''однострочный'''. Подробнее будет описано позже. [В дальнейшем автор рассказывает, что существует два типа данных: однострочный и многострочный]
*'''Pawn не собирает мусор''' Pawn, как язык, не имеет встроенных ресурсов памяти, и потому он не мусорит. Если функция выделит память, то Вы отвечаете за её освобождение.
*'''Pawn не объектно-ориентированный язык''' Pawn является процедурным, и полагается на подпрограммы. Также у него нету C подобных структур.
*'''Pawn не функциональный.''' Pawn является процедурным, и не поддерживает функции "лямбды" (Lambda), поздние присвоения, и все то, что можно найти в языках высшего уровня, таких как Phyton и Ruby.
*'''Pawn однопоточный''' As of this writing, Pawn is not thread safe.
*'''Pawn не интерпретируемый''' Ну, почти. Он интерпретируется на очень низком уровне. Вы должны скомпилировать код, из которого получится бинарный файл. Эта программа будет работать на той платформе, которую использует хост. Это ускоряет загрузку и позволяет легче находить ошибки.

Этот язык был выпущен ITB CompuPhase. Язык разработан для устройств низкого уровня и таким образом конечные программы очень маленькие по размеру и очень быстрые.

=Переменные=
В Pawn есть всего два типа переменных: '''однострочные''' и '''многострочные'''. Однострочные могут содержать 32 бита цифровых данных. Многострочные - последовательный список из UTF-8 символов.

'''однострочные''' не имеет своего типа, однако они могут быть '''маркированы'''(tagged). Тег позволяет Вам указывать, где определенную ячейку можно использовать. Типичные теги:
*(пусто), или '''_''' - Нет тега. Обычно используют для целых чисел ([http://en.wikipedia.org/wiki/Integer Integers]).
*'''Float''' - используют для чисел с плавающей точкой (небольших).
*'''bool''' - используют для хранения значений '''true''' (истина) или '''false''' (ложь).

Со строками все по другому, они будут рассмотрены далее.

==Объявления==
Примеры разных правильных объявлений переменных.
<pawn>
new a = 5;
new Float:b = 5.0;
new bool:c = true;
new bool:d = 0; //Работает, поскольку 0 равно false (ложь)
</pawn>

Неправильные объявления переменных
<pawn>
new a = 5.0; //Несоответствие тегов. 5.0 с тегом Float
new Float:b = 5; //Несоответствие тегов. 5 без тега.
</pawn>

Если переменная не определена в объявлении то ее значения станет 0
<pawn>
new a; //значение 0
new Float:b; //значение 0.0
new bool:c; //значение false
</pawn>

==Присвоение==
Переменным могут быть присвоены данные после создания. Пример:
<pawn>new a, Float:b, bool:c;

a = 5;
b = 5.0;
c = true;
</pawn>

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

==Описание==
Массив объявляется с помощью квадратных скобок. Вот некоторые примеры массивов:
<pawn>
new players[32]; //Набор из 32 однострочных (числовых) данных
new Float:origin[3]; //Набор из 3 чисел с плавающей точкой
</pawn>

По умолчанию, массивам присваиваются нули. Вы можете присвоить им разные значения по умолчанию, однако:
<pawn>
new numbers[5] = {1, 2, 3, 4, 5}; //Набор 1, 2, 3, 4, 5 из однострочных данных.
new Float:origin[3] = {1.0, 2.0, 3.0}; //Набор 1.0, 2.0, 3.0 из однострочных данных.
</pawn>

Вы можете оставить массив без размера, если вы собираетесь заранее присвоить ему данные. Например:
<pawn>
new numbers[] = {1, 3, 5, 7, 9};
</pawn>

Компилятор будет автоматически делать вывод о том, что Вы хотите получить массив размером 5.

==Использование==
Использование массива равносильно использованию обычных переменной. Единственное отличие массива состоит в том, что он должен быть '''индексируемым'''. Индексирование массива означает присутствие возможности выбрать элемент, который Вы хотите использовать.

Вот пример кода с использованием индексов:
<pawn>
new numbers[5], Float:origin[3];

numbers[0] = 1;
numbers[1] = 2;
numbers[2] = 3;
numbers[3] = 4;
numbers[4] = 5;
origin[0] = 1.0;
origin[1] = 2.0;
origin[2] = 3.0;
</pawn>

Заметим, что '''индекс''' это текст, который находится в квадратных скобках. Индекс всегда начинается с нуля. То есть, если массив имеет N элементов, его действительный индекс от 0 до N-1. Доступ к данным с индексами работает так же, как с обычной переменной.

Использование неверного индекса вызовет ошибку. Например:
<pawn>
new numbers[5];

numbers[5] = 20;</pawn>

Это может выглядеть верно, но число 5 не является допустимым индексом. Наибольшим значением индекса является число 4.

Вы можете использовать любые выражения, как индекс. Например:
<pawn>new a, numbers[5];

a = 1; //Сделает a = 1
numbers[a] = 4; //Сделает numbers[1] = 4
numbers[numbers[a]] = 2; //Сделает numbers[4] = 2
</pawn>

Выражения будут обсуждаться подробнее в конце статьи.

=Строки=
Строки являются удобным способом хранения текста. Символы хранятся в массиве. Строка ограничивается '''нулевым символом''', или 0. Без нулевого символа, Pawn не знает, где остановить чтение строки. Все строки в SourcePawn используют кодировку UTF-8.

Отметим, что строки имеют комбинацию из массивов и однострочных переменных. В отличие от других языков, это означает, что Вы должны знать заранее, как много места будут использовать строки. Это означает, что строки не являются динамичными. Они могут лишь вырасти до размера, которым Вы их ограничили.

''Примечание для специалистов: они фактически не однострочные. SourcePawn использует 8-битный строки для хранения массивов в качестве оптимизации. Это и есть то, что делает строки типом, а не меткой.''

==Использование==
Строки были созданы почти в равной степени и для массивов. Например:
<pawn>
new String:message[] = "Hello!";
new String:clams[6] = "Clams";
</pawn>

Это равносильно следующему:
<pawn>
new String:message[7], String:clams[6];

message[0] = 'H';
message[1] = 'e';
message[2] = 'l';
message[3] = 'l';
message[4] = 'o';
message[5] = '!';
message[6] = 0;
clams[0] = 'C';
clams[1] = 'l';
clams[2] = 'a';
clams[3] = 'm';
clams[4] = 's';
clams[5] = 0;
</pawn>

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

Заметим, что строка должна быть заключена в двойных кавычках, а символ в одиночных.

==Символы==
Особенность текста может быть использована в любой строке или однострочной переменной. Например:
<pawn>new String:text[] = "Crab";
new clam;

clam = 'D'; //Устанавливает однострочной переменной значение 'D'
text[0] = 'A'; //Меняет 'C' на 'A', сейчас получилось 'Arab'
clam = text[0]; //Устанавливает однострочной переменной значение 'A'
text[1] = clam; //Меняет 'r' на 'A', сейчас получилось 'AAab'
</pawn>

То, что вы не можете сделать, это соотнести символы массивов со строками. Внутреннее хранение отличается. Например:
<pawn>
new clams[] = "Clams"; //Не верно, нужен тип String:
new clams[] = {'C', 'l', 'a', 'm', 's', 0}; //Верно, но это НЕ СТРОКА.
</pawn>

=Функции=
Функции, как отмечалось ранее, имеют отдельные составляющие кода, которые выполняют определенные действия. Функции могут быть задействованы или '''вызвоны''' с '''параметрами''', которые дают особые настройки.

Существуют два типа вызова функции:
*'''прямой вызов''' - Вы специально вызываете функцию в своем коде.
*'''обратный вызов''' - Применение вызова функций в Вашем коде, как если бы это было событием триггера (совокупность условий, инициирующих выполнение действия).

Существуют пять видов функций:
*'''native''': Прямая, внутренняя функция, предусмотренная в приложении.
*'''public''': Функция обратного вызова, что делает её видимой для приложения и других сценариев.
*'''normal''': Нормальная функция, которую Вы можете только вызвать.
*'''stock''': Нормальная функция, предусмотренная если включает в себя файл. Если не используется, то не компилируется.
*'''forward''': Эта функция представляет собой глобальное событие, предусмотренная приложением. Если Вы её привели в исполнение, она будет вызвона.

Весь код в Pawn должен существовать в функциях. Это основное отличие от языков, таких как PHP, Perl и Python, которые позволяют Вам писать глобальный код. Это происходит потому, что Pawn вызывается на основе другого языка: он реагирует на действия от родительского приложения, и функции должны быть написаны для обработки этих действий. Хотя наш пример, часто содержат свободно плавающий код, это сделано исключительно для демонстрационных целей. Свободно плавающий код в нашем примере означает, что код является частью ряда функций.

==Описание==
В отличие от переменных, функции, не нужно объявлять, прежде чем использовать их. Функции имеют две части, '''модель''' и '''тело'''. Модель содержит имя Вашей функции и параметры, которые она будет принимать. Тело является контейнером для кода.

Пример функции:
<pawn>
AddTwoNumbers(first, second)
{
new sum = first + second;

return sum;
}</pawn>

Это простая функция. Модель этой строки:
<pawn>AddTwoNumbers(first, second)</pawn>

Распишем по отдельности:
*<tt>AddTwoNumbers</tt> - Название функции.
*<tt>first</tt> - Название первого параметра, который представляет собой простой элемент.
*<tt>second</tt> - Название второго параметра, который представляет собой простой элемент.

Тело представляет собой простой блок кода. Он создает новую переменную, названную <tt>sum</tt>, и присваивает ей значение этих двух параметров, добавленных совместно (другие выражения будут позже). Важно заметить оператор <tt>return</tt>, в котором обозначается конец функции и возврат с полученными значениями из этой функции. Все функции ''возвращают значения'' после завершения. Это означает, например:

<pawn>new sum = AddTwoNumbers(4, 5);</pawn>

Приведенный выше код будет присваивать число 9 к sum. Функция получает два значения и передает новое значение sum в качестве '''возвращаемого значения'''. Если функция не имеет возвращаемого значения или не имеет значений для возврата, то возвращается 0 по умолчанию.

Функция может принимать любые типы значений. Она может вернуть любую однострочную переменную, но не массивы или строки. Пример:
<pawn>Float:AddTwoFloats(Float:a, Float:b)
{
new Float:sum = a + b;

return sum;
}</pawn>

''Заметим, что если в приведенной выше функции, Вам вернулась не Float значение, Вы получите не соответствие значений.''

Можно, конечно, передавать переменные в функции:
<pawn>new numbers[3] = {1, 2, 0};

numbers[2] = AddTwoNumbers(numbers[0], numbers[1]);</pawn>

Заметим, что однострочные переменные передаются '''по значению'''. То есть, их значение не может быть изменено функцией. Например:
<pawn>new a = 5;

ChangeValue(a);

ChangeValue(b)
{
b = 5;
}</pawn>

Этот код не будет менять значение <tt>a</tt>. Это происходит потому, что копия этого значения в <tt>a</tt> передается вместо <tt>a</tt> самостоятельно.

Больше примеров функций будут демонстрироваться и в других частях статьи.

==Publics==
Публичные функции используются для осуществления обратных вызовов. Вы не должны создавать какую-либо публичную функцию, если это вынудит выполнение обратного вызова. Например, вот два обратных вызова из <tt>sourcemod.inc</tt>:

<pawn>forward OnPluginStart();
forward OnClientDisconnected(client);</pawn>

Чтобы выполнить и получить эти два события, Вы должны написать такие функции как:

<pawn>public OnPluginStart()
{
/* Код здесь */
}

public OnClientDisconnected(client)
{
/* Код здесь */
}</pawn>

Ключевое слово '''public''' делает функцию публичной, а также позволяет родительскому приложению непосредственно вызывать функцию.

==Natives==
Natives имеют встроенные функции, предоставляемые приложением. Вы можете вызвать их, как если бы они были normal функциями. Например, SourceMod имеет следующие функции:

<pawn>native FloatRound(Float:num);</pawn>

Её можно вызвать таким образом:
<pawn>new num = FloatRound(5.2); //Результат в num = 5</pawn>

==Параметры массива==
Вы можете передавать массивы или строки в качестве параметров. Важно отметить, что они идут '''как ссылка'''. То есть не делать копию данных, а отдавать непосредственно ссылки на данные. Существует простой способ объяснить это более конкретно.

<pawn>
new example[] = {1, 2, 3, 4, 5};

ChangeArray(example, 2, 29);

ChangeArray(array[], index, value)
{
array[index] = value;
}</pawn>

Эта функция устанавливает заданный индекс в массиве с учетом значений. Когда она запускается на примере нашего массива, она меняет индекс 2 для значения 3 на 29. То есть:
<pawn>example[2] = 29;</pawn>

Это возможно лишь потому, что массив может быть непосредственно изменён. Чтобы предотвратить массив от изменения, можно пометить его как постоянную <tt>const</tt>. Это позволит понизить риск на ошибку в коде от её изменения. Например:

<pawn>CantChangeArray(const array[], index, value)
{
array[index] = value; //Не компилируется
}</pawn>

Это хорошая идея использовать <tt>const</tt> в параметрах массивов и Вы будете точно знать, что массив не будет изменен; это может предотвратить ошибки кодирования.

=Выражения=
Выражения являются точно такими же, какими они существуют в математике. Это группы операторов/символов, которые приходятся на один фрагмент данных. Они часто заключены в скобках (внутри скобок). Они содержат строгий "порядок операций". Они могут содержать переменные, функции, цифры и выражения сами могут быть вложенные внутрь других выражений, и даже приняты в качестве параметров.

Приведем пример простейшего выражения:
<pawn>
0; //Возвращает число 0
(0); //Так же возвращает число 0
</pawn>

Хотя выражения могут возвращать значения, они также могут ответить какое значение содержит ответ ''ноль или не ноль''. В этом смысле, ''ноль'' является ''ложью'' (false), а ''не нулевое'' значение ''истиной'' (true). Например, -1 ''истина'' в Pawn, поскольку она не является нулем. Не думайте, что отрицательные числа являются ложными.

Порядок операций выражения аналогичен языку C. PMDAS: Parenthesis, Multiplication, Division, Addition, Subtraction. Вот несколько примеров выражений:
<pawn>
5 + 6; //Вычисляет как 11
5 * 6 + 3; //Вычисляет как 33
5 * (6 + 3); //Вычисляет как 45
5.0 + 2.3; //Вычисляет как 7.3
(5 * 6) % 7; //Modulo operator, вычисляет как 2
(5 + 3) / 2 * 4 - 9; //Вычисляет как 7
</pawn>

Как уже отмечалось, выражения могут содержать переменные, или даже функции:
<pawn>
new a = 5 * 6;
new b = a * 3; //Вычисляет как 90
new c = AddTwoNumbers(a, b) + (a * b);
</pawn>

==Операторы==
Есть несколько полезных дополнительных операторов в Pawn. Первый набор упрощает аутоагрегацию выражения. Например:
<pawn>new a = 5;

a = a + 5;</pawn>

Может быть переписан, как:
<pawn>new a = 5;
a += 5;</pawn>

Это верно в отношении следующих операторов в Pawn:
*Four-function: *, /, -, +
*Bit-wise: |, &, ^, ~, <<, >>

Кроме того, существуют инкремент/декремент операторы:
<pawn>a = a + 1;
a = a - 1;</pawn>

Может быть упрощено, как:
<pawn>a++;
a--;</pawn>

Дополнительно отметим, что ++ или -- может быть представлен до переменной (до-инкремент, до-декремент) или после переменной (пост-инкремент, пост-декремент). Разница заключается в том, как остальная часть выражения содержащие их, видит результат.

* ''До:'' Переменная увеличивается до определения и остальная часть выражения видит новое значение.
* ''Пост:'' Переменная увеличивается после определения и остальная часть выражения видит старое значение.

Иными словами, <tt>a++</tt> определяет значение как <tt>a</tt> в то время как <tt>++a</tt> определяет значение как <tt>a + 1</tt>. В обоих случаях <tt>a</tt> увеличивается на <tt>1</tt>.

Например:

<pawn>new a = 5;
new b = a++; // b = 5, a = 6 (1)
new c = ++a; // a = 7, c = 7 (2)
</pawn>

(1) <tt>b</tt> присваивается <tt>a</tt> со ''старым'' значением, ''до'' того, как он будет увеличено до <tt>6</tt>. (2) <tt>c</tt> присваивается <tt>a</tt> с ''новым'' значением, ''после'' того, как он увеличивается до <tt>7</tt>.

==Операторы сравнения==
Существуют шесть операторов для сравнения двух числовых значений, а результат является либо истиной (не ноль) или ложью (ноль):
*<tt>a == b</tt> - Действительно, если и b имеет то же значение.
*<tt>a != b</tt> - Действительно, если b имеет другое значение.
*<tt>a > b</tt> - Действительно, если оно больше b
*<tt>a >= b</tt> - Действительно, если оно больше или равно b
*<tt>a < b</tt> - Действительно, если оно меньше b
*<tt>a <= b</tt> - Действительно, если оно меньше или равно b

Например:
<pawn>
(1 != 3); //Определяется как истина, поскольку 1 не равно 3.
(3 + 3 == 6); //Определяется как истина, поскольку 3+3 равно 6.
(5 - 2 >= 4); //Определяется как ложь, поскольку 3 меньше 4.
</pawn>

Заметим, что эти операторы не работают с массивами и строками. То есть, вы не можете сравнить их с помощью <tt>==</tt>.

==Действительные операторы==
Действительные операторы могут быть скомбинированы тремя булевыми (boolean) операторами:
*<tt>a && b</tt> - Истина, если a и b истинные. Ложь, если a и (или) b ложные.
{| border="1" cellpadding="2" cellspacing="0" align="center"
! <tt>&&</tt> !! 0 !! 1
|-
! 0
| 0 || 0
|-
! 1
| 0 || 1
|}
*<tt>a || b</tt> - Истина, если a или b (или обе переменные) истинные. Ложь, если обе переменные a и b ложные.
{| border="1" cellpadding="2" cellspacing="0" align="center"
! <tt><nowiki>||</nowiki></tt> !! 0 !! 1
|-
! 0
| 0 || 1
|-
! 1
| 1 || 1
|}
*<tt>!a</tt> - Истина, если a ложь. Ложь, если a истина.
{| border="1" cellpadding="2" cellspacing="0" align="center"
! <tt>!</tt> !! 0 !! 1
|-
!
| 1 || 0
|}

Например:
<pawn>
(1 || 0); //Определяется как истина, так как выражение 1 истинное
(1 && 0); //Определяется как ложь, так как выражение 0 ложное
(!1 || 0); //Определяется как ложь, так как выражение !1 ложное.
</pawn>

==Левое/правое значения==
Два важных понятия левого и правого значений, или левостороннее и правостороннее значения. Левостороннее значение имеет то, что появляется на левой стороне выражения, а правостороннее значение - появляется на правой стороне выражения.

Например:
<pawn>
new a = 5;</pawn>

В этом примере <tt>a</tt> является левосторонним значением и <tt>5</tt> является правосторонним значением.

Правила:
*'''Выражения никогда не будут левосторонними значениями'''.
*'''Переменные являются двумя, левосторонними и правосторонними значениями'''.

=Условия=
Условия позволяют Вам запускать код, определенное условие выполнено.

==Если соответствует==
Если соответствует одно или более условий. Например:

<pawn>
if (a == 5)
{
/* Код будет запущен, если условие будет истинным */
}</pawn>

Они могут быть расширены для более сложных случаев:
<pawn>
if (a == 5)
{
/* Код */
}
else if (a == 6)
{
/* Код */
}
else if (a == 7)
{
/* Код */
}</pawn>

Вы так же можете обрабатывать случаи, даже если выражение не верно. Например:
<pawn>
if (a == 5)
{
/* Код */
}
else
{
/* Код, который будет запущен если нет истинного выражения */
}</pawn>

==Оператор выбора==
Оператор выбора будет ограничен условием. Он необходим для выражения, выполняющего код для целого ряда возможных значений. Например:

<pawn>
switch (a)
{
case 5:
{
/* Код */
}
case 6:
{
/* Код */
}
case 7:
{
/* Код */
}
case 8, 9, 10:
{
/* Код */
}
default:
{
/* будет запущен, если не одно условие не соответствует */
}
}</pawn>

В отличие от некоторых других языков, оператор выбора не проваливается. То есть существуют случаи, когда код не будет запущен. При случае совпадения его код выполняется, а ключ является местом для немедленного прекращения.

=Циклы=
Циклы позволяют Вам без труда повторять выполнение кода, пока условие станет истинным.

==For циклы==
For циклы, это циклы, которые состоят из четырех частей:
*Оператор '''инициализации''' - запускается один раз перед первым циклом.
*Оператор '''условия''' - проверяет условие и запускает следующий цикл, в том числе первый. Цикл прекращается, когда это выражение становится ложным.
*Оператор '''итерации''' - запускается после каждого цикла.
* '''тело''' цикла - запускается каждый раз, пока оператор '''условия''' вычисляется как истинный.

<pawn>
for ( /* инициализация */ ; /* условие */ ; /* итерация */ )
{
/* тело */
}
</pawn>

Простым примером является функция сложения массива:
<pawn>
new array[10] = {1, 2, 3, 4, 5, 6, 7, 8, 9, 10};
new sum = SumArray(array, 10);

SumArray(const array[], count)
{
new total;

for (new i = 0; i < count; i++)
{
total += array[i];
}

return total;
}</pawn>

По отдельности:
*<tt>new i = 0</tt> - Создает новую переменную для цикла, и устанавливает её в 0.
*<tt>i < count</tt> - Только запускает цикл, если <tt>i</tt> меньше, чем <tt>count</tt>. Это гарантирует, что чтение цикла прекращается в определенный момент. В этом случае, мы не хотим читать недействительные индексы в массиве.
*<tt>i++</tt> - Увеличивает <tt>i</tt> на единицу после каждого цикла. Это гарантирует, что цикл не будет запущен вечно; в конце концов <tt>i</tt> станет слишком большим, и цикл завершится.

Таким образом, функция <tt>SumArray</tt> будет циклом каждого действительного индекса массива, каждый раз добавляя это значение в sum. Для циклов очень распространены массивы такие, как в нашем примере.

==While циклы==
While циклы являются менее распространенными, чем for циклы, но на самом деле это более простые циклы. Они имеют только две части:
*Оператор '''условия''' - проверяется перед началом каждого цикла. Цикл прекращается, когда условие становится ложным.
*'''тело''' цикла - запускается каждый раз пока цикл выполняется.

<pawn>
while ( /* условие */ )
{
/* тело */
}
</pawn>

До тех пор, пока условие выражения остается истинным, цикл будет выполняться. Каждый for цикл может быть переписан, как while цикл:

<pawn>
/* инициализация */
while ( /* условие */ )
{
/* тело */
/* итерация */
}
</pawn>

Вот предыдущий for цикл переписан как while цикл:
<pawn>
SumArray(const array[], count)
{
new total, i;

while (i < count)
{
total += array[i];
i++;
}

return total;
}</pawn>

Существуют также '''do...while''' циклы, которые используются еще реже. Они работают как и while циклы, но проверяют условие ПОСЛЕ каждого цикла, а не перед ним. Это означает, что цикл всегда будет запущен, по крайней мере один раз. Например:

<pawn>
do
{
/* тело */
}
while ( /* условие */ );
</pawn>

==Управление циклами==
Существуют два случая, в которых Мы хотели бы контролировать цикл:
*'''пропустить''' одну итерацию или цикл и продолжить выполнение цикла как обычно, или;
*'''разорвать''' цикл целиком, прежде чем он закончится.

Допустим у вас есть функция, которая принимает массив и ищет соответствия цифр. Вы хотите его остановить, когда число будет найдено:
<pawn>
/**
* Возвращает массив, если индекс значения, или -1, не найдены.
*/
SearchInArray(const array[], count, value)
{
new index = -1;

for (new i = 0; i < count; i++)
{
if (array[i] == value)
{
index = i;
break;
}
}

return index;
}</pawn>

Конечно, эту функцию можно вернуть и способом <tt>return i</tt>, но пример показывает, как <tt>break</tt> может остановить цикл.

Кроме того, ключевое слово <tt>continue</tt> пропускает итерации цикла. Например, Мы хотим суммировать все четные числа:

<pawn>
SumEvenNumbers(const array[], count)
{
new sum;

for (new i = 0; i < count; i++)
{
/* If divisibility by 2 is 1, we know it's odd */
if (array[i] % 2 == 1)
{
/* Пропускаем оставшуюся часть итерации цикла */
continue;
}
sum += array[i];
}

return sum;
}</pawn>

=Область действия=
Область действия относится к '''удобочитаемости''' кода. Это означает, что код одного уровня не может быть "виден" в коде другого уровня. Пример:

<pawn>
new A, B, C;

Function1()
{
new B;

Function2();
}

Function2()
{
new C;
}</pawn>

В этом примере, <tt>A</tt>, <tt>B</tt>, и <tt>C</tt> имеют '''глобальную область действия'''. Их можно увидеть в любой функции. Вместе с тем, <tt>B</tt> в функции <tt>Function1</tt> не является той же переменной, как <tt>B</tt> на глобальном уровне. Вместо этого она находится в '''локальной области действия''', и поэтому является '''локально изменяемой'''.

Кроме того, функции <tt>Function1</tt> и <tt>Function2</tt> ничего не знают о существовании других переменных.

Она так же является не только локальной переменной функции <tt>Function1</tt>, но и создается заново каждый раз, когда функция вызывается. Попробуйте представить это:
<pawn>
Function1()
{
new B;

Function1();
}</pawn>

В приведенном выше примере, функция <tt>Function1</tt> вызывает сама себя. Конечно, это бесконечной рекурсии (а это очень плохо), но идея заключается в том, что каждый раз, когда функция срабатывает, то создается новая копия <tt>B</tt>. Когда функция завершается, <tt>B</tt> уничтожается, и её значение теряется.

Это свойство можно объяснить проще тем, что область действия переменной равна уровню её вложенности. То есть, переменная на глобальной области действия видна для всех функций. Переменная в локальной области действия видна всему блоку кода расположенному "ниже" этого уровня. Например:

<pawn>Function1()
{
new A;

if (A)
{
A = 5;
}
}</pawn>

Приведенный выше код является действительным, поскольку в область действия распространяется по всей функции. Однако этот код, работать не будет:
<pawn>
Function1()
{
new A;

if (A)
{
new B = 5;
}

B = 5;
}</pawn>

Отметим, что <tt>B</tt> объявляется в новом блоке кода. Это означает, что <tt>B</tt> доступна только в том блоке кода, в котором была создана (и всем под-блокам вложенных внутри него). Как только блок кода прекращается, <tt>B</tt> становится не действительной.

=Динамические массивы=
Динамические массивы это массивы, которые не имеют фиксированного размера. Например:

<pawn>Function1(size)
{
new array[size];

/* Код */
}</pawn>

Динамические массивы могут иметь любое выражение, соответствующее их размеру до тех пор, пока выражение вычисляется, как число большее чем 0. Как и для обычных массивов, SourcePawn не сможет узнать размер массива после того, как он будет создан; Вы должны задать его, если хотите использовать массив позднее.

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

=Расширенное объявление переменных=
Переменные могут быть объявлены более длинным путем чем просто <tt>new</tt>.

==decl==
===Назначение===
По умолчанию, все переменные в Pawn будут инициализированы как нуль. Если есть явная инициализация, переменная инициализируется для выражения <tt>=</tt> определенным символам. В локальной области действия, это может потребовать время на выполнение. Ключевое слово <tt>decl</tt> (которое действительно только в локальной области действия) было введено, чтобы позволить решать пользователю, хочит ли он инициализировать переменную или нет.

Примечание: <tt>decl</tt> не должно быть использовано на одну однострочную переменную. Это почти никогда не будет выгодно.

===Объяснение===
Например:

<pawn>
new c = 5;
new d;
new String:blah[512];

Format(blah, sizeof(blah), "%d %d", c, d);
</pawn>

В этом коде, <tt>c</tt> равна 5 и <tt>d</tt> равна 0. Во время выполнения этого кода затраты на инициализацию незначительные. Вместе с тем, <tt>blah</tt> является большим массивом, и затраты на инициализацию всего массива могут быть больше 0 сек. и иметь плохие последствия в определенных ситуациях.

Заметим, что <tt>blah</tt> не должен быть нулевой. В период времени с объявления <tt>new</tt> и и перемещения в <tt>Format()</tt>, массив <tt>blah</tt> никогда не будет загружен или прочитан. Данный код будет более эффективен, если будет написанный следующим образом:

<pawn>
new c = 5;
new d;
decl String:blah[512];

Format(blah, sizeof(blah), "%d %d", c, d);
</pawn>

===Caveats===
The downside to <tt>decl</tt> is that it means its variables will start with "garbage" contents. For example, if we were to use:

<pawn>
new c = 5;
new d;
decl String:blah[512];

PrintToServer("%s", blah);

Format(blah, sizeof(blah), "%d %d", c, d);
</pawn>

This code may crash the server, because <tt>blah</tt> may be completely corrupt (strings require a terminator, and that may not be present). Similarly, if we did:

<pawn>
new c = 5;
decl d;
decl String:blah[512];

Format(blah, sizeof(blah), "%d %d", c, d);
</pawn>

The value of <tt>d</tt> is now undefined. It could be any value, negative or positive.

Note that it is easy to efficiently make strings safe. The example below shows how to terminate a garbage string:
<pawn>
decl String:blah[512];

blah[0] = '\0';
</pawn>

===Golden Rules===
*'''Only use decl if in between declaring and loading/reading the value, you are absolutely sure there is at least one store/set operation that gives the variable valid data.'''
*'''Do not prematurely optimize.''' Likewise, there is no need to use <tt>decl</tt> on non-arrays, because there is no added expense for initializing a single cell value.

===Notes===
This example is NOT as efficient as a <tt>decl</tt>:
<pawn>
new String:blah[512] = "a";
</pawn>

Even though the string is only one character, the <tt>new</tt> operator guarantees the rest of the array will be zeroed as well.

Also note, it is invalid to explicitly initialize a <tt>decl</tt>:
<pawn>decl String:blah[512] = "a";</pawn>

The above code will not compile, because the purpose of <tt>decl</tt> is to avoid any initialization.

==static==
The <tt>static</tt> keyword is available at global and local scope. It has different meanings in each.

===Global static===
A global static variable can only be accessed from within the same file. For example:

<pawn>//file1.inc
static Float:g_value1 = 0.15f;

//file2.inc
static Float:g_value2 = 0.15f;</pawn>

If a plugin includes both of these files, it will not be able to use either <tt>g_value1</tt> or <tt>g_value2</tt>. This is a simple information hiding mechanism, and is similar to declaring member variables as <tt>private</tt> in languages like C++, Java, or C#.

===Local static===
A local static variable is a global variable that is only visible from its local lexical scope. For example:

<pawn>
MyFunction(inc)
{
static counter = -1;

counter += inc;

return counter;
}</pawn>

In this example, <tt>counter</tt> is technically a global variable -- it is initialized once to -1 and is never initialized again. It does not exist on the stack. That means each time <tt>MyFunction</tt> runs, the <tt>counter</tt> variable and its storage in memory is the same.

Take this example:
<pawn>MyFunction(5);
MyFunction(6);
MyFunction(10);</pawn>

In this example, <tt>counter</tt> will be <tt>-1 + 5 + 6 + 10</tt>, or <tt>20</tt>, because it persists beyond the frame of the function. Note this may pose problems for recursive functions: if your function may be recursive, then <tt>static</tt> is usually not a good idea unless your code is re-entrant.

The benefit of a local static variable is that you don't have to clutter your script with global variables. As long as the variable doesn't need to be read by another function, you can squirrel it inside the function and its persistence will be guaranteed.

Note that statics can exist in any local scope:

<pawn>
MyFunction(inc)
{
if (inc > 0)
{
static counter;
return (counter += inc);
}
return -1;
}</pawn>

[[Category:Ru:SourceMod Scripting]]

Ru:Introduction to SourcePawn

2008-12-26T11:43:32Z

Frenzzy: /* Purpose */

Это руководство призвано дать Вам самые основные представления по основам написания сприптов в SourcePawn. [[Pawn]] это "скриптовый" язык используемый для внедрения функциональности в других программах. Это означает, что это не самостоятельный язык, как C++ или Java, и его элементы будут отличаться в различных приложениях. SourcePawn это вариация языка Pawn используемая в [[SourceMod]].

Это руководство не расскажет Вам как писать SourceMod плагины; оно предназначено для получения общих представлений о синтаксисе и семантике этого языка. Читайте отдельную статью [[Ru:Introduction to SourceMod Plugins]] (Введение в SourceMod плагины), для введения в SourceMod API.

=Введение для новичков=
Этот раздел создан не для программистов. Если Вы по прежнему в замешательстве, Вы можете прочитать книги о других языках программирования, таких как PHP, Python, или Java, чтобы получить более полное представление о программировании.

==Идентификаторы/Ключевые слова==
Идентификаторы представляет собой набор букв, цифр и/или нижнего подчеркивания, что представляет собой нечто уникальное. Идентификаторы вводятся с учетом регистра (в отличие от PHP, где иногда это не требуется). Идентификаторы не начинаются с какого-либо специального символа, но они должны начинаться с буквы.

Есть несколько зарезервированных символов, которые имеют особое значение. Например, <tt>if</tt>, <tt>for</tt>, и <tt>return</tt> специальные конструкции в языке, которые будут описаны позднее. Они не могут быть использованы в качестве названий идентификаторов.

==Переменные==
Существует несколько важных конструкций, которые Вы должны знать, прежде чем приступить к написанию сценария. Во-первых, это '''переменные'''. Переменная это идентификатор, который содержит данные. Например, переменная "a" может содержать числа "2", "16", "0", и так далее. Переменные создаются для хранения данных внутри программы. Переменные должны быть объявлены до их использования, с помощью ключевого слова "new". Данные можно присвоить переменной, используя знак равенства (=). Пример:

<pawn>new a, b, c, d;

a = 5;
b = 16;
c = 0;
d = 500;</pawn>

В SourcePawn, переменные бывают двух типов, которые будут более подробно описаны далее.
*Однострочные (могут содержать только произвольные числовые данные), как показано выше.
*Многострочные (могут содержать целый ряд текстовых символов)

==Функции==
Следующим важным понятием являются '''функции'''. Функции идентификаторов или имен, которые выполняют действия. Это означает, что когда вы их активируете, они выполняют конкретную последовательность кода. Есть несколько типов функций, но все функции активируется одинаковым образом. "Вызов функции" является термином ссылающимся на функцию действия. Функция числовых переменных строятся так:
<pawn>функция(<параметры>)</pawn>

Примеры:

<pawn>show(56); //Активирует функцию "show" и присваивает ей число 56
show(); //Активирует функцию "show" без каких-либо данных, пустую
show(a); //Активирует функцию "show" и присваивает ей переменную с данными
</pawn>

Каждый фрагмент данных передаваемый вызываемой функции, называется '''параметр'''. Функция может иметь любое количество параметров (но есть "допустимый" предел в SourceMod: 32). Параметры будут описаны далее в этой статье.

==Комментарии==
Примечания и любой текст, который пишется после "//" считается "Комментарием", а не фактическим кодом. Есть два стиля комментариев:
*<tt>//</tt> - Двойная косая черта, всё следующие после этой строки игнорируется.
*<tt>/* */</tt> - Много-строчный комментарий, весь текст, внутри звездочек игнорируются. You cannot nest these.

==Массивы==
Описание массивов. Вы можете группировать код в виде "массивов", разделенных { и }. Это фактически создает возможность работать с целым массивом как с одним оператором. Например:

<pawn>{
here;
is;
some;
code;
}</pawn>

Массивы с фигурными скобками используются достаточно широко в программировании. Массивы кода могут быть вложенными друг в друга. Это хорошая возможность адаптировать последовательность когда и сделать его удобочитаемым, благодаря отступам код не будет смотреться как одна большая и длинная макаронина.

=Особенности языка=
Pawn может показаться очень похожим на другие языки программирования, например C, но Pawn от них фундаментально отличается. Не столь важно, чтобы Вы сейчас же поняли его отличия, но они понадобятся, если Вы уже знаете один из языков программирования.
*'''Pawn не печатает''' Pawn имеет только один тип данных - '''однострочный'''. Подробнее будет описано позже. [В дальнейшем автор рассказывает, что существует два типа данных: однострочный и многострочный]
*'''Pawn не собирает мусор''' Pawn, как язык, не имеет встроенных ресурсов памяти, и потому он не мусорит. Если функция выделит память, то Вы отвечаете за её освобождение.
*'''Pawn не объектно-ориентированный язык''' Pawn является процедурным, и полагается на подпрограммы. Также у него нету C подобных структур.
*'''Pawn не функциональный.''' Pawn является процедурным, и не поддерживает функции "лямбды" (Lambda), поздние присвоения, и все то, что можно найти в языках высшего уровня, таких как Phyton и Ruby.
*'''Pawn однопоточный''' As of this writing, Pawn is not thread safe.
*'''Pawn не интерпретируемый''' Ну, почти. Он интерпретируется на очень низком уровне. Вы должны скомпилировать код, из которого получится бинарный файл. Эта программа будет работать на той платформе, которую использует хост. Это ускоряет загрузку и позволяет легче находить ошибки.

Этот язык был выпущен ITB CompuPhase. Язык разработан для устройств низкого уровня и таким образом конечные программы очень маленькие по размеру и очень быстрые.

=Переменные=
В Pawn есть всего два типа переменных: '''однострочные''' и '''многострочные'''. Однострочные могут содержать 32 бита цифровых данных. Многострочные - последовательный список из UTF-8 символов.

'''однострочные''' не имеет своего типа, однако они могут быть '''маркированы'''(tagged). Тег позволяет Вам указывать, где определенную ячейку можно использовать. Типичные теги:
*(пусто), или '''_''' - Нет тега. Обычно используют для целых чисел ([http://en.wikipedia.org/wiki/Integer Integers]).
*'''Float''' - используют для чисел с плавающей точкой (небольших).
*'''bool''' - используют для хранения значений '''true''' (истина) или '''false''' (ложь).

Со строками все по другому, они будут рассмотрены далее.

==Объявления==
Примеры разных правильных объявлений переменных.
<pawn>
new a = 5;
new Float:b = 5.0;
new bool:c = true;
new bool:d = 0; //Работает, поскольку 0 равно false (ложь)
</pawn>

Неправильные объявления переменных
<pawn>
new a = 5.0; //Несоответствие тегов. 5.0 с тегом Float
new Float:b = 5; //Несоответствие тегов. 5 без тега.
</pawn>

Если переменная не определена в объявлении то ее значения станет 0
<pawn>
new a; //значение 0
new Float:b; //значение 0.0
new bool:c; //значение false
</pawn>

==Присвоение==
Переменным могут быть присвоены данные после создания. Пример:
<pawn>new a, Float:b, bool:c;

a = 5;
b = 5.0;
c = true;
</pawn>

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

==Описание==
Массив объявляется с помощью квадратных скобок. Вот некоторые примеры массивов:
<pawn>
new players[32]; //Набор из 32 однострочных (числовых) данных
new Float:origin[3]; //Набор из 3 чисел с плавающей точкой
</pawn>

По умолчанию, массивам присваиваются нули. Вы можете присвоить им разные значения по умолчанию, однако:
<pawn>
new numbers[5] = {1, 2, 3, 4, 5}; //Набор 1, 2, 3, 4, 5 из однострочных данных.
new Float:origin[3] = {1.0, 2.0, 3.0}; //Набор 1.0, 2.0, 3.0 из однострочных данных.
</pawn>

Вы можете оставить массив без размера, если вы собираетесь заранее присвоить ему данные. Например:
<pawn>
new numbers[] = {1, 3, 5, 7, 9};
</pawn>

Компилятор будет автоматически делать вывод о том, что Вы хотите получить массив размером 5.

==Использование==
Использование массива равносильно использованию обычных переменной. Единственное отличие массива состоит в том, что он должен быть '''индексируемым'''. Индексирование массива означает присутствие возможности выбрать элемент, который Вы хотите использовать.

Вот пример кода с использованием индексов:
<pawn>
new numbers[5], Float:origin[3];

numbers[0] = 1;
numbers[1] = 2;
numbers[2] = 3;
numbers[3] = 4;
numbers[4] = 5;
origin[0] = 1.0;
origin[1] = 2.0;
origin[2] = 3.0;
</pawn>

Заметим, что '''индекс''' это текст, который находится в квадратных скобках. Индекс всегда начинается с нуля. То есть, если массив имеет N элементов, его действительный индекс от 0 до N-1. Доступ к данным с индексами работает так же, как с обычной переменной.

Использование неверного индекса вызовет ошибку. Например:
<pawn>
new numbers[5];

numbers[5] = 20;</pawn>

Это может выглядеть верно, но число 5 не является допустимым индексом. Наибольшим значением индекса является число 4.

Вы можете использовать любые выражения, как индекс. Например:
<pawn>new a, numbers[5];

a = 1; //Сделает a = 1
numbers[a] = 4; //Сделает numbers[1] = 4
numbers[numbers[a]] = 2; //Сделает numbers[4] = 2
</pawn>

Выражения будут обсуждаться подробнее в конце статьи.

=Строки=
Строки являются удобным способом хранения текста. Символы хранятся в массиве. Строка ограничивается '''нулевым символом''', или 0. Без нулевого символа, Pawn не знает, где остановить чтение строки. Все строки в SourcePawn используют кодировку UTF-8.

Отметим, что строки имеют комбинацию из массивов и однострочных переменных. В отличие от других языков, это означает, что Вы должны знать заранее, как много места будут использовать строки. Это означает, что строки не являются динамичными. Они могут лишь вырасти до размера, которым Вы их ограничили.

''Примечание для специалистов: они фактически не однострочные. SourcePawn использует 8-битный строки для хранения массивов в качестве оптимизации. Это и есть то, что делает строки типом, а не меткой.''

==Использование==
Строки были созданы почти в равной степени и для массивов. Например:
<pawn>
new String:message[] = "Hello!";
new String:clams[6] = "Clams";
</pawn>

Это равносильно следующему:
<pawn>
new String:message[7], String:clams[6];

message[0] = 'H';
message[1] = 'e';
message[2] = 'l';
message[3] = 'l';
message[4] = 'o';
message[5] = '!';
message[6] = 0;
clams[0] = 'C';
clams[1] = 'l';
clams[2] = 'a';
clams[3] = 'm';
clams[4] = 's';
clams[5] = 0;
</pawn>

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

Заметим, что строка должна быть заключена в двойных кавычках, а символ в одиночных.

==Символы==
Особенность текста может быть использована в любой строке или однострочной переменной. Например:
<pawn>new String:text[] = "Crab";
new clam;

clam = 'D'; //Устанавливает однострочной переменной значение 'D'
text[0] = 'A'; //Меняет 'C' на 'A', сейчас получилось 'Arab'
clam = text[0]; //Устанавливает однострочной переменной значение 'A'
text[1] = clam; //Меняет 'r' на 'A', сейчас получилось 'AAab'
</pawn>

То, что вы не можете сделать, это соотнести символы массивов со строками. Внутреннее хранение отличается. Например:
<pawn>
new clams[] = "Clams"; //Не верно, нужен тип String:
new clams[] = {'C', 'l', 'a', 'm', 's', 0}; //Верно, но это НЕ СТРОКА.
</pawn>

=Функции=
Функции, как отмечалось ранее, имеют отдельные составляющие кода, которые выполняют определенные действия. Функции могут быть задействованы или '''вызвоны''' с '''параметрами''', которые дают особые настройки.

Существуют два типа вызова функции:
*'''прямой вызов''' - Вы специально вызываете функцию в своем коде.
*'''обратный вызов''' - Применение вызова функций в Вашем коде, как если бы это было событием триггера (совокупность условий, инициирующих выполнение действия).

Существуют пять видов функций:
*'''native''': Прямая, внутренняя функция, предусмотренная в приложении.
*'''public''': Функция обратного вызова, что делает её видимой для приложения и других сценариев.
*'''normal''': Нормальная функция, которую Вы можете только вызвать.
*'''stock''': Нормальная функция, предусмотренная если включает в себя файл. Если не используется, то не компилируется.
*'''forward''': Эта функция представляет собой глобальное событие, предусмотренная приложением. Если Вы её привели в исполнение, она будет вызвона.

Весь код в Pawn должен существовать в функциях. Это основное отличие от языков, таких как PHP, Perl и Python, которые позволяют Вам писать глобальный код. Это происходит потому, что Pawn вызывается на основе другого языка: он реагирует на действия от родительского приложения, и функции должны быть написаны для обработки этих действий. Хотя наш пример, часто содержат свободно плавающий код, это сделано исключительно для демонстрационных целей. Свободно плавающий код в нашем примере означает, что код является частью ряда функций.

==Описание==
В отличие от переменных, функции, не нужно объявлять, прежде чем использовать их. Функции имеют две части, '''модель''' и '''тело'''. Модель содержит имя Вашей функции и параметры, которые она будет принимать. Тело является контейнером для кода.

Пример функции:
<pawn>
AddTwoNumbers(first, second)
{
new sum = first + second;

return sum;
}</pawn>

Это простая функция. Модель этой строки:
<pawn>AddTwoNumbers(first, second)</pawn>

Распишем по отдельности:
*<tt>AddTwoNumbers</tt> - Название функции.
*<tt>first</tt> - Название первого параметра, который представляет собой простой элемент.
*<tt>second</tt> - Название второго параметра, который представляет собой простой элемент.

Тело представляет собой простой блок кода. Он создает новую переменную, названную <tt>sum</tt>, и присваивает ей значение этих двух параметров, добавленных совместно (другие выражения будут позже). Важно заметить оператор <tt>return</tt>, в котором обозначается конец функции и возврат с полученными значениями из этой функции. Все функции ''возвращают значения'' после завершения. Это означает, например:

<pawn>new sum = AddTwoNumbers(4, 5);</pawn>

Приведенный выше код будет присваивать число 9 к sum. Функция получает два значения и передает новое значение sum в качестве '''возвращаемого значения'''. Если функция не имеет возвращаемого значения или не имеет значений для возврата, то возвращается 0 по умолчанию.

Функция может принимать любые типы значений. Она может вернуть любую однострочную переменную, но не массивы или строки. Пример:
<pawn>Float:AddTwoFloats(Float:a, Float:b)
{
new Float:sum = a + b;

return sum;
}</pawn>

''Заметим, что если в приведенной выше функции, Вам вернулась не Float значение, Вы получите не соответствие значений.''

Можно, конечно, передавать переменные в функции:
<pawn>new numbers[3] = {1, 2, 0};

numbers[2] = AddTwoNumbers(numbers[0], numbers[1]);</pawn>

Заметим, что однострочные переменные передаются '''по значению'''. То есть, их значение не может быть изменено функцией. Например:
<pawn>new a = 5;

ChangeValue(a);

ChangeValue(b)
{
b = 5;
}</pawn>

Этот код не будет менять значение <tt>a</tt>. Это происходит потому, что копия этого значения в <tt>a</tt> передается вместо <tt>a</tt> самостоятельно.

Больше примеров функций будут демонстрироваться и в других частях статьи.

==Publics==
Публичные функции используются для осуществления обратных вызовов. Вы не должны создавать какую-либо публичную функцию, если это вынудит выполнение обратного вызова. Например, вот два обратных вызова из <tt>sourcemod.inc</tt>:

<pawn>forward OnPluginStart();
forward OnClientDisconnected(client);</pawn>

Чтобы выполнить и получить эти два события, Вы должны написать такие функции как:

<pawn>public OnPluginStart()
{
/* Код здесь */
}

public OnClientDisconnected(client)
{
/* Код здесь */
}</pawn>

Ключевое слово '''public''' делает функцию публичной, а также позволяет родительскому приложению непосредственно вызывать функцию.

==Natives==
Natives имеют встроенные функции, предоставляемые приложением. Вы можете вызвать их, как если бы они были normal функциями. Например, SourceMod имеет следующие функции:

<pawn>native FloatRound(Float:num);</pawn>

Её можно вызвать таким образом:
<pawn>new num = FloatRound(5.2); //Результат в num = 5</pawn>

==Параметры массива==
Вы можете передавать массивы или строки в качестве параметров. Важно отметить, что они идут '''как ссылка'''. То есть не делать копию данных, а отдавать непосредственно ссылки на данные. Существует простой способ объяснить это более конкретно.

<pawn>
new example[] = {1, 2, 3, 4, 5};

ChangeArray(example, 2, 29);

ChangeArray(array[], index, value)
{
array[index] = value;
}</pawn>

Эта функция устанавливает заданный индекс в массиве с учетом значений. Когда она запускается на примере нашего массива, она меняет индекс 2 для значения 3 на 29. То есть:
<pawn>example[2] = 29;</pawn>

Это возможно лишь потому, что массив может быть непосредственно изменён. Чтобы предотвратить массив от изменения, можно пометить его как постоянную <tt>const</tt>. Это позволит понизить риск на ошибку в коде от её изменения. Например:

<pawn>CantChangeArray(const array[], index, value)
{
array[index] = value; //Не компилируется
}</pawn>

Это хорошая идея использовать <tt>const</tt> в параметрах массивов и Вы будете точно знать, что массив не будет изменен; это может предотвратить ошибки кодирования.

=Выражения=
Выражения являются точно такими же, какими они существуют в математике. Это группы операторов/символов, которые приходятся на один фрагмент данных. Они часто заключены в скобках (внутри скобок). Они содержат строгий "порядок операций". Они могут содержать переменные, функции, цифры и выражения сами могут быть вложенные внутрь других выражений, и даже приняты в качестве параметров.

Приведем пример простейшего выражения:
<pawn>
0; //Возвращает число 0
(0); //Так же возвращает число 0
</pawn>

Хотя выражения могут возвращать значения, они также могут ответить какое значение содержит ответ ''ноль или не ноль''. В этом смысле, ''ноль'' является ''ложью'' (false), а ''не нулевое'' значение ''истиной'' (true). Например, -1 ''истина'' в Pawn, поскольку она не является нулем. Не думайте, что отрицательные числа являются ложными.

Порядок операций выражения аналогичен языку C. PMDAS: Parenthesis, Multiplication, Division, Addition, Subtraction. Вот несколько примеров выражений:
<pawn>
5 + 6; //Вычисляет как 11
5 * 6 + 3; //Вычисляет как 33
5 * (6 + 3); //Вычисляет как 45
5.0 + 2.3; //Вычисляет как 7.3
(5 * 6) % 7; //Modulo operator, вычисляет как 2
(5 + 3) / 2 * 4 - 9; //Вычисляет как 7
</pawn>

Как уже отмечалось, выражения могут содержать переменные, или даже функции:
<pawn>
new a = 5 * 6;
new b = a * 3; //Вычисляет как 90
new c = AddTwoNumbers(a, b) + (a * b);
</pawn>

==Операторы==
Есть несколько полезных дополнительных операторов в Pawn. Первый набор упрощает аутоагрегацию выражения. Например:
<pawn>new a = 5;

a = a + 5;</pawn>

Может быть переписан, как:
<pawn>new a = 5;
a += 5;</pawn>

Это верно в отношении следующих операторов в Pawn:
*Four-function: *, /, -, +
*Bit-wise: |, &, ^, ~, <<, >>

Кроме того, существуют инкремент/декремент операторы:
<pawn>a = a + 1;
a = a - 1;</pawn>

Может быть упрощено, как:
<pawn>a++;
a--;</pawn>

Дополнительно отметим, что ++ или -- может быть представлен до переменной (до-инкремент, до-декремент) или после переменной (пост-инкремент, пост-декремент). Разница заключается в том, как остальная часть выражения содержащие их, видит результат.

* ''До:'' Переменная увеличивается до определения и остальная часть выражения видит новое значение.
* ''Пост:'' Переменная увеличивается после определения и остальная часть выражения видит старое значение.

Иными словами, <tt>a++</tt> определяет значение как <tt>a</tt> в то время как <tt>++a</tt> определяет значение как <tt>a + 1</tt>. В обоих случаях <tt>a</tt> увеличивается на <tt>1</tt>.

Например:

<pawn>new a = 5;
new b = a++; // b = 5, a = 6 (1)
new c = ++a; // a = 7, c = 7 (2)
</pawn>

(1) <tt>b</tt> присваивается <tt>a</tt> со ''старым'' значением, ''до'' того, как он будет увеличено до <tt>6</tt>. (2) <tt>c</tt> присваивается <tt>a</tt> с ''новым'' значением, ''после'' того, как он увеличивается до <tt>7</tt>.

==Операторы сравнения==
Существуют шесть операторов для сравнения двух числовых значений, а результат является либо истиной (не ноль) или ложью (ноль):
*<tt>a == b</tt> - Действительно, если и b имеет то же значение.
*<tt>a != b</tt> - Действительно, если b имеет другое значение.
*<tt>a > b</tt> - Действительно, если оно больше b
*<tt>a >= b</tt> - Действительно, если оно больше или равно b
*<tt>a < b</tt> - Действительно, если оно меньше b
*<tt>a <= b</tt> - Действительно, если оно меньше или равно b

Например:
<pawn>
(1 != 3); //Определяется как истина, поскольку 1 не равно 3.
(3 + 3 == 6); //Определяется как истина, поскольку 3+3 равно 6.
(5 - 2 >= 4); //Определяется как ложь, поскольку 3 меньше 4.
</pawn>

Заметим, что эти операторы не работают с массивами и строками. То есть, вы не можете сравнить их с помощью <tt>==</tt>.

==Действительные операторы==
Действительные операторы могут быть скомбинированы тремя булевыми (boolean) операторами:
*<tt>a && b</tt> - Истина, если a и b истинные. Ложь, если a и (или) b ложные.
{| border="1" cellpadding="2" cellspacing="0" align="center"
! <tt>&&</tt> !! 0 !! 1
|-
! 0
| 0 || 0
|-
! 1
| 0 || 1
|}
*<tt>a || b</tt> - Истина, если a или b (или обе переменные) истинные. Ложь, если обе переменные a и b ложные.
{| border="1" cellpadding="2" cellspacing="0" align="center"
! <tt><nowiki>||</nowiki></tt> !! 0 !! 1
|-
! 0
| 0 || 1
|-
! 1
| 1 || 1
|}
*<tt>!a</tt> - Истина, если a ложь. Ложь, если a истина.
{| border="1" cellpadding="2" cellspacing="0" align="center"
! <tt>!</tt> !! 0 !! 1
|-
!
| 1 || 0
|}

Например:
<pawn>
(1 || 0); //Определяется как истина, так как выражение 1 истинное
(1 && 0); //Определяется как ложь, так как выражение 0 ложное
(!1 || 0); //Определяется как ложь, так как выражение !1 ложное.
</pawn>

==Левое/правое значения==
Два важных понятия левого и правого значений, или левостороннее и правостороннее значения. Левостороннее значение имеет то, что появляется на левой стороне выражения, а правостороннее значение - появляется на правой стороне выражения.

Например:
<pawn>
new a = 5;</pawn>

В этом примере <tt>a</tt> является левосторонним значением и <tt>5</tt> является правосторонним значением.

Правила:
*'''Выражения никогда не будут левосторонними значениями'''.
*'''Переменные являются двумя, левосторонними и правосторонними значениями'''.

=Условия=
Условия позволяют Вам запускать код, определенное условие выполнено.

==Если соответствует==
Если соответствует одно или более условий. Например:

<pawn>
if (a == 5)
{
/* Код будет запущен, если условие будет истинным */
}</pawn>

Они могут быть расширены для более сложных случаев:
<pawn>
if (a == 5)
{
/* Код */
}
else if (a == 6)
{
/* Код */
}
else if (a == 7)
{
/* Код */
}</pawn>

Вы так же можете обрабатывать случаи, даже если выражение не верно. Например:
<pawn>
if (a == 5)
{
/* Код */
}
else
{
/* Код, который будет запущен если нет истинного выражения */
}</pawn>

==Оператор выбора==
Оператор выбора будет ограничен условием. Он необходим для выражения, выполняющего код для целого ряда возможных значений. Например:

<pawn>
switch (a)
{
case 5:
{
/* Код */
}
case 6:
{
/* Код */
}
case 7:
{
/* Код */
}
case 8, 9, 10:
{
/* Код */
}
default:
{
/* будет запущен, если не одно условие не соответствует */
}
}</pawn>

В отличие от некоторых других языков, оператор выбора не проваливается. То есть существуют случаи, когда код не будет запущен. При случае совпадения его код выполняется, а ключ является местом для немедленного прекращения.

=Циклы=
Циклы позволяют Вам без труда повторять выполнение кода, пока условие станет истинным.

==For циклы==
For циклы, это циклы, которые состоят из четырех частей:
*Оператор '''инициализации''' - запускается один раз перед первым циклом.
*Оператор '''условия''' - проверяет условие и запускает следующий цикл, в том числе первый. Цикл прекращается, когда это выражение становится ложным.
*Оператор '''итерации''' - запускается после каждого цикла.
* '''тело''' цикла - запускается каждый раз, пока оператор '''условия''' вычисляется как истинный.

<pawn>
for ( /* инициализация */ ; /* условие */ ; /* итерация */ )
{
/* тело */
}
</pawn>

Простым примером является функция сложения массива:
<pawn>
new array[10] = {1, 2, 3, 4, 5, 6, 7, 8, 9, 10};
new sum = SumArray(array, 10);

SumArray(const array[], count)
{
new total;

for (new i = 0; i < count; i++)
{
total += array[i];
}

return total;
}</pawn>

По отдельности:
*<tt>new i = 0</tt> - Создает новую переменную для цикла, и устанавливает её в 0.
*<tt>i < count</tt> - Только запускает цикл, если <tt>i</tt> меньше, чем <tt>count</tt>. Это гарантирует, что чтение цикла прекращается в определенный момент. В этом случае, мы не хотим читать недействительные индексы в массиве.
*<tt>i++</tt> - Увеличивает <tt>i</tt> на единицу после каждого цикла. Это гарантирует, что цикл не будет запущен вечно; в конце концов <tt>i</tt> станет слишком большим, и цикл завершится.

Таким образом, функция <tt>SumArray</tt> будет циклом каждого действительного индекса массива, каждый раз добавляя это значение в sum. Для циклов очень распространены массивы такие, как в нашем примере.

==While циклы==
While циклы являются менее распространенными, чем for циклы, но на самом деле это более простые циклы. Они имеют только две части:
*Оператор '''условия''' - проверяется перед началом каждого цикла. Цикл прекращается, когда условие становится ложным.
*'''тело''' цикла - запускается каждый раз пока цикл выполняется.

<pawn>
while ( /* условие */ )
{
/* тело */
}
</pawn>

До тех пор, пока условие выражения остается истинным, цикл будет выполняться. Каждый for цикл может быть переписан, как while цикл:

<pawn>
/* инициализация */
while ( /* условие */ )
{
/* тело */
/* итерация */
}
</pawn>

Вот предыдущий for цикл переписан как while цикл:
<pawn>
SumArray(const array[], count)
{
new total, i;

while (i < count)
{
total += array[i];
i++;
}

return total;
}</pawn>

Существуют также '''do...while''' циклы, которые используются еще реже. Они работают как и while циклы, но проверяют условие ПОСЛЕ каждого цикла, а не перед ним. Это означает, что цикл всегда будет запущен, по крайней мере один раз. Например:

<pawn>
do
{
/* тело */
}
while ( /* условие */ );
</pawn>

==Управление циклами==
Существуют два случая, в которых Мы хотели бы контролировать цикл:
*'''пропустить''' одну итерацию или цикл и продолжить выполнение цикла как обычно, или;
*'''разорвать''' цикл целиком, прежде чем он закончится.

Допустим у вас есть функция, которая принимает массив и ищет соответствия цифр. Вы хотите его остановить, когда число будет найдено:
<pawn>
/**
* Возвращает массив, если индекс значения, или -1, не найдены.
*/
SearchInArray(const array[], count, value)
{
new index = -1;

for (new i = 0; i < count; i++)
{
if (array[i] == value)
{
index = i;
break;
}
}

return index;
}</pawn>

Конечно, эту функцию можно вернуть и способом <tt>return i</tt>, но пример показывает, как <tt>break</tt> может остановить цикл.

Кроме того, ключевое слово <tt>continue</tt> пропускает итерации цикла. Например, Мы хотим суммировать все четные числа:

<pawn>
SumEvenNumbers(const array[], count)
{
new sum;

for (new i = 0; i < count; i++)
{
/* If divisibility by 2 is 1, we know it's odd */
if (array[i] % 2 == 1)
{
/* Пропускаем оставшуюся часть итерации цикла */
continue;
}
sum += array[i];
}

return sum;
}</pawn>

=Область действия=
Область действия относится к '''удобочитаемости''' кода. Это означает, что код одного уровня не может быть "виден" в коде другого уровня. Пример:

<pawn>
new A, B, C;

Function1()
{
new B;

Function2();
}

Function2()
{
new C;
}</pawn>

В этом примере, <tt>A</tt>, <tt>B</tt>, и <tt>C</tt> имеют '''глобальную область действия'''. Их можно увидеть в любой функции. Вместе с тем, <tt>B</tt> в функции <tt>Function1</tt> не является той же переменной, как <tt>B</tt> на глобальном уровне. Вместо этого она находится в '''локальной области действия''', и поэтому является '''локально изменяемой'''.

Кроме того, функции <tt>Function1</tt> и <tt>Function2</tt> ничего не знают о существовании других переменных.

Она так же является не только локальной переменной функции <tt>Function1</tt>, но и создается заново каждый раз, когда функция вызывается. Попробуйте представить это:
<pawn>
Function1()
{
new B;

Function1();
}</pawn>

В приведенном выше примере, функция <tt>Function1</tt> вызывает сама себя. Конечно, это бесконечной рекурсии (а это очень плохо), но идея заключается в том, что каждый раз, когда функция срабатывает, то создается новая копия <tt>B</tt>. Когда функция завершается, <tt>B</tt> уничтожается, и её значение теряется.

Это свойство можно объяснить проще тем, что область действия переменной равна уровню её вложенности. То есть, переменная на глобальной области действия видна для всех функций. Переменная в локальной области действия видна всему блоку кода расположенному "ниже" этого уровня. Например:

<pawn>Function1()
{
new A;

if (A)
{
A = 5;
}
}</pawn>

Приведенный выше код является действительным, поскольку в область действия распространяется по всей функции. Однако этот код, работать не будет:
<pawn>
Function1()
{
new A;

if (A)
{
new B = 5;
}

B = 5;
}</pawn>

Отметим, что <tt>B</tt> объявляется в новом блоке кода. Это означает, что <tt>B</tt> доступна только в том блоке кода, в котором была создана (и всем под-блокам вложенных внутри него). Как только блок кода прекращается, <tt>B</tt> становится не действительной.

=Динамические массивы=
Динамические массивы это массивы, которые не имеют фиксированного размера. Например:

<pawn>Function1(size)
{
new array[size];

/* Код */
}</pawn>

Динамические массивы могут иметь любое выражение, соответствующее их размеру до тех пор, пока выражение вычисляется, как число большее чем 0. Как и для обычных массивов, SourcePawn не сможет узнать размер массива после того, как он будет создан; Вы должны задать его, если хотите использовать массив позднее.

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

=Расширенное объявление переменных=
Переменные могут быть объявлены более длинным путем чем просто <tt>new</tt>.

==decl==
===Назначение===
По умолчанию, все переменные в Pawn будут инициализированы как нуль. Если есть явная инициализация, переменная инициализируется для выражения <tt>=</tt> определенным символам. В локальной области действия, это может потребовать время на выполнение. Ключевое слово <tt>decl</tt> (которое действительно только в локальной области действия) было введено, чтобы позволить решать пользователю, хочит ли он инициализировать переменную или нет.

Примечание: <tt>decl</tt> не должно быть использовано на одну однострочную переменную. Это почти никогда не будет выгодно.

===Explanation===
For example:

<pawn>
new c = 5;
new d;
new String:blah[512];

Format(blah, sizeof(blah), "%d %d", c, d);
</pawn>

In this code, <tt>c</tt> is equal to 5 and <tt>d</tt> is equal to 0. The run-time expense of this initialization is negligible. However, <tt>blah</tt> is a large array, and the expense of initializing the entire array to 0s could be detrimental in certain situations.

Note that <tt>blah</tt> does not need to be zeroed. In between being declared with <tt>new</tt> and stored with <tt>Format()</tt>, <tt>blah</tt> is never loaded or read. Thus this code would be more efficiently written as:

<pawn>
new c = 5;
new d;
decl String:blah[512];

Format(blah, sizeof(blah), "%d %d", c, d);
</pawn>

===Caveats===
The downside to <tt>decl</tt> is that it means its variables will start with "garbage" contents. For example, if we were to use:

<pawn>
new c = 5;
new d;
decl String:blah[512];

PrintToServer("%s", blah);

Format(blah, sizeof(blah), "%d %d", c, d);
</pawn>

This code may crash the server, because <tt>blah</tt> may be completely corrupt (strings require a terminator, and that may not be present). Similarly, if we did:

<pawn>
new c = 5;
decl d;
decl String:blah[512];

Format(blah, sizeof(blah), "%d %d", c, d);
</pawn>

The value of <tt>d</tt> is now undefined. It could be any value, negative or positive.

Note that it is easy to efficiently make strings safe. The example below shows how to terminate a garbage string:
<pawn>
decl String:blah[512];

blah[0] = '\0';
</pawn>

===Golden Rules===
*'''Only use decl if in between declaring and loading/reading the value, you are absolutely sure there is at least one store/set operation that gives the variable valid data.'''
*'''Do not prematurely optimize.''' Likewise, there is no need to use <tt>decl</tt> on non-arrays, because there is no added expense for initializing a single cell value.

===Notes===
This example is NOT as efficient as a <tt>decl</tt>:
<pawn>
new String:blah[512] = "a";
</pawn>

Even though the string is only one character, the <tt>new</tt> operator guarantees the rest of the array will be zeroed as well.

Also note, it is invalid to explicitly initialize a <tt>decl</tt>:
<pawn>decl String:blah[512] = "a";</pawn>

The above code will not compile, because the purpose of <tt>decl</tt> is to avoid any initialization.

==static==
The <tt>static</tt> keyword is available at global and local scope. It has different meanings in each.

===Global static===
A global static variable can only be accessed from within the same file. For example:

<pawn>//file1.inc
static Float:g_value1 = 0.15f;

//file2.inc
static Float:g_value2 = 0.15f;</pawn>

If a plugin includes both of these files, it will not be able to use either <tt>g_value1</tt> or <tt>g_value2</tt>. This is a simple information hiding mechanism, and is similar to declaring member variables as <tt>private</tt> in languages like C++, Java, or C#.

===Local static===
A local static variable is a global variable that is only visible from its local lexical scope. For example:

<pawn>
MyFunction(inc)
{
static counter = -1;

counter += inc;

return counter;
}</pawn>

In this example, <tt>counter</tt> is technically a global variable -- it is initialized once to -1 and is never initialized again. It does not exist on the stack. That means each time <tt>MyFunction</tt> runs, the <tt>counter</tt> variable and its storage in memory is the same.

Take this example:
<pawn>MyFunction(5);
MyFunction(6);
MyFunction(10);</pawn>

In this example, <tt>counter</tt> will be <tt>-1 + 5 + 6 + 10</tt>, or <tt>20</tt>, because it persists beyond the frame of the function. Note this may pose problems for recursive functions: if your function may be recursive, then <tt>static</tt> is usually not a good idea unless your code is re-entrant.

The benefit of a local static variable is that you don't have to clutter your script with global variables. As long as the variable doesn't need to be read by another function, you can squirrel it inside the function and its persistence will be guaranteed.

Note that statics can exist in any local scope:

<pawn>
MyFunction(inc)
{
if (inc > 0)
{
static counter;
return (counter += inc);
}
return -1;
}</pawn>

[[Category:Ru:SourceMod Scripting]]

Ru:Introduction to SourcePawn

2008-12-26T11:30:46Z

Frenzzy: /* Extended Variable Declarations */

Это руководство призвано дать Вам самые основные представления по основам написания сприптов в SourcePawn. [[Pawn]] это "скриптовый" язык используемый для внедрения функциональности в других программах. Это означает, что это не самостоятельный язык, как C++ или Java, и его элементы будут отличаться в различных приложениях. SourcePawn это вариация языка Pawn используемая в [[SourceMod]].

Это руководство не расскажет Вам как писать SourceMod плагины; оно предназначено для получения общих представлений о синтаксисе и семантике этого языка. Читайте отдельную статью [[Ru:Introduction to SourceMod Plugins]] (Введение в SourceMod плагины), для введения в SourceMod API.

=Введение для новичков=
Этот раздел создан не для программистов. Если Вы по прежнему в замешательстве, Вы можете прочитать книги о других языках программирования, таких как PHP, Python, или Java, чтобы получить более полное представление о программировании.

==Идентификаторы/Ключевые слова==
Идентификаторы представляет собой набор букв, цифр и/или нижнего подчеркивания, что представляет собой нечто уникальное. Идентификаторы вводятся с учетом регистра (в отличие от PHP, где иногда это не требуется). Идентификаторы не начинаются с какого-либо специального символа, но они должны начинаться с буквы.

Есть несколько зарезервированных символов, которые имеют особое значение. Например, <tt>if</tt>, <tt>for</tt>, и <tt>return</tt> специальные конструкции в языке, которые будут описаны позднее. Они не могут быть использованы в качестве названий идентификаторов.

==Переменные==
Существует несколько важных конструкций, которые Вы должны знать, прежде чем приступить к написанию сценария. Во-первых, это '''переменные'''. Переменная это идентификатор, который содержит данные. Например, переменная "a" может содержать числа "2", "16", "0", и так далее. Переменные создаются для хранения данных внутри программы. Переменные должны быть объявлены до их использования, с помощью ключевого слова "new". Данные можно присвоить переменной, используя знак равенства (=). Пример:

<pawn>new a, b, c, d;

a = 5;
b = 16;
c = 0;
d = 500;</pawn>

В SourcePawn, переменные бывают двух типов, которые будут более подробно описаны далее.
*Однострочные (могут содержать только произвольные числовые данные), как показано выше.
*Многострочные (могут содержать целый ряд текстовых символов)

==Функции==
Следующим важным понятием являются '''функции'''. Функции идентификаторов или имен, которые выполняют действия. Это означает, что когда вы их активируете, они выполняют конкретную последовательность кода. Есть несколько типов функций, но все функции активируется одинаковым образом. "Вызов функции" является термином ссылающимся на функцию действия. Функция числовых переменных строятся так:
<pawn>функция(<параметры>)</pawn>

Примеры:

<pawn>show(56); //Активирует функцию "show" и присваивает ей число 56
show(); //Активирует функцию "show" без каких-либо данных, пустую
show(a); //Активирует функцию "show" и присваивает ей переменную с данными
</pawn>

Каждый фрагмент данных передаваемый вызываемой функции, называется '''параметр'''. Функция может иметь любое количество параметров (но есть "допустимый" предел в SourceMod: 32). Параметры будут описаны далее в этой статье.

==Комментарии==
Примечания и любой текст, который пишется после "//" считается "Комментарием", а не фактическим кодом. Есть два стиля комментариев:
*<tt>//</tt> - Двойная косая черта, всё следующие после этой строки игнорируется.
*<tt>/* */</tt> - Много-строчный комментарий, весь текст, внутри звездочек игнорируются. You cannot nest these.

==Массивы==
Описание массивов. Вы можете группировать код в виде "массивов", разделенных { и }. Это фактически создает возможность работать с целым массивом как с одним оператором. Например:

<pawn>{
here;
is;
some;
code;
}</pawn>

Массивы с фигурными скобками используются достаточно широко в программировании. Массивы кода могут быть вложенными друг в друга. Это хорошая возможность адаптировать последовательность когда и сделать его удобочитаемым, благодаря отступам код не будет смотреться как одна большая и длинная макаронина.

=Особенности языка=
Pawn может показаться очень похожим на другие языки программирования, например C, но Pawn от них фундаментально отличается. Не столь важно, чтобы Вы сейчас же поняли его отличия, но они понадобятся, если Вы уже знаете один из языков программирования.
*'''Pawn не печатает''' Pawn имеет только один тип данных - '''однострочный'''. Подробнее будет описано позже. [В дальнейшем автор рассказывает, что существует два типа данных: однострочный и многострочный]
*'''Pawn не собирает мусор''' Pawn, как язык, не имеет встроенных ресурсов памяти, и потому он не мусорит. Если функция выделит память, то Вы отвечаете за её освобождение.
*'''Pawn не объектно-ориентированный язык''' Pawn является процедурным, и полагается на подпрограммы. Также у него нету C подобных структур.
*'''Pawn не функциональный.''' Pawn является процедурным, и не поддерживает функции "лямбды" (Lambda), поздние присвоения, и все то, что можно найти в языках высшего уровня, таких как Phyton и Ruby.
*'''Pawn однопоточный''' As of this writing, Pawn is not thread safe.
*'''Pawn не интерпретируемый''' Ну, почти. Он интерпретируется на очень низком уровне. Вы должны скомпилировать код, из которого получится бинарный файл. Эта программа будет работать на той платформе, которую использует хост. Это ускоряет загрузку и позволяет легче находить ошибки.

Этот язык был выпущен ITB CompuPhase. Язык разработан для устройств низкого уровня и таким образом конечные программы очень маленькие по размеру и очень быстрые.

=Переменные=
В Pawn есть всего два типа переменных: '''однострочные''' и '''многострочные'''. Однострочные могут содержать 32 бита цифровых данных. Многострочные - последовательный список из UTF-8 символов.

'''однострочные''' не имеет своего типа, однако они могут быть '''маркированы'''(tagged). Тег позволяет Вам указывать, где определенную ячейку можно использовать. Типичные теги:
*(пусто), или '''_''' - Нет тега. Обычно используют для целых чисел ([http://en.wikipedia.org/wiki/Integer Integers]).
*'''Float''' - используют для чисел с плавающей точкой (небольших).
*'''bool''' - используют для хранения значений '''true''' (истина) или '''false''' (ложь).

Со строками все по другому, они будут рассмотрены далее.

==Объявления==
Примеры разных правильных объявлений переменных.
<pawn>
new a = 5;
new Float:b = 5.0;
new bool:c = true;
new bool:d = 0; //Работает, поскольку 0 равно false (ложь)
</pawn>

Неправильные объявления переменных
<pawn>
new a = 5.0; //Несоответствие тегов. 5.0 с тегом Float
new Float:b = 5; //Несоответствие тегов. 5 без тега.
</pawn>

Если переменная не определена в объявлении то ее значения станет 0
<pawn>
new a; //значение 0
new Float:b; //значение 0.0
new bool:c; //значение false
</pawn>

==Присвоение==
Переменным могут быть присвоены данные после создания. Пример:
<pawn>new a, Float:b, bool:c;

a = 5;
b = 5.0;
c = true;
</pawn>

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

==Описание==
Массив объявляется с помощью квадратных скобок. Вот некоторые примеры массивов:
<pawn>
new players[32]; //Набор из 32 однострочных (числовых) данных
new Float:origin[3]; //Набор из 3 чисел с плавающей точкой
</pawn>

По умолчанию, массивам присваиваются нули. Вы можете присвоить им разные значения по умолчанию, однако:
<pawn>
new numbers[5] = {1, 2, 3, 4, 5}; //Набор 1, 2, 3, 4, 5 из однострочных данных.
new Float:origin[3] = {1.0, 2.0, 3.0}; //Набор 1.0, 2.0, 3.0 из однострочных данных.
</pawn>

Вы можете оставить массив без размера, если вы собираетесь заранее присвоить ему данные. Например:
<pawn>
new numbers[] = {1, 3, 5, 7, 9};
</pawn>

Компилятор будет автоматически делать вывод о том, что Вы хотите получить массив размером 5.

==Использование==
Использование массива равносильно использованию обычных переменной. Единственное отличие массива состоит в том, что он должен быть '''индексируемым'''. Индексирование массива означает присутствие возможности выбрать элемент, который Вы хотите использовать.

Вот пример кода с использованием индексов:
<pawn>
new numbers[5], Float:origin[3];

numbers[0] = 1;
numbers[1] = 2;
numbers[2] = 3;
numbers[3] = 4;
numbers[4] = 5;
origin[0] = 1.0;
origin[1] = 2.0;
origin[2] = 3.0;
</pawn>

Заметим, что '''индекс''' это текст, который находится в квадратных скобках. Индекс всегда начинается с нуля. То есть, если массив имеет N элементов, его действительный индекс от 0 до N-1. Доступ к данным с индексами работает так же, как с обычной переменной.

Использование неверного индекса вызовет ошибку. Например:
<pawn>
new numbers[5];

numbers[5] = 20;</pawn>

Это может выглядеть верно, но число 5 не является допустимым индексом. Наибольшим значением индекса является число 4.

Вы можете использовать любые выражения, как индекс. Например:
<pawn>new a, numbers[5];

a = 1; //Сделает a = 1
numbers[a] = 4; //Сделает numbers[1] = 4
numbers[numbers[a]] = 2; //Сделает numbers[4] = 2
</pawn>

Выражения будут обсуждаться подробнее в конце статьи.

=Строки=
Строки являются удобным способом хранения текста. Символы хранятся в массиве. Строка ограничивается '''нулевым символом''', или 0. Без нулевого символа, Pawn не знает, где остановить чтение строки. Все строки в SourcePawn используют кодировку UTF-8.

Отметим, что строки имеют комбинацию из массивов и однострочных переменных. В отличие от других языков, это означает, что Вы должны знать заранее, как много места будут использовать строки. Это означает, что строки не являются динамичными. Они могут лишь вырасти до размера, которым Вы их ограничили.

''Примечание для специалистов: они фактически не однострочные. SourcePawn использует 8-битный строки для хранения массивов в качестве оптимизации. Это и есть то, что делает строки типом, а не меткой.''

==Использование==
Строки были созданы почти в равной степени и для массивов. Например:
<pawn>
new String:message[] = "Hello!";
new String:clams[6] = "Clams";
</pawn>

Это равносильно следующему:
<pawn>
new String:message[7], String:clams[6];

message[0] = 'H';
message[1] = 'e';
message[2] = 'l';
message[3] = 'l';
message[4] = 'o';
message[5] = '!';
message[6] = 0;
clams[0] = 'C';
clams[1] = 'l';
clams[2] = 'a';
clams[3] = 'm';
clams[4] = 's';
clams[5] = 0;
</pawn>

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

Заметим, что строка должна быть заключена в двойных кавычках, а символ в одиночных.

==Символы==
Особенность текста может быть использована в любой строке или однострочной переменной. Например:
<pawn>new String:text[] = "Crab";
new clam;

clam = 'D'; //Устанавливает однострочной переменной значение 'D'
text[0] = 'A'; //Меняет 'C' на 'A', сейчас получилось 'Arab'
clam = text[0]; //Устанавливает однострочной переменной значение 'A'
text[1] = clam; //Меняет 'r' на 'A', сейчас получилось 'AAab'
</pawn>

То, что вы не можете сделать, это соотнести символы массивов со строками. Внутреннее хранение отличается. Например:
<pawn>
new clams[] = "Clams"; //Не верно, нужен тип String:
new clams[] = {'C', 'l', 'a', 'm', 's', 0}; //Верно, но это НЕ СТРОКА.
</pawn>

=Функции=
Функции, как отмечалось ранее, имеют отдельные составляющие кода, которые выполняют определенные действия. Функции могут быть задействованы или '''вызвоны''' с '''параметрами''', которые дают особые настройки.

Существуют два типа вызова функции:
*'''прямой вызов''' - Вы специально вызываете функцию в своем коде.
*'''обратный вызов''' - Применение вызова функций в Вашем коде, как если бы это было событием триггера (совокупность условий, инициирующих выполнение действия).

Существуют пять видов функций:
*'''native''': Прямая, внутренняя функция, предусмотренная в приложении.
*'''public''': Функция обратного вызова, что делает её видимой для приложения и других сценариев.
*'''normal''': Нормальная функция, которую Вы можете только вызвать.
*'''stock''': Нормальная функция, предусмотренная если включает в себя файл. Если не используется, то не компилируется.
*'''forward''': Эта функция представляет собой глобальное событие, предусмотренная приложением. Если Вы её привели в исполнение, она будет вызвона.

Весь код в Pawn должен существовать в функциях. Это основное отличие от языков, таких как PHP, Perl и Python, которые позволяют Вам писать глобальный код. Это происходит потому, что Pawn вызывается на основе другого языка: он реагирует на действия от родительского приложения, и функции должны быть написаны для обработки этих действий. Хотя наш пример, часто содержат свободно плавающий код, это сделано исключительно для демонстрационных целей. Свободно плавающий код в нашем примере означает, что код является частью ряда функций.

==Описание==
В отличие от переменных, функции, не нужно объявлять, прежде чем использовать их. Функции имеют две части, '''модель''' и '''тело'''. Модель содержит имя Вашей функции и параметры, которые она будет принимать. Тело является контейнером для кода.

Пример функции:
<pawn>
AddTwoNumbers(first, second)
{
new sum = first + second;

return sum;
}</pawn>

Это простая функция. Модель этой строки:
<pawn>AddTwoNumbers(first, second)</pawn>

Распишем по отдельности:
*<tt>AddTwoNumbers</tt> - Название функции.
*<tt>first</tt> - Название первого параметра, который представляет собой простой элемент.
*<tt>second</tt> - Название второго параметра, который представляет собой простой элемент.

Тело представляет собой простой блок кода. Он создает новую переменную, названную <tt>sum</tt>, и присваивает ей значение этих двух параметров, добавленных совместно (другие выражения будут позже). Важно заметить оператор <tt>return</tt>, в котором обозначается конец функции и возврат с полученными значениями из этой функции. Все функции ''возвращают значения'' после завершения. Это означает, например:

<pawn>new sum = AddTwoNumbers(4, 5);</pawn>

Приведенный выше код будет присваивать число 9 к sum. Функция получает два значения и передает новое значение sum в качестве '''возвращаемого значения'''. Если функция не имеет возвращаемого значения или не имеет значений для возврата, то возвращается 0 по умолчанию.

Функция может принимать любые типы значений. Она может вернуть любую однострочную переменную, но не массивы или строки. Пример:
<pawn>Float:AddTwoFloats(Float:a, Float:b)
{
new Float:sum = a + b;

return sum;
}</pawn>

''Заметим, что если в приведенной выше функции, Вам вернулась не Float значение, Вы получите не соответствие значений.''

Можно, конечно, передавать переменные в функции:
<pawn>new numbers[3] = {1, 2, 0};

numbers[2] = AddTwoNumbers(numbers[0], numbers[1]);</pawn>

Заметим, что однострочные переменные передаются '''по значению'''. То есть, их значение не может быть изменено функцией. Например:
<pawn>new a = 5;

ChangeValue(a);

ChangeValue(b)
{
b = 5;
}</pawn>

Этот код не будет менять значение <tt>a</tt>. Это происходит потому, что копия этого значения в <tt>a</tt> передается вместо <tt>a</tt> самостоятельно.

Больше примеров функций будут демонстрироваться и в других частях статьи.

==Publics==
Публичные функции используются для осуществления обратных вызовов. Вы не должны создавать какую-либо публичную функцию, если это вынудит выполнение обратного вызова. Например, вот два обратных вызова из <tt>sourcemod.inc</tt>:

<pawn>forward OnPluginStart();
forward OnClientDisconnected(client);</pawn>

Чтобы выполнить и получить эти два события, Вы должны написать такие функции как:

<pawn>public OnPluginStart()
{
/* Код здесь */
}

public OnClientDisconnected(client)
{
/* Код здесь */
}</pawn>

Ключевое слово '''public''' делает функцию публичной, а также позволяет родительскому приложению непосредственно вызывать функцию.

==Natives==
Natives имеют встроенные функции, предоставляемые приложением. Вы можете вызвать их, как если бы они были normal функциями. Например, SourceMod имеет следующие функции:

<pawn>native FloatRound(Float:num);</pawn>

Её можно вызвать таким образом:
<pawn>new num = FloatRound(5.2); //Результат в num = 5</pawn>

==Параметры массива==
Вы можете передавать массивы или строки в качестве параметров. Важно отметить, что они идут '''как ссылка'''. То есть не делать копию данных, а отдавать непосредственно ссылки на данные. Существует простой способ объяснить это более конкретно.

<pawn>
new example[] = {1, 2, 3, 4, 5};

ChangeArray(example, 2, 29);

ChangeArray(array[], index, value)
{
array[index] = value;
}</pawn>

Эта функция устанавливает заданный индекс в массиве с учетом значений. Когда она запускается на примере нашего массива, она меняет индекс 2 для значения 3 на 29. То есть:
<pawn>example[2] = 29;</pawn>

Это возможно лишь потому, что массив может быть непосредственно изменён. Чтобы предотвратить массив от изменения, можно пометить его как постоянную <tt>const</tt>. Это позволит понизить риск на ошибку в коде от её изменения. Например:

<pawn>CantChangeArray(const array[], index, value)
{
array[index] = value; //Не компилируется
}</pawn>

Это хорошая идея использовать <tt>const</tt> в параметрах массивов и Вы будете точно знать, что массив не будет изменен; это может предотвратить ошибки кодирования.

=Выражения=
Выражения являются точно такими же, какими они существуют в математике. Это группы операторов/символов, которые приходятся на один фрагмент данных. Они часто заключены в скобках (внутри скобок). Они содержат строгий "порядок операций". Они могут содержать переменные, функции, цифры и выражения сами могут быть вложенные внутрь других выражений, и даже приняты в качестве параметров.

Приведем пример простейшего выражения:
<pawn>
0; //Возвращает число 0
(0); //Так же возвращает число 0
</pawn>

Хотя выражения могут возвращать значения, они также могут ответить какое значение содержит ответ ''ноль или не ноль''. В этом смысле, ''ноль'' является ''ложью'' (false), а ''не нулевое'' значение ''истиной'' (true). Например, -1 ''истина'' в Pawn, поскольку она не является нулем. Не думайте, что отрицательные числа являются ложными.

Порядок операций выражения аналогичен языку C. PMDAS: Parenthesis, Multiplication, Division, Addition, Subtraction. Вот несколько примеров выражений:
<pawn>
5 + 6; //Вычисляет как 11
5 * 6 + 3; //Вычисляет как 33
5 * (6 + 3); //Вычисляет как 45
5.0 + 2.3; //Вычисляет как 7.3
(5 * 6) % 7; //Modulo operator, вычисляет как 2
(5 + 3) / 2 * 4 - 9; //Вычисляет как 7
</pawn>

Как уже отмечалось, выражения могут содержать переменные, или даже функции:
<pawn>
new a = 5 * 6;
new b = a * 3; //Вычисляет как 90
new c = AddTwoNumbers(a, b) + (a * b);
</pawn>

==Операторы==
Есть несколько полезных дополнительных операторов в Pawn. Первый набор упрощает аутоагрегацию выражения. Например:
<pawn>new a = 5;

a = a + 5;</pawn>

Может быть переписан, как:
<pawn>new a = 5;
a += 5;</pawn>

Это верно в отношении следующих операторов в Pawn:
*Four-function: *, /, -, +
*Bit-wise: |, &, ^, ~, <<, >>

Кроме того, существуют инкремент/декремент операторы:
<pawn>a = a + 1;
a = a - 1;</pawn>

Может быть упрощено, как:
<pawn>a++;
a--;</pawn>

Дополнительно отметим, что ++ или -- может быть представлен до переменной (до-инкремент, до-декремент) или после переменной (пост-инкремент, пост-декремент). Разница заключается в том, как остальная часть выражения содержащие их, видит результат.

* ''До:'' Переменная увеличивается до определения и остальная часть выражения видит новое значение.
* ''Пост:'' Переменная увеличивается после определения и остальная часть выражения видит старое значение.

Иными словами, <tt>a++</tt> определяет значение как <tt>a</tt> в то время как <tt>++a</tt> определяет значение как <tt>a + 1</tt>. В обоих случаях <tt>a</tt> увеличивается на <tt>1</tt>.

Например:

<pawn>new a = 5;
new b = a++; // b = 5, a = 6 (1)
new c = ++a; // a = 7, c = 7 (2)
</pawn>

(1) <tt>b</tt> присваивается <tt>a</tt> со ''старым'' значением, ''до'' того, как он будет увеличено до <tt>6</tt>. (2) <tt>c</tt> присваивается <tt>a</tt> с ''новым'' значением, ''после'' того, как он увеличивается до <tt>7</tt>.

==Операторы сравнения==
Существуют шесть операторов для сравнения двух числовых значений, а результат является либо истиной (не ноль) или ложью (ноль):
*<tt>a == b</tt> - Действительно, если и b имеет то же значение.
*<tt>a != b</tt> - Действительно, если b имеет другое значение.
*<tt>a > b</tt> - Действительно, если оно больше b
*<tt>a >= b</tt> - Действительно, если оно больше или равно b
*<tt>a < b</tt> - Действительно, если оно меньше b
*<tt>a <= b</tt> - Действительно, если оно меньше или равно b

Например:
<pawn>
(1 != 3); //Определяется как истина, поскольку 1 не равно 3.
(3 + 3 == 6); //Определяется как истина, поскольку 3+3 равно 6.
(5 - 2 >= 4); //Определяется как ложь, поскольку 3 меньше 4.
</pawn>

Заметим, что эти операторы не работают с массивами и строками. То есть, вы не можете сравнить их с помощью <tt>==</tt>.

==Действительные операторы==
Действительные операторы могут быть скомбинированы тремя булевыми (boolean) операторами:
*<tt>a && b</tt> - Истина, если a и b истинные. Ложь, если a и (или) b ложные.
{| border="1" cellpadding="2" cellspacing="0" align="center"
! <tt>&&</tt> !! 0 !! 1
|-
! 0
| 0 || 0
|-
! 1
| 0 || 1
|}
*<tt>a || b</tt> - Истина, если a или b (или обе переменные) истинные. Ложь, если обе переменные a и b ложные.
{| border="1" cellpadding="2" cellspacing="0" align="center"
! <tt><nowiki>||</nowiki></tt> !! 0 !! 1
|-
! 0
| 0 || 1
|-
! 1
| 1 || 1
|}
*<tt>!a</tt> - Истина, если a ложь. Ложь, если a истина.
{| border="1" cellpadding="2" cellspacing="0" align="center"
! <tt>!</tt> !! 0 !! 1
|-
!
| 1 || 0
|}

Например:
<pawn>
(1 || 0); //Определяется как истина, так как выражение 1 истинное
(1 && 0); //Определяется как ложь, так как выражение 0 ложное
(!1 || 0); //Определяется как ложь, так как выражение !1 ложное.
</pawn>

==Левое/правое значения==
Два важных понятия левого и правого значений, или левостороннее и правостороннее значения. Левостороннее значение имеет то, что появляется на левой стороне выражения, а правостороннее значение - появляется на правой стороне выражения.

Например:
<pawn>
new a = 5;</pawn>

В этом примере <tt>a</tt> является левосторонним значением и <tt>5</tt> является правосторонним значением.

Правила:
*'''Выражения никогда не будут левосторонними значениями'''.
*'''Переменные являются двумя, левосторонними и правосторонними значениями'''.

=Условия=
Условия позволяют Вам запускать код, определенное условие выполнено.

==Если соответствует==
Если соответствует одно или более условий. Например:

<pawn>
if (a == 5)
{
/* Код будет запущен, если условие будет истинным */
}</pawn>

Они могут быть расширены для более сложных случаев:
<pawn>
if (a == 5)
{
/* Код */
}
else if (a == 6)
{
/* Код */
}
else if (a == 7)
{
/* Код */
}</pawn>

Вы так же можете обрабатывать случаи, даже если выражение не верно. Например:
<pawn>
if (a == 5)
{
/* Код */
}
else
{
/* Код, который будет запущен если нет истинного выражения */
}</pawn>

==Оператор выбора==
Оператор выбора будет ограничен условием. Он необходим для выражения, выполняющего код для целого ряда возможных значений. Например:

<pawn>
switch (a)
{
case 5:
{
/* Код */
}
case 6:
{
/* Код */
}
case 7:
{
/* Код */
}
case 8, 9, 10:
{
/* Код */
}
default:
{
/* будет запущен, если не одно условие не соответствует */
}
}</pawn>

В отличие от некоторых других языков, оператор выбора не проваливается. То есть существуют случаи, когда код не будет запущен. При случае совпадения его код выполняется, а ключ является местом для немедленного прекращения.

=Циклы=
Циклы позволяют Вам без труда повторять выполнение кода, пока условие станет истинным.

==For циклы==
For циклы, это циклы, которые состоят из четырех частей:
*Оператор '''инициализации''' - запускается один раз перед первым циклом.
*Оператор '''условия''' - проверяет условие и запускает следующий цикл, в том числе первый. Цикл прекращается, когда это выражение становится ложным.
*Оператор '''итерации''' - запускается после каждого цикла.
* '''тело''' цикла - запускается каждый раз, пока оператор '''условия''' вычисляется как истинный.

<pawn>
for ( /* инициализация */ ; /* условие */ ; /* итерация */ )
{
/* тело */
}
</pawn>

Простым примером является функция сложения массива:
<pawn>
new array[10] = {1, 2, 3, 4, 5, 6, 7, 8, 9, 10};
new sum = SumArray(array, 10);

SumArray(const array[], count)
{
new total;

for (new i = 0; i < count; i++)
{
total += array[i];
}

return total;
}</pawn>

По отдельности:
*<tt>new i = 0</tt> - Создает новую переменную для цикла, и устанавливает её в 0.
*<tt>i < count</tt> - Только запускает цикл, если <tt>i</tt> меньше, чем <tt>count</tt>. Это гарантирует, что чтение цикла прекращается в определенный момент. В этом случае, мы не хотим читать недействительные индексы в массиве.
*<tt>i++</tt> - Увеличивает <tt>i</tt> на единицу после каждого цикла. Это гарантирует, что цикл не будет запущен вечно; в конце концов <tt>i</tt> станет слишком большим, и цикл завершится.

Таким образом, функция <tt>SumArray</tt> будет циклом каждого действительного индекса массива, каждый раз добавляя это значение в sum. Для циклов очень распространены массивы такие, как в нашем примере.

==While циклы==
While циклы являются менее распространенными, чем for циклы, но на самом деле это более простые циклы. Они имеют только две части:
*Оператор '''условия''' - проверяется перед началом каждого цикла. Цикл прекращается, когда условие становится ложным.
*'''тело''' цикла - запускается каждый раз пока цикл выполняется.

<pawn>
while ( /* условие */ )
{
/* тело */
}
</pawn>

До тех пор, пока условие выражения остается истинным, цикл будет выполняться. Каждый for цикл может быть переписан, как while цикл:

<pawn>
/* инициализация */
while ( /* условие */ )
{
/* тело */
/* итерация */
}
</pawn>

Вот предыдущий for цикл переписан как while цикл:
<pawn>
SumArray(const array[], count)
{
new total, i;

while (i < count)
{
total += array[i];
i++;
}

return total;
}</pawn>

Существуют также '''do...while''' циклы, которые используются еще реже. Они работают как и while циклы, но проверяют условие ПОСЛЕ каждого цикла, а не перед ним. Это означает, что цикл всегда будет запущен, по крайней мере один раз. Например:

<pawn>
do
{
/* тело */
}
while ( /* условие */ );
</pawn>

==Управление циклами==
Существуют два случая, в которых Мы хотели бы контролировать цикл:
*'''пропустить''' одну итерацию или цикл и продолжить выполнение цикла как обычно, или;
*'''разорвать''' цикл целиком, прежде чем он закончится.

Допустим у вас есть функция, которая принимает массив и ищет соответствия цифр. Вы хотите его остановить, когда число будет найдено:
<pawn>
/**
* Возвращает массив, если индекс значения, или -1, не найдены.
*/
SearchInArray(const array[], count, value)
{
new index = -1;

for (new i = 0; i < count; i++)
{
if (array[i] == value)
{
index = i;
break;
}
}

return index;
}</pawn>

Конечно, эту функцию можно вернуть и способом <tt>return i</tt>, но пример показывает, как <tt>break</tt> может остановить цикл.

Кроме того, ключевое слово <tt>continue</tt> пропускает итерации цикла. Например, Мы хотим суммировать все четные числа:

<pawn>
SumEvenNumbers(const array[], count)
{
new sum;

for (new i = 0; i < count; i++)
{
/* If divisibility by 2 is 1, we know it's odd */
if (array[i] % 2 == 1)
{
/* Пропускаем оставшуюся часть итерации цикла */
continue;
}
sum += array[i];
}

return sum;
}</pawn>

=Область действия=
Область действия относится к '''удобочитаемости''' кода. Это означает, что код одного уровня не может быть "виден" в коде другого уровня. Пример:

<pawn>
new A, B, C;

Function1()
{
new B;

Function2();
}

Function2()
{
new C;
}</pawn>

В этом примере, <tt>A</tt>, <tt>B</tt>, и <tt>C</tt> имеют '''глобальную область действия'''. Их можно увидеть в любой функции. Вместе с тем, <tt>B</tt> в функции <tt>Function1</tt> не является той же переменной, как <tt>B</tt> на глобальном уровне. Вместо этого она находится в '''локальной области действия''', и поэтому является '''локально изменяемой'''.

Кроме того, функции <tt>Function1</tt> и <tt>Function2</tt> ничего не знают о существовании других переменных.

Она так же является не только локальной переменной функции <tt>Function1</tt>, но и создается заново каждый раз, когда функция вызывается. Попробуйте представить это:
<pawn>
Function1()
{
new B;

Function1();
}</pawn>

В приведенном выше примере, функция <tt>Function1</tt> вызывает сама себя. Конечно, это бесконечной рекурсии (а это очень плохо), но идея заключается в том, что каждый раз, когда функция срабатывает, то создается новая копия <tt>B</tt>. Когда функция завершается, <tt>B</tt> уничтожается, и её значение теряется.

Это свойство можно объяснить проще тем, что область действия переменной равна уровню её вложенности. То есть, переменная на глобальной области действия видна для всех функций. Переменная в локальной области действия видна всему блоку кода расположенному "ниже" этого уровня. Например:

<pawn>Function1()
{
new A;

if (A)
{
A = 5;
}
}</pawn>

Приведенный выше код является действительным, поскольку в область действия распространяется по всей функции. Однако этот код, работать не будет:
<pawn>
Function1()
{
new A;

if (A)
{
new B = 5;
}

B = 5;
}</pawn>

Отметим, что <tt>B</tt> объявляется в новом блоке кода. Это означает, что <tt>B</tt> доступна только в том блоке кода, в котором была создана (и всем под-блокам вложенных внутри него). Как только блок кода прекращается, <tt>B</tt> становится не действительной.

=Динамические массивы=
Динамические массивы это массивы, которые не имеют фиксированного размера. Например:

<pawn>Function1(size)
{
new array[size];

/* Код */
}</pawn>

Динамические массивы могут иметь любое выражение, соответствующее их размеру до тех пор, пока выражение вычисляется, как число большее чем 0. Как и для обычных массивов, SourcePawn не сможет узнать размер массива после того, как он будет создан; Вы должны задать его, если хотите использовать массив позднее.

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

=Расширенное объявление переменных=
Переменные могут быть объявлены более длинным путем чем просто <tt>new</tt>.

==decl==
===Purpose===
By default, all variables in Pawn are initialized to zero. If there is an explicit initializer, the variable is initialized to the expression after the <tt>=</tt> token. At a local scope, this can be a run-time expense. The <tt>decl</tt> keyword (which is only valid at local scope) was introduced to let users decide if they want variables initialized or not.

Note: <tt>decl</tt> should not be used on single cell variables. There is almost never any benefit.

===Explanation===
For example:

<pawn>
new c = 5;
new d;
new String:blah[512];

Format(blah, sizeof(blah), "%d %d", c, d);
</pawn>

In this code, <tt>c</tt> is equal to 5 and <tt>d</tt> is equal to 0. The run-time expense of this initialization is negligible. However, <tt>blah</tt> is a large array, and the expense of initializing the entire array to 0s could be detrimental in certain situations.

Note that <tt>blah</tt> does not need to be zeroed. In between being declared with <tt>new</tt> and stored with <tt>Format()</tt>, <tt>blah</tt> is never loaded or read. Thus this code would be more efficiently written as:

<pawn>
new c = 5;
new d;
decl String:blah[512];

Format(blah, sizeof(blah), "%d %d", c, d);
</pawn>

===Caveats===
The downside to <tt>decl</tt> is that it means its variables will start with "garbage" contents. For example, if we were to use:

<pawn>
new c = 5;
new d;
decl String:blah[512];

PrintToServer("%s", blah);

Format(blah, sizeof(blah), "%d %d", c, d);
</pawn>

This code may crash the server, because <tt>blah</tt> may be completely corrupt (strings require a terminator, and that may not be present). Similarly, if we did:

<pawn>
new c = 5;
decl d;
decl String:blah[512];

Format(blah, sizeof(blah), "%d %d", c, d);
</pawn>

The value of <tt>d</tt> is now undefined. It could be any value, negative or positive.

Note that it is easy to efficiently make strings safe. The example below shows how to terminate a garbage string:
<pawn>
decl String:blah[512];

blah[0] = '\0';
</pawn>

===Golden Rules===
*'''Only use decl if in between declaring and loading/reading the value, you are absolutely sure there is at least one store/set operation that gives the variable valid data.'''
*'''Do not prematurely optimize.''' Likewise, there is no need to use <tt>decl</tt> on non-arrays, because there is no added expense for initializing a single cell value.

===Notes===
This example is NOT as efficient as a <tt>decl</tt>:
<pawn>
new String:blah[512] = "a";
</pawn>

Even though the string is only one character, the <tt>new</tt> operator guarantees the rest of the array will be zeroed as well.

Also note, it is invalid to explicitly initialize a <tt>decl</tt>:
<pawn>decl String:blah[512] = "a";</pawn>

The above code will not compile, because the purpose of <tt>decl</tt> is to avoid any initialization.

==static==
The <tt>static</tt> keyword is available at global and local scope. It has different meanings in each.

===Global static===
A global static variable can only be accessed from within the same file. For example:

<pawn>//file1.inc
static Float:g_value1 = 0.15f;

//file2.inc
static Float:g_value2 = 0.15f;</pawn>

If a plugin includes both of these files, it will not be able to use either <tt>g_value1</tt> or <tt>g_value2</tt>. This is a simple information hiding mechanism, and is similar to declaring member variables as <tt>private</tt> in languages like C++, Java, or C#.

===Local static===
A local static variable is a global variable that is only visible from its local lexical scope. For example:

<pawn>
MyFunction(inc)
{
static counter = -1;

counter += inc;

return counter;
}</pawn>

In this example, <tt>counter</tt> is technically a global variable -- it is initialized once to -1 and is never initialized again. It does not exist on the stack. That means each time <tt>MyFunction</tt> runs, the <tt>counter</tt> variable and its storage in memory is the same.

Take this example:
<pawn>MyFunction(5);
MyFunction(6);
MyFunction(10);</pawn>

In this example, <tt>counter</tt> will be <tt>-1 + 5 + 6 + 10</tt>, or <tt>20</tt>, because it persists beyond the frame of the function. Note this may pose problems for recursive functions: if your function may be recursive, then <tt>static</tt> is usually not a good idea unless your code is re-entrant.

The benefit of a local static variable is that you don't have to clutter your script with global variables. As long as the variable doesn't need to be read by another function, you can squirrel it inside the function and its persistence will be guaranteed.

Note that statics can exist in any local scope:

<pawn>
MyFunction(inc)
{
if (inc > 0)
{
static counter;
return (counter += inc);
}
return -1;
}</pawn>

[[Category:Ru:SourceMod Scripting]]

Ru:Introduction to SourcePawn

2008-12-26T11:11:05Z

Frenzzy: /* Dynamic Arrays */

Это руководство призвано дать Вам самые основные представления по основам написания сприптов в SourcePawn. [[Pawn]] это "скриптовый" язык используемый для внедрения функциональности в других программах. Это означает, что это не самостоятельный язык, как C++ или Java, и его элементы будут отличаться в различных приложениях. SourcePawn это вариация языка Pawn используемая в [[SourceMod]].

Это руководство не расскажет Вам как писать SourceMod плагины; оно предназначено для получения общих представлений о синтаксисе и семантике этого языка. Читайте отдельную статью [[Ru:Introduction to SourceMod Plugins]] (Введение в SourceMod плагины), для введения в SourceMod API.

=Введение для новичков=
Этот раздел создан не для программистов. Если Вы по прежнему в замешательстве, Вы можете прочитать книги о других языках программирования, таких как PHP, Python, или Java, чтобы получить более полное представление о программировании.

==Идентификаторы/Ключевые слова==
Идентификаторы представляет собой набор букв, цифр и/или нижнего подчеркивания, что представляет собой нечто уникальное. Идентификаторы вводятся с учетом регистра (в отличие от PHP, где иногда это не требуется). Идентификаторы не начинаются с какого-либо специального символа, но они должны начинаться с буквы.

Есть несколько зарезервированных символов, которые имеют особое значение. Например, <tt>if</tt>, <tt>for</tt>, и <tt>return</tt> специальные конструкции в языке, которые будут описаны позднее. Они не могут быть использованы в качестве названий идентификаторов.

==Переменные==
Существует несколько важных конструкций, которые Вы должны знать, прежде чем приступить к написанию сценария. Во-первых, это '''переменные'''. Переменная это идентификатор, который содержит данные. Например, переменная "a" может содержать числа "2", "16", "0", и так далее. Переменные создаются для хранения данных внутри программы. Переменные должны быть объявлены до их использования, с помощью ключевого слова "new". Данные можно присвоить переменной, используя знак равенства (=). Пример:

<pawn>new a, b, c, d;

a = 5;
b = 16;
c = 0;
d = 500;</pawn>

В SourcePawn, переменные бывают двух типов, которые будут более подробно описаны далее.
*Однострочные (могут содержать только произвольные числовые данные), как показано выше.
*Многострочные (могут содержать целый ряд текстовых символов)

==Функции==
Следующим важным понятием являются '''функции'''. Функции идентификаторов или имен, которые выполняют действия. Это означает, что когда вы их активируете, они выполняют конкретную последовательность кода. Есть несколько типов функций, но все функции активируется одинаковым образом. "Вызов функции" является термином ссылающимся на функцию действия. Функция числовых переменных строятся так:
<pawn>функция(<параметры>)</pawn>

Примеры:

<pawn>show(56); //Активирует функцию "show" и присваивает ей число 56
show(); //Активирует функцию "show" без каких-либо данных, пустую
show(a); //Активирует функцию "show" и присваивает ей переменную с данными
</pawn>

Каждый фрагмент данных передаваемый вызываемой функции, называется '''параметр'''. Функция может иметь любое количество параметров (но есть "допустимый" предел в SourceMod: 32). Параметры будут описаны далее в этой статье.

==Комментарии==
Примечания и любой текст, который пишется после "//" считается "Комментарием", а не фактическим кодом. Есть два стиля комментариев:
*<tt>//</tt> - Двойная косая черта, всё следующие после этой строки игнорируется.
*<tt>/* */</tt> - Много-строчный комментарий, весь текст, внутри звездочек игнорируются. You cannot nest these.

==Массивы==
Описание массивов. Вы можете группировать код в виде "массивов", разделенных { и }. Это фактически создает возможность работать с целым массивом как с одним оператором. Например:

<pawn>{
here;
is;
some;
code;
}</pawn>

Массивы с фигурными скобками используются достаточно широко в программировании. Массивы кода могут быть вложенными друг в друга. Это хорошая возможность адаптировать последовательность когда и сделать его удобочитаемым, благодаря отступам код не будет смотреться как одна большая и длинная макаронина.

=Особенности языка=
Pawn может показаться очень похожим на другие языки программирования, например C, но Pawn от них фундаментально отличается. Не столь важно, чтобы Вы сейчас же поняли его отличия, но они понадобятся, если Вы уже знаете один из языков программирования.
*'''Pawn не печатает''' Pawn имеет только один тип данных - '''однострочный'''. Подробнее будет описано позже. [В дальнейшем автор рассказывает, что существует два типа данных: однострочный и многострочный]
*'''Pawn не собирает мусор''' Pawn, как язык, не имеет встроенных ресурсов памяти, и потому он не мусорит. Если функция выделит память, то Вы отвечаете за её освобождение.
*'''Pawn не объектно-ориентированный язык''' Pawn является процедурным, и полагается на подпрограммы. Также у него нету C подобных структур.
*'''Pawn не функциональный.''' Pawn является процедурным, и не поддерживает функции "лямбды" (Lambda), поздние присвоения, и все то, что можно найти в языках высшего уровня, таких как Phyton и Ruby.
*'''Pawn однопоточный''' As of this writing, Pawn is not thread safe.
*'''Pawn не интерпретируемый''' Ну, почти. Он интерпретируется на очень низком уровне. Вы должны скомпилировать код, из которого получится бинарный файл. Эта программа будет работать на той платформе, которую использует хост. Это ускоряет загрузку и позволяет легче находить ошибки.

Этот язык был выпущен ITB CompuPhase. Язык разработан для устройств низкого уровня и таким образом конечные программы очень маленькие по размеру и очень быстрые.

=Переменные=
В Pawn есть всего два типа переменных: '''однострочные''' и '''многострочные'''. Однострочные могут содержать 32 бита цифровых данных. Многострочные - последовательный список из UTF-8 символов.

'''однострочные''' не имеет своего типа, однако они могут быть '''маркированы'''(tagged). Тег позволяет Вам указывать, где определенную ячейку можно использовать. Типичные теги:
*(пусто), или '''_''' - Нет тега. Обычно используют для целых чисел ([http://en.wikipedia.org/wiki/Integer Integers]).
*'''Float''' - используют для чисел с плавающей точкой (небольших).
*'''bool''' - используют для хранения значений '''true''' (истина) или '''false''' (ложь).

Со строками все по другому, они будут рассмотрены далее.

==Объявления==
Примеры разных правильных объявлений переменных.
<pawn>
new a = 5;
new Float:b = 5.0;
new bool:c = true;
new bool:d = 0; //Работает, поскольку 0 равно false (ложь)
</pawn>

Неправильные объявления переменных
<pawn>
new a = 5.0; //Несоответствие тегов. 5.0 с тегом Float
new Float:b = 5; //Несоответствие тегов. 5 без тега.
</pawn>

Если переменная не определена в объявлении то ее значения станет 0
<pawn>
new a; //значение 0
new Float:b; //значение 0.0
new bool:c; //значение false
</pawn>

==Присвоение==
Переменным могут быть присвоены данные после создания. Пример:
<pawn>new a, Float:b, bool:c;

a = 5;
b = 5.0;
c = true;
</pawn>

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

==Описание==
Массив объявляется с помощью квадратных скобок. Вот некоторые примеры массивов:
<pawn>
new players[32]; //Набор из 32 однострочных (числовых) данных
new Float:origin[3]; //Набор из 3 чисел с плавающей точкой
</pawn>

По умолчанию, массивам присваиваются нули. Вы можете присвоить им разные значения по умолчанию, однако:
<pawn>
new numbers[5] = {1, 2, 3, 4, 5}; //Набор 1, 2, 3, 4, 5 из однострочных данных.
new Float:origin[3] = {1.0, 2.0, 3.0}; //Набор 1.0, 2.0, 3.0 из однострочных данных.
</pawn>

Вы можете оставить массив без размера, если вы собираетесь заранее присвоить ему данные. Например:
<pawn>
new numbers[] = {1, 3, 5, 7, 9};
</pawn>

Компилятор будет автоматически делать вывод о том, что Вы хотите получить массив размером 5.

==Использование==
Использование массива равносильно использованию обычных переменной. Единственное отличие массива состоит в том, что он должен быть '''индексируемым'''. Индексирование массива означает присутствие возможности выбрать элемент, который Вы хотите использовать.

Вот пример кода с использованием индексов:
<pawn>
new numbers[5], Float:origin[3];

numbers[0] = 1;
numbers[1] = 2;
numbers[2] = 3;
numbers[3] = 4;
numbers[4] = 5;
origin[0] = 1.0;
origin[1] = 2.0;
origin[2] = 3.0;
</pawn>

Заметим, что '''индекс''' это текст, который находится в квадратных скобках. Индекс всегда начинается с нуля. То есть, если массив имеет N элементов, его действительный индекс от 0 до N-1. Доступ к данным с индексами работает так же, как с обычной переменной.

Использование неверного индекса вызовет ошибку. Например:
<pawn>
new numbers[5];

numbers[5] = 20;</pawn>

Это может выглядеть верно, но число 5 не является допустимым индексом. Наибольшим значением индекса является число 4.

Вы можете использовать любые выражения, как индекс. Например:
<pawn>new a, numbers[5];

a = 1; //Сделает a = 1
numbers[a] = 4; //Сделает numbers[1] = 4
numbers[numbers[a]] = 2; //Сделает numbers[4] = 2
</pawn>

Выражения будут обсуждаться подробнее в конце статьи.

=Строки=
Строки являются удобным способом хранения текста. Символы хранятся в массиве. Строка ограничивается '''нулевым символом''', или 0. Без нулевого символа, Pawn не знает, где остановить чтение строки. Все строки в SourcePawn используют кодировку UTF-8.

Отметим, что строки имеют комбинацию из массивов и однострочных переменных. В отличие от других языков, это означает, что Вы должны знать заранее, как много места будут использовать строки. Это означает, что строки не являются динамичными. Они могут лишь вырасти до размера, которым Вы их ограничили.

''Примечание для специалистов: они фактически не однострочные. SourcePawn использует 8-битный строки для хранения массивов в качестве оптимизации. Это и есть то, что делает строки типом, а не меткой.''

==Использование==
Строки были созданы почти в равной степени и для массивов. Например:
<pawn>
new String:message[] = "Hello!";
new String:clams[6] = "Clams";
</pawn>

Это равносильно следующему:
<pawn>
new String:message[7], String:clams[6];

message[0] = 'H';
message[1] = 'e';
message[2] = 'l';
message[3] = 'l';
message[4] = 'o';
message[5] = '!';
message[6] = 0;
clams[0] = 'C';
clams[1] = 'l';
clams[2] = 'a';
clams[3] = 'm';
clams[4] = 's';
clams[5] = 0;
</pawn>

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

Заметим, что строка должна быть заключена в двойных кавычках, а символ в одиночных.

==Символы==
Особенность текста может быть использована в любой строке или однострочной переменной. Например:
<pawn>new String:text[] = "Crab";
new clam;

clam = 'D'; //Устанавливает однострочной переменной значение 'D'
text[0] = 'A'; //Меняет 'C' на 'A', сейчас получилось 'Arab'
clam = text[0]; //Устанавливает однострочной переменной значение 'A'
text[1] = clam; //Меняет 'r' на 'A', сейчас получилось 'AAab'
</pawn>

То, что вы не можете сделать, это соотнести символы массивов со строками. Внутреннее хранение отличается. Например:
<pawn>
new clams[] = "Clams"; //Не верно, нужен тип String:
new clams[] = {'C', 'l', 'a', 'm', 's', 0}; //Верно, но это НЕ СТРОКА.
</pawn>

=Функции=
Функции, как отмечалось ранее, имеют отдельные составляющие кода, которые выполняют определенные действия. Функции могут быть задействованы или '''вызвоны''' с '''параметрами''', которые дают особые настройки.

Существуют два типа вызова функции:
*'''прямой вызов''' - Вы специально вызываете функцию в своем коде.
*'''обратный вызов''' - Применение вызова функций в Вашем коде, как если бы это было событием триггера (совокупность условий, инициирующих выполнение действия).

Существуют пять видов функций:
*'''native''': Прямая, внутренняя функция, предусмотренная в приложении.
*'''public''': Функция обратного вызова, что делает её видимой для приложения и других сценариев.
*'''normal''': Нормальная функция, которую Вы можете только вызвать.
*'''stock''': Нормальная функция, предусмотренная если включает в себя файл. Если не используется, то не компилируется.
*'''forward''': Эта функция представляет собой глобальное событие, предусмотренная приложением. Если Вы её привели в исполнение, она будет вызвона.

Весь код в Pawn должен существовать в функциях. Это основное отличие от языков, таких как PHP, Perl и Python, которые позволяют Вам писать глобальный код. Это происходит потому, что Pawn вызывается на основе другого языка: он реагирует на действия от родительского приложения, и функции должны быть написаны для обработки этих действий. Хотя наш пример, часто содержат свободно плавающий код, это сделано исключительно для демонстрационных целей. Свободно плавающий код в нашем примере означает, что код является частью ряда функций.

==Описание==
В отличие от переменных, функции, не нужно объявлять, прежде чем использовать их. Функции имеют две части, '''модель''' и '''тело'''. Модель содержит имя Вашей функции и параметры, которые она будет принимать. Тело является контейнером для кода.

Пример функции:
<pawn>
AddTwoNumbers(first, second)
{
new sum = first + second;

return sum;
}</pawn>

Это простая функция. Модель этой строки:
<pawn>AddTwoNumbers(first, second)</pawn>

Распишем по отдельности:
*<tt>AddTwoNumbers</tt> - Название функции.
*<tt>first</tt> - Название первого параметра, который представляет собой простой элемент.
*<tt>second</tt> - Название второго параметра, который представляет собой простой элемент.

Тело представляет собой простой блок кода. Он создает новую переменную, названную <tt>sum</tt>, и присваивает ей значение этих двух параметров, добавленных совместно (другие выражения будут позже). Важно заметить оператор <tt>return</tt>, в котором обозначается конец функции и возврат с полученными значениями из этой функции. Все функции ''возвращают значения'' после завершения. Это означает, например:

<pawn>new sum = AddTwoNumbers(4, 5);</pawn>

Приведенный выше код будет присваивать число 9 к sum. Функция получает два значения и передает новое значение sum в качестве '''возвращаемого значения'''. Если функция не имеет возвращаемого значения или не имеет значений для возврата, то возвращается 0 по умолчанию.

Функция может принимать любые типы значений. Она может вернуть любую однострочную переменную, но не массивы или строки. Пример:
<pawn>Float:AddTwoFloats(Float:a, Float:b)
{
new Float:sum = a + b;

return sum;
}</pawn>

''Заметим, что если в приведенной выше функции, Вам вернулась не Float значение, Вы получите не соответствие значений.''

Можно, конечно, передавать переменные в функции:
<pawn>new numbers[3] = {1, 2, 0};

numbers[2] = AddTwoNumbers(numbers[0], numbers[1]);</pawn>

Заметим, что однострочные переменные передаются '''по значению'''. То есть, их значение не может быть изменено функцией. Например:
<pawn>new a = 5;

ChangeValue(a);

ChangeValue(b)
{
b = 5;
}</pawn>

Этот код не будет менять значение <tt>a</tt>. Это происходит потому, что копия этого значения в <tt>a</tt> передается вместо <tt>a</tt> самостоятельно.

Больше примеров функций будут демонстрироваться и в других частях статьи.

==Publics==
Публичные функции используются для осуществления обратных вызовов. Вы не должны создавать какую-либо публичную функцию, если это вынудит выполнение обратного вызова. Например, вот два обратных вызова из <tt>sourcemod.inc</tt>:

<pawn>forward OnPluginStart();
forward OnClientDisconnected(client);</pawn>

Чтобы выполнить и получить эти два события, Вы должны написать такие функции как:

<pawn>public OnPluginStart()
{
/* Код здесь */
}

public OnClientDisconnected(client)
{
/* Код здесь */
}</pawn>

Ключевое слово '''public''' делает функцию публичной, а также позволяет родительскому приложению непосредственно вызывать функцию.

==Natives==
Natives имеют встроенные функции, предоставляемые приложением. Вы можете вызвать их, как если бы они были normal функциями. Например, SourceMod имеет следующие функции:

<pawn>native FloatRound(Float:num);</pawn>

Её можно вызвать таким образом:
<pawn>new num = FloatRound(5.2); //Результат в num = 5</pawn>

==Параметры массива==
Вы можете передавать массивы или строки в качестве параметров. Важно отметить, что они идут '''как ссылка'''. То есть не делать копию данных, а отдавать непосредственно ссылки на данные. Существует простой способ объяснить это более конкретно.

<pawn>
new example[] = {1, 2, 3, 4, 5};

ChangeArray(example, 2, 29);

ChangeArray(array[], index, value)
{
array[index] = value;
}</pawn>

Эта функция устанавливает заданный индекс в массиве с учетом значений. Когда она запускается на примере нашего массива, она меняет индекс 2 для значения 3 на 29. То есть:
<pawn>example[2] = 29;</pawn>

Это возможно лишь потому, что массив может быть непосредственно изменён. Чтобы предотвратить массив от изменения, можно пометить его как постоянную <tt>const</tt>. Это позволит понизить риск на ошибку в коде от её изменения. Например:

<pawn>CantChangeArray(const array[], index, value)
{
array[index] = value; //Не компилируется
}</pawn>

Это хорошая идея использовать <tt>const</tt> в параметрах массивов и Вы будете точно знать, что массив не будет изменен; это может предотвратить ошибки кодирования.

=Выражения=
Выражения являются точно такими же, какими они существуют в математике. Это группы операторов/символов, которые приходятся на один фрагмент данных. Они часто заключены в скобках (внутри скобок). Они содержат строгий "порядок операций". Они могут содержать переменные, функции, цифры и выражения сами могут быть вложенные внутрь других выражений, и даже приняты в качестве параметров.

Приведем пример простейшего выражения:
<pawn>
0; //Возвращает число 0
(0); //Так же возвращает число 0
</pawn>

Хотя выражения могут возвращать значения, они также могут ответить какое значение содержит ответ ''ноль или не ноль''. В этом смысле, ''ноль'' является ''ложью'' (false), а ''не нулевое'' значение ''истиной'' (true). Например, -1 ''истина'' в Pawn, поскольку она не является нулем. Не думайте, что отрицательные числа являются ложными.

Порядок операций выражения аналогичен языку C. PMDAS: Parenthesis, Multiplication, Division, Addition, Subtraction. Вот несколько примеров выражений:
<pawn>
5 + 6; //Вычисляет как 11
5 * 6 + 3; //Вычисляет как 33
5 * (6 + 3); //Вычисляет как 45
5.0 + 2.3; //Вычисляет как 7.3
(5 * 6) % 7; //Modulo operator, вычисляет как 2
(5 + 3) / 2 * 4 - 9; //Вычисляет как 7
</pawn>

Как уже отмечалось, выражения могут содержать переменные, или даже функции:
<pawn>
new a = 5 * 6;
new b = a * 3; //Вычисляет как 90
new c = AddTwoNumbers(a, b) + (a * b);
</pawn>

==Операторы==
Есть несколько полезных дополнительных операторов в Pawn. Первый набор упрощает аутоагрегацию выражения. Например:
<pawn>new a = 5;

a = a + 5;</pawn>

Может быть переписан, как:
<pawn>new a = 5;
a += 5;</pawn>

Это верно в отношении следующих операторов в Pawn:
*Four-function: *, /, -, +
*Bit-wise: |, &, ^, ~, <<, >>

Кроме того, существуют инкремент/декремент операторы:
<pawn>a = a + 1;
a = a - 1;</pawn>

Может быть упрощено, как:
<pawn>a++;
a--;</pawn>

Дополнительно отметим, что ++ или -- может быть представлен до переменной (до-инкремент, до-декремент) или после переменной (пост-инкремент, пост-декремент). Разница заключается в том, как остальная часть выражения содержащие их, видит результат.

* ''До:'' Переменная увеличивается до определения и остальная часть выражения видит новое значение.
* ''Пост:'' Переменная увеличивается после определения и остальная часть выражения видит старое значение.

Иными словами, <tt>a++</tt> определяет значение как <tt>a</tt> в то время как <tt>++a</tt> определяет значение как <tt>a + 1</tt>. В обоих случаях <tt>a</tt> увеличивается на <tt>1</tt>.

Например:

<pawn>new a = 5;
new b = a++; // b = 5, a = 6 (1)
new c = ++a; // a = 7, c = 7 (2)
</pawn>

(1) <tt>b</tt> присваивается <tt>a</tt> со ''старым'' значением, ''до'' того, как он будет увеличено до <tt>6</tt>. (2) <tt>c</tt> присваивается <tt>a</tt> с ''новым'' значением, ''после'' того, как он увеличивается до <tt>7</tt>.

==Операторы сравнения==
Существуют шесть операторов для сравнения двух числовых значений, а результат является либо истиной (не ноль) или ложью (ноль):
*<tt>a == b</tt> - Действительно, если и b имеет то же значение.
*<tt>a != b</tt> - Действительно, если b имеет другое значение.
*<tt>a > b</tt> - Действительно, если оно больше b
*<tt>a >= b</tt> - Действительно, если оно больше или равно b
*<tt>a < b</tt> - Действительно, если оно меньше b
*<tt>a <= b</tt> - Действительно, если оно меньше или равно b

Например:
<pawn>
(1 != 3); //Определяется как истина, поскольку 1 не равно 3.
(3 + 3 == 6); //Определяется как истина, поскольку 3+3 равно 6.
(5 - 2 >= 4); //Определяется как ложь, поскольку 3 меньше 4.
</pawn>

Заметим, что эти операторы не работают с массивами и строками. То есть, вы не можете сравнить их с помощью <tt>==</tt>.

==Действительные операторы==
Действительные операторы могут быть скомбинированы тремя булевыми (boolean) операторами:
*<tt>a && b</tt> - Истина, если a и b истинные. Ложь, если a и (или) b ложные.
{| border="1" cellpadding="2" cellspacing="0" align="center"
! <tt>&&</tt> !! 0 !! 1
|-
! 0
| 0 || 0
|-
! 1
| 0 || 1
|}
*<tt>a || b</tt> - Истина, если a или b (или обе переменные) истинные. Ложь, если обе переменные a и b ложные.
{| border="1" cellpadding="2" cellspacing="0" align="center"
! <tt><nowiki>||</nowiki></tt> !! 0 !! 1
|-
! 0
| 0 || 1
|-
! 1
| 1 || 1
|}
*<tt>!a</tt> - Истина, если a ложь. Ложь, если a истина.
{| border="1" cellpadding="2" cellspacing="0" align="center"
! <tt>!</tt> !! 0 !! 1
|-
!
| 1 || 0
|}

Например:
<pawn>
(1 || 0); //Определяется как истина, так как выражение 1 истинное
(1 && 0); //Определяется как ложь, так как выражение 0 ложное
(!1 || 0); //Определяется как ложь, так как выражение !1 ложное.
</pawn>

==Левое/правое значения==
Два важных понятия левого и правого значений, или левостороннее и правостороннее значения. Левостороннее значение имеет то, что появляется на левой стороне выражения, а правостороннее значение - появляется на правой стороне выражения.

Например:
<pawn>
new a = 5;</pawn>

В этом примере <tt>a</tt> является левосторонним значением и <tt>5</tt> является правосторонним значением.

Правила:
*'''Выражения никогда не будут левосторонними значениями'''.
*'''Переменные являются двумя, левосторонними и правосторонними значениями'''.

=Условия=
Условия позволяют Вам запускать код, определенное условие выполнено.

==Если соответствует==
Если соответствует одно или более условий. Например:

<pawn>
if (a == 5)
{
/* Код будет запущен, если условие будет истинным */
}</pawn>

Они могут быть расширены для более сложных случаев:
<pawn>
if (a == 5)
{
/* Код */
}
else if (a == 6)
{
/* Код */
}
else if (a == 7)
{
/* Код */
}</pawn>

Вы так же можете обрабатывать случаи, даже если выражение не верно. Например:
<pawn>
if (a == 5)
{
/* Код */
}
else
{
/* Код, который будет запущен если нет истинного выражения */
}</pawn>

==Оператор выбора==
Оператор выбора будет ограничен условием. Он необходим для выражения, выполняющего код для целого ряда возможных значений. Например:

<pawn>
switch (a)
{
case 5:
{
/* Код */
}
case 6:
{
/* Код */
}
case 7:
{
/* Код */
}
case 8, 9, 10:
{
/* Код */
}
default:
{
/* будет запущен, если не одно условие не соответствует */
}
}</pawn>

В отличие от некоторых других языков, оператор выбора не проваливается. То есть существуют случаи, когда код не будет запущен. При случае совпадения его код выполняется, а ключ является местом для немедленного прекращения.

=Циклы=
Циклы позволяют Вам без труда повторять выполнение кода, пока условие станет истинным.

==For циклы==
For циклы, это циклы, которые состоят из четырех частей:
*Оператор '''инициализации''' - запускается один раз перед первым циклом.
*Оператор '''условия''' - проверяет условие и запускает следующий цикл, в том числе первый. Цикл прекращается, когда это выражение становится ложным.
*Оператор '''итерации''' - запускается после каждого цикла.
* '''тело''' цикла - запускается каждый раз, пока оператор '''условия''' вычисляется как истинный.

<pawn>
for ( /* инициализация */ ; /* условие */ ; /* итерация */ )
{
/* тело */
}
</pawn>

Простым примером является функция сложения массива:
<pawn>
new array[10] = {1, 2, 3, 4, 5, 6, 7, 8, 9, 10};
new sum = SumArray(array, 10);

SumArray(const array[], count)
{
new total;

for (new i = 0; i < count; i++)
{
total += array[i];
}

return total;
}</pawn>

По отдельности:
*<tt>new i = 0</tt> - Создает новую переменную для цикла, и устанавливает её в 0.
*<tt>i < count</tt> - Только запускает цикл, если <tt>i</tt> меньше, чем <tt>count</tt>. Это гарантирует, что чтение цикла прекращается в определенный момент. В этом случае, мы не хотим читать недействительные индексы в массиве.
*<tt>i++</tt> - Увеличивает <tt>i</tt> на единицу после каждого цикла. Это гарантирует, что цикл не будет запущен вечно; в конце концов <tt>i</tt> станет слишком большим, и цикл завершится.

Таким образом, функция <tt>SumArray</tt> будет циклом каждого действительного индекса массива, каждый раз добавляя это значение в sum. Для циклов очень распространены массивы такие, как в нашем примере.

==While циклы==
While циклы являются менее распространенными, чем for циклы, но на самом деле это более простые циклы. Они имеют только две части:
*Оператор '''условия''' - проверяется перед началом каждого цикла. Цикл прекращается, когда условие становится ложным.
*'''тело''' цикла - запускается каждый раз пока цикл выполняется.

<pawn>
while ( /* условие */ )
{
/* тело */
}
</pawn>

До тех пор, пока условие выражения остается истинным, цикл будет выполняться. Каждый for цикл может быть переписан, как while цикл:

<pawn>
/* инициализация */
while ( /* условие */ )
{
/* тело */
/* итерация */
}
</pawn>

Вот предыдущий for цикл переписан как while цикл:
<pawn>
SumArray(const array[], count)
{
new total, i;

while (i < count)
{
total += array[i];
i++;
}

return total;
}</pawn>

Существуют также '''do...while''' циклы, которые используются еще реже. Они работают как и while циклы, но проверяют условие ПОСЛЕ каждого цикла, а не перед ним. Это означает, что цикл всегда будет запущен, по крайней мере один раз. Например:

<pawn>
do
{
/* тело */
}
while ( /* условие */ );
</pawn>

==Управление циклами==
Существуют два случая, в которых Мы хотели бы контролировать цикл:
*'''пропустить''' одну итерацию или цикл и продолжить выполнение цикла как обычно, или;
*'''разорвать''' цикл целиком, прежде чем он закончится.

Допустим у вас есть функция, которая принимает массив и ищет соответствия цифр. Вы хотите его остановить, когда число будет найдено:
<pawn>
/**
* Возвращает массив, если индекс значения, или -1, не найдены.
*/
SearchInArray(const array[], count, value)
{
new index = -1;

for (new i = 0; i < count; i++)
{
if (array[i] == value)
{
index = i;
break;
}
}

return index;
}</pawn>

Конечно, эту функцию можно вернуть и способом <tt>return i</tt>, но пример показывает, как <tt>break</tt> может остановить цикл.

Кроме того, ключевое слово <tt>continue</tt> пропускает итерации цикла. Например, Мы хотим суммировать все четные числа:

<pawn>
SumEvenNumbers(const array[], count)
{
new sum;

for (new i = 0; i < count; i++)
{
/* If divisibility by 2 is 1, we know it's odd */
if (array[i] % 2 == 1)
{
/* Пропускаем оставшуюся часть итерации цикла */
continue;
}
sum += array[i];
}

return sum;
}</pawn>

=Область действия=
Область действия относится к '''удобочитаемости''' кода. Это означает, что код одного уровня не может быть "виден" в коде другого уровня. Пример:

<pawn>
new A, B, C;

Function1()
{
new B;

Function2();
}

Function2()
{
new C;
}</pawn>

В этом примере, <tt>A</tt>, <tt>B</tt>, и <tt>C</tt> имеют '''глобальную область действия'''. Их можно увидеть в любой функции. Вместе с тем, <tt>B</tt> в функции <tt>Function1</tt> не является той же переменной, как <tt>B</tt> на глобальном уровне. Вместо этого она находится в '''локальной области действия''', и поэтому является '''локально изменяемой'''.

Кроме того, функции <tt>Function1</tt> и <tt>Function2</tt> ничего не знают о существовании других переменных.

Она так же является не только локальной переменной функции <tt>Function1</tt>, но и создается заново каждый раз, когда функция вызывается. Попробуйте представить это:
<pawn>
Function1()
{
new B;

Function1();
}</pawn>

В приведенном выше примере, функция <tt>Function1</tt> вызывает сама себя. Конечно, это бесконечной рекурсии (а это очень плохо), но идея заключается в том, что каждый раз, когда функция срабатывает, то создается новая копия <tt>B</tt>. Когда функция завершается, <tt>B</tt> уничтожается, и её значение теряется.

Это свойство можно объяснить проще тем, что область действия переменной равна уровню её вложенности. То есть, переменная на глобальной области действия видна для всех функций. Переменная в локальной области действия видна всему блоку кода расположенному "ниже" этого уровня. Например:

<pawn>Function1()
{
new A;

if (A)
{
A = 5;
}
}</pawn>

Приведенный выше код является действительным, поскольку в область действия распространяется по всей функции. Однако этот код, работать не будет:
<pawn>
Function1()
{
new A;

if (A)
{
new B = 5;
}

B = 5;
}</pawn>

Отметим, что <tt>B</tt> объявляется в новом блоке кода. Это означает, что <tt>B</tt> доступна только в том блоке кода, в котором была создана (и всем под-блокам вложенных внутри него). Как только блок кода прекращается, <tt>B</tt> становится не действительной.

=Динамические массивы=
Динамические массивы это массивы, которые не имеют фиксированного размера. Например:

<pawn>Function1(size)
{
new array[size];

/* Код */
}</pawn>

Динамические массивы могут иметь любое выражение, соответствующее их размеру до тех пор, пока выражение вычисляется, как число большее чем 0. Как и для обычных массивов, SourcePawn не сможет узнать размер массива после того, как он будет создан; Вы должны задать его, если хотите использовать массив позднее.

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

=Extended Variable Declarations=
Variables can be declared in more ways than simply <tt>new</tt>.

==decl==
===Purpose===
By default, all variables in Pawn are initialized to zero. If there is an explicit initializer, the variable is initialized to the expression after the <tt>=</tt> token. At a local scope, this can be a run-time expense. The <tt>decl</tt> keyword (which is only valid at local scope) was introduced to let users decide if they want variables initialized or not.

Note: <tt>decl</tt> should not be used on single cell variables. There is almost never any benefit.

===Explanation===
For example:

<pawn>
new c = 5;
new d;
new String:blah[512];

Format(blah, sizeof(blah), "%d %d", c, d);
</pawn>

In this code, <tt>c</tt> is equal to 5 and <tt>d</tt> is equal to 0. The run-time expense of this initialization is negligible. However, <tt>blah</tt> is a large array, and the expense of initializing the entire array to 0s could be detrimental in certain situations.

Note that <tt>blah</tt> does not need to be zeroed. In between being declared with <tt>new</tt> and stored with <tt>Format()</tt>, <tt>blah</tt> is never loaded or read. Thus this code would be more efficiently written as:

<pawn>
new c = 5;
new d;
decl String:blah[512];

Format(blah, sizeof(blah), "%d %d", c, d);
</pawn>

===Caveats===
The downside to <tt>decl</tt> is that it means its variables will start with "garbage" contents. For example, if we were to use:

<pawn>
new c = 5;
new d;
decl String:blah[512];

PrintToServer("%s", blah);

Format(blah, sizeof(blah), "%d %d", c, d);
</pawn>

This code may crash the server, because <tt>blah</tt> may be completely corrupt (strings require a terminator, and that may not be present). Similarly, if we did:

<pawn>
new c = 5;
decl d;
decl String:blah[512];

Format(blah, sizeof(blah), "%d %d", c, d);
</pawn>

The value of <tt>d</tt> is now undefined. It could be any value, negative or positive.

Note that it is easy to efficiently make strings safe. The example below shows how to terminate a garbage string:
<pawn>
decl String:blah[512];

blah[0] = '\0';
</pawn>

===Golden Rules===
*'''Only use decl if in between declaring and loading/reading the value, you are absolutely sure there is at least one store/set operation that gives the variable valid data.'''
*'''Do not prematurely optimize.''' Likewise, there is no need to use <tt>decl</tt> on non-arrays, because there is no added expense for initializing a single cell value.

===Notes===
This example is NOT as efficient as a <tt>decl</tt>:
<pawn>
new String:blah[512] = "a";
</pawn>

Even though the string is only one character, the <tt>new</tt> operator guarantees the rest of the array will be zeroed as well.

Also note, it is invalid to explicitly initialize a <tt>decl</tt>:
<pawn>decl String:blah[512] = "a";</pawn>

The above code will not compile, because the purpose of <tt>decl</tt> is to avoid any initialization.

==static==
The <tt>static</tt> keyword is available at global and local scope. It has different meanings in each.

===Global static===
A global static variable can only be accessed from within the same file. For example:

<pawn>//file1.inc
static Float:g_value1 = 0.15f;

//file2.inc
static Float:g_value2 = 0.15f;</pawn>

If a plugin includes both of these files, it will not be able to use either <tt>g_value1</tt> or <tt>g_value2</tt>. This is a simple information hiding mechanism, and is similar to declaring member variables as <tt>private</tt> in languages like C++, Java, or C#.

===Local static===
A local static variable is a global variable that is only visible from its local lexical scope. For example:

<pawn>
MyFunction(inc)
{
static counter = -1;

counter += inc;

return counter;
}</pawn>

In this example, <tt>counter</tt> is technically a global variable -- it is initialized once to -1 and is never initialized again. It does not exist on the stack. That means each time <tt>MyFunction</tt> runs, the <tt>counter</tt> variable and its storage in memory is the same.

Take this example:
<pawn>MyFunction(5);
MyFunction(6);
MyFunction(10);</pawn>

In this example, <tt>counter</tt> will be <tt>-1 + 5 + 6 + 10</tt>, or <tt>20</tt>, because it persists beyond the frame of the function. Note this may pose problems for recursive functions: if your function may be recursive, then <tt>static</tt> is usually not a good idea unless your code is re-entrant.

The benefit of a local static variable is that you don't have to clutter your script with global variables. As long as the variable doesn't need to be read by another function, you can squirrel it inside the function and its persistence will be guaranteed.

Note that statics can exist in any local scope:

<pawn>
MyFunction(inc)
{
if (inc > 0)
{
static counter;
return (counter += inc);
}
return -1;
}</pawn>

[[Category:Ru:SourceMod Scripting]]

Ru:Introduction to SourcePawn

2008-12-26T10:58:49Z

Frenzzy: /* Scope */

Это руководство призвано дать Вам самые основные представления по основам написания сприптов в SourcePawn. [[Pawn]] это "скриптовый" язык используемый для внедрения функциональности в других программах. Это означает, что это не самостоятельный язык, как C++ или Java, и его элементы будут отличаться в различных приложениях. SourcePawn это вариация языка Pawn используемая в [[SourceMod]].

Это руководство не расскажет Вам как писать SourceMod плагины; оно предназначено для получения общих представлений о синтаксисе и семантике этого языка. Читайте отдельную статью [[Ru:Introduction to SourceMod Plugins]] (Введение в SourceMod плагины), для введения в SourceMod API.

=Введение для новичков=
Этот раздел создан не для программистов. Если Вы по прежнему в замешательстве, Вы можете прочитать книги о других языках программирования, таких как PHP, Python, или Java, чтобы получить более полное представление о программировании.

==Идентификаторы/Ключевые слова==
Идентификаторы представляет собой набор букв, цифр и/или нижнего подчеркивания, что представляет собой нечто уникальное. Идентификаторы вводятся с учетом регистра (в отличие от PHP, где иногда это не требуется). Идентификаторы не начинаются с какого-либо специального символа, но они должны начинаться с буквы.

Есть несколько зарезервированных символов, которые имеют особое значение. Например, <tt>if</tt>, <tt>for</tt>, и <tt>return</tt> специальные конструкции в языке, которые будут описаны позднее. Они не могут быть использованы в качестве названий идентификаторов.

==Переменные==
Существует несколько важных конструкций, которые Вы должны знать, прежде чем приступить к написанию сценария. Во-первых, это '''переменные'''. Переменная это идентификатор, который содержит данные. Например, переменная "a" может содержать числа "2", "16", "0", и так далее. Переменные создаются для хранения данных внутри программы. Переменные должны быть объявлены до их использования, с помощью ключевого слова "new". Данные можно присвоить переменной, используя знак равенства (=). Пример:

<pawn>new a, b, c, d;

a = 5;
b = 16;
c = 0;
d = 500;</pawn>

В SourcePawn, переменные бывают двух типов, которые будут более подробно описаны далее.
*Однострочные (могут содержать только произвольные числовые данные), как показано выше.
*Многострочные (могут содержать целый ряд текстовых символов)

==Функции==
Следующим важным понятием являются '''функции'''. Функции идентификаторов или имен, которые выполняют действия. Это означает, что когда вы их активируете, они выполняют конкретную последовательность кода. Есть несколько типов функций, но все функции активируется одинаковым образом. "Вызов функции" является термином ссылающимся на функцию действия. Функция числовых переменных строятся так:
<pawn>функция(<параметры>)</pawn>

Примеры:

<pawn>show(56); //Активирует функцию "show" и присваивает ей число 56
show(); //Активирует функцию "show" без каких-либо данных, пустую
show(a); //Активирует функцию "show" и присваивает ей переменную с данными
</pawn>

Каждый фрагмент данных передаваемый вызываемой функции, называется '''параметр'''. Функция может иметь любое количество параметров (но есть "допустимый" предел в SourceMod: 32). Параметры будут описаны далее в этой статье.

==Комментарии==
Примечания и любой текст, который пишется после "//" считается "Комментарием", а не фактическим кодом. Есть два стиля комментариев:
*<tt>//</tt> - Двойная косая черта, всё следующие после этой строки игнорируется.
*<tt>/* */</tt> - Много-строчный комментарий, весь текст, внутри звездочек игнорируются. You cannot nest these.

==Массивы==
Описание массивов. Вы можете группировать код в виде "массивов", разделенных { и }. Это фактически создает возможность работать с целым массивом как с одним оператором. Например:

<pawn>{
here;
is;
some;
code;
}</pawn>

Массивы с фигурными скобками используются достаточно широко в программировании. Массивы кода могут быть вложенными друг в друга. Это хорошая возможность адаптировать последовательность когда и сделать его удобочитаемым, благодаря отступам код не будет смотреться как одна большая и длинная макаронина.

=Особенности языка=
Pawn может показаться очень похожим на другие языки программирования, например C, но Pawn от них фундаментально отличается. Не столь важно, чтобы Вы сейчас же поняли его отличия, но они понадобятся, если Вы уже знаете один из языков программирования.
*'''Pawn не печатает''' Pawn имеет только один тип данных - '''однострочный'''. Подробнее будет описано позже. [В дальнейшем автор рассказывает, что существует два типа данных: однострочный и многострочный]
*'''Pawn не собирает мусор''' Pawn, как язык, не имеет встроенных ресурсов памяти, и потому он не мусорит. Если функция выделит память, то Вы отвечаете за её освобождение.
*'''Pawn не объектно-ориентированный язык''' Pawn является процедурным, и полагается на подпрограммы. Также у него нету C подобных структур.
*'''Pawn не функциональный.''' Pawn является процедурным, и не поддерживает функции "лямбды" (Lambda), поздние присвоения, и все то, что можно найти в языках высшего уровня, таких как Phyton и Ruby.
*'''Pawn однопоточный''' As of this writing, Pawn is not thread safe.
*'''Pawn не интерпретируемый''' Ну, почти. Он интерпретируется на очень низком уровне. Вы должны скомпилировать код, из которого получится бинарный файл. Эта программа будет работать на той платформе, которую использует хост. Это ускоряет загрузку и позволяет легче находить ошибки.

Этот язык был выпущен ITB CompuPhase. Язык разработан для устройств низкого уровня и таким образом конечные программы очень маленькие по размеру и очень быстрые.

=Переменные=
В Pawn есть всего два типа переменных: '''однострочные''' и '''многострочные'''. Однострочные могут содержать 32 бита цифровых данных. Многострочные - последовательный список из UTF-8 символов.

'''однострочные''' не имеет своего типа, однако они могут быть '''маркированы'''(tagged). Тег позволяет Вам указывать, где определенную ячейку можно использовать. Типичные теги:
*(пусто), или '''_''' - Нет тега. Обычно используют для целых чисел ([http://en.wikipedia.org/wiki/Integer Integers]).
*'''Float''' - используют для чисел с плавающей точкой (небольших).
*'''bool''' - используют для хранения значений '''true''' (истина) или '''false''' (ложь).

Со строками все по другому, они будут рассмотрены далее.

==Объявления==
Примеры разных правильных объявлений переменных.
<pawn>
new a = 5;
new Float:b = 5.0;
new bool:c = true;
new bool:d = 0; //Работает, поскольку 0 равно false (ложь)
</pawn>

Неправильные объявления переменных
<pawn>
new a = 5.0; //Несоответствие тегов. 5.0 с тегом Float
new Float:b = 5; //Несоответствие тегов. 5 без тега.
</pawn>

Если переменная не определена в объявлении то ее значения станет 0
<pawn>
new a; //значение 0
new Float:b; //значение 0.0
new bool:c; //значение false
</pawn>

==Присвоение==
Переменным могут быть присвоены данные после создания. Пример:
<pawn>new a, Float:b, bool:c;

a = 5;
b = 5.0;
c = true;
</pawn>

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

==Описание==
Массив объявляется с помощью квадратных скобок. Вот некоторые примеры массивов:
<pawn>
new players[32]; //Набор из 32 однострочных (числовых) данных
new Float:origin[3]; //Набор из 3 чисел с плавающей точкой
</pawn>

По умолчанию, массивам присваиваются нули. Вы можете присвоить им разные значения по умолчанию, однако:
<pawn>
new numbers[5] = {1, 2, 3, 4, 5}; //Набор 1, 2, 3, 4, 5 из однострочных данных.
new Float:origin[3] = {1.0, 2.0, 3.0}; //Набор 1.0, 2.0, 3.0 из однострочных данных.
</pawn>

Вы можете оставить массив без размера, если вы собираетесь заранее присвоить ему данные. Например:
<pawn>
new numbers[] = {1, 3, 5, 7, 9};
</pawn>

Компилятор будет автоматически делать вывод о том, что Вы хотите получить массив размером 5.

==Использование==
Использование массива равносильно использованию обычных переменной. Единственное отличие массива состоит в том, что он должен быть '''индексируемым'''. Индексирование массива означает присутствие возможности выбрать элемент, который Вы хотите использовать.

Вот пример кода с использованием индексов:
<pawn>
new numbers[5], Float:origin[3];

numbers[0] = 1;
numbers[1] = 2;
numbers[2] = 3;
numbers[3] = 4;
numbers[4] = 5;
origin[0] = 1.0;
origin[1] = 2.0;
origin[2] = 3.0;
</pawn>

Заметим, что '''индекс''' это текст, который находится в квадратных скобках. Индекс всегда начинается с нуля. То есть, если массив имеет N элементов, его действительный индекс от 0 до N-1. Доступ к данным с индексами работает так же, как с обычной переменной.

Использование неверного индекса вызовет ошибку. Например:
<pawn>
new numbers[5];

numbers[5] = 20;</pawn>

Это может выглядеть верно, но число 5 не является допустимым индексом. Наибольшим значением индекса является число 4.

Вы можете использовать любые выражения, как индекс. Например:
<pawn>new a, numbers[5];

a = 1; //Сделает a = 1
numbers[a] = 4; //Сделает numbers[1] = 4
numbers[numbers[a]] = 2; //Сделает numbers[4] = 2
</pawn>

Выражения будут обсуждаться подробнее в конце статьи.

=Строки=
Строки являются удобным способом хранения текста. Символы хранятся в массиве. Строка ограничивается '''нулевым символом''', или 0. Без нулевого символа, Pawn не знает, где остановить чтение строки. Все строки в SourcePawn используют кодировку UTF-8.

Отметим, что строки имеют комбинацию из массивов и однострочных переменных. В отличие от других языков, это означает, что Вы должны знать заранее, как много места будут использовать строки. Это означает, что строки не являются динамичными. Они могут лишь вырасти до размера, которым Вы их ограничили.

''Примечание для специалистов: они фактически не однострочные. SourcePawn использует 8-битный строки для хранения массивов в качестве оптимизации. Это и есть то, что делает строки типом, а не меткой.''

==Использование==
Строки были созданы почти в равной степени и для массивов. Например:
<pawn>
new String:message[] = "Hello!";
new String:clams[6] = "Clams";
</pawn>

Это равносильно следующему:
<pawn>
new String:message[7], String:clams[6];

message[0] = 'H';
message[1] = 'e';
message[2] = 'l';
message[3] = 'l';
message[4] = 'o';
message[5] = '!';
message[6] = 0;
clams[0] = 'C';
clams[1] = 'l';
clams[2] = 'a';
clams[3] = 'm';
clams[4] = 's';
clams[5] = 0;
</pawn>

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

Заметим, что строка должна быть заключена в двойных кавычках, а символ в одиночных.

==Символы==
Особенность текста может быть использована в любой строке или однострочной переменной. Например:
<pawn>new String:text[] = "Crab";
new clam;

clam = 'D'; //Устанавливает однострочной переменной значение 'D'
text[0] = 'A'; //Меняет 'C' на 'A', сейчас получилось 'Arab'
clam = text[0]; //Устанавливает однострочной переменной значение 'A'
text[1] = clam; //Меняет 'r' на 'A', сейчас получилось 'AAab'
</pawn>

То, что вы не можете сделать, это соотнести символы массивов со строками. Внутреннее хранение отличается. Например:
<pawn>
new clams[] = "Clams"; //Не верно, нужен тип String:
new clams[] = {'C', 'l', 'a', 'm', 's', 0}; //Верно, но это НЕ СТРОКА.
</pawn>

=Функции=
Функции, как отмечалось ранее, имеют отдельные составляющие кода, которые выполняют определенные действия. Функции могут быть задействованы или '''вызвоны''' с '''параметрами''', которые дают особые настройки.

Существуют два типа вызова функции:
*'''прямой вызов''' - Вы специально вызываете функцию в своем коде.
*'''обратный вызов''' - Применение вызова функций в Вашем коде, как если бы это было событием триггера (совокупность условий, инициирующих выполнение действия).

Существуют пять видов функций:
*'''native''': Прямая, внутренняя функция, предусмотренная в приложении.
*'''public''': Функция обратного вызова, что делает её видимой для приложения и других сценариев.
*'''normal''': Нормальная функция, которую Вы можете только вызвать.
*'''stock''': Нормальная функция, предусмотренная если включает в себя файл. Если не используется, то не компилируется.
*'''forward''': Эта функция представляет собой глобальное событие, предусмотренная приложением. Если Вы её привели в исполнение, она будет вызвона.

Весь код в Pawn должен существовать в функциях. Это основное отличие от языков, таких как PHP, Perl и Python, которые позволяют Вам писать глобальный код. Это происходит потому, что Pawn вызывается на основе другого языка: он реагирует на действия от родительского приложения, и функции должны быть написаны для обработки этих действий. Хотя наш пример, часто содержат свободно плавающий код, это сделано исключительно для демонстрационных целей. Свободно плавающий код в нашем примере означает, что код является частью ряда функций.

==Описание==
В отличие от переменных, функции, не нужно объявлять, прежде чем использовать их. Функции имеют две части, '''модель''' и '''тело'''. Модель содержит имя Вашей функции и параметры, которые она будет принимать. Тело является контейнером для кода.

Пример функции:
<pawn>
AddTwoNumbers(first, second)
{
new sum = first + second;

return sum;
}</pawn>

Это простая функция. Модель этой строки:
<pawn>AddTwoNumbers(first, second)</pawn>

Распишем по отдельности:
*<tt>AddTwoNumbers</tt> - Название функции.
*<tt>first</tt> - Название первого параметра, который представляет собой простой элемент.
*<tt>second</tt> - Название второго параметра, который представляет собой простой элемент.

Тело представляет собой простой блок кода. Он создает новую переменную, названную <tt>sum</tt>, и присваивает ей значение этих двух параметров, добавленных совместно (другие выражения будут позже). Важно заметить оператор <tt>return</tt>, в котором обозначается конец функции и возврат с полученными значениями из этой функции. Все функции ''возвращают значения'' после завершения. Это означает, например:

<pawn>new sum = AddTwoNumbers(4, 5);</pawn>

Приведенный выше код будет присваивать число 9 к sum. Функция получает два значения и передает новое значение sum в качестве '''возвращаемого значения'''. Если функция не имеет возвращаемого значения или не имеет значений для возврата, то возвращается 0 по умолчанию.

Функция может принимать любые типы значений. Она может вернуть любую однострочную переменную, но не массивы или строки. Пример:
<pawn>Float:AddTwoFloats(Float:a, Float:b)
{
new Float:sum = a + b;

return sum;
}</pawn>

''Заметим, что если в приведенной выше функции, Вам вернулась не Float значение, Вы получите не соответствие значений.''

Можно, конечно, передавать переменные в функции:
<pawn>new numbers[3] = {1, 2, 0};

numbers[2] = AddTwoNumbers(numbers[0], numbers[1]);</pawn>

Заметим, что однострочные переменные передаются '''по значению'''. То есть, их значение не может быть изменено функцией. Например:
<pawn>new a = 5;

ChangeValue(a);

ChangeValue(b)
{
b = 5;
}</pawn>

Этот код не будет менять значение <tt>a</tt>. Это происходит потому, что копия этого значения в <tt>a</tt> передается вместо <tt>a</tt> самостоятельно.

Больше примеров функций будут демонстрироваться и в других частях статьи.

==Publics==
Публичные функции используются для осуществления обратных вызовов. Вы не должны создавать какую-либо публичную функцию, если это вынудит выполнение обратного вызова. Например, вот два обратных вызова из <tt>sourcemod.inc</tt>:

<pawn>forward OnPluginStart();
forward OnClientDisconnected(client);</pawn>

Чтобы выполнить и получить эти два события, Вы должны написать такие функции как:

<pawn>public OnPluginStart()
{
/* Код здесь */
}

public OnClientDisconnected(client)
{
/* Код здесь */
}</pawn>

Ключевое слово '''public''' делает функцию публичной, а также позволяет родительскому приложению непосредственно вызывать функцию.

==Natives==
Natives имеют встроенные функции, предоставляемые приложением. Вы можете вызвать их, как если бы они были normal функциями. Например, SourceMod имеет следующие функции:

<pawn>native FloatRound(Float:num);</pawn>

Её можно вызвать таким образом:
<pawn>new num = FloatRound(5.2); //Результат в num = 5</pawn>

==Параметры массива==
Вы можете передавать массивы или строки в качестве параметров. Важно отметить, что они идут '''как ссылка'''. То есть не делать копию данных, а отдавать непосредственно ссылки на данные. Существует простой способ объяснить это более конкретно.

<pawn>
new example[] = {1, 2, 3, 4, 5};

ChangeArray(example, 2, 29);

ChangeArray(array[], index, value)
{
array[index] = value;
}</pawn>

Эта функция устанавливает заданный индекс в массиве с учетом значений. Когда она запускается на примере нашего массива, она меняет индекс 2 для значения 3 на 29. То есть:
<pawn>example[2] = 29;</pawn>

Это возможно лишь потому, что массив может быть непосредственно изменён. Чтобы предотвратить массив от изменения, можно пометить его как постоянную <tt>const</tt>. Это позволит понизить риск на ошибку в коде от её изменения. Например:

<pawn>CantChangeArray(const array[], index, value)
{
array[index] = value; //Не компилируется
}</pawn>

Это хорошая идея использовать <tt>const</tt> в параметрах массивов и Вы будете точно знать, что массив не будет изменен; это может предотвратить ошибки кодирования.

=Выражения=
Выражения являются точно такими же, какими они существуют в математике. Это группы операторов/символов, которые приходятся на один фрагмент данных. Они часто заключены в скобках (внутри скобок). Они содержат строгий "порядок операций". Они могут содержать переменные, функции, цифры и выражения сами могут быть вложенные внутрь других выражений, и даже приняты в качестве параметров.

Приведем пример простейшего выражения:
<pawn>
0; //Возвращает число 0
(0); //Так же возвращает число 0
</pawn>

Хотя выражения могут возвращать значения, они также могут ответить какое значение содержит ответ ''ноль или не ноль''. В этом смысле, ''ноль'' является ''ложью'' (false), а ''не нулевое'' значение ''истиной'' (true). Например, -1 ''истина'' в Pawn, поскольку она не является нулем. Не думайте, что отрицательные числа являются ложными.

Порядок операций выражения аналогичен языку C. PMDAS: Parenthesis, Multiplication, Division, Addition, Subtraction. Вот несколько примеров выражений:
<pawn>
5 + 6; //Вычисляет как 11
5 * 6 + 3; //Вычисляет как 33
5 * (6 + 3); //Вычисляет как 45
5.0 + 2.3; //Вычисляет как 7.3
(5 * 6) % 7; //Modulo operator, вычисляет как 2
(5 + 3) / 2 * 4 - 9; //Вычисляет как 7
</pawn>

Как уже отмечалось, выражения могут содержать переменные, или даже функции:
<pawn>
new a = 5 * 6;
new b = a * 3; //Вычисляет как 90
new c = AddTwoNumbers(a, b) + (a * b);
</pawn>

==Операторы==
Есть несколько полезных дополнительных операторов в Pawn. Первый набор упрощает аутоагрегацию выражения. Например:
<pawn>new a = 5;

a = a + 5;</pawn>

Может быть переписан, как:
<pawn>new a = 5;
a += 5;</pawn>

Это верно в отношении следующих операторов в Pawn:
*Four-function: *, /, -, +
*Bit-wise: |, &, ^, ~, <<, >>

Кроме того, существуют инкремент/декремент операторы:
<pawn>a = a + 1;
a = a - 1;</pawn>

Может быть упрощено, как:
<pawn>a++;
a--;</pawn>

Дополнительно отметим, что ++ или -- может быть представлен до переменной (до-инкремент, до-декремент) или после переменной (пост-инкремент, пост-декремент). Разница заключается в том, как остальная часть выражения содержащие их, видит результат.

* ''До:'' Переменная увеличивается до определения и остальная часть выражения видит новое значение.
* ''Пост:'' Переменная увеличивается после определения и остальная часть выражения видит старое значение.

Иными словами, <tt>a++</tt> определяет значение как <tt>a</tt> в то время как <tt>++a</tt> определяет значение как <tt>a + 1</tt>. В обоих случаях <tt>a</tt> увеличивается на <tt>1</tt>.

Например:

<pawn>new a = 5;
new b = a++; // b = 5, a = 6 (1)
new c = ++a; // a = 7, c = 7 (2)
</pawn>

(1) <tt>b</tt> присваивается <tt>a</tt> со ''старым'' значением, ''до'' того, как он будет увеличено до <tt>6</tt>. (2) <tt>c</tt> присваивается <tt>a</tt> с ''новым'' значением, ''после'' того, как он увеличивается до <tt>7</tt>.

==Операторы сравнения==
Существуют шесть операторов для сравнения двух числовых значений, а результат является либо истиной (не ноль) или ложью (ноль):
*<tt>a == b</tt> - Действительно, если и b имеет то же значение.
*<tt>a != b</tt> - Действительно, если b имеет другое значение.
*<tt>a > b</tt> - Действительно, если оно больше b
*<tt>a >= b</tt> - Действительно, если оно больше или равно b
*<tt>a < b</tt> - Действительно, если оно меньше b
*<tt>a <= b</tt> - Действительно, если оно меньше или равно b

Например:
<pawn>
(1 != 3); //Определяется как истина, поскольку 1 не равно 3.
(3 + 3 == 6); //Определяется как истина, поскольку 3+3 равно 6.
(5 - 2 >= 4); //Определяется как ложь, поскольку 3 меньше 4.
</pawn>

Заметим, что эти операторы не работают с массивами и строками. То есть, вы не можете сравнить их с помощью <tt>==</tt>.

==Действительные операторы==
Действительные операторы могут быть скомбинированы тремя булевыми (boolean) операторами:
*<tt>a && b</tt> - Истина, если a и b истинные. Ложь, если a и (или) b ложные.
{| border="1" cellpadding="2" cellspacing="0" align="center"
! <tt>&&</tt> !! 0 !! 1
|-
! 0
| 0 || 0
|-
! 1
| 0 || 1
|}
*<tt>a || b</tt> - Истина, если a или b (или обе переменные) истинные. Ложь, если обе переменные a и b ложные.
{| border="1" cellpadding="2" cellspacing="0" align="center"
! <tt><nowiki>||</nowiki></tt> !! 0 !! 1
|-
! 0
| 0 || 1
|-
! 1
| 1 || 1
|}
*<tt>!a</tt> - Истина, если a ложь. Ложь, если a истина.
{| border="1" cellpadding="2" cellspacing="0" align="center"
! <tt>!</tt> !! 0 !! 1
|-
!
| 1 || 0
|}

Например:
<pawn>
(1 || 0); //Определяется как истина, так как выражение 1 истинное
(1 && 0); //Определяется как ложь, так как выражение 0 ложное
(!1 || 0); //Определяется как ложь, так как выражение !1 ложное.
</pawn>

==Левое/правое значения==
Два важных понятия левого и правого значений, или левостороннее и правостороннее значения. Левостороннее значение имеет то, что появляется на левой стороне выражения, а правостороннее значение - появляется на правой стороне выражения.

Например:
<pawn>
new a = 5;</pawn>

В этом примере <tt>a</tt> является левосторонним значением и <tt>5</tt> является правосторонним значением.

Правила:
*'''Выражения никогда не будут левосторонними значениями'''.
*'''Переменные являются двумя, левосторонними и правосторонними значениями'''.

=Условия=
Условия позволяют Вам запускать код, определенное условие выполнено.

==Если соответствует==
Если соответствует одно или более условий. Например:

<pawn>
if (a == 5)
{
/* Код будет запущен, если условие будет истинным */
}</pawn>

Они могут быть расширены для более сложных случаев:
<pawn>
if (a == 5)
{
/* Код */
}
else if (a == 6)
{
/* Код */
}
else if (a == 7)
{
/* Код */
}</pawn>

Вы так же можете обрабатывать случаи, даже если выражение не верно. Например:
<pawn>
if (a == 5)
{
/* Код */
}
else
{
/* Код, который будет запущен если нет истинного выражения */
}</pawn>

==Оператор выбора==
Оператор выбора будет ограничен условием. Он необходим для выражения, выполняющего код для целого ряда возможных значений. Например:

<pawn>
switch (a)
{
case 5:
{
/* Код */
}
case 6:
{
/* Код */
}
case 7:
{
/* Код */
}
case 8, 9, 10:
{
/* Код */
}
default:
{
/* будет запущен, если не одно условие не соответствует */
}
}</pawn>

В отличие от некоторых других языков, оператор выбора не проваливается. То есть существуют случаи, когда код не будет запущен. При случае совпадения его код выполняется, а ключ является местом для немедленного прекращения.

=Циклы=
Циклы позволяют Вам без труда повторять выполнение кода, пока условие станет истинным.

==For циклы==
For циклы, это циклы, которые состоят из четырех частей:
*Оператор '''инициализации''' - запускается один раз перед первым циклом.
*Оператор '''условия''' - проверяет условие и запускает следующий цикл, в том числе первый. Цикл прекращается, когда это выражение становится ложным.
*Оператор '''итерации''' - запускается после каждого цикла.
* '''тело''' цикла - запускается каждый раз, пока оператор '''условия''' вычисляется как истинный.

<pawn>
for ( /* инициализация */ ; /* условие */ ; /* итерация */ )
{
/* тело */
}
</pawn>

Простым примером является функция сложения массива:
<pawn>
new array[10] = {1, 2, 3, 4, 5, 6, 7, 8, 9, 10};
new sum = SumArray(array, 10);

SumArray(const array[], count)
{
new total;

for (new i = 0; i < count; i++)
{
total += array[i];
}

return total;
}</pawn>

По отдельности:
*<tt>new i = 0</tt> - Создает новую переменную для цикла, и устанавливает её в 0.
*<tt>i < count</tt> - Только запускает цикл, если <tt>i</tt> меньше, чем <tt>count</tt>. Это гарантирует, что чтение цикла прекращается в определенный момент. В этом случае, мы не хотим читать недействительные индексы в массиве.
*<tt>i++</tt> - Увеличивает <tt>i</tt> на единицу после каждого цикла. Это гарантирует, что цикл не будет запущен вечно; в конце концов <tt>i</tt> станет слишком большим, и цикл завершится.

Таким образом, функция <tt>SumArray</tt> будет циклом каждого действительного индекса массива, каждый раз добавляя это значение в sum. Для циклов очень распространены массивы такие, как в нашем примере.

==While циклы==
While циклы являются менее распространенными, чем for циклы, но на самом деле это более простые циклы. Они имеют только две части:
*Оператор '''условия''' - проверяется перед началом каждого цикла. Цикл прекращается, когда условие становится ложным.
*'''тело''' цикла - запускается каждый раз пока цикл выполняется.

<pawn>
while ( /* условие */ )
{
/* тело */
}
</pawn>

До тех пор, пока условие выражения остается истинным, цикл будет выполняться. Каждый for цикл может быть переписан, как while цикл:

<pawn>
/* инициализация */
while ( /* условие */ )
{
/* тело */
/* итерация */
}
</pawn>

Вот предыдущий for цикл переписан как while цикл:
<pawn>
SumArray(const array[], count)
{
new total, i;

while (i < count)
{
total += array[i];
i++;
}

return total;
}</pawn>

Существуют также '''do...while''' циклы, которые используются еще реже. Они работают как и while циклы, но проверяют условие ПОСЛЕ каждого цикла, а не перед ним. Это означает, что цикл всегда будет запущен, по крайней мере один раз. Например:

<pawn>
do
{
/* тело */
}
while ( /* условие */ );
</pawn>

==Управление циклами==
Существуют два случая, в которых Мы хотели бы контролировать цикл:
*'''пропустить''' одну итерацию или цикл и продолжить выполнение цикла как обычно, или;
*'''разорвать''' цикл целиком, прежде чем он закончится.

Допустим у вас есть функция, которая принимает массив и ищет соответствия цифр. Вы хотите его остановить, когда число будет найдено:
<pawn>
/**
* Возвращает массив, если индекс значения, или -1, не найдены.
*/
SearchInArray(const array[], count, value)
{
new index = -1;

for (new i = 0; i < count; i++)
{
if (array[i] == value)
{
index = i;
break;
}
}

return index;
}</pawn>

Конечно, эту функцию можно вернуть и способом <tt>return i</tt>, но пример показывает, как <tt>break</tt> может остановить цикл.

Кроме того, ключевое слово <tt>continue</tt> пропускает итерации цикла. Например, Мы хотим суммировать все четные числа:

<pawn>
SumEvenNumbers(const array[], count)
{
new sum;

for (new i = 0; i < count; i++)
{
/* If divisibility by 2 is 1, we know it's odd */
if (array[i] % 2 == 1)
{
/* Пропускаем оставшуюся часть итерации цикла */
continue;
}
sum += array[i];
}

return sum;
}</pawn>

=Область действия=
Область действия относится к '''удобочитаемости''' кода. Это означает, что код одного уровня не может быть "виден" в коде другого уровня. Пример:

<pawn>
new A, B, C;

Function1()
{
new B;

Function2();
}

Function2()
{
new C;
}</pawn>

В этом примере, <tt>A</tt>, <tt>B</tt>, и <tt>C</tt> имеют '''глобальную область действия'''. Их можно увидеть в любой функции. Вместе с тем, <tt>B</tt> в функции <tt>Function1</tt> не является той же переменной, как <tt>B</tt> на глобальном уровне. Вместо этого она находится в '''локальной области действия''', и поэтому является '''локально изменяемой'''.

Кроме того, функции <tt>Function1</tt> и <tt>Function2</tt> ничего не знают о существовании других переменных.

Она так же является не только локальной переменной функции <tt>Function1</tt>, но и создается заново каждый раз, когда функция вызывается. Попробуйте представить это:
<pawn>
Function1()
{
new B;

Function1();
}</pawn>

В приведенном выше примере, функция <tt>Function1</tt> вызывает сама себя. Конечно, это бесконечной рекурсии (а это очень плохо), но идея заключается в том, что каждый раз, когда функция срабатывает, то создается новая копия <tt>B</tt>. Когда функция завершается, <tt>B</tt> уничтожается, и её значение теряется.

Это свойство можно объяснить проще тем, что область действия переменной равна уровню её вложенности. То есть, переменная на глобальной области действия видна для всех функций. Переменная в локальной области действия видна всему блоку кода расположенному "ниже" этого уровня. Например:

<pawn>Function1()
{
new A;

if (A)
{
A = 5;
}
}</pawn>

Приведенный выше код является действительным, поскольку в область действия распространяется по всей функции. Однако этот код, работать не будет:
<pawn>
Function1()
{
new A;

if (A)
{
new B = 5;
}

B = 5;
}</pawn>

Отметим, что <tt>B</tt> объявляется в новом блоке кода. Это означает, что <tt>B</tt> доступна только в том блоке кода, в котором была создана (и всем под-блокам вложенных внутри него). Как только блок кода прекращается, <tt>B</tt> становится не действительной.

=Dynamic Arrays=
Dynamic arrays are arrays which don't have a hardcoded size. For example:

<pawn>Function1(size)
{
new array[size];

/* Code */
}</pawn>

Dynamic arrays can have any expression as their size as long as the expression evaluates to a number larger than 0. Like normal arrays, SourcePawn does not know the array size after it is created; you have to save it if you want it later.

Dynamic arrays are only valid at the local scope level, since code cannot exist globally.

=Extended Variable Declarations=
Variables can be declared in more ways than simply <tt>new</tt>.

==decl==
===Purpose===
By default, all variables in Pawn are initialized to zero. If there is an explicit initializer, the variable is initialized to the expression after the <tt>=</tt> token. At a local scope, this can be a run-time expense. The <tt>decl</tt> keyword (which is only valid at local scope) was introduced to let users decide if they want variables initialized or not.

Note: <tt>decl</tt> should not be used on single cell variables. There is almost never any benefit.

===Explanation===
For example:

<pawn>
new c = 5;
new d;
new String:blah[512];

Format(blah, sizeof(blah), "%d %d", c, d);
</pawn>

In this code, <tt>c</tt> is equal to 5 and <tt>d</tt> is equal to 0. The run-time expense of this initialization is negligible. However, <tt>blah</tt> is a large array, and the expense of initializing the entire array to 0s could be detrimental in certain situations.

Note that <tt>blah</tt> does not need to be zeroed. In between being declared with <tt>new</tt> and stored with <tt>Format()</tt>, <tt>blah</tt> is never loaded or read. Thus this code would be more efficiently written as:

<pawn>
new c = 5;
new d;
decl String:blah[512];

Format(blah, sizeof(blah), "%d %d", c, d);
</pawn>

===Caveats===
The downside to <tt>decl</tt> is that it means its variables will start with "garbage" contents. For example, if we were to use:

<pawn>
new c = 5;
new d;
decl String:blah[512];

PrintToServer("%s", blah);

Format(blah, sizeof(blah), "%d %d", c, d);
</pawn>

This code may crash the server, because <tt>blah</tt> may be completely corrupt (strings require a terminator, and that may not be present). Similarly, if we did:

<pawn>
new c = 5;
decl d;
decl String:blah[512];

Format(blah, sizeof(blah), "%d %d", c, d);
</pawn>

The value of <tt>d</tt> is now undefined. It could be any value, negative or positive.

Note that it is easy to efficiently make strings safe. The example below shows how to terminate a garbage string:
<pawn>
decl String:blah[512];

blah[0] = '\0';
</pawn>

===Golden Rules===
*'''Only use decl if in between declaring and loading/reading the value, you are absolutely sure there is at least one store/set operation that gives the variable valid data.'''
*'''Do not prematurely optimize.''' Likewise, there is no need to use <tt>decl</tt> on non-arrays, because there is no added expense for initializing a single cell value.

===Notes===
This example is NOT as efficient as a <tt>decl</tt>:
<pawn>
new String:blah[512] = "a";
</pawn>

Even though the string is only one character, the <tt>new</tt> operator guarantees the rest of the array will be zeroed as well.

Also note, it is invalid to explicitly initialize a <tt>decl</tt>:
<pawn>decl String:blah[512] = "a";</pawn>

The above code will not compile, because the purpose of <tt>decl</tt> is to avoid any initialization.

==static==
The <tt>static</tt> keyword is available at global and local scope. It has different meanings in each.

===Global static===
A global static variable can only be accessed from within the same file. For example:

<pawn>//file1.inc
static Float:g_value1 = 0.15f;

//file2.inc
static Float:g_value2 = 0.15f;</pawn>

If a plugin includes both of these files, it will not be able to use either <tt>g_value1</tt> or <tt>g_value2</tt>. This is a simple information hiding mechanism, and is similar to declaring member variables as <tt>private</tt> in languages like C++, Java, or C#.

===Local static===
A local static variable is a global variable that is only visible from its local lexical scope. For example:

<pawn>
MyFunction(inc)
{
static counter = -1;

counter += inc;

return counter;
}</pawn>

In this example, <tt>counter</tt> is technically a global variable -- it is initialized once to -1 and is never initialized again. It does not exist on the stack. That means each time <tt>MyFunction</tt> runs, the <tt>counter</tt> variable and its storage in memory is the same.

Take this example:
<pawn>MyFunction(5);
MyFunction(6);
MyFunction(10);</pawn>

In this example, <tt>counter</tt> will be <tt>-1 + 5 + 6 + 10</tt>, or <tt>20</tt>, because it persists beyond the frame of the function. Note this may pose problems for recursive functions: if your function may be recursive, then <tt>static</tt> is usually not a good idea unless your code is re-entrant.

The benefit of a local static variable is that you don't have to clutter your script with global variables. As long as the variable doesn't need to be read by another function, you can squirrel it inside the function and its persistence will be guaranteed.

Note that statics can exist in any local scope:

<pawn>
MyFunction(inc)
{
if (inc > 0)
{
static counter;
return (counter += inc);
}
return -1;
}</pawn>

[[Category:Ru:SourceMod Scripting]]

Ru:Introduction to SourcePawn

2008-12-26T10:13:26Z

Frenzzy: /* Ключ соответствия */

Это руководство призвано дать Вам самые основные представления по основам написания сприптов в SourcePawn. [[Pawn]] это "скриптовый" язык используемый для внедрения функциональности в других программах. Это означает, что это не самостоятельный язык, как C++ или Java, и его элементы будут отличаться в различных приложениях. SourcePawn это вариация языка Pawn используемая в [[SourceMod]].

Это руководство не расскажет Вам как писать SourceMod плагины; оно предназначено для получения общих представлений о синтаксисе и семантике этого языка. Читайте отдельную статью [[Ru:Introduction to SourceMod Plugins]] (Введение в SourceMod плагины), для введения в SourceMod API.

=Введение для новичков=
Этот раздел создан не для программистов. Если Вы по прежнему в замешательстве, Вы можете прочитать книги о других языках программирования, таких как PHP, Python, или Java, чтобы получить более полное представление о программировании.

==Идентификаторы/Ключевые слова==
Идентификаторы представляет собой набор букв, цифр и/или нижнего подчеркивания, что представляет собой нечто уникальное. Идентификаторы вводятся с учетом регистра (в отличие от PHP, где иногда это не требуется). Идентификаторы не начинаются с какого-либо специального символа, но они должны начинаться с буквы.

Есть несколько зарезервированных символов, которые имеют особое значение. Например, <tt>if</tt>, <tt>for</tt>, и <tt>return</tt> специальные конструкции в языке, которые будут описаны позднее. Они не могут быть использованы в качестве названий идентификаторов.

==Переменные==
Существует несколько важных конструкций, которые Вы должны знать, прежде чем приступить к написанию сценария. Во-первых, это '''переменные'''. Переменная это идентификатор, который содержит данные. Например, переменная "a" может содержать числа "2", "16", "0", и так далее. Переменные создаются для хранения данных внутри программы. Переменные должны быть объявлены до их использования, с помощью ключевого слова "new". Данные можно присвоить переменной, используя знак равенства (=). Пример:

<pawn>new a, b, c, d;

a = 5;
b = 16;
c = 0;
d = 500;</pawn>

В SourcePawn, переменные бывают двух типов, которые будут более подробно описаны далее.
*Однострочные (могут содержать только произвольные числовые данные), как показано выше.
*Многострочные (могут содержать целый ряд текстовых символов)

==Функции==
Следующим важным понятием являются '''функции'''. Функции идентификаторов или имен, которые выполняют действия. Это означает, что когда вы их активируете, они выполняют конкретную последовательность кода. Есть несколько типов функций, но все функции активируется одинаковым образом. "Вызов функции" является термином ссылающимся на функцию действия. Функция числовых переменных строятся так:
<pawn>функция(<параметры>)</pawn>

Примеры:

<pawn>show(56); //Активирует функцию "show" и присваивает ей число 56
show(); //Активирует функцию "show" без каких-либо данных, пустую
show(a); //Активирует функцию "show" и присваивает ей переменную с данными
</pawn>

Каждый фрагмент данных передаваемый вызываемой функции, называется '''параметр'''. Функция может иметь любое количество параметров (но есть "допустимый" предел в SourceMod: 32). Параметры будут описаны далее в этой статье.

==Комментарии==
Примечания и любой текст, который пишется после "//" считается "Комментарием", а не фактическим кодом. Есть два стиля комментариев:
*<tt>//</tt> - Двойная косая черта, всё следующие после этой строки игнорируется.
*<tt>/* */</tt> - Много-строчный комментарий, весь текст, внутри звездочек игнорируются. You cannot nest these.

==Массивы==
Описание массивов. Вы можете группировать код в виде "массивов", разделенных { и }. Это фактически создает возможность работать с целым массивом как с одним оператором. Например:

<pawn>{
here;
is;
some;
code;
}</pawn>

Массивы с фигурными скобками используются достаточно широко в программировании. Массивы кода могут быть вложенными друг в друга. Это хорошая возможность адаптировать последовательность когда и сделать его удобочитаемым, благодаря отступам код не будет смотреться как одна большая и длинная макаронина.

=Особенности языка=
Pawn может показаться очень похожим на другие языки программирования, например C, но Pawn от них фундаментально отличается. Не столь важно, чтобы Вы сейчас же поняли его отличия, но они понадобятся, если Вы уже знаете один из языков программирования.
*'''Pawn не печатает''' Pawn имеет только один тип данных - '''однострочный'''. Подробнее будет описано позже. [В дальнейшем автор рассказывает, что существует два типа данных: однострочный и многострочный]
*'''Pawn не собирает мусор''' Pawn, как язык, не имеет встроенных ресурсов памяти, и потому он не мусорит. Если функция выделит память, то Вы отвечаете за её освобождение.
*'''Pawn не объектно-ориентированный язык''' Pawn является процедурным, и полагается на подпрограммы. Также у него нету C подобных структур.
*'''Pawn не функциональный.''' Pawn является процедурным, и не поддерживает функции "лямбды" (Lambda), поздние присвоения, и все то, что можно найти в языках высшего уровня, таких как Phyton и Ruby.
*'''Pawn однопоточный''' As of this writing, Pawn is not thread safe.
*'''Pawn не интерпретируемый''' Ну, почти. Он интерпретируется на очень низком уровне. Вы должны скомпилировать код, из которого получится бинарный файл. Эта программа будет работать на той платформе, которую использует хост. Это ускоряет загрузку и позволяет легче находить ошибки.

Этот язык был выпущен ITB CompuPhase. Язык разработан для устройств низкого уровня и таким образом конечные программы очень маленькие по размеру и очень быстрые.

=Переменные=
В Pawn есть всего два типа переменных: '''однострочные''' и '''многострочные'''. Однострочные могут содержать 32 бита цифровых данных. Многострочные - последовательный список из UTF-8 символов.

'''однострочные''' не имеет своего типа, однако они могут быть '''маркированы'''(tagged). Тег позволяет Вам указывать, где определенную ячейку можно использовать. Типичные теги:
*(пусто), или '''_''' - Нет тега. Обычно используют для целых чисел ([http://en.wikipedia.org/wiki/Integer Integers]).
*'''Float''' - используют для чисел с плавающей точкой (небольших).
*'''bool''' - используют для хранения значений '''true''' (истина) или '''false''' (ложь).

Со строками все по другому, они будут рассмотрены далее.

==Объявления==
Примеры разных правильных объявлений переменных.
<pawn>
new a = 5;
new Float:b = 5.0;
new bool:c = true;
new bool:d = 0; //Работает, поскольку 0 равно false (ложь)
</pawn>

Неправильные объявления переменных
<pawn>
new a = 5.0; //Несоответствие тегов. 5.0 с тегом Float
new Float:b = 5; //Несоответствие тегов. 5 без тега.
</pawn>

Если переменная не определена в объявлении то ее значения станет 0
<pawn>
new a; //значение 0
new Float:b; //значение 0.0
new bool:c; //значение false
</pawn>

==Присвоение==
Переменным могут быть присвоены данные после создания. Пример:
<pawn>new a, Float:b, bool:c;

a = 5;
b = 5.0;
c = true;
</pawn>

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

==Описание==
Массив объявляется с помощью квадратных скобок. Вот некоторые примеры массивов:
<pawn>
new players[32]; //Набор из 32 однострочных (числовых) данных
new Float:origin[3]; //Набор из 3 чисел с плавающей точкой
</pawn>

По умолчанию, массивам присваиваются нули. Вы можете присвоить им разные значения по умолчанию, однако:
<pawn>
new numbers[5] = {1, 2, 3, 4, 5}; //Набор 1, 2, 3, 4, 5 из однострочных данных.
new Float:origin[3] = {1.0, 2.0, 3.0}; //Набор 1.0, 2.0, 3.0 из однострочных данных.
</pawn>

Вы можете оставить массив без размера, если вы собираетесь заранее присвоить ему данные. Например:
<pawn>
new numbers[] = {1, 3, 5, 7, 9};
</pawn>

Компилятор будет автоматически делать вывод о том, что Вы хотите получить массив размером 5.

==Использование==
Использование массива равносильно использованию обычных переменной. Единственное отличие массива состоит в том, что он должен быть '''индексируемым'''. Индексирование массива означает присутствие возможности выбрать элемент, который Вы хотите использовать.

Вот пример кода с использованием индексов:
<pawn>
new numbers[5], Float:origin[3];

numbers[0] = 1;
numbers[1] = 2;
numbers[2] = 3;
numbers[3] = 4;
numbers[4] = 5;
origin[0] = 1.0;
origin[1] = 2.0;
origin[2] = 3.0;
</pawn>

Заметим, что '''индекс''' это текст, который находится в квадратных скобках. Индекс всегда начинается с нуля. То есть, если массив имеет N элементов, его действительный индекс от 0 до N-1. Доступ к данным с индексами работает так же, как с обычной переменной.

Использование неверного индекса вызовет ошибку. Например:
<pawn>
new numbers[5];

numbers[5] = 20;</pawn>

Это может выглядеть верно, но число 5 не является допустимым индексом. Наибольшим значением индекса является число 4.

Вы можете использовать любые выражения, как индекс. Например:
<pawn>new a, numbers[5];

a = 1; //Сделает a = 1
numbers[a] = 4; //Сделает numbers[1] = 4
numbers[numbers[a]] = 2; //Сделает numbers[4] = 2
</pawn>

Выражения будут обсуждаться подробнее в конце статьи.

=Строки=
Строки являются удобным способом хранения текста. Символы хранятся в массиве. Строка ограничивается '''нулевым символом''', или 0. Без нулевого символа, Pawn не знает, где остановить чтение строки. Все строки в SourcePawn используют кодировку UTF-8.

Отметим, что строки имеют комбинацию из массивов и однострочных переменных. В отличие от других языков, это означает, что Вы должны знать заранее, как много места будут использовать строки. Это означает, что строки не являются динамичными. Они могут лишь вырасти до размера, которым Вы их ограничили.

''Примечание для специалистов: они фактически не однострочные. SourcePawn использует 8-битный строки для хранения массивов в качестве оптимизации. Это и есть то, что делает строки типом, а не меткой.''

==Использование==
Строки были созданы почти в равной степени и для массивов. Например:
<pawn>
new String:message[] = "Hello!";
new String:clams[6] = "Clams";
</pawn>

Это равносильно следующему:
<pawn>
new String:message[7], String:clams[6];

message[0] = 'H';
message[1] = 'e';
message[2] = 'l';
message[3] = 'l';
message[4] = 'o';
message[5] = '!';
message[6] = 0;
clams[0] = 'C';
clams[1] = 'l';
clams[2] = 'a';
clams[3] = 'm';
clams[4] = 's';
clams[5] = 0;
</pawn>

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

Заметим, что строка должна быть заключена в двойных кавычках, а символ в одиночных.

==Символы==
Особенность текста может быть использована в любой строке или однострочной переменной. Например:
<pawn>new String:text[] = "Crab";
new clam;

clam = 'D'; //Устанавливает однострочной переменной значение 'D'
text[0] = 'A'; //Меняет 'C' на 'A', сейчас получилось 'Arab'
clam = text[0]; //Устанавливает однострочной переменной значение 'A'
text[1] = clam; //Меняет 'r' на 'A', сейчас получилось 'AAab'
</pawn>

То, что вы не можете сделать, это соотнести символы массивов со строками. Внутреннее хранение отличается. Например:
<pawn>
new clams[] = "Clams"; //Не верно, нужен тип String:
new clams[] = {'C', 'l', 'a', 'm', 's', 0}; //Верно, но это НЕ СТРОКА.
</pawn>

=Функции=
Функции, как отмечалось ранее, имеют отдельные составляющие кода, которые выполняют определенные действия. Функции могут быть задействованы или '''вызвоны''' с '''параметрами''', которые дают особые настройки.

Существуют два типа вызова функции:
*'''прямой вызов''' - Вы специально вызываете функцию в своем коде.
*'''обратный вызов''' - Применение вызова функций в Вашем коде, как если бы это было событием триггера (совокупность условий, инициирующих выполнение действия).

Существуют пять видов функций:
*'''native''': Прямая, внутренняя функция, предусмотренная в приложении.
*'''public''': Функция обратного вызова, что делает её видимой для приложения и других сценариев.
*'''normal''': Нормальная функция, которую Вы можете только вызвать.
*'''stock''': Нормальная функция, предусмотренная если включает в себя файл. Если не используется, то не компилируется.
*'''forward''': Эта функция представляет собой глобальное событие, предусмотренная приложением. Если Вы её привели в исполнение, она будет вызвона.

Весь код в Pawn должен существовать в функциях. Это основное отличие от языков, таких как PHP, Perl и Python, которые позволяют Вам писать глобальный код. Это происходит потому, что Pawn вызывается на основе другого языка: он реагирует на действия от родительского приложения, и функции должны быть написаны для обработки этих действий. Хотя наш пример, часто содержат свободно плавающий код, это сделано исключительно для демонстрационных целей. Свободно плавающий код в нашем примере означает, что код является частью ряда функций.

==Описание==
В отличие от переменных, функции, не нужно объявлять, прежде чем использовать их. Функции имеют две части, '''модель''' и '''тело'''. Модель содержит имя Вашей функции и параметры, которые она будет принимать. Тело является контейнером для кода.

Пример функции:
<pawn>
AddTwoNumbers(first, second)
{
new sum = first + second;

return sum;
}</pawn>

Это простая функция. Модель этой строки:
<pawn>AddTwoNumbers(first, second)</pawn>

Распишем по отдельности:
*<tt>AddTwoNumbers</tt> - Название функции.
*<tt>first</tt> - Название первого параметра, который представляет собой простой элемент.
*<tt>second</tt> - Название второго параметра, который представляет собой простой элемент.

Тело представляет собой простой блок кода. Он создает новую переменную, названную <tt>sum</tt>, и присваивает ей значение этих двух параметров, добавленных совместно (другие выражения будут позже). Важно заметить оператор <tt>return</tt>, в котором обозначается конец функции и возврат с полученными значениями из этой функции. Все функции ''возвращают значения'' после завершения. Это означает, например:

<pawn>new sum = AddTwoNumbers(4, 5);</pawn>

Приведенный выше код будет присваивать число 9 к sum. Функция получает два значения и передает новое значение sum в качестве '''возвращаемого значения'''. Если функция не имеет возвращаемого значения или не имеет значений для возврата, то возвращается 0 по умолчанию.

Функция может принимать любые типы значений. Она может вернуть любую однострочную переменную, но не массивы или строки. Пример:
<pawn>Float:AddTwoFloats(Float:a, Float:b)
{
new Float:sum = a + b;

return sum;
}</pawn>

''Заметим, что если в приведенной выше функции, Вам вернулась не Float значение, Вы получите не соответствие значений.''

Можно, конечно, передавать переменные в функции:
<pawn>new numbers[3] = {1, 2, 0};

numbers[2] = AddTwoNumbers(numbers[0], numbers[1]);</pawn>

Заметим, что однострочные переменные передаются '''по значению'''. То есть, их значение не может быть изменено функцией. Например:
<pawn>new a = 5;

ChangeValue(a);

ChangeValue(b)
{
b = 5;
}</pawn>

Этот код не будет менять значение <tt>a</tt>. Это происходит потому, что копия этого значения в <tt>a</tt> передается вместо <tt>a</tt> самостоятельно.

Больше примеров функций будут демонстрироваться и в других частях статьи.

==Publics==
Публичные функции используются для осуществления обратных вызовов. Вы не должны создавать какую-либо публичную функцию, если это вынудит выполнение обратного вызова. Например, вот два обратных вызова из <tt>sourcemod.inc</tt>:

<pawn>forward OnPluginStart();
forward OnClientDisconnected(client);</pawn>

Чтобы выполнить и получить эти два события, Вы должны написать такие функции как:

<pawn>public OnPluginStart()
{
/* Код здесь */
}

public OnClientDisconnected(client)
{
/* Код здесь */
}</pawn>

Ключевое слово '''public''' делает функцию публичной, а также позволяет родительскому приложению непосредственно вызывать функцию.

==Natives==
Natives имеют встроенные функции, предоставляемые приложением. Вы можете вызвать их, как если бы они были normal функциями. Например, SourceMod имеет следующие функции:

<pawn>native FloatRound(Float:num);</pawn>

Её можно вызвать таким образом:
<pawn>new num = FloatRound(5.2); //Результат в num = 5</pawn>

==Параметры массива==
Вы можете передавать массивы или строки в качестве параметров. Важно отметить, что они идут '''как ссылка'''. То есть не делать копию данных, а отдавать непосредственно ссылки на данные. Существует простой способ объяснить это более конкретно.

<pawn>
new example[] = {1, 2, 3, 4, 5};

ChangeArray(example, 2, 29);

ChangeArray(array[], index, value)
{
array[index] = value;
}</pawn>

Эта функция устанавливает заданный индекс в массиве с учетом значений. Когда она запускается на примере нашего массива, она меняет индекс 2 для значения 3 на 29. То есть:
<pawn>example[2] = 29;</pawn>

Это возможно лишь потому, что массив может быть непосредственно изменён. Чтобы предотвратить массив от изменения, можно пометить его как постоянную <tt>const</tt>. Это позволит понизить риск на ошибку в коде от её изменения. Например:

<pawn>CantChangeArray(const array[], index, value)
{
array[index] = value; //Не компилируется
}</pawn>

Это хорошая идея использовать <tt>const</tt> в параметрах массивов и Вы будете точно знать, что массив не будет изменен; это может предотвратить ошибки кодирования.

=Выражения=
Выражения являются точно такими же, какими они существуют в математике. Это группы операторов/символов, которые приходятся на один фрагмент данных. Они часто заключены в скобках (внутри скобок). Они содержат строгий "порядок операций". Они могут содержать переменные, функции, цифры и выражения сами могут быть вложенные внутрь других выражений, и даже приняты в качестве параметров.

Приведем пример простейшего выражения:
<pawn>
0; //Возвращает число 0
(0); //Так же возвращает число 0
</pawn>

Хотя выражения могут возвращать значения, они также могут ответить какое значение содержит ответ ''ноль или не ноль''. В этом смысле, ''ноль'' является ''ложью'' (false), а ''не нулевое'' значение ''истиной'' (true). Например, -1 ''истина'' в Pawn, поскольку она не является нулем. Не думайте, что отрицательные числа являются ложными.

Порядок операций выражения аналогичен языку C. PMDAS: Parenthesis, Multiplication, Division, Addition, Subtraction. Вот несколько примеров выражений:
<pawn>
5 + 6; //Вычисляет как 11
5 * 6 + 3; //Вычисляет как 33
5 * (6 + 3); //Вычисляет как 45
5.0 + 2.3; //Вычисляет как 7.3
(5 * 6) % 7; //Modulo operator, вычисляет как 2
(5 + 3) / 2 * 4 - 9; //Вычисляет как 7
</pawn>

Как уже отмечалось, выражения могут содержать переменные, или даже функции:
<pawn>
new a = 5 * 6;
new b = a * 3; //Вычисляет как 90
new c = AddTwoNumbers(a, b) + (a * b);
</pawn>

==Операторы==
Есть несколько полезных дополнительных операторов в Pawn. Первый набор упрощает аутоагрегацию выражения. Например:
<pawn>new a = 5;

a = a + 5;</pawn>

Может быть переписан, как:
<pawn>new a = 5;
a += 5;</pawn>

Это верно в отношении следующих операторов в Pawn:
*Four-function: *, /, -, +
*Bit-wise: |, &, ^, ~, <<, >>

Кроме того, существуют инкремент/декремент операторы:
<pawn>a = a + 1;
a = a - 1;</pawn>

Может быть упрощено, как:
<pawn>a++;
a--;</pawn>

Дополнительно отметим, что ++ или -- может быть представлен до переменной (до-инкремент, до-декремент) или после переменной (пост-инкремент, пост-декремент). Разница заключается в том, как остальная часть выражения содержащие их, видит результат.

* ''До:'' Переменная увеличивается до определения и остальная часть выражения видит новое значение.
* ''Пост:'' Переменная увеличивается после определения и остальная часть выражения видит старое значение.

Иными словами, <tt>a++</tt> определяет значение как <tt>a</tt> в то время как <tt>++a</tt> определяет значение как <tt>a + 1</tt>. В обоих случаях <tt>a</tt> увеличивается на <tt>1</tt>.

Например:

<pawn>new a = 5;
new b = a++; // b = 5, a = 6 (1)
new c = ++a; // a = 7, c = 7 (2)
</pawn>

(1) <tt>b</tt> присваивается <tt>a</tt> со ''старым'' значением, ''до'' того, как он будет увеличено до <tt>6</tt>. (2) <tt>c</tt> присваивается <tt>a</tt> с ''новым'' значением, ''после'' того, как он увеличивается до <tt>7</tt>.

==Операторы сравнения==
Существуют шесть операторов для сравнения двух числовых значений, а результат является либо истиной (не ноль) или ложью (ноль):
*<tt>a == b</tt> - Действительно, если и b имеет то же значение.
*<tt>a != b</tt> - Действительно, если b имеет другое значение.
*<tt>a > b</tt> - Действительно, если оно больше b
*<tt>a >= b</tt> - Действительно, если оно больше или равно b
*<tt>a < b</tt> - Действительно, если оно меньше b
*<tt>a <= b</tt> - Действительно, если оно меньше или равно b

Например:
<pawn>
(1 != 3); //Определяется как истина, поскольку 1 не равно 3.
(3 + 3 == 6); //Определяется как истина, поскольку 3+3 равно 6.
(5 - 2 >= 4); //Определяется как ложь, поскольку 3 меньше 4.
</pawn>

Заметим, что эти операторы не работают с массивами и строками. То есть, вы не можете сравнить их с помощью <tt>==</tt>.

==Действительные операторы==
Действительные операторы могут быть скомбинированы тремя булевыми (boolean) операторами:
*<tt>a && b</tt> - Истина, если a и b истинные. Ложь, если a и (или) b ложные.
{| border="1" cellpadding="2" cellspacing="0" align="center"
! <tt>&&</tt> !! 0 !! 1
|-
! 0
| 0 || 0
|-
! 1
| 0 || 1
|}
*<tt>a || b</tt> - Истина, если a или b (или обе переменные) истинные. Ложь, если обе переменные a и b ложные.
{| border="1" cellpadding="2" cellspacing="0" align="center"
! <tt><nowiki>||</nowiki></tt> !! 0 !! 1
|-
! 0
| 0 || 1
|-
! 1
| 1 || 1
|}
*<tt>!a</tt> - Истина, если a ложь. Ложь, если a истина.
{| border="1" cellpadding="2" cellspacing="0" align="center"
! <tt>!</tt> !! 0 !! 1
|-
!
| 1 || 0
|}

Например:
<pawn>
(1 || 0); //Определяется как истина, так как выражение 1 истинное
(1 && 0); //Определяется как ложь, так как выражение 0 ложное
(!1 || 0); //Определяется как ложь, так как выражение !1 ложное.
</pawn>

==Левое/правое значения==
Два важных понятия левого и правого значений, или левостороннее и правостороннее значения. Левостороннее значение имеет то, что появляется на левой стороне выражения, а правостороннее значение - появляется на правой стороне выражения.

Например:
<pawn>
new a = 5;</pawn>

В этом примере <tt>a</tt> является левосторонним значением и <tt>5</tt> является правосторонним значением.

Правила:
*'''Выражения никогда не будут левосторонними значениями'''.
*'''Переменные являются двумя, левосторонними и правосторонними значениями'''.

=Условия=
Условия позволяют Вам запускать код, определенное условие выполнено.

==Если соответствует==
Если соответствует одно или более условий. Например:

<pawn>
if (a == 5)
{
/* Код будет запущен, если условие будет истинным */
}</pawn>

Они могут быть расширены для более сложных случаев:
<pawn>
if (a == 5)
{
/* Код */
}
else if (a == 6)
{
/* Код */
}
else if (a == 7)
{
/* Код */
}</pawn>

Вы так же можете обрабатывать случаи, даже если выражение не верно. Например:
<pawn>
if (a == 5)
{
/* Код */
}
else
{
/* Код, который будет запущен если нет истинного выражения */
}</pawn>

==Оператор выбора==
Оператор выбора будет ограничен условием. Он необходим для выражения, выполняющего код для целого ряда возможных значений. Например:

<pawn>
switch (a)
{
case 5:
{
/* Код */
}
case 6:
{
/* Код */
}
case 7:
{
/* Код */
}
case 8, 9, 10:
{
/* Код */
}
default:
{
/* будет запущен, если не одно условие не соответствует */
}
}</pawn>

В отличие от некоторых других языков, оператор выбора не проваливается. То есть существуют случаи, когда код не будет запущен. При случае совпадения его код выполняется, а ключ является местом для немедленного прекращения.

=Циклы=
Циклы позволяют Вам без труда повторять выполнение кода, пока условие станет истинным.

==For циклы==
For циклы, это циклы, которые состоят из четырех частей:
*Оператор '''инициализации''' - запускается один раз перед первым циклом.
*Оператор '''условия''' - проверяет условие и запускает следующий цикл, в том числе первый. Цикл прекращается, когда это выражение становится ложным.
*Оператор '''итерации''' - запускается после каждого цикла.
* '''тело''' цикла - запускается каждый раз, пока оператор '''условия''' вычисляется как истинный.

<pawn>
for ( /* инициализация */ ; /* условие */ ; /* итерация */ )
{
/* тело */
}
</pawn>

Простым примером является функция сложения массива:
<pawn>
new array[10] = {1, 2, 3, 4, 5, 6, 7, 8, 9, 10};
new sum = SumArray(array, 10);

SumArray(const array[], count)
{
new total;

for (new i = 0; i < count; i++)
{
total += array[i];
}

return total;
}</pawn>

По отдельности:
*<tt>new i = 0</tt> - Создает новую переменную для цикла, и устанавливает её в 0.
*<tt>i < count</tt> - Только запускает цикл, если <tt>i</tt> меньше, чем <tt>count</tt>. Это гарантирует, что чтение цикла прекращается в определенный момент. В этом случае, мы не хотим читать недействительные индексы в массиве.
*<tt>i++</tt> - Увеличивает <tt>i</tt> на единицу после каждого цикла. Это гарантирует, что цикл не будет запущен вечно; в конце концов <tt>i</tt> станет слишком большим, и цикл завершится.

Таким образом, функция <tt>SumArray</tt> будет циклом каждого действительного индекса массива, каждый раз добавляя это значение в sum. Для циклов очень распространены массивы такие, как в нашем примере.

==While циклы==
While циклы являются менее распространенными, чем for циклы, но на самом деле это более простые циклы. Они имеют только две части:
*Оператор '''условия''' - проверяется перед началом каждого цикла. Цикл прекращается, когда условие становится ложным.
*'''тело''' цикла - запускается каждый раз пока цикл выполняется.

<pawn>
while ( /* условие */ )
{
/* тело */
}
</pawn>

До тех пор, пока условие выражения остается истинным, цикл будет выполняться. Каждый for цикл может быть переписан, как while цикл:

<pawn>
/* инициализация */
while ( /* условие */ )
{
/* тело */
/* итерация */
}
</pawn>

Вот предыдущий for цикл переписан как while цикл:
<pawn>
SumArray(const array[], count)
{
new total, i;

while (i < count)
{
total += array[i];
i++;
}

return total;
}</pawn>

Существуют также '''do...while''' циклы, которые используются еще реже. Они работают как и while циклы, но проверяют условие ПОСЛЕ каждого цикла, а не перед ним. Это означает, что цикл всегда будет запущен, по крайней мере один раз. Например:

<pawn>
do
{
/* тело */
}
while ( /* условие */ );
</pawn>

==Управление циклами==
Существуют два случая, в которых Мы хотели бы контролировать цикл:
*'''пропустить''' одну итерацию или цикл и продолжить выполнение цикла как обычно, или;
*'''разорвать''' цикл целиком, прежде чем он закончится.

Допустим у вас есть функция, которая принимает массив и ищет соответствия цифр. Вы хотите его остановить, когда число будет найдено:
<pawn>
/**
* Возвращает массив, если индекс значения, или -1, не найдены.
*/
SearchInArray(const array[], count, value)
{
new index = -1;

for (new i = 0; i < count; i++)
{
if (array[i] == value)
{
index = i;
break;
}
}

return index;
}</pawn>

Конечно, эту функцию можно вернуть и способом <tt>return i</tt>, но пример показывает, как <tt>break</tt> может остановить цикл.

Кроме того, ключевое слово <tt>continue</tt> пропускает итерации цикла. Например, Мы хотим суммировать все четные числа:

<pawn>
SumEvenNumbers(const array[], count)
{
new sum;

for (new i = 0; i < count; i++)
{
/* If divisibility by 2 is 1, we know it's odd */
if (array[i] % 2 == 1)
{
/* Пропускаем оставшуюся часть итерации цикла */
continue;
}
sum += array[i];
}

return sum;
}</pawn>

=Scope=
Scope refers to the '''visibility''' of code. That is, code at one level may not be "visible" to code at another level. For example:

<pawn>
new A, B, C;

Function1()
{
new B;

Function2();
}

Function2()
{
new C;
}</pawn>

In this example, <tt>A</tt>, <tt>B</tt>, and <tt>C</tt> exist at '''global scope'''. They can be seen by any function. However, the <tt>B</tt> in <tt>Function1</tt> is not the same variable as the <tt>B</tt> at the global level. Instead, it is at '''local scope''', and is thus a '''local variable'''.

Similarly, <tt>Function1</tt> and <tt>Function2</tt> know nothing about each other's variables.

Not only is the variable private to <tt>Function1</tt>, but it is re-created each time the function is invoked. Imagine this:
<pawn>
Function1()
{
new B;

Function1();
}</pawn>

In the above example, <tt>Function1</tt> calls itself. Of course, this is infinite recursion (a bad thing), but the idea is that each time the function runs, there is a new copy of <tt>B</tt>. When the function ends, <tt>B</tt> is destroyed, and the value is lost.

This property can be simplified by saying that a variable's scope is equal to the nesting level it is in. That is, a variable at global scope is visible globally to all functions. A variable at local scope is visible to all code blocks "beneath" its nesting level. For example:

<pawn>Function1()
{
new A;

if (A)
{
A = 5;
}
}</pawn>

The above code is valid since A's scope extends throughout the function. The following code, however, is not valid:
<pawn>
Function1()
{
new A;

if (A)
{
new B = 5;
}

B = 5;
}</pawn>

Notice that <tt>B</tt> is declared in a new code block. That means <tt>B</tt> is only accessible to that code block (and all sub-blocks nested within). As soon as the code block terminates, <tt>B</tt> is no longer valid.

=Dynamic Arrays=
Dynamic arrays are arrays which don't have a hardcoded size. For example:

<pawn>Function1(size)
{
new array[size];

/* Code */
}</pawn>

Dynamic arrays can have any expression as their size as long as the expression evaluates to a number larger than 0. Like normal arrays, SourcePawn does not know the array size after it is created; you have to save it if you want it later.

Dynamic arrays are only valid at the local scope level, since code cannot exist globally.

=Extended Variable Declarations=
Variables can be declared in more ways than simply <tt>new</tt>.

==decl==
===Purpose===
By default, all variables in Pawn are initialized to zero. If there is an explicit initializer, the variable is initialized to the expression after the <tt>=</tt> token. At a local scope, this can be a run-time expense. The <tt>decl</tt> keyword (which is only valid at local scope) was introduced to let users decide if they want variables initialized or not.

Note: <tt>decl</tt> should not be used on single cell variables. There is almost never any benefit.

===Explanation===
For example:

<pawn>
new c = 5;
new d;
new String:blah[512];

Format(blah, sizeof(blah), "%d %d", c, d);
</pawn>

In this code, <tt>c</tt> is equal to 5 and <tt>d</tt> is equal to 0. The run-time expense of this initialization is negligible. However, <tt>blah</tt> is a large array, and the expense of initializing the entire array to 0s could be detrimental in certain situations.

Note that <tt>blah</tt> does not need to be zeroed. In between being declared with <tt>new</tt> and stored with <tt>Format()</tt>, <tt>blah</tt> is never loaded or read. Thus this code would be more efficiently written as:

<pawn>
new c = 5;
new d;
decl String:blah[512];

Format(blah, sizeof(blah), "%d %d", c, d);
</pawn>

===Caveats===
The downside to <tt>decl</tt> is that it means its variables will start with "garbage" contents. For example, if we were to use:

<pawn>
new c = 5;
new d;
decl String:blah[512];

PrintToServer("%s", blah);

Format(blah, sizeof(blah), "%d %d", c, d);
</pawn>

This code may crash the server, because <tt>blah</tt> may be completely corrupt (strings require a terminator, and that may not be present). Similarly, if we did:

<pawn>
new c = 5;
decl d;
decl String:blah[512];

Format(blah, sizeof(blah), "%d %d", c, d);
</pawn>

The value of <tt>d</tt> is now undefined. It could be any value, negative or positive.

Note that it is easy to efficiently make strings safe. The example below shows how to terminate a garbage string:
<pawn>
decl String:blah[512];

blah[0] = '\0';
</pawn>

===Golden Rules===
*'''Only use decl if in between declaring and loading/reading the value, you are absolutely sure there is at least one store/set operation that gives the variable valid data.'''
*'''Do not prematurely optimize.''' Likewise, there is no need to use <tt>decl</tt> on non-arrays, because there is no added expense for initializing a single cell value.

===Notes===
This example is NOT as efficient as a <tt>decl</tt>:
<pawn>
new String:blah[512] = "a";
</pawn>

Even though the string is only one character, the <tt>new</tt> operator guarantees the rest of the array will be zeroed as well.

Also note, it is invalid to explicitly initialize a <tt>decl</tt>:
<pawn>decl String:blah[512] = "a";</pawn>

The above code will not compile, because the purpose of <tt>decl</tt> is to avoid any initialization.

==static==
The <tt>static</tt> keyword is available at global and local scope. It has different meanings in each.

===Global static===
A global static variable can only be accessed from within the same file. For example:

<pawn>//file1.inc
static Float:g_value1 = 0.15f;

//file2.inc
static Float:g_value2 = 0.15f;</pawn>

If a plugin includes both of these files, it will not be able to use either <tt>g_value1</tt> or <tt>g_value2</tt>. This is a simple information hiding mechanism, and is similar to declaring member variables as <tt>private</tt> in languages like C++, Java, or C#.

===Local static===
A local static variable is a global variable that is only visible from its local lexical scope. For example:

<pawn>
MyFunction(inc)
{
static counter = -1;

counter += inc;

return counter;
}</pawn>

In this example, <tt>counter</tt> is technically a global variable -- it is initialized once to -1 and is never initialized again. It does not exist on the stack. That means each time <tt>MyFunction</tt> runs, the <tt>counter</tt> variable and its storage in memory is the same.

Take this example:
<pawn>MyFunction(5);
MyFunction(6);
MyFunction(10);</pawn>

In this example, <tt>counter</tt> will be <tt>-1 + 5 + 6 + 10</tt>, or <tt>20</tt>, because it persists beyond the frame of the function. Note this may pose problems for recursive functions: if your function may be recursive, then <tt>static</tt> is usually not a good idea unless your code is re-entrant.

The benefit of a local static variable is that you don't have to clutter your script with global variables. As long as the variable doesn't need to be read by another function, you can squirrel it inside the function and its persistence will be guaranteed.

Note that statics can exist in any local scope:

<pawn>
MyFunction(inc)
{
if (inc > 0)
{
static counter;
return (counter += inc);
}
return -1;
}</pawn>

[[Category:Ru:SourceMod Scripting]]

Ru:Introduction to SourcePawn

2008-12-26T10:09:49Z

Frenzzy: /* While Loops */

Это руководство призвано дать Вам самые основные представления по основам написания сприптов в SourcePawn. [[Pawn]] это "скриптовый" язык используемый для внедрения функциональности в других программах. Это означает, что это не самостоятельный язык, как C++ или Java, и его элементы будут отличаться в различных приложениях. SourcePawn это вариация языка Pawn используемая в [[SourceMod]].

Это руководство не расскажет Вам как писать SourceMod плагины; оно предназначено для получения общих представлений о синтаксисе и семантике этого языка. Читайте отдельную статью [[Ru:Introduction to SourceMod Plugins]] (Введение в SourceMod плагины), для введения в SourceMod API.

=Введение для новичков=
Этот раздел создан не для программистов. Если Вы по прежнему в замешательстве, Вы можете прочитать книги о других языках программирования, таких как PHP, Python, или Java, чтобы получить более полное представление о программировании.

==Идентификаторы/Ключевые слова==
Идентификаторы представляет собой набор букв, цифр и/или нижнего подчеркивания, что представляет собой нечто уникальное. Идентификаторы вводятся с учетом регистра (в отличие от PHP, где иногда это не требуется). Идентификаторы не начинаются с какого-либо специального символа, но они должны начинаться с буквы.

Есть несколько зарезервированных символов, которые имеют особое значение. Например, <tt>if</tt>, <tt>for</tt>, и <tt>return</tt> специальные конструкции в языке, которые будут описаны позднее. Они не могут быть использованы в качестве названий идентификаторов.

==Переменные==
Существует несколько важных конструкций, которые Вы должны знать, прежде чем приступить к написанию сценария. Во-первых, это '''переменные'''. Переменная это идентификатор, который содержит данные. Например, переменная "a" может содержать числа "2", "16", "0", и так далее. Переменные создаются для хранения данных внутри программы. Переменные должны быть объявлены до их использования, с помощью ключевого слова "new". Данные можно присвоить переменной, используя знак равенства (=). Пример:

<pawn>new a, b, c, d;

a = 5;
b = 16;
c = 0;
d = 500;</pawn>

В SourcePawn, переменные бывают двух типов, которые будут более подробно описаны далее.
*Однострочные (могут содержать только произвольные числовые данные), как показано выше.
*Многострочные (могут содержать целый ряд текстовых символов)

==Функции==
Следующим важным понятием являются '''функции'''. Функции идентификаторов или имен, которые выполняют действия. Это означает, что когда вы их активируете, они выполняют конкретную последовательность кода. Есть несколько типов функций, но все функции активируется одинаковым образом. "Вызов функции" является термином ссылающимся на функцию действия. Функция числовых переменных строятся так:
<pawn>функция(<параметры>)</pawn>

Примеры:

<pawn>show(56); //Активирует функцию "show" и присваивает ей число 56
show(); //Активирует функцию "show" без каких-либо данных, пустую
show(a); //Активирует функцию "show" и присваивает ей переменную с данными
</pawn>

Каждый фрагмент данных передаваемый вызываемой функции, называется '''параметр'''. Функция может иметь любое количество параметров (но есть "допустимый" предел в SourceMod: 32). Параметры будут описаны далее в этой статье.

==Комментарии==
Примечания и любой текст, который пишется после "//" считается "Комментарием", а не фактическим кодом. Есть два стиля комментариев:
*<tt>//</tt> - Двойная косая черта, всё следующие после этой строки игнорируется.
*<tt>/* */</tt> - Много-строчный комментарий, весь текст, внутри звездочек игнорируются. You cannot nest these.

==Массивы==
Описание массивов. Вы можете группировать код в виде "массивов", разделенных { и }. Это фактически создает возможность работать с целым массивом как с одним оператором. Например:

<pawn>{
here;
is;
some;
code;
}</pawn>

Массивы с фигурными скобками используются достаточно широко в программировании. Массивы кода могут быть вложенными друг в друга. Это хорошая возможность адаптировать последовательность когда и сделать его удобочитаемым, благодаря отступам код не будет смотреться как одна большая и длинная макаронина.

=Особенности языка=
Pawn может показаться очень похожим на другие языки программирования, например C, но Pawn от них фундаментально отличается. Не столь важно, чтобы Вы сейчас же поняли его отличия, но они понадобятся, если Вы уже знаете один из языков программирования.
*'''Pawn не печатает''' Pawn имеет только один тип данных - '''однострочный'''. Подробнее будет описано позже. [В дальнейшем автор рассказывает, что существует два типа данных: однострочный и многострочный]
*'''Pawn не собирает мусор''' Pawn, как язык, не имеет встроенных ресурсов памяти, и потому он не мусорит. Если функция выделит память, то Вы отвечаете за её освобождение.
*'''Pawn не объектно-ориентированный язык''' Pawn является процедурным, и полагается на подпрограммы. Также у него нету C подобных структур.
*'''Pawn не функциональный.''' Pawn является процедурным, и не поддерживает функции "лямбды" (Lambda), поздние присвоения, и все то, что можно найти в языках высшего уровня, таких как Phyton и Ruby.
*'''Pawn однопоточный''' As of this writing, Pawn is not thread safe.
*'''Pawn не интерпретируемый''' Ну, почти. Он интерпретируется на очень низком уровне. Вы должны скомпилировать код, из которого получится бинарный файл. Эта программа будет работать на той платформе, которую использует хост. Это ускоряет загрузку и позволяет легче находить ошибки.

Этот язык был выпущен ITB CompuPhase. Язык разработан для устройств низкого уровня и таким образом конечные программы очень маленькие по размеру и очень быстрые.

=Переменные=
В Pawn есть всего два типа переменных: '''однострочные''' и '''многострочные'''. Однострочные могут содержать 32 бита цифровых данных. Многострочные - последовательный список из UTF-8 символов.

'''однострочные''' не имеет своего типа, однако они могут быть '''маркированы'''(tagged). Тег позволяет Вам указывать, где определенную ячейку можно использовать. Типичные теги:
*(пусто), или '''_''' - Нет тега. Обычно используют для целых чисел ([http://en.wikipedia.org/wiki/Integer Integers]).
*'''Float''' - используют для чисел с плавающей точкой (небольших).
*'''bool''' - используют для хранения значений '''true''' (истина) или '''false''' (ложь).

Со строками все по другому, они будут рассмотрены далее.

==Объявления==
Примеры разных правильных объявлений переменных.
<pawn>
new a = 5;
new Float:b = 5.0;
new bool:c = true;
new bool:d = 0; //Работает, поскольку 0 равно false (ложь)
</pawn>

Неправильные объявления переменных
<pawn>
new a = 5.0; //Несоответствие тегов. 5.0 с тегом Float
new Float:b = 5; //Несоответствие тегов. 5 без тега.
</pawn>

Если переменная не определена в объявлении то ее значения станет 0
<pawn>
new a; //значение 0
new Float:b; //значение 0.0
new bool:c; //значение false
</pawn>

==Присвоение==
Переменным могут быть присвоены данные после создания. Пример:
<pawn>new a, Float:b, bool:c;

a = 5;
b = 5.0;
c = true;
</pawn>

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

==Описание==
Массив объявляется с помощью квадратных скобок. Вот некоторые примеры массивов:
<pawn>
new players[32]; //Набор из 32 однострочных (числовых) данных
new Float:origin[3]; //Набор из 3 чисел с плавающей точкой
</pawn>

По умолчанию, массивам присваиваются нули. Вы можете присвоить им разные значения по умолчанию, однако:
<pawn>
new numbers[5] = {1, 2, 3, 4, 5}; //Набор 1, 2, 3, 4, 5 из однострочных данных.
new Float:origin[3] = {1.0, 2.0, 3.0}; //Набор 1.0, 2.0, 3.0 из однострочных данных.
</pawn>

Вы можете оставить массив без размера, если вы собираетесь заранее присвоить ему данные. Например:
<pawn>
new numbers[] = {1, 3, 5, 7, 9};
</pawn>

Компилятор будет автоматически делать вывод о том, что Вы хотите получить массив размером 5.

==Использование==
Использование массива равносильно использованию обычных переменной. Единственное отличие массива состоит в том, что он должен быть '''индексируемым'''. Индексирование массива означает присутствие возможности выбрать элемент, который Вы хотите использовать.

Вот пример кода с использованием индексов:
<pawn>
new numbers[5], Float:origin[3];

numbers[0] = 1;
numbers[1] = 2;
numbers[2] = 3;
numbers[3] = 4;
numbers[4] = 5;
origin[0] = 1.0;
origin[1] = 2.0;
origin[2] = 3.0;
</pawn>

Заметим, что '''индекс''' это текст, который находится в квадратных скобках. Индекс всегда начинается с нуля. То есть, если массив имеет N элементов, его действительный индекс от 0 до N-1. Доступ к данным с индексами работает так же, как с обычной переменной.

Использование неверного индекса вызовет ошибку. Например:
<pawn>
new numbers[5];

numbers[5] = 20;</pawn>

Это может выглядеть верно, но число 5 не является допустимым индексом. Наибольшим значением индекса является число 4.

Вы можете использовать любые выражения, как индекс. Например:
<pawn>new a, numbers[5];

a = 1; //Сделает a = 1
numbers[a] = 4; //Сделает numbers[1] = 4
numbers[numbers[a]] = 2; //Сделает numbers[4] = 2
</pawn>

Выражения будут обсуждаться подробнее в конце статьи.

=Строки=
Строки являются удобным способом хранения текста. Символы хранятся в массиве. Строка ограничивается '''нулевым символом''', или 0. Без нулевого символа, Pawn не знает, где остановить чтение строки. Все строки в SourcePawn используют кодировку UTF-8.

Отметим, что строки имеют комбинацию из массивов и однострочных переменных. В отличие от других языков, это означает, что Вы должны знать заранее, как много места будут использовать строки. Это означает, что строки не являются динамичными. Они могут лишь вырасти до размера, которым Вы их ограничили.

''Примечание для специалистов: они фактически не однострочные. SourcePawn использует 8-битный строки для хранения массивов в качестве оптимизации. Это и есть то, что делает строки типом, а не меткой.''

==Использование==
Строки были созданы почти в равной степени и для массивов. Например:
<pawn>
new String:message[] = "Hello!";
new String:clams[6] = "Clams";
</pawn>

Это равносильно следующему:
<pawn>
new String:message[7], String:clams[6];

message[0] = 'H';
message[1] = 'e';
message[2] = 'l';
message[3] = 'l';
message[4] = 'o';
message[5] = '!';
message[6] = 0;
clams[0] = 'C';
clams[1] = 'l';
clams[2] = 'a';
clams[3] = 'm';
clams[4] = 's';
clams[5] = 0;
</pawn>

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

Заметим, что строка должна быть заключена в двойных кавычках, а символ в одиночных.

==Символы==
Особенность текста может быть использована в любой строке или однострочной переменной. Например:
<pawn>new String:text[] = "Crab";
new clam;

clam = 'D'; //Устанавливает однострочной переменной значение 'D'
text[0] = 'A'; //Меняет 'C' на 'A', сейчас получилось 'Arab'
clam = text[0]; //Устанавливает однострочной переменной значение 'A'
text[1] = clam; //Меняет 'r' на 'A', сейчас получилось 'AAab'
</pawn>

То, что вы не можете сделать, это соотнести символы массивов со строками. Внутреннее хранение отличается. Например:
<pawn>
new clams[] = "Clams"; //Не верно, нужен тип String:
new clams[] = {'C', 'l', 'a', 'm', 's', 0}; //Верно, но это НЕ СТРОКА.
</pawn>

=Функции=
Функции, как отмечалось ранее, имеют отдельные составляющие кода, которые выполняют определенные действия. Функции могут быть задействованы или '''вызвоны''' с '''параметрами''', которые дают особые настройки.

Существуют два типа вызова функции:
*'''прямой вызов''' - Вы специально вызываете функцию в своем коде.
*'''обратный вызов''' - Применение вызова функций в Вашем коде, как если бы это было событием триггера (совокупность условий, инициирующих выполнение действия).

Существуют пять видов функций:
*'''native''': Прямая, внутренняя функция, предусмотренная в приложении.
*'''public''': Функция обратного вызова, что делает её видимой для приложения и других сценариев.
*'''normal''': Нормальная функция, которую Вы можете только вызвать.
*'''stock''': Нормальная функция, предусмотренная если включает в себя файл. Если не используется, то не компилируется.
*'''forward''': Эта функция представляет собой глобальное событие, предусмотренная приложением. Если Вы её привели в исполнение, она будет вызвона.

Весь код в Pawn должен существовать в функциях. Это основное отличие от языков, таких как PHP, Perl и Python, которые позволяют Вам писать глобальный код. Это происходит потому, что Pawn вызывается на основе другого языка: он реагирует на действия от родительского приложения, и функции должны быть написаны для обработки этих действий. Хотя наш пример, часто содержат свободно плавающий код, это сделано исключительно для демонстрационных целей. Свободно плавающий код в нашем примере означает, что код является частью ряда функций.

==Описание==
В отличие от переменных, функции, не нужно объявлять, прежде чем использовать их. Функции имеют две части, '''модель''' и '''тело'''. Модель содержит имя Вашей функции и параметры, которые она будет принимать. Тело является контейнером для кода.

Пример функции:
<pawn>
AddTwoNumbers(first, second)
{
new sum = first + second;

return sum;
}</pawn>

Это простая функция. Модель этой строки:
<pawn>AddTwoNumbers(first, second)</pawn>

Распишем по отдельности:
*<tt>AddTwoNumbers</tt> - Название функции.
*<tt>first</tt> - Название первого параметра, который представляет собой простой элемент.
*<tt>second</tt> - Название второго параметра, который представляет собой простой элемент.

Тело представляет собой простой блок кода. Он создает новую переменную, названную <tt>sum</tt>, и присваивает ей значение этих двух параметров, добавленных совместно (другие выражения будут позже). Важно заметить оператор <tt>return</tt>, в котором обозначается конец функции и возврат с полученными значениями из этой функции. Все функции ''возвращают значения'' после завершения. Это означает, например:

<pawn>new sum = AddTwoNumbers(4, 5);</pawn>

Приведенный выше код будет присваивать число 9 к sum. Функция получает два значения и передает новое значение sum в качестве '''возвращаемого значения'''. Если функция не имеет возвращаемого значения или не имеет значений для возврата, то возвращается 0 по умолчанию.

Функция может принимать любые типы значений. Она может вернуть любую однострочную переменную, но не массивы или строки. Пример:
<pawn>Float:AddTwoFloats(Float:a, Float:b)
{
new Float:sum = a + b;

return sum;
}</pawn>

''Заметим, что если в приведенной выше функции, Вам вернулась не Float значение, Вы получите не соответствие значений.''

Можно, конечно, передавать переменные в функции:
<pawn>new numbers[3] = {1, 2, 0};

numbers[2] = AddTwoNumbers(numbers[0], numbers[1]);</pawn>

Заметим, что однострочные переменные передаются '''по значению'''. То есть, их значение не может быть изменено функцией. Например:
<pawn>new a = 5;

ChangeValue(a);

ChangeValue(b)
{
b = 5;
}</pawn>

Этот код не будет менять значение <tt>a</tt>. Это происходит потому, что копия этого значения в <tt>a</tt> передается вместо <tt>a</tt> самостоятельно.

Больше примеров функций будут демонстрироваться и в других частях статьи.

==Publics==
Публичные функции используются для осуществления обратных вызовов. Вы не должны создавать какую-либо публичную функцию, если это вынудит выполнение обратного вызова. Например, вот два обратных вызова из <tt>sourcemod.inc</tt>:

<pawn>forward OnPluginStart();
forward OnClientDisconnected(client);</pawn>

Чтобы выполнить и получить эти два события, Вы должны написать такие функции как:

<pawn>public OnPluginStart()
{
/* Код здесь */
}

public OnClientDisconnected(client)
{
/* Код здесь */
}</pawn>

Ключевое слово '''public''' делает функцию публичной, а также позволяет родительскому приложению непосредственно вызывать функцию.

==Natives==
Natives имеют встроенные функции, предоставляемые приложением. Вы можете вызвать их, как если бы они были normal функциями. Например, SourceMod имеет следующие функции:

<pawn>native FloatRound(Float:num);</pawn>

Её можно вызвать таким образом:
<pawn>new num = FloatRound(5.2); //Результат в num = 5</pawn>

==Параметры массива==
Вы можете передавать массивы или строки в качестве параметров. Важно отметить, что они идут '''как ссылка'''. То есть не делать копию данных, а отдавать непосредственно ссылки на данные. Существует простой способ объяснить это более конкретно.

<pawn>
new example[] = {1, 2, 3, 4, 5};

ChangeArray(example, 2, 29);

ChangeArray(array[], index, value)
{
array[index] = value;
}</pawn>

Эта функция устанавливает заданный индекс в массиве с учетом значений. Когда она запускается на примере нашего массива, она меняет индекс 2 для значения 3 на 29. То есть:
<pawn>example[2] = 29;</pawn>

Это возможно лишь потому, что массив может быть непосредственно изменён. Чтобы предотвратить массив от изменения, можно пометить его как постоянную <tt>const</tt>. Это позволит понизить риск на ошибку в коде от её изменения. Например:

<pawn>CantChangeArray(const array[], index, value)
{
array[index] = value; //Не компилируется
}</pawn>

Это хорошая идея использовать <tt>const</tt> в параметрах массивов и Вы будете точно знать, что массив не будет изменен; это может предотвратить ошибки кодирования.

=Выражения=
Выражения являются точно такими же, какими они существуют в математике. Это группы операторов/символов, которые приходятся на один фрагмент данных. Они часто заключены в скобках (внутри скобок). Они содержат строгий "порядок операций". Они могут содержать переменные, функции, цифры и выражения сами могут быть вложенные внутрь других выражений, и даже приняты в качестве параметров.

Приведем пример простейшего выражения:
<pawn>
0; //Возвращает число 0
(0); //Так же возвращает число 0
</pawn>

Хотя выражения могут возвращать значения, они также могут ответить какое значение содержит ответ ''ноль или не ноль''. В этом смысле, ''ноль'' является ''ложью'' (false), а ''не нулевое'' значение ''истиной'' (true). Например, -1 ''истина'' в Pawn, поскольку она не является нулем. Не думайте, что отрицательные числа являются ложными.

Порядок операций выражения аналогичен языку C. PMDAS: Parenthesis, Multiplication, Division, Addition, Subtraction. Вот несколько примеров выражений:
<pawn>
5 + 6; //Вычисляет как 11
5 * 6 + 3; //Вычисляет как 33
5 * (6 + 3); //Вычисляет как 45
5.0 + 2.3; //Вычисляет как 7.3
(5 * 6) % 7; //Modulo operator, вычисляет как 2
(5 + 3) / 2 * 4 - 9; //Вычисляет как 7
</pawn>

Как уже отмечалось, выражения могут содержать переменные, или даже функции:
<pawn>
new a = 5 * 6;
new b = a * 3; //Вычисляет как 90
new c = AddTwoNumbers(a, b) + (a * b);
</pawn>

==Операторы==
Есть несколько полезных дополнительных операторов в Pawn. Первый набор упрощает аутоагрегацию выражения. Например:
<pawn>new a = 5;

a = a + 5;</pawn>

Может быть переписан, как:
<pawn>new a = 5;
a += 5;</pawn>

Это верно в отношении следующих операторов в Pawn:
*Four-function: *, /, -, +
*Bit-wise: |, &, ^, ~, <<, >>

Кроме того, существуют инкремент/декремент операторы:
<pawn>a = a + 1;
a = a - 1;</pawn>

Может быть упрощено, как:
<pawn>a++;
a--;</pawn>

Дополнительно отметим, что ++ или -- может быть представлен до переменной (до-инкремент, до-декремент) или после переменной (пост-инкремент, пост-декремент). Разница заключается в том, как остальная часть выражения содержащие их, видит результат.

* ''До:'' Переменная увеличивается до определения и остальная часть выражения видит новое значение.
* ''Пост:'' Переменная увеличивается после определения и остальная часть выражения видит старое значение.

Иными словами, <tt>a++</tt> определяет значение как <tt>a</tt> в то время как <tt>++a</tt> определяет значение как <tt>a + 1</tt>. В обоих случаях <tt>a</tt> увеличивается на <tt>1</tt>.

Например:

<pawn>new a = 5;
new b = a++; // b = 5, a = 6 (1)
new c = ++a; // a = 7, c = 7 (2)
</pawn>

(1) <tt>b</tt> присваивается <tt>a</tt> со ''старым'' значением, ''до'' того, как он будет увеличено до <tt>6</tt>. (2) <tt>c</tt> присваивается <tt>a</tt> с ''новым'' значением, ''после'' того, как он увеличивается до <tt>7</tt>.

==Операторы сравнения==
Существуют шесть операторов для сравнения двух числовых значений, а результат является либо истиной (не ноль) или ложью (ноль):
*<tt>a == b</tt> - Действительно, если и b имеет то же значение.
*<tt>a != b</tt> - Действительно, если b имеет другое значение.
*<tt>a > b</tt> - Действительно, если оно больше b
*<tt>a >= b</tt> - Действительно, если оно больше или равно b
*<tt>a < b</tt> - Действительно, если оно меньше b
*<tt>a <= b</tt> - Действительно, если оно меньше или равно b

Например:
<pawn>
(1 != 3); //Определяется как истина, поскольку 1 не равно 3.
(3 + 3 == 6); //Определяется как истина, поскольку 3+3 равно 6.
(5 - 2 >= 4); //Определяется как ложь, поскольку 3 меньше 4.
</pawn>

Заметим, что эти операторы не работают с массивами и строками. То есть, вы не можете сравнить их с помощью <tt>==</tt>.

==Действительные операторы==
Действительные операторы могут быть скомбинированы тремя булевыми (boolean) операторами:
*<tt>a && b</tt> - Истина, если a и b истинные. Ложь, если a и (или) b ложные.
{| border="1" cellpadding="2" cellspacing="0" align="center"
! <tt>&&</tt> !! 0 !! 1
|-
! 0
| 0 || 0
|-
! 1
| 0 || 1
|}
*<tt>a || b</tt> - Истина, если a или b (или обе переменные) истинные. Ложь, если обе переменные a и b ложные.
{| border="1" cellpadding="2" cellspacing="0" align="center"
! <tt><nowiki>||</nowiki></tt> !! 0 !! 1
|-
! 0
| 0 || 1
|-
! 1
| 1 || 1
|}
*<tt>!a</tt> - Истина, если a ложь. Ложь, если a истина.
{| border="1" cellpadding="2" cellspacing="0" align="center"
! <tt>!</tt> !! 0 !! 1
|-
!
| 1 || 0
|}

Например:
<pawn>
(1 || 0); //Определяется как истина, так как выражение 1 истинное
(1 && 0); //Определяется как ложь, так как выражение 0 ложное
(!1 || 0); //Определяется как ложь, так как выражение !1 ложное.
</pawn>

==Левое/правое значения==
Два важных понятия левого и правого значений, или левостороннее и правостороннее значения. Левостороннее значение имеет то, что появляется на левой стороне выражения, а правостороннее значение - появляется на правой стороне выражения.

Например:
<pawn>
new a = 5;</pawn>

В этом примере <tt>a</tt> является левосторонним значением и <tt>5</tt> является правосторонним значением.

Правила:
*'''Выражения никогда не будут левосторонними значениями'''.
*'''Переменные являются двумя, левосторонними и правосторонними значениями'''.

=Условия=
Условия позволяют Вам запускать код, определенное условие выполнено.

==Если соответствует==
Если соответствует одно или более условий. Например:

<pawn>
if (a == 5)
{
/* Код будет запущен, если условие будет истинным */
}</pawn>

Они могут быть расширены для более сложных случаев:
<pawn>
if (a == 5)
{
/* Код */
}
else if (a == 6)
{
/* Код */
}
else if (a == 7)
{
/* Код */
}</pawn>

Вы так же можете обрабатывать случаи, даже если выражение не верно. Например:
<pawn>
if (a == 5)
{
/* Код */
}
else
{
/* Код, который будет запущен если нет истинного выражения */
}</pawn>

==Ключ соответствия==
Ключ соответствия будет ограничен условием. Он необходим для выражения, выполняющего код для целого ряда возможных значений. Например:

<pawn>
switch (a)
{
case 5:
{
/* Код */
}
case 6:
{
/* Код */
}
case 7:
{
/* Код */
}
case 8, 9, 10:
{
/* Код */
}
default:
{
/* будет запущен, если не одно условие не соответствует */
}
}</pawn>

В отличие от некоторых других языков, ключи не терпят неудачи. То есть существуют случаи, когда код не будет запущен. При случае совпадения его код выполняется, а ключ является местом для немедленного прекращения.

=Циклы=
Циклы позволяют Вам без труда повторять выполнение кода, пока условие станет истинным.

==For циклы==
For циклы, это циклы, которые состоят из четырех частей:
*Оператор '''инициализации''' - запускается один раз перед первым циклом.
*Оператор '''условия''' - проверяет условие и запускает следующий цикл, в том числе первый. Цикл прекращается, когда это выражение становится ложным.
*Оператор '''итерации''' - запускается после каждого цикла.
* '''тело''' цикла - запускается каждый раз, пока оператор '''условия''' вычисляется как истинный.

<pawn>
for ( /* инициализация */ ; /* условие */ ; /* итерация */ )
{
/* тело */
}
</pawn>

Простым примером является функция сложения массива:
<pawn>
new array[10] = {1, 2, 3, 4, 5, 6, 7, 8, 9, 10};
new sum = SumArray(array, 10);

SumArray(const array[], count)
{
new total;

for (new i = 0; i < count; i++)
{
total += array[i];
}

return total;
}</pawn>

По отдельности:
*<tt>new i = 0</tt> - Создает новую переменную для цикла, и устанавливает её в 0.
*<tt>i < count</tt> - Только запускает цикл, если <tt>i</tt> меньше, чем <tt>count</tt>. Это гарантирует, что чтение цикла прекращается в определенный момент. В этом случае, мы не хотим читать недействительные индексы в массиве.
*<tt>i++</tt> - Увеличивает <tt>i</tt> на единицу после каждого цикла. Это гарантирует, что цикл не будет запущен вечно; в конце концов <tt>i</tt> станет слишком большим, и цикл завершится.

Таким образом, функция <tt>SumArray</tt> будет циклом каждого действительного индекса массива, каждый раз добавляя это значение в sum. Для циклов очень распространены массивы такие, как в нашем примере.

==While циклы==
While циклы являются менее распространенными, чем for циклы, но на самом деле это более простые циклы. Они имеют только две части:
*Оператор '''условия''' - проверяется перед началом каждого цикла. Цикл прекращается, когда условие становится ложным.
*'''тело''' цикла - запускается каждый раз пока цикл выполняется.

<pawn>
while ( /* условие */ )
{
/* тело */
}
</pawn>

До тех пор, пока условие выражения остается истинным, цикл будет выполняться. Каждый for цикл может быть переписан, как while цикл:

<pawn>
/* инициализация */
while ( /* условие */ )
{
/* тело */
/* итерация */
}
</pawn>

Вот предыдущий for цикл переписан как while цикл:
<pawn>
SumArray(const array[], count)
{
new total, i;

while (i < count)
{
total += array[i];
i++;
}

return total;
}</pawn>

Существуют также '''do...while''' циклы, которые используются еще реже. Они работают как и while циклы, но проверяют условие ПОСЛЕ каждого цикла, а не перед ним. Это означает, что цикл всегда будет запущен, по крайней мере один раз. Например:

<pawn>
do
{
/* тело */
}
while ( /* условие */ );
</pawn>

==Управление циклами==
Существуют два случая, в которых Мы хотели бы контролировать цикл:
*'''пропустить''' одну итерацию или цикл и продолжить выполнение цикла как обычно, или;
*'''разорвать''' цикл целиком, прежде чем он закончится.

Допустим у вас есть функция, которая принимает массив и ищет соответствия цифр. Вы хотите его остановить, когда число будет найдено:
<pawn>
/**
* Возвращает массив, если индекс значения, или -1, не найдены.
*/
SearchInArray(const array[], count, value)
{
new index = -1;

for (new i = 0; i < count; i++)
{
if (array[i] == value)
{
index = i;
break;
}
}

return index;
}</pawn>

Конечно, эту функцию можно вернуть и способом <tt>return i</tt>, но пример показывает, как <tt>break</tt> может остановить цикл.

Кроме того, ключевое слово <tt>continue</tt> пропускает итерации цикла. Например, Мы хотим суммировать все четные числа:

<pawn>
SumEvenNumbers(const array[], count)
{
new sum;

for (new i = 0; i < count; i++)
{
/* If divisibility by 2 is 1, we know it's odd */
if (array[i] % 2 == 1)
{
/* Пропускаем оставшуюся часть итерации цикла */
continue;
}
sum += array[i];
}

return sum;
}</pawn>

=Scope=
Scope refers to the '''visibility''' of code. That is, code at one level may not be "visible" to code at another level. For example:

<pawn>
new A, B, C;

Function1()
{
new B;

Function2();
}

Function2()
{
new C;
}</pawn>

In this example, <tt>A</tt>, <tt>B</tt>, and <tt>C</tt> exist at '''global scope'''. They can be seen by any function. However, the <tt>B</tt> in <tt>Function1</tt> is not the same variable as the <tt>B</tt> at the global level. Instead, it is at '''local scope''', and is thus a '''local variable'''.

Similarly, <tt>Function1</tt> and <tt>Function2</tt> know nothing about each other's variables.

Not only is the variable private to <tt>Function1</tt>, but it is re-created each time the function is invoked. Imagine this:
<pawn>
Function1()
{
new B;

Function1();
}</pawn>

In the above example, <tt>Function1</tt> calls itself. Of course, this is infinite recursion (a bad thing), but the idea is that each time the function runs, there is a new copy of <tt>B</tt>. When the function ends, <tt>B</tt> is destroyed, and the value is lost.

This property can be simplified by saying that a variable's scope is equal to the nesting level it is in. That is, a variable at global scope is visible globally to all functions. A variable at local scope is visible to all code blocks "beneath" its nesting level. For example:

<pawn>Function1()
{
new A;

if (A)
{
A = 5;
}
}</pawn>

The above code is valid since A's scope extends throughout the function. The following code, however, is not valid:
<pawn>
Function1()
{
new A;

if (A)
{
new B = 5;
}

B = 5;
}</pawn>

Notice that <tt>B</tt> is declared in a new code block. That means <tt>B</tt> is only accessible to that code block (and all sub-blocks nested within). As soon as the code block terminates, <tt>B</tt> is no longer valid.

=Dynamic Arrays=
Dynamic arrays are arrays which don't have a hardcoded size. For example:

<pawn>Function1(size)
{
new array[size];

/* Code */
}</pawn>

Dynamic arrays can have any expression as their size as long as the expression evaluates to a number larger than 0. Like normal arrays, SourcePawn does not know the array size after it is created; you have to save it if you want it later.

Dynamic arrays are only valid at the local scope level, since code cannot exist globally.

=Extended Variable Declarations=
Variables can be declared in more ways than simply <tt>new</tt>.

==decl==
===Purpose===
By default, all variables in Pawn are initialized to zero. If there is an explicit initializer, the variable is initialized to the expression after the <tt>=</tt> token. At a local scope, this can be a run-time expense. The <tt>decl</tt> keyword (which is only valid at local scope) was introduced to let users decide if they want variables initialized or not.

Note: <tt>decl</tt> should not be used on single cell variables. There is almost never any benefit.

===Explanation===
For example:

<pawn>
new c = 5;
new d;
new String:blah[512];

Format(blah, sizeof(blah), "%d %d", c, d);
</pawn>

In this code, <tt>c</tt> is equal to 5 and <tt>d</tt> is equal to 0. The run-time expense of this initialization is negligible. However, <tt>blah</tt> is a large array, and the expense of initializing the entire array to 0s could be detrimental in certain situations.

Note that <tt>blah</tt> does not need to be zeroed. In between being declared with <tt>new</tt> and stored with <tt>Format()</tt>, <tt>blah</tt> is never loaded or read. Thus this code would be more efficiently written as:

<pawn>
new c = 5;
new d;
decl String:blah[512];

Format(blah, sizeof(blah), "%d %d", c, d);
</pawn>

===Caveats===
The downside to <tt>decl</tt> is that it means its variables will start with "garbage" contents. For example, if we were to use:

<pawn>
new c = 5;
new d;
decl String:blah[512];

PrintToServer("%s", blah);

Format(blah, sizeof(blah), "%d %d", c, d);
</pawn>

This code may crash the server, because <tt>blah</tt> may be completely corrupt (strings require a terminator, and that may not be present). Similarly, if we did:

<pawn>
new c = 5;
decl d;
decl String:blah[512];

Format(blah, sizeof(blah), "%d %d", c, d);
</pawn>

The value of <tt>d</tt> is now undefined. It could be any value, negative or positive.

Note that it is easy to efficiently make strings safe. The example below shows how to terminate a garbage string:
<pawn>
decl String:blah[512];

blah[0] = '\0';
</pawn>

===Golden Rules===
*'''Only use decl if in between declaring and loading/reading the value, you are absolutely sure there is at least one store/set operation that gives the variable valid data.'''
*'''Do not prematurely optimize.''' Likewise, there is no need to use <tt>decl</tt> on non-arrays, because there is no added expense for initializing a single cell value.

===Notes===
This example is NOT as efficient as a <tt>decl</tt>:
<pawn>
new String:blah[512] = "a";
</pawn>

Even though the string is only one character, the <tt>new</tt> operator guarantees the rest of the array will be zeroed as well.

Also note, it is invalid to explicitly initialize a <tt>decl</tt>:
<pawn>decl String:blah[512] = "a";</pawn>

The above code will not compile, because the purpose of <tt>decl</tt> is to avoid any initialization.

==static==
The <tt>static</tt> keyword is available at global and local scope. It has different meanings in each.

===Global static===
A global static variable can only be accessed from within the same file. For example:

<pawn>//file1.inc
static Float:g_value1 = 0.15f;

//file2.inc
static Float:g_value2 = 0.15f;</pawn>

If a plugin includes both of these files, it will not be able to use either <tt>g_value1</tt> or <tt>g_value2</tt>. This is a simple information hiding mechanism, and is similar to declaring member variables as <tt>private</tt> in languages like C++, Java, or C#.

===Local static===
A local static variable is a global variable that is only visible from its local lexical scope. For example:

<pawn>
MyFunction(inc)
{
static counter = -1;

counter += inc;

return counter;
}</pawn>

In this example, <tt>counter</tt> is technically a global variable -- it is initialized once to -1 and is never initialized again. It does not exist on the stack. That means each time <tt>MyFunction</tt> runs, the <tt>counter</tt> variable and its storage in memory is the same.

Take this example:
<pawn>MyFunction(5);
MyFunction(6);
MyFunction(10);</pawn>

In this example, <tt>counter</tt> will be <tt>-1 + 5 + 6 + 10</tt>, or <tt>20</tt>, because it persists beyond the frame of the function. Note this may pose problems for recursive functions: if your function may be recursive, then <tt>static</tt> is usually not a good idea unless your code is re-entrant.

The benefit of a local static variable is that you don't have to clutter your script with global variables. As long as the variable doesn't need to be read by another function, you can squirrel it inside the function and its persistence will be guaranteed.

Note that statics can exist in any local scope:

<pawn>
MyFunction(inc)
{
if (inc > 0)
{
static counter;
return (counter += inc);
}
return -1;
}</pawn>

[[Category:Ru:SourceMod Scripting]]

Ru:Introduction to SourcePawn

2008-12-26T10:08:41Z

Frenzzy: /* For Loops */

Это руководство призвано дать Вам самые основные представления по основам написания сприптов в SourcePawn. [[Pawn]] это "скриптовый" язык используемый для внедрения функциональности в других программах. Это означает, что это не самостоятельный язык, как C++ или Java, и его элементы будут отличаться в различных приложениях. SourcePawn это вариация языка Pawn используемая в [[SourceMod]].

Это руководство не расскажет Вам как писать SourceMod плагины; оно предназначено для получения общих представлений о синтаксисе и семантике этого языка. Читайте отдельную статью [[Ru:Introduction to SourceMod Plugins]] (Введение в SourceMod плагины), для введения в SourceMod API.

=Введение для новичков=
Этот раздел создан не для программистов. Если Вы по прежнему в замешательстве, Вы можете прочитать книги о других языках программирования, таких как PHP, Python, или Java, чтобы получить более полное представление о программировании.

==Идентификаторы/Ключевые слова==
Идентификаторы представляет собой набор букв, цифр и/или нижнего подчеркивания, что представляет собой нечто уникальное. Идентификаторы вводятся с учетом регистра (в отличие от PHP, где иногда это не требуется). Идентификаторы не начинаются с какого-либо специального символа, но они должны начинаться с буквы.

Есть несколько зарезервированных символов, которые имеют особое значение. Например, <tt>if</tt>, <tt>for</tt>, и <tt>return</tt> специальные конструкции в языке, которые будут описаны позднее. Они не могут быть использованы в качестве названий идентификаторов.

==Переменные==
Существует несколько важных конструкций, которые Вы должны знать, прежде чем приступить к написанию сценария. Во-первых, это '''переменные'''. Переменная это идентификатор, который содержит данные. Например, переменная "a" может содержать числа "2", "16", "0", и так далее. Переменные создаются для хранения данных внутри программы. Переменные должны быть объявлены до их использования, с помощью ключевого слова "new". Данные можно присвоить переменной, используя знак равенства (=). Пример:

<pawn>new a, b, c, d;

a = 5;
b = 16;
c = 0;
d = 500;</pawn>

В SourcePawn, переменные бывают двух типов, которые будут более подробно описаны далее.
*Однострочные (могут содержать только произвольные числовые данные), как показано выше.
*Многострочные (могут содержать целый ряд текстовых символов)

==Функции==
Следующим важным понятием являются '''функции'''. Функции идентификаторов или имен, которые выполняют действия. Это означает, что когда вы их активируете, они выполняют конкретную последовательность кода. Есть несколько типов функций, но все функции активируется одинаковым образом. "Вызов функции" является термином ссылающимся на функцию действия. Функция числовых переменных строятся так:
<pawn>функция(<параметры>)</pawn>

Примеры:

<pawn>show(56); //Активирует функцию "show" и присваивает ей число 56
show(); //Активирует функцию "show" без каких-либо данных, пустую
show(a); //Активирует функцию "show" и присваивает ей переменную с данными
</pawn>

Каждый фрагмент данных передаваемый вызываемой функции, называется '''параметр'''. Функция может иметь любое количество параметров (но есть "допустимый" предел в SourceMod: 32). Параметры будут описаны далее в этой статье.

==Комментарии==
Примечания и любой текст, который пишется после "//" считается "Комментарием", а не фактическим кодом. Есть два стиля комментариев:
*<tt>//</tt> - Двойная косая черта, всё следующие после этой строки игнорируется.
*<tt>/* */</tt> - Много-строчный комментарий, весь текст, внутри звездочек игнорируются. You cannot nest these.

==Массивы==
Описание массивов. Вы можете группировать код в виде "массивов", разделенных { и }. Это фактически создает возможность работать с целым массивом как с одним оператором. Например:

<pawn>{
here;
is;
some;
code;
}</pawn>

Массивы с фигурными скобками используются достаточно широко в программировании. Массивы кода могут быть вложенными друг в друга. Это хорошая возможность адаптировать последовательность когда и сделать его удобочитаемым, благодаря отступам код не будет смотреться как одна большая и длинная макаронина.

=Особенности языка=
Pawn может показаться очень похожим на другие языки программирования, например C, но Pawn от них фундаментально отличается. Не столь важно, чтобы Вы сейчас же поняли его отличия, но они понадобятся, если Вы уже знаете один из языков программирования.
*'''Pawn не печатает''' Pawn имеет только один тип данных - '''однострочный'''. Подробнее будет описано позже. [В дальнейшем автор рассказывает, что существует два типа данных: однострочный и многострочный]
*'''Pawn не собирает мусор''' Pawn, как язык, не имеет встроенных ресурсов памяти, и потому он не мусорит. Если функция выделит память, то Вы отвечаете за её освобождение.
*'''Pawn не объектно-ориентированный язык''' Pawn является процедурным, и полагается на подпрограммы. Также у него нету C подобных структур.
*'''Pawn не функциональный.''' Pawn является процедурным, и не поддерживает функции "лямбды" (Lambda), поздние присвоения, и все то, что можно найти в языках высшего уровня, таких как Phyton и Ruby.
*'''Pawn однопоточный''' As of this writing, Pawn is not thread safe.
*'''Pawn не интерпретируемый''' Ну, почти. Он интерпретируется на очень низком уровне. Вы должны скомпилировать код, из которого получится бинарный файл. Эта программа будет работать на той платформе, которую использует хост. Это ускоряет загрузку и позволяет легче находить ошибки.

Этот язык был выпущен ITB CompuPhase. Язык разработан для устройств низкого уровня и таким образом конечные программы очень маленькие по размеру и очень быстрые.

=Переменные=
В Pawn есть всего два типа переменных: '''однострочные''' и '''многострочные'''. Однострочные могут содержать 32 бита цифровых данных. Многострочные - последовательный список из UTF-8 символов.

'''однострочные''' не имеет своего типа, однако они могут быть '''маркированы'''(tagged). Тег позволяет Вам указывать, где определенную ячейку можно использовать. Типичные теги:
*(пусто), или '''_''' - Нет тега. Обычно используют для целых чисел ([http://en.wikipedia.org/wiki/Integer Integers]).
*'''Float''' - используют для чисел с плавающей точкой (небольших).
*'''bool''' - используют для хранения значений '''true''' (истина) или '''false''' (ложь).

Со строками все по другому, они будут рассмотрены далее.

==Объявления==
Примеры разных правильных объявлений переменных.
<pawn>
new a = 5;
new Float:b = 5.0;
new bool:c = true;
new bool:d = 0; //Работает, поскольку 0 равно false (ложь)
</pawn>

Неправильные объявления переменных
<pawn>
new a = 5.0; //Несоответствие тегов. 5.0 с тегом Float
new Float:b = 5; //Несоответствие тегов. 5 без тега.
</pawn>

Если переменная не определена в объявлении то ее значения станет 0
<pawn>
new a; //значение 0
new Float:b; //значение 0.0
new bool:c; //значение false
</pawn>

==Присвоение==
Переменным могут быть присвоены данные после создания. Пример:
<pawn>new a, Float:b, bool:c;

a = 5;
b = 5.0;
c = true;
</pawn>

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

==Описание==
Массив объявляется с помощью квадратных скобок. Вот некоторые примеры массивов:
<pawn>
new players[32]; //Набор из 32 однострочных (числовых) данных
new Float:origin[3]; //Набор из 3 чисел с плавающей точкой
</pawn>

По умолчанию, массивам присваиваются нули. Вы можете присвоить им разные значения по умолчанию, однако:
<pawn>
new numbers[5] = {1, 2, 3, 4, 5}; //Набор 1, 2, 3, 4, 5 из однострочных данных.
new Float:origin[3] = {1.0, 2.0, 3.0}; //Набор 1.0, 2.0, 3.0 из однострочных данных.
</pawn>

Вы можете оставить массив без размера, если вы собираетесь заранее присвоить ему данные. Например:
<pawn>
new numbers[] = {1, 3, 5, 7, 9};
</pawn>

Компилятор будет автоматически делать вывод о том, что Вы хотите получить массив размером 5.

==Использование==
Использование массива равносильно использованию обычных переменной. Единственное отличие массива состоит в том, что он должен быть '''индексируемым'''. Индексирование массива означает присутствие возможности выбрать элемент, который Вы хотите использовать.

Вот пример кода с использованием индексов:
<pawn>
new numbers[5], Float:origin[3];

numbers[0] = 1;
numbers[1] = 2;
numbers[2] = 3;
numbers[3] = 4;
numbers[4] = 5;
origin[0] = 1.0;
origin[1] = 2.0;
origin[2] = 3.0;
</pawn>

Заметим, что '''индекс''' это текст, который находится в квадратных скобках. Индекс всегда начинается с нуля. То есть, если массив имеет N элементов, его действительный индекс от 0 до N-1. Доступ к данным с индексами работает так же, как с обычной переменной.

Использование неверного индекса вызовет ошибку. Например:
<pawn>
new numbers[5];

numbers[5] = 20;</pawn>

Это может выглядеть верно, но число 5 не является допустимым индексом. Наибольшим значением индекса является число 4.

Вы можете использовать любые выражения, как индекс. Например:
<pawn>new a, numbers[5];

a = 1; //Сделает a = 1
numbers[a] = 4; //Сделает numbers[1] = 4
numbers[numbers[a]] = 2; //Сделает numbers[4] = 2
</pawn>

Выражения будут обсуждаться подробнее в конце статьи.

=Строки=
Строки являются удобным способом хранения текста. Символы хранятся в массиве. Строка ограничивается '''нулевым символом''', или 0. Без нулевого символа, Pawn не знает, где остановить чтение строки. Все строки в SourcePawn используют кодировку UTF-8.

Отметим, что строки имеют комбинацию из массивов и однострочных переменных. В отличие от других языков, это означает, что Вы должны знать заранее, как много места будут использовать строки. Это означает, что строки не являются динамичными. Они могут лишь вырасти до размера, которым Вы их ограничили.

''Примечание для специалистов: они фактически не однострочные. SourcePawn использует 8-битный строки для хранения массивов в качестве оптимизации. Это и есть то, что делает строки типом, а не меткой.''

==Использование==
Строки были созданы почти в равной степени и для массивов. Например:
<pawn>
new String:message[] = "Hello!";
new String:clams[6] = "Clams";
</pawn>

Это равносильно следующему:
<pawn>
new String:message[7], String:clams[6];

message[0] = 'H';
message[1] = 'e';
message[2] = 'l';
message[3] = 'l';
message[4] = 'o';
message[5] = '!';
message[6] = 0;
clams[0] = 'C';
clams[1] = 'l';
clams[2] = 'a';
clams[3] = 'm';
clams[4] = 's';
clams[5] = 0;
</pawn>

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

Заметим, что строка должна быть заключена в двойных кавычках, а символ в одиночных.

==Символы==
Особенность текста может быть использована в любой строке или однострочной переменной. Например:
<pawn>new String:text[] = "Crab";
new clam;

clam = 'D'; //Устанавливает однострочной переменной значение 'D'
text[0] = 'A'; //Меняет 'C' на 'A', сейчас получилось 'Arab'
clam = text[0]; //Устанавливает однострочной переменной значение 'A'
text[1] = clam; //Меняет 'r' на 'A', сейчас получилось 'AAab'
</pawn>

То, что вы не можете сделать, это соотнести символы массивов со строками. Внутреннее хранение отличается. Например:
<pawn>
new clams[] = "Clams"; //Не верно, нужен тип String:
new clams[] = {'C', 'l', 'a', 'm', 's', 0}; //Верно, но это НЕ СТРОКА.
</pawn>

=Функции=
Функции, как отмечалось ранее, имеют отдельные составляющие кода, которые выполняют определенные действия. Функции могут быть задействованы или '''вызвоны''' с '''параметрами''', которые дают особые настройки.

Существуют два типа вызова функции:
*'''прямой вызов''' - Вы специально вызываете функцию в своем коде.
*'''обратный вызов''' - Применение вызова функций в Вашем коде, как если бы это было событием триггера (совокупность условий, инициирующих выполнение действия).

Существуют пять видов функций:
*'''native''': Прямая, внутренняя функция, предусмотренная в приложении.
*'''public''': Функция обратного вызова, что делает её видимой для приложения и других сценариев.
*'''normal''': Нормальная функция, которую Вы можете только вызвать.
*'''stock''': Нормальная функция, предусмотренная если включает в себя файл. Если не используется, то не компилируется.
*'''forward''': Эта функция представляет собой глобальное событие, предусмотренная приложением. Если Вы её привели в исполнение, она будет вызвона.

Весь код в Pawn должен существовать в функциях. Это основное отличие от языков, таких как PHP, Perl и Python, которые позволяют Вам писать глобальный код. Это происходит потому, что Pawn вызывается на основе другого языка: он реагирует на действия от родительского приложения, и функции должны быть написаны для обработки этих действий. Хотя наш пример, часто содержат свободно плавающий код, это сделано исключительно для демонстрационных целей. Свободно плавающий код в нашем примере означает, что код является частью ряда функций.

==Описание==
В отличие от переменных, функции, не нужно объявлять, прежде чем использовать их. Функции имеют две части, '''модель''' и '''тело'''. Модель содержит имя Вашей функции и параметры, которые она будет принимать. Тело является контейнером для кода.

Пример функции:
<pawn>
AddTwoNumbers(first, second)
{
new sum = first + second;

return sum;
}</pawn>

Это простая функция. Модель этой строки:
<pawn>AddTwoNumbers(first, second)</pawn>

Распишем по отдельности:
*<tt>AddTwoNumbers</tt> - Название функции.
*<tt>first</tt> - Название первого параметра, который представляет собой простой элемент.
*<tt>second</tt> - Название второго параметра, который представляет собой простой элемент.

Тело представляет собой простой блок кода. Он создает новую переменную, названную <tt>sum</tt>, и присваивает ей значение этих двух параметров, добавленных совместно (другие выражения будут позже). Важно заметить оператор <tt>return</tt>, в котором обозначается конец функции и возврат с полученными значениями из этой функции. Все функции ''возвращают значения'' после завершения. Это означает, например:

<pawn>new sum = AddTwoNumbers(4, 5);</pawn>

Приведенный выше код будет присваивать число 9 к sum. Функция получает два значения и передает новое значение sum в качестве '''возвращаемого значения'''. Если функция не имеет возвращаемого значения или не имеет значений для возврата, то возвращается 0 по умолчанию.

Функция может принимать любые типы значений. Она может вернуть любую однострочную переменную, но не массивы или строки. Пример:
<pawn>Float:AddTwoFloats(Float:a, Float:b)
{
new Float:sum = a + b;

return sum;
}</pawn>

''Заметим, что если в приведенной выше функции, Вам вернулась не Float значение, Вы получите не соответствие значений.''

Можно, конечно, передавать переменные в функции:
<pawn>new numbers[3] = {1, 2, 0};

numbers[2] = AddTwoNumbers(numbers[0], numbers[1]);</pawn>

Заметим, что однострочные переменные передаются '''по значению'''. То есть, их значение не может быть изменено функцией. Например:
<pawn>new a = 5;

ChangeValue(a);

ChangeValue(b)
{
b = 5;
}</pawn>

Этот код не будет менять значение <tt>a</tt>. Это происходит потому, что копия этого значения в <tt>a</tt> передается вместо <tt>a</tt> самостоятельно.

Больше примеров функций будут демонстрироваться и в других частях статьи.

==Publics==
Публичные функции используются для осуществления обратных вызовов. Вы не должны создавать какую-либо публичную функцию, если это вынудит выполнение обратного вызова. Например, вот два обратных вызова из <tt>sourcemod.inc</tt>:

<pawn>forward OnPluginStart();
forward OnClientDisconnected(client);</pawn>

Чтобы выполнить и получить эти два события, Вы должны написать такие функции как:

<pawn>public OnPluginStart()
{
/* Код здесь */
}

public OnClientDisconnected(client)
{
/* Код здесь */
}</pawn>

Ключевое слово '''public''' делает функцию публичной, а также позволяет родительскому приложению непосредственно вызывать функцию.

==Natives==
Natives имеют встроенные функции, предоставляемые приложением. Вы можете вызвать их, как если бы они были normal функциями. Например, SourceMod имеет следующие функции:

<pawn>native FloatRound(Float:num);</pawn>

Её можно вызвать таким образом:
<pawn>new num = FloatRound(5.2); //Результат в num = 5</pawn>

==Параметры массива==
Вы можете передавать массивы или строки в качестве параметров. Важно отметить, что они идут '''как ссылка'''. То есть не делать копию данных, а отдавать непосредственно ссылки на данные. Существует простой способ объяснить это более конкретно.

<pawn>
new example[] = {1, 2, 3, 4, 5};

ChangeArray(example, 2, 29);

ChangeArray(array[], index, value)
{
array[index] = value;
}</pawn>

Эта функция устанавливает заданный индекс в массиве с учетом значений. Когда она запускается на примере нашего массива, она меняет индекс 2 для значения 3 на 29. То есть:
<pawn>example[2] = 29;</pawn>

Это возможно лишь потому, что массив может быть непосредственно изменён. Чтобы предотвратить массив от изменения, можно пометить его как постоянную <tt>const</tt>. Это позволит понизить риск на ошибку в коде от её изменения. Например:

<pawn>CantChangeArray(const array[], index, value)
{
array[index] = value; //Не компилируется
}</pawn>

Это хорошая идея использовать <tt>const</tt> в параметрах массивов и Вы будете точно знать, что массив не будет изменен; это может предотвратить ошибки кодирования.

=Выражения=
Выражения являются точно такими же, какими они существуют в математике. Это группы операторов/символов, которые приходятся на один фрагмент данных. Они часто заключены в скобках (внутри скобок). Они содержат строгий "порядок операций". Они могут содержать переменные, функции, цифры и выражения сами могут быть вложенные внутрь других выражений, и даже приняты в качестве параметров.

Приведем пример простейшего выражения:
<pawn>
0; //Возвращает число 0
(0); //Так же возвращает число 0
</pawn>

Хотя выражения могут возвращать значения, они также могут ответить какое значение содержит ответ ''ноль или не ноль''. В этом смысле, ''ноль'' является ''ложью'' (false), а ''не нулевое'' значение ''истиной'' (true). Например, -1 ''истина'' в Pawn, поскольку она не является нулем. Не думайте, что отрицательные числа являются ложными.

Порядок операций выражения аналогичен языку C. PMDAS: Parenthesis, Multiplication, Division, Addition, Subtraction. Вот несколько примеров выражений:
<pawn>
5 + 6; //Вычисляет как 11
5 * 6 + 3; //Вычисляет как 33
5 * (6 + 3); //Вычисляет как 45
5.0 + 2.3; //Вычисляет как 7.3
(5 * 6) % 7; //Modulo operator, вычисляет как 2
(5 + 3) / 2 * 4 - 9; //Вычисляет как 7
</pawn>

Как уже отмечалось, выражения могут содержать переменные, или даже функции:
<pawn>
new a = 5 * 6;
new b = a * 3; //Вычисляет как 90
new c = AddTwoNumbers(a, b) + (a * b);
</pawn>

==Операторы==
Есть несколько полезных дополнительных операторов в Pawn. Первый набор упрощает аутоагрегацию выражения. Например:
<pawn>new a = 5;

a = a + 5;</pawn>

Может быть переписан, как:
<pawn>new a = 5;
a += 5;</pawn>

Это верно в отношении следующих операторов в Pawn:
*Four-function: *, /, -, +
*Bit-wise: |, &, ^, ~, <<, >>

Кроме того, существуют инкремент/декремент операторы:
<pawn>a = a + 1;
a = a - 1;</pawn>

Может быть упрощено, как:
<pawn>a++;
a--;</pawn>

Дополнительно отметим, что ++ или -- может быть представлен до переменной (до-инкремент, до-декремент) или после переменной (пост-инкремент, пост-декремент). Разница заключается в том, как остальная часть выражения содержащие их, видит результат.

* ''До:'' Переменная увеличивается до определения и остальная часть выражения видит новое значение.
* ''Пост:'' Переменная увеличивается после определения и остальная часть выражения видит старое значение.

Иными словами, <tt>a++</tt> определяет значение как <tt>a</tt> в то время как <tt>++a</tt> определяет значение как <tt>a + 1</tt>. В обоих случаях <tt>a</tt> увеличивается на <tt>1</tt>.

Например:

<pawn>new a = 5;
new b = a++; // b = 5, a = 6 (1)
new c = ++a; // a = 7, c = 7 (2)
</pawn>

(1) <tt>b</tt> присваивается <tt>a</tt> со ''старым'' значением, ''до'' того, как он будет увеличено до <tt>6</tt>. (2) <tt>c</tt> присваивается <tt>a</tt> с ''новым'' значением, ''после'' того, как он увеличивается до <tt>7</tt>.

==Операторы сравнения==
Существуют шесть операторов для сравнения двух числовых значений, а результат является либо истиной (не ноль) или ложью (ноль):
*<tt>a == b</tt> - Действительно, если и b имеет то же значение.
*<tt>a != b</tt> - Действительно, если b имеет другое значение.
*<tt>a > b</tt> - Действительно, если оно больше b
*<tt>a >= b</tt> - Действительно, если оно больше или равно b
*<tt>a < b</tt> - Действительно, если оно меньше b
*<tt>a <= b</tt> - Действительно, если оно меньше или равно b

Например:
<pawn>
(1 != 3); //Определяется как истина, поскольку 1 не равно 3.
(3 + 3 == 6); //Определяется как истина, поскольку 3+3 равно 6.
(5 - 2 >= 4); //Определяется как ложь, поскольку 3 меньше 4.
</pawn>

Заметим, что эти операторы не работают с массивами и строками. То есть, вы не можете сравнить их с помощью <tt>==</tt>.

==Действительные операторы==
Действительные операторы могут быть скомбинированы тремя булевыми (boolean) операторами:
*<tt>a && b</tt> - Истина, если a и b истинные. Ложь, если a и (или) b ложные.
{| border="1" cellpadding="2" cellspacing="0" align="center"
! <tt>&&</tt> !! 0 !! 1
|-
! 0
| 0 || 0
|-
! 1
| 0 || 1
|}
*<tt>a || b</tt> - Истина, если a или b (или обе переменные) истинные. Ложь, если обе переменные a и b ложные.
{| border="1" cellpadding="2" cellspacing="0" align="center"
! <tt><nowiki>||</nowiki></tt> !! 0 !! 1
|-
! 0
| 0 || 1
|-
! 1
| 1 || 1
|}
*<tt>!a</tt> - Истина, если a ложь. Ложь, если a истина.
{| border="1" cellpadding="2" cellspacing="0" align="center"
! <tt>!</tt> !! 0 !! 1
|-
!
| 1 || 0
|}

Например:
<pawn>
(1 || 0); //Определяется как истина, так как выражение 1 истинное
(1 && 0); //Определяется как ложь, так как выражение 0 ложное
(!1 || 0); //Определяется как ложь, так как выражение !1 ложное.
</pawn>

==Левое/правое значения==
Два важных понятия левого и правого значений, или левостороннее и правостороннее значения. Левостороннее значение имеет то, что появляется на левой стороне выражения, а правостороннее значение - появляется на правой стороне выражения.

Например:
<pawn>
new a = 5;</pawn>

В этом примере <tt>a</tt> является левосторонним значением и <tt>5</tt> является правосторонним значением.

Правила:
*'''Выражения никогда не будут левосторонними значениями'''.
*'''Переменные являются двумя, левосторонними и правосторонними значениями'''.

=Условия=
Условия позволяют Вам запускать код, определенное условие выполнено.

==Если соответствует==
Если соответствует одно или более условий. Например:

<pawn>
if (a == 5)
{
/* Код будет запущен, если условие будет истинным */
}</pawn>

Они могут быть расширены для более сложных случаев:
<pawn>
if (a == 5)
{
/* Код */
}
else if (a == 6)
{
/* Код */
}
else if (a == 7)
{
/* Код */
}</pawn>

Вы так же можете обрабатывать случаи, даже если выражение не верно. Например:
<pawn>
if (a == 5)
{
/* Код */
}
else
{
/* Код, который будет запущен если нет истинного выражения */
}</pawn>

==Ключ соответствия==
Ключ соответствия будет ограничен условием. Он необходим для выражения, выполняющего код для целого ряда возможных значений. Например:

<pawn>
switch (a)
{
case 5:
{
/* Код */
}
case 6:
{
/* Код */
}
case 7:
{
/* Код */
}
case 8, 9, 10:
{
/* Код */
}
default:
{
/* будет запущен, если не одно условие не соответствует */
}
}</pawn>

В отличие от некоторых других языков, ключи не терпят неудачи. То есть существуют случаи, когда код не будет запущен. При случае совпадения его код выполняется, а ключ является местом для немедленного прекращения.

=Циклы=
Циклы позволяют Вам без труда повторять выполнение кода, пока условие станет истинным.

==For циклы==
For циклы, это циклы, которые состоят из четырех частей:
*Оператор '''инициализации''' - запускается один раз перед первым циклом.
*Оператор '''условия''' - проверяет условие и запускает следующий цикл, в том числе первый. Цикл прекращается, когда это выражение становится ложным.
*Оператор '''итерации''' - запускается после каждого цикла.
* '''тело''' цикла - запускается каждый раз, пока оператор '''условия''' вычисляется как истинный.

<pawn>
for ( /* инициализация */ ; /* условие */ ; /* итерация */ )
{
/* тело */
}
</pawn>

Простым примером является функция сложения массива:
<pawn>
new array[10] = {1, 2, 3, 4, 5, 6, 7, 8, 9, 10};
new sum = SumArray(array, 10);

SumArray(const array[], count)
{
new total;

for (new i = 0; i < count; i++)
{
total += array[i];
}

return total;
}</pawn>

По отдельности:
*<tt>new i = 0</tt> - Создает новую переменную для цикла, и устанавливает её в 0.
*<tt>i < count</tt> - Только запускает цикл, если <tt>i</tt> меньше, чем <tt>count</tt>. Это гарантирует, что чтение цикла прекращается в определенный момент. В этом случае, мы не хотим читать недействительные индексы в массиве.
*<tt>i++</tt> - Увеличивает <tt>i</tt> на единицу после каждого цикла. Это гарантирует, что цикл не будет запущен вечно; в конце концов <tt>i</tt> станет слишком большим, и цикл завершится.

Таким образом, функция <tt>SumArray</tt> будет циклом каждого действительного индекса массива, каждый раз добавляя это значение в sum. Для циклов очень распространены массивы такие, как в нашем примере.

==While Loops==
While Loops являются менее распространенными, чем for loops, но на самом деле это более простые циклы. Они имеют только две части:
*Оператор '''условия''' - проверяется перед началом каждого цикла. Цикл прекращается, когда условие становится ложным.
*'''тело''' цикла - запускается каждый раз пока цикл выполняется.

<pawn>
while ( /* условие */ )
{
/* тело */
}
</pawn>

До тех пор, пока условие выражения остается истинным, цикл будет выполняться. Каждый for loop может быть переписан, как while loop:

<pawn>
/* инициализация */
while ( /* условие */ )
{
/* тело */
/* итерация */
}
</pawn>

Вот предыдущий for loop переписан как while loop:
<pawn>
SumArray(const array[], count)
{
new total, i;

while (i < count)
{
total += array[i];
i++;
}

return total;
}</pawn>

Существуют также '''do...while''' циклы, которые используются еще реже. Они работают как и while loops, но проверяют условие ПОСЛЕ каждого цикла, а не перед ним. Это означает, что цикл всегда будет запущен, по крайней мере один раз. Например:

<pawn>
do
{
/* тело */
}
while ( /* условие */ );
</pawn>

==Управление циклами==
Существуют два случая, в которых Мы хотели бы контролировать цикл:
*'''пропустить''' одну итерацию или цикл и продолжить выполнение цикла как обычно, или;
*'''разорвать''' цикл целиком, прежде чем он закончится.

Допустим у вас есть функция, которая принимает массив и ищет соответствия цифр. Вы хотите его остановить, когда число будет найдено:
<pawn>
/**
* Возвращает массив, если индекс значения, или -1, не найдены.
*/
SearchInArray(const array[], count, value)
{
new index = -1;

for (new i = 0; i < count; i++)
{
if (array[i] == value)
{
index = i;
break;
}
}

return index;
}</pawn>

Конечно, эту функцию можно вернуть и способом <tt>return i</tt>, но пример показывает, как <tt>break</tt> может остановить цикл.

Кроме того, ключевое слово <tt>continue</tt> пропускает итерации цикла. Например, Мы хотим суммировать все четные числа:

<pawn>
SumEvenNumbers(const array[], count)
{
new sum;

for (new i = 0; i < count; i++)
{
/* If divisibility by 2 is 1, we know it's odd */
if (array[i] % 2 == 1)
{
/* Пропускаем оставшуюся часть итерации цикла */
continue;
}
sum += array[i];
}

return sum;
}</pawn>

=Scope=
Scope refers to the '''visibility''' of code. That is, code at one level may not be "visible" to code at another level. For example:

<pawn>
new A, B, C;

Function1()
{
new B;

Function2();
}

Function2()
{
new C;
}</pawn>

In this example, <tt>A</tt>, <tt>B</tt>, and <tt>C</tt> exist at '''global scope'''. They can be seen by any function. However, the <tt>B</tt> in <tt>Function1</tt> is not the same variable as the <tt>B</tt> at the global level. Instead, it is at '''local scope''', and is thus a '''local variable'''.

Similarly, <tt>Function1</tt> and <tt>Function2</tt> know nothing about each other's variables.

Not only is the variable private to <tt>Function1</tt>, but it is re-created each time the function is invoked. Imagine this:
<pawn>
Function1()
{
new B;

Function1();
}</pawn>

In the above example, <tt>Function1</tt> calls itself. Of course, this is infinite recursion (a bad thing), but the idea is that each time the function runs, there is a new copy of <tt>B</tt>. When the function ends, <tt>B</tt> is destroyed, and the value is lost.

This property can be simplified by saying that a variable's scope is equal to the nesting level it is in. That is, a variable at global scope is visible globally to all functions. A variable at local scope is visible to all code blocks "beneath" its nesting level. For example:

<pawn>Function1()
{
new A;

if (A)
{
A = 5;
}
}</pawn>

The above code is valid since A's scope extends throughout the function. The following code, however, is not valid:
<pawn>
Function1()
{
new A;

if (A)
{
new B = 5;
}

B = 5;
}</pawn>

Notice that <tt>B</tt> is declared in a new code block. That means <tt>B</tt> is only accessible to that code block (and all sub-blocks nested within). As soon as the code block terminates, <tt>B</tt> is no longer valid.

=Dynamic Arrays=
Dynamic arrays are arrays which don't have a hardcoded size. For example:

<pawn>Function1(size)
{
new array[size];

/* Code */
}</pawn>

Dynamic arrays can have any expression as their size as long as the expression evaluates to a number larger than 0. Like normal arrays, SourcePawn does not know the array size after it is created; you have to save it if you want it later.

Dynamic arrays are only valid at the local scope level, since code cannot exist globally.

=Extended Variable Declarations=
Variables can be declared in more ways than simply <tt>new</tt>.

==decl==
===Purpose===
By default, all variables in Pawn are initialized to zero. If there is an explicit initializer, the variable is initialized to the expression after the <tt>=</tt> token. At a local scope, this can be a run-time expense. The <tt>decl</tt> keyword (which is only valid at local scope) was introduced to let users decide if they want variables initialized or not.

Note: <tt>decl</tt> should not be used on single cell variables. There is almost never any benefit.

===Explanation===
For example:

<pawn>
new c = 5;
new d;
new String:blah[512];

Format(blah, sizeof(blah), "%d %d", c, d);
</pawn>

In this code, <tt>c</tt> is equal to 5 and <tt>d</tt> is equal to 0. The run-time expense of this initialization is negligible. However, <tt>blah</tt> is a large array, and the expense of initializing the entire array to 0s could be detrimental in certain situations.

Note that <tt>blah</tt> does not need to be zeroed. In between being declared with <tt>new</tt> and stored with <tt>Format()</tt>, <tt>blah</tt> is never loaded or read. Thus this code would be more efficiently written as:

<pawn>
new c = 5;
new d;
decl String:blah[512];

Format(blah, sizeof(blah), "%d %d", c, d);
</pawn>

===Caveats===
The downside to <tt>decl</tt> is that it means its variables will start with "garbage" contents. For example, if we were to use:

<pawn>
new c = 5;
new d;
decl String:blah[512];

PrintToServer("%s", blah);

Format(blah, sizeof(blah), "%d %d", c, d);
</pawn>

This code may crash the server, because <tt>blah</tt> may be completely corrupt (strings require a terminator, and that may not be present). Similarly, if we did:

<pawn>
new c = 5;
decl d;
decl String:blah[512];

Format(blah, sizeof(blah), "%d %d", c, d);
</pawn>

The value of <tt>d</tt> is now undefined. It could be any value, negative or positive.

Note that it is easy to efficiently make strings safe. The example below shows how to terminate a garbage string:
<pawn>
decl String:blah[512];

blah[0] = '\0';
</pawn>

===Golden Rules===
*'''Only use decl if in between declaring and loading/reading the value, you are absolutely sure there is at least one store/set operation that gives the variable valid data.'''
*'''Do not prematurely optimize.''' Likewise, there is no need to use <tt>decl</tt> on non-arrays, because there is no added expense for initializing a single cell value.

===Notes===
This example is NOT as efficient as a <tt>decl</tt>:
<pawn>
new String:blah[512] = "a";
</pawn>

Even though the string is only one character, the <tt>new</tt> operator guarantees the rest of the array will be zeroed as well.

Also note, it is invalid to explicitly initialize a <tt>decl</tt>:
<pawn>decl String:blah[512] = "a";</pawn>

The above code will not compile, because the purpose of <tt>decl</tt> is to avoid any initialization.

==static==
The <tt>static</tt> keyword is available at global and local scope. It has different meanings in each.

===Global static===
A global static variable can only be accessed from within the same file. For example:

<pawn>//file1.inc
static Float:g_value1 = 0.15f;

//file2.inc
static Float:g_value2 = 0.15f;</pawn>

If a plugin includes both of these files, it will not be able to use either <tt>g_value1</tt> or <tt>g_value2</tt>. This is a simple information hiding mechanism, and is similar to declaring member variables as <tt>private</tt> in languages like C++, Java, or C#.

===Local static===
A local static variable is a global variable that is only visible from its local lexical scope. For example:

<pawn>
MyFunction(inc)
{
static counter = -1;

counter += inc;

return counter;
}</pawn>

In this example, <tt>counter</tt> is technically a global variable -- it is initialized once to -1 and is never initialized again. It does not exist on the stack. That means each time <tt>MyFunction</tt> runs, the <tt>counter</tt> variable and its storage in memory is the same.

Take this example:
<pawn>MyFunction(5);
MyFunction(6);
MyFunction(10);</pawn>

In this example, <tt>counter</tt> will be <tt>-1 + 5 + 6 + 10</tt>, or <tt>20</tt>, because it persists beyond the frame of the function. Note this may pose problems for recursive functions: if your function may be recursive, then <tt>static</tt> is usually not a good idea unless your code is re-entrant.

The benefit of a local static variable is that you don't have to clutter your script with global variables. As long as the variable doesn't need to be read by another function, you can squirrel it inside the function and its persistence will be guaranteed.

Note that statics can exist in any local scope:

<pawn>
MyFunction(inc)
{
if (inc > 0)
{
static counter;
return (counter += inc);
}
return -1;
}</pawn>

[[Category:Ru:SourceMod Scripting]]