ГАЙД по Macro plugin

[4epT]

САМЫЙ СВЕЖИЙ МАНУАЛ НА РУССКОМ

Этот гайд для макропланига версии 1.3.5 (это примерно кора версии не позже 1.9.4)

Щас есть макро плагин 2.0.1 (он для коры версии выше 2.0.0) В этой версии удалили некоторые опции(отладку), так что можно пользоваться этим гайдом.
Гайд для макро плагина версии 2.0.1 находится тут

1. Что такое macro плагин?
2. Установка macro плагина
3. Настройка файлов
4. Команды
5. Синтаксис макроса
6. Переменные
   • 6.1 Собственные переменные
   • 6.2 Специальные переменные
   • 6.3 Вложенные переменные
7. Операторы макроса
8. Условия
9. Специальные операторы
10. Формирование "цепочки команд"
11. Пример макроса
12. Синтаксис автомакроса
    • Часть 1
    • Часть 2
13. Пример автомакроса
14. Отладка
15. Ограничения
16. Специальная переменная $.lastMatchN и регулярные выражения (regexp)

Оригинал мануала, также есть и на русском
Форум по обсуждению макросов (на англ.)
Сборник макросов

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

[4epT]

1. Что такое macro плагин?

С этим плагином Вы сможете написать последовательность команд (макросов), которые бот будет выполнять вручную или в зависимости от ситуации (условия). Последняя версия - 1.3.5.

[4epT]

2. Установка macro плагина

Отмечу, что на нашем сайте плагин macro уже добавлен в OpenKore. Как и на многих других сайтах.

Скачайте macro plugin 1.3.5.
Переместитесь в папку с ботом (думаю не надо объяснять что это).
В это папке создайте новую папку plugins (если она ещё не создана).
Из скаченного zip-файла извлеките файлы macro.pl и cvsdebug.pm, а также папку (со в сем содержимым) macro в папку plugins.
В папке control создайте новый файл macros.txt (если он ещё не создан). В это файл Вы будете писать свои макросы или автомакросы.
Так должно выглядеть дерево каталогов Вашего бота (исключая файлы самого OpenKorа):

OPENCORE
|-- openkore.pl
|-- CONTROL
| `-- macros.txt
|-- FIELDS
|-- LOGS
|-- PLUGINS
| |-- MACRO
| | |-- Automacro.pm
| | |-- Data.pm
| | |-- Parser.pm
| | |-- Script.pm
| | `-- Utilities.pm
| |-- macro.pl
| `-- cvsdebug.pm
|-- SCR
`-- TABLES

[4epT]

3. Настройка файлов

control/macros.txt

В этот файл вписываются сами макросы или автомакросы.
Внимание: если у вас в этом файле содержится русский текст, то файл необходимо сохранить в кодировке utf-8 и закомментировать 1 строчку знаком #.

Пример макроса, включающего команду "@autoloot 100" при заходе в игру:

###@autoloot 100###
automacro loot {
console /You are now in the game/
delay 4
call lootM
}
macro lootM {
do c @autoloot 100
}

control/timeouts.txt

В это файл добавьте строчку:
macro_delay <n>
<n> - пауза в секундах, которую плагин будет делать между командами.

Пример:

###macros###
macro_delay 1

control/config.txt

В это файл добавьте строчки:

macro_nowarn <значение>
<значение> - 0 или 1 - вкл. или выкл. раздражающие предупреждения когда автомакрос не использует команду call

macro_orphans <метод>
<метод> - terminate, reregister или reregister_safe

Например, если использовать команду "ai clear" во время работающего макроса, то этот макрос станет "одиночным". Это означает что макрос существует, но не может продолжатся, т.е. макрос остается без поддержки Искусственного Интеллекта (ИИ, он же AI) и не может действовать самостоятельно. До версии макроса 1.0.2 нужно было вручную вводить остановку макроса командой "macro stop". Начиная с версии 1.0.2 Вы можете выбрать определённый метод решения этой проблемы.

Есть три метода:
1. terminate - завершает макрос (аналогично команде "macro stop")
2. reregister - перерегистрация ИИ и отмена других входов. Это вызывает продолжение макроса
3. reregister_safe - перерегистрация ИИ и установка ожидания. Это означает, что макрос будет продолжен как только выполнятся все другие задачи.

macro_readmanual red/chili
Эта строчку нужна для того чтобы macro plugin загрузился. Т.е. проверка на внимательность. Без неё плагин выгрузится!

Пример:

###macros###
macro_readmanual red/chili
macro_nowarn 1
macro_orphans reregister

[4epT]

