От переводчика: старался перевести как есть, но тем не менее это довольно вольный перевод. Суть статьи, её смысл оставлен тем же. Так что думаю проблем с пониманием возникнуть не должно.
Окей, фактически никто никогда не писал обучающих пособий по написанию плагинов. У многих (в том числе и у меня) было много проблем из-за этого. Я "брошу первый камень" и посмотрю, выйдет ли что-либо полезное. Если что-то выйдет, можно будет продолжить.
Писать плагины на языке Small достаточно легко, и после нескольких уроков, вероятно, вы сможете написать свой собственный плагин к AMX. Поэтому, думаю, я не должен писать излишне многое до тех пор пока вы сами не начнёте самостоятельно думать как же написать плагин (код).
Конечно, если вы писали раньше программы, это сильно поможет. Но я думаю язык Small – хорошее начало для новичка. Я надеюсь, вы имеете некоторые ключевые понятия в языках программирования. Если не понимаете что такое переменные и функции, то вы должны пойти и найти информацию по этим вопросам. Я не буду вам этого объяснять. Однако не пугайтесь. Я думаю, из моих уроков вы сможете понять, что к чему.
Я писал этот плагин под мод HL - Counter- Strike. Так что примите это к сведению. Но, думаю, всё сказанное здесь будет полезным для написания скриптов к другим модам HL.
030613
Урок 1
Ваш первый плагин
*****************
Давайте начнем с простого: вывод сообщений на экран. Придумаем команду, которая это будет делать: amx_ helloworld, amx_ hello или даже hello. Надо что бы админ смог, когда захочет, вписать соответствующую команду и на экран выводилось соответствующая надпись: hello world, hello или даже " Privet, 4 itaki"( ;) ).
Прежде чем начать я хочу сказать несколько слов о том, что нужно для написания скриптов:
Вам нужен редактор текста. Блокнот ( notepad) – это хорошо, но worldpad лучше. Когда вы освоитесь можно переходить на более удобные редакторы. Мы доберёмся до них в более поздних уроках.
У вас должен быть установлен AMXMod и соответственно должен быть сервер на котором он стоит. Я не буду объяснять вам как устанавливать и настраивать AMXMod на сервере, так как это очень хорошо описано в документации к AMXMod'у.
Проверьте наличие файла sc.exe и sc. bat, они идут вместе с AMXMod.
Всё проверили? Поехали!
Создайте новый файл и назовите его helloworld. sma. Начинаем с секции "комментарий", в самом начале файла helloworld. sma. Секция комментарий – часть кода, не являясь кодом. Это всего на всего комментарий. Обычно здесь указывают название плагина, его версию. Позже можно более детально описать работу вашего плагина, его установку и т.д. Но пока начнём с малого:/*
Hello world, v0.1
By JGHG
*/
Я всегда начинаю нумерацию версии плагина с 0.1. На самом деле не имеет значения с какой версии начать, но не начинайте с версии 1.0. Всегда нано начинать с меньшей версии. А когда вы пойметё, что ваш плагин уже готов к финалу, тогда вам и карты в руки. Так или иначе это всего на всего комментарий. Тут вы можете расписать весь ваш день, по минутам, как дневник. Это не будет критично, т.к. компилятор не будет читать эти строки. Но наличие названия плагина, версии и автора логично поместить здесь.
Любой плагин должен иметь функцию plugin_ init(). Всё то, что вставлено в эту данную функцию будет регистрироваться в AMX, что бы он мог использовать ваш плагин:public plugin_init() {
register_plugin("Hello world","0.1","jghg")
}
Это сделает ваш плагин зарегистрированным. plugin_ init() берёт три параметра из плагина: это его название ( Hello world), его версию (0.1) и автора ( jghg). Старайтесь не терять кавычек, иначе работать не будет.
Но этого не достаточно, для нашей цели. Должна быть команда которую админ сможет использовать и для этого мы должны её зарегистрировать в plugin_ init() функции. Команды, которые вводятся в консоле сервера или от клиента должны быть в нутрии plugin_ init() для того, что бы ею могли пользоваться. plugin_ init() важен по многим другим причинам, о которых вы узнаете из более поздних уроках. Функция plugin_ init() это как сообщение для AMXMod, что существкет ваш плагин, и в случае чего (введение команды) юзать его.register_clcmd("amx_helloworld","myfunction",ADMIN_VOTE," : prints Hello world!!! to everyone")
Допишите данную строку в секцию функции plugin_ init(). С помощью этой строки мы регистрируем команду, которую будем в последствии использовать. Первый параметр в кавычках - это команда, которую мы будет вбивать в консоле. Следующий параметр в кавычках – это функция в нашем плагине, когда команда будет введена будет выполнена данная функция. Эту функцию мы напишем позже. На самом деле назвать можно как угодно. Название не должно быть очень большим, тогда данное название не подходит ( ;) ). Назвал её так для простоты и непринужденности прочтения текста. Следующий параметр – уровень доступа. Т.е. кто на сервере имеет права для выполнения данной команды. В данном случае админ ( ADMIN _ VOTE ). Зачем простым игрокам разводить флуд ( ;) ). Но можно сделать доступ всем: надо указать 0 вместо ADMIN _ VOTE. Замете кавычек нет! Таким образом командой могут пользоваться админы с уровнем доступа к голосованию ( vote). И последний параметр – это комментарий. Он будет отображен когда вы введёте amx_ help. НЕ ТЕРЯЙТЕ КАВЫЧЕК!!!
Таким образом функция plugin_ init() выглядит так:public plugin_init() {
register_plugin("Hello world","0.1","jghg")
register_clcmd("amx_helloworld","myfunction",ADMIN_VOTE," : says Hello world!!! to game screen")
}
Держите отступы, т.е. используйте " tab" или, к примеру, пробелы в написании функций. Откройте любой . sma файл, поставляемый вместе с AMX, и вы поймёте, о чем я говорю. Это упростит компиляцию и плагин будет откомпилирован более качественно. Так же это упростит изучение вашего плагина других разработчиков. Куда проще разбираться в структурированном коде, чем в бардаке :) . Есть ещё серьёзные основания, но сейчас я не буду в них вдаваться.
Добавьте данные строки. Они должны обязательно присутствовать в плагине:#include <amxmod>
#include <amxmisc>
Данные строки помещаются сразу после комментариев и перед plugin_ init() функцией. Некоторый (это не про меня) помещают plugin_ init() как последняя функция плагина. Но, по крайней мере, я всегда могу быстро найти свою функцию и думаю так удобнее делать.
Мы уже довольно много написали. Должно быть, похоже вот на это:/*
Hello world, v0.1
By JGHG
*/
#include <amxmod>
#include <amxmisc>
public plugin_init() {
register_plugin("Hello world","0.1","jghg")
register_clcmd("amx_helloworld","myfunction",ADMIN_VOTE," : says Hello world!!! to game screen")
}
Всегда сохраняйте написанное. Кто знает когда отключат электричество :) . Попробуйте откомпилировать данный плагин. Если есть ошибки, то их проще найти сейчас, чем потом ковырять груду кода. Это значительно упрощает поиск ошибок.
Сохраните плагин и запустите sc. bat. sc. bat – это командный файл, который осуществляет поиск всех sma-файлов в директории source. Компилирует и складывает в директории compiled с расширением . amx. Если вы хотите откомпилировать только свой плагин, то нужно запустить sc. exe с параметром равный названию файла в котором сохранён плагин ( sc. exe helloworld. sma). Файл с расширением .amx будет сохранен в текущем каталоге.
Если что-то не так при компиляции проверьте правильность написания плагина.
Нам осталось написать последнюю функцию – вывод сообщения на экран. Мы зарегистрировали команду которая будет выполнятся в консоли, сообщение выводимое на экран тоже зарегистрировали. Теперь осталось создать функцию которая будет всё это делать:public myfunction(id,level,cid) {
if (!cmd_access(id,level,cid,1)) {
return PLUGIN_HANDLED
}
}
Я не буду расписывать как работает функция cmd_ access(). Скажу только, что она проверяет может ли клиент использовать данную команду.
Хочу прокомментировать следующее – id. Id – это уникальный номер каждого присутствующего на сервере. Оно будет ему присвоено при входе и отобрано при выходе. Это уникальный номер каждого играющего, одинаковых быть не может. Если сервер рассчитан на 32 игрока, то id будет от 1 до 32. Движок Half- Life более 32 игроков не держит. Если сервер рассчитан на 16, то от 1 до 16.
Id используется по разному. В cmd_ access() через id проверяется уровень доступа этого текучего пользователя, и никого другого. Надеюсь это понятно.
Следующая линия кода: client_print(0,print_center,"Hello world!!!")
Это та строчка кода, которая отвечает за печатание сообщения у клиента. с lient_ print является названием функции, которая берёт три параметра (может требоваться больше, но об этом в других уроках). Первый параметр (0) отвечает за то кому будет выведена данная команда. Если поставить id номер игрока, то сообщение будет выведено ему и вам. В данном случае выведено будет для всех присутствующих на сервере (живым или мертвым). Т.е. когда вам надо сделать со всеми что-то или сообщить всем что-то надо использовать 0. Второй параметр указывает где следует выводить сообщение. Можно поместить сообщение в районе чата - print_ chat или print_ notify – отображает только в консоле. И третий параметр – само сообщение. То, что в пределах кавычек то и есть сообщение, которое будет печататься на экран. Не теряйте кавычек.
Мы почти написали наш первый плагин. Осталось только дописать следующую строчку в функцию myfunction():return PLUGIN_HANDLED
Это важная строчка. Её терять нельзя. Помните, это последнее что вы должны добавить во всех ваших функциях, которые вызываются командами, напечатанные в консоле сервера или в консоле клиента. Если вы этого не сделаете, то AMX не будет знать, что команда выполнена, выведет сообщение на экран, а в консоле появится следующая ошибка: Unknown command: amx_helloworld
Поэтому всегда заканчивайте функцию return PLUGIN_HANDLED.
Полностью наш плагин выглядит так:/*
Hello world, v0.1
By JGHG
*/
#include <amxmod>
#include <amxmisc>
public myfunction(id,level,cid) {
if (!cmd_access(id,level,cid,1)) {
return PLUGIN_HANDLED
}
client_print(0,print_center,"Hello world!!!")
return PLUGIN_HANDLED
}
public plugin_init() {
register_plugin("Hello world","0.1","jghg")
register_clcmd("amx_helloworld","myfunction",ADMIN_VOTE," : prints Hello world!!! to everyone")
}
Всё, плагин готов. Откомпилируйте его и убедитесь, что нет ошибок во время компиляции. Если при компиляции вы получаете сообщение warning 217: loose indentation, перейдите на указанную строчку и проследите что бы углубление (" tab" – помните…) было одинаково везде в вашем плагине.
Тперь можете поместить файл helloworld. amx в папку amx\ plugins и прописать плагин в amx\ config\ plugins. ini. Добавьте строчку helloworld. amx в самый конец списка плагинов. Теперь запускайте сервер. Если сервер запущен можно в консоле сервера использовать команду restart. Вместе с рестартом карты произойдет пересчитывание плагинов и новый добавленный плагин будет использован AMX.
Теперь заходите в игру и пропишите amx_ helloworld и убедитесь что всё отображается как надо. Удостоверьтесь, что при вводе команды amx_ help описание соответствует тому, что использовали мы. Если плагин не работает, в консоле сервера введите amx plugins и убедитесь, что плагин загружен. Возможно вы забыли прописать себя админом ;)
Пока всё. Экспериментируйте с плагином. Усваивайте материал, пока мы не пересечёмся в следующем уроке.