4. Команды

Для запуска макроса необходимо в командной строке написать:
macro <имя макроса>

Макрос можно запускать с различными опциями и параметрами:
macro <имя макроса> [опции] [-- параметр(ы)]

При запуске макроса можно воспользоваться следующими опциями:
-repeat <n>
Повторяет макрос n раз. n должно быть целым числом.
Т.е. если n=2, то макрос 1 раз выполнится и ещё 2 раза повторится.

-overrideAI
Отключает искусственный интеллект бота.

-macro_delay <n>
Устанавливает задержку между командами макроса в n секунд, игнорируя значение в timeouts.txt.

-exclusive
Не позволит автомакросу закончит этот макрос.

-orphan <метод>
Использует <метод> (terminate, reregister или reregister_safe) для обработки одиночного макроса. Про методы подробнее написано тут.


Параметр для макроса определяется после двойного тире (--). Эти параметры эквивалентны переменным от $.param1 до $.paramN.

Например:
Пусть файл macros.txt содержит следующее:

macro foo {
 log Parametr 1 -> $.param1
 log Parametr 2 -> $.param2
}

Если макрос foo запустить с параметрами abra и kadabra (macro foo -- abra kadabra), то на экране появится:

[macro] Parametr 1 -> abra
[macro] Parametr 2 -> kadabra

macro list
Показывает список всех доступных макросов.

macro stop
Останавливает текущий макрос.

macro pause
Приостанавливает запущенный макрос.

macro resume
Включает приостановленный макрос.

macro set <имя переменной> <значение>
Устанавливает (заменяет) переменной <имя переменной> значение <значение> или удаляет переменную, если значение не задано.

macro version
Выводит на экран версию macro плагина.

macro reset [<имя автомакроса>]
Сбрасывает "run-once" всех автомакросов или определённого [COLOR="Ыршае+"]автомакроса[/COLOR]. Эту команду можно использовать для нескольких автомакросов сразу. Для этого имена автомакросов пишутся через пробел.

macro status
Показывает запущен ли макрос в настоящее время. Если макрос запущен, то показывает:
status: running << запущен
delay: 10s << задержка перед следующей командой
line: 3 << текущая строку макроса
override AI: no << настройка опции "-overrideAI"
paused: no << пауза макроса
finished: no << закончен ли макрос

[4epT]

5. Синтаксис макроса

Теоретически вы можете использовать любую консольную команду в макросе =)

# <комментарий>
Всё что находится за значком "#" OpenKore воспринимает как комментарий.

do <команда>
Выполнить <команду>. Со списком команд можно ознакомиться тут. Например (бот пойдёт в пронту на координаты 123 234, затем сядет, а потом скажет в общий чат "hello world"):

macro foo {
 do move 123 234 prontera
 do sit
 do c "hello world"
}

log <текст>
Выводит <текст> на консоль (это текст увидите только Вы). Например:

macro foo {
 log 3Ta koMaHDa BbIBoDuT TekcT B koHcoLb.
 log Ee Mo)I(Ho uCnoLb30BaTb DL9 noDcka3ok!
}

pause <n>
Останавливает макрос на <n> секунд. Например:

macro foo {
 log I'm here and...
 pause 10
 log now I'm here.
}

call <имя макроса> <n>
Вызывает макрос с именем <имя макроса> <n> раз (n – целое число). Когда макрос <имя макроса> закончится, то текущий макрос продолжит работу.

release <имя автомакроса> | all
Включает закрытый автомакрос. Для включения всех автомакросов, используйте команду "release all".

lock <имя автомакроса>
Закрывает автомакрос и выключает его проверку.

stop
Немедленно завершает запущенный макрос.

set <опция> <значение>
Устанавливает <опции> соответствующее <значение>:
repeat <число раз>
overrideAI [0|1]
macro_delay <задержка>
exclusive [0|1]
orphan <метод>
Подробнее про опции макроса можно узнать тут.

[4epT]

6.1 Собственные переменные

Вы можете задавать и работать с собственными переменными.
Чтобы установить (или задать новое значение) переменную, используйте:
$<имя переменной> = <значение>

Для увеличения или уменьшения значения переменной на 1, используйте:
$<имя переменной>++ или $<имя переменной>--

Для вычислительных операций с переменными используйте команду @eval.
Переменную можно задать как список, состоящий из нескольких переменных, разделённых запятой:
$list = element one,element two,foo,bar,baz
Чтобы извлечь первую переменную из этого списка, используйте:

macro foo {
 $list = element one,element two,foo,bar,baz
 $var = [$list]
 log nepeMeHHa9 "var" uMeeT 3Ha4eHue: $var (element one)
 log nepeMeHHa9 "list" Tenepb uMeeT 3Ha4eHue: $list (element two,foo,bar,baz)
}

Отмечу, что <имя переменной> должно начинаться с буквы и не должно содержать ничего кроме букв и цифр.

Пример, отображающий основные операции с переменными:

macro foo {
 $var1 = world
 $var2 = hello
 $var3 = $var2 $var1
 log next line will yell out "hello world . world . hello"
 do c $var3 . $var1 . $var2
 $var4 = 47
 log \$var4 is $var4
 $var4++
 log \$var4 is $var4
 $var4 = @eval ($var4 + 52)
 log \$var4 is $var4
}

[4epT]

6.2 Специальные переменные

Здесь представлены специальные переменные. Они начинаются с символов "$."

$.map - карта на которой вы находитесь ("prontera")
$.pos - ваша текущая позиция ("123 234")

$.time - текущее время как отметка пользователей Юникс ("1131116304"). Хз чё такое
$.datetime - текущее число и время ("Fri Nov 4 15:59:36 2005")

$.hp - текущее ХП
$.sp - текущее СП

$.lvl - текущий базовый левл
$.joblvl - текущий джоб левл

$.spirits - текущее количество сферок (для монка)

$.zeny - текущее количество баксов

$.status - текущие статусы (аги, блесс, перевес...). Хз чё такое

$.lastLogMsg - текст, запустивший последний автомакрос условием "console"

$.lastpub - имя игрока, который запустил последний автомакрос условием "pubm"
$.lastpubMsg - последнее его написанное сообщение

$.lastpm - имя игрока, который запустил последний автомакрос условием "pm"
$.lastpmMsg - последнее его написанное сообщение

$.lastguild - имя игрока, который запустил последний автомакрос условием "guild"
$.lastguildMsg - последнее его написанное сообщение

$.lastparty - имя игрока, который запустил последний автомакрос условием "party"
$.lastpartyMsg - последнее его написанное сообщение

$.lastMonster - имя монстра, который запустил последний автомакрос условием "monster"
$.lastMonsterPos - последняя известная позиция этого монстра ("123 234 prontera")

$.lastMatchN - текст регулярного выражения (regexp)

$.paramN - N-ый параметр при запуске макроса
Например если макрос запустить так: "macro foo -- abra kadabra", то $.param1 = abra, а $.param2 = kadabra. См. команды.

$.caller - имя последнего запущенного автомакроса

$.hooksaveN - value of a hash key (argument that's given with hook). Хз чё такое

[4epT]

6.3 Вложенные переменные

Вы можете определить динамические или вложенные переменные. Например:

macro foo {
 $var = foo
 log \$var is "foo"
 ${$var} = bar
 log \$\$var is \$foo is "bar"
}

[4epT]

7. Операторы макроса

Macro плагин поддерживает только три оператора ("while", "if (...) + goto" и "goto"). Так как нет (видимой) нумерации строк, то Вы должны использовать метки которые определяются как:
:<имя метки>

Пример конструкции "while":

macro foo {
$i = 0
log the next lines will loop 11 times (0 .. 10)
while ($i <= 10) as exampleloop
log loop $i
$i++
end exampleloop
}

Пример конструкции "if" + "goto" (аналог if (...) then (...)):
проверяем условие равенста i=1

macro foo {
$i = @random ("1", "2")
if ($i = 1) goto one
goto end
:one
log i is one
log tra-ta-ta
:end
}

Однако короче будет "от противного", т.е. проверить условие "i не равно 1"

macro foo {
$i = @random ("1", "2")
if ($i != 1) goto end
log i is one
:end
log tra-ta-ta
}

Отмечу, что метки оператора goto не могут содержать ничего кроме букв и цифр. Например: "warp_to_payon" писать неправильно, правильно писать так: warpToPayon.

Оператор if (...), можно использовать только с последующим оператором goto. Т.е. написать как в обычных языках программирования:

if ($a != 2) $a = 3 <- нельзя!

Необходимо реализовать следующим образом:

if ($a != 2) goto end
$a = 3
:end

В случае если необходимо пользоваться конструкцией вида:

if (...)
then (...)
else (...)

то в макросах это будет выглядеть так:

macro foo {
$i = @random ("1", "2")
if ($i == 1) goto one
log i is two
goto end
:one
log i is one
goto end
:end
log tra-ta-ta
}

Пример конструкции "goto":

macro foo {
$i = 1
:plus
$i++
log i = $i
goto plus
}

Получился цикл: 1,2,3...