This manual is for macro plugin version 1.3.3.
$Date: 2006-08-24 11:40:49 +0300 (Чт, 24 авг 2006) $

With this plugin you can predefine command sequences (macros) which are run either manually or by situation-dependent triggers.

First grab your copy of the macro plugin and unzip the file.
You should now have a folder called Macro containing some .pm files and two files called macro.pl and cvsdebug.pm.
Create a folder plugins in your openkore folder and put the Macro folder and the macro.pl file inside. Copy cvsdebug.pm in your openkore root folder then create a blank file macros.txt in your control folder. This is where your macros/automacros belong in.

Your openkore tree should look like this (ignoring openkore's own files):

openkore
|-- control
|   `-- macros.txt
|-- cvsdebug.pm
|-- fields
|-- logs
|-- plugins
|   |-- Macro
|   |   |-- Automacro.pm
|   |   |-- Data.pm
|   |   |-- Parser.pm
|   |   |-- Script.pm
|   |   `-- Utilities.pm
|   `-- macro.pl
|-- src
`-- tables

To configure the plugin please refer to the Configuration files topic.
Before being able to use this plugin you'll need to read this documentation.
back to top

macro <macroname> [options] [-- parameter(s)]

Runs macro <macroname>.

option	value	description
-repeat	n	repeat the macro n times
-overrideAI	(none)	override openkore's AI
-macro_delay	delay	override global macro_delay for this macro
-exclusive	(none)	do not allow automacros to cancel this macro
-orphan	method	use method for handling orphaned macros

Parameters for the macro can be specified after a double dash (--). These parameters are saved to the variables $.param1 to $.paramN.
Example:

macro foo {
    log Parameter 1 is $.param1
    log Parameter 2 is $.param2
}

When called as macro foo -- foo bar it would print out

[macro] Parameter 1 is foo
[macro] Parameter 2 is bar

macro list

Lists all available macros.

macro stop

Stop current macro.

macro pause

interrupts the running macro

macro resume

resumes an interrupted macro

macro set variable value

set/change variable to value or delete variable if no value is given.

macro version

Print version number.

macro reset [<name(s)>]

Resets all run-once automacros or the specified automacro <name>.

macro status

Shows whether or not a macro is currently running. If that's the case it shows the delay for the next command, the current line, overrideAI setting, whether or not it has finished and whether or not the macro registered to AI queue

back to top

control/macros.txt

Put your macros and automacros in here.

control/timeouts.txt

Add macro_delay and set it to the number of seconds you want the plugin to pause between commands.

control/config.txt

(optional)

variable	values	description
macro_nowarn	0 1	enable or disable the annoying warnings when not using call in your automacro(s)
macro_orphans	terminate reregister reregister_safe	see orphaned macros section
macro_debug	level(s)	see debugging section
macro_file	filename	file containing the macros ("macros.txt" by default)

back to top

macro foo {
    do this..
    and that..
    yattayatta..
}

In theory, you can use any console command in a macro. I tested this plugin for buying silver arrows, talking to npc and pm'ing people. Lazy people could use this plugin for completing the amatsu dungeon quest or something like that.

do <command>

let openkore run <command>.
Examples:

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

log <text>

Sends <text> to console.
Examples:

macro foo {
    log This line logs a text to console.
    log All your base are belong to us!
}

pause [<n>]

pauses for one or <n> seconds.
Example:

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

call <macroname> [<n>]

calls a macro <macroname> [<n> times]. When <macroname> is finished the current macro continues.

release (<name> | all)

reenables a locked automacro ("run-once" keyword or locked by "lock") or reenables all automacros when using release all

lock <name>

locks an automacro and disables it's checks

stop

immediately terminates the running macro

set <option> <value>

sets macro features:

• orphan method
• macro_delay timeout
• overrideAI [0|1]
• repeat times
• exclusive [0|1]

See automacro section.

Variable declaration and usage

You can define and work with own variables.
To set a variable use $variable = value, to recall the value use $variable.
It is possible to increment and to decrement a variable.
To extract the first item of a comma-separated list use

macro foo {
   $list = element one,element two,foo,bar,baz
   $var = [$list]
   log var contains $var (element one)
   log list contains $list (element two,foo,bar,baz)
}

Note that variable names must begin with a letter and must not contain anything other than letters and digits.
Examples:

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
}

Special variables

There are special readonly variables which begin with a dot.

• $.map - the map you're on ("prontera")
• $.pos - your current position ("123 234")
• $.time - current time as unix timestamp ("1131116304")
• $.datetime - current date and time ("Fri Nov 4 15:59:36 2005")
• $.hp - current hp
• $.sp - current sp
• $.lvl - current base level
• $.joblvl - current job level
• $.spirits - current number of spirit spheres
• $.zeny - current amount of zeny
• $.status - current statuses in a comma-separated list
• $.lastLogMsg - the text that triggered the last automacro condition "console"
• $.lastpub - the name of the player who triggered the last automacro condition "pubm"
• $.lastpubMsg - what he wrote
• $.lastpm - the name of the player who triggered the last automacro condition "pm"
• $.lastpmMsg - what he wrote
• $.lastguild - the name of the player who triggered the last automacro condition "guild"
• $.lastguildMsg - what he wrote
• $.lastparty - the name of the player who triggered the last automacro condition "party"
• $.lastpartyMsg - what he wrote
• $.lastMonster - the name of the monster which triggered the last automacro condition "monster"
• $.lastMonsterPos - the last known position of that monster ("123 234 prontera")
• $.lastMatchN - backreferences for the last regexp match
• $.paramN - command line parameters (see commands)
• $.caller - name of the last triggered automacro
• $.hooksaveN - value of a hash key (argument that's given with hook)

Nested variables

You can define dynamic or nested variables.
Examples:

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

Flow control and labels

While all high level programming languages have constructs like "if .. then", "while", "repeat", "for .. next", "do .. while" and function calls their common denominators are "if", "goto" and "while". That's why the macro plugin only supports these three keywords.
Since there are no (visible) line numbers you'll need to use labels which can be defined by a colon followed by the name of the label.
Example for a "while" construct:

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
}

Examples:

macro foo {
   $i = @random ("1", "2", "3")
   if ($i == 1) goto one
   if ($i == 2) goto two
   log i is three.
   goto end
   :one
   log i is one
   goto end
   :two
   log i is two
   :end
}

conditions:

condition	meaning
<	less than
<=	less than or equal to
==	equal to
>=	greater than or equal to
>	greater than
!=	not equal to
~	<left part> is element of <right part (comma-separated list)>

Special keywords

@npc (<x> <y>)

expands to npc's ID who's located at <x>, <y> or to -1 if the npc was not found

@inventory (<item>)

searches your inventory for <item> and returns ID or -1 if the item was not found

@Inventory (<item>)

same as @inventory but returns all matching IDs as a comma-separated list or -1 if the item was not found

@cart (<item>)

searches your cart for <item> and returns ID or -1 if the item was not found

@Cart (<item>)

same as @cart but returns all matching IDs as a comma-separated list or -1 if the item was not found

@storage (<item>)

searches your storage for <item> and returns ID or -1 if the item was not found

@Storage (<item>)

same as @storage but returns all matching IDs as a comma-separated list or -1 if the item was not found

@player (<name>)

looks for a player and returns ID or -1 if the player was not found

@vender (<name>)

looks for a vender and returns ID or -1 if the vender was not found

@store (<name>)

looks for an item in a store and returns ID or -1 if the item was not found

@random ("<argument1>"[, "<argument2>"[, ...]])

returns randomly one of the given arguments

@rand (<n>, <m>)

returns a random number between (and including) <n> and <m>

@invamount (<item>)

returns the amount of the given <item> in inventory

@cartamount (<item>)

returns the amount of the given <item> in cart

@shopamount (<item>)

returns the amount of the given <item> in shop

@storamount (<item>)

returns the amount of the given <item> in storage

@eval (<argument>)

evaluates the given <argument>

@arg ("<argument>", <n>)

returns the <n>th word of <argument> or an empty string if the word index is out of range

@config (<variable>)

returns the value of <variable> specified in config.txt

Simple Macro Example

macro foo {
   $foobegin = $.pos
   do move 168 128 prt_in
   do talk @npc (172 130)
   do store
   do store
   do buy @store (Silver Arrow) 10000
   do move 280 198 prontera
   do talk @npc (282 200)
   do talk cont
   do talk resp 1
   do storage add @inventory (Silver Arrow) @eval (@invamount (Silver Arrow) - 1000)
   do move $foobegin
}

When invoked via the command "macro foo [times]" the macro does the following:

• store our current position in "foobegin"
• move to 168 128 prt_in (weapon shop)
• talk to the npc which is located at 172 130 (weapon dealer)
• type "store" twice to show what he sells
• buy 10,000 silver arrows.
• move to 280 198 prontera (Prontera east gate)
• talk to kafra
• talk conf and talk resp 1 opens the storage
• add all but 1000 silver arrows to storage and finally
• return to where we were before running this macro

back to top

automacro foo {
    <condition> bar
    <condition> baz, yatta
    call macroname
}
automacro mi {
    <condition> moo
    <condition> xyz
    call {
    	do this
    	do that
    }
}

Automacros are macros that will be automatically triggered when certain given conditions match.

map <mapname>

triggers when your current map is <mapname>

location [not] <mapname [<x1> <y1> [<x2> <y2>]] [, ...]

triggers when you are [not] at the specified location.
When neither <x1> <y1> nor <x2> <y2> are given it triggers when you are [not] on <mapname>.
When <x2> <y2> are not given it triggers when you are [not] on <mapname> at <x1>, <x2>.
When both <x1> <y1> and <x2> <y2> are defined it triggers when you are on <mapname> somewhere between <x1>, <y1> (upper left) and <x2>, <y2> (lower right, where <x1> < <x2> and <y1> > <y2>
Comma-separated arguments are treated as OR conditions:

location geffen, prontera 123 234

triggers when you are either in geffen or in prontera at 123 234.
Multiple lines are treated as AND conditions:

location not geffen
location not prontera

triggers when you are neither in geffen nor in prontera.

mapchange (<mapname>|any) [, ...]

triggers when changing map to <mapname>. If the argument is any then it triggers on any map change.
Comma-separated arguments are treated as OR conditions.

hp <condition> <amount>[%]

triggers when your hp match <condition> <amount> (absolute value) or <condition> <amount> percent (relative value).
Multiple lines are treated as AND conditions.

sp <condition> <amount>[%]

triggers when your sp match <condition> <amount> (absolute value) or <condition> <amount> percent (relative value).
Multiple lines are treated as AND conditions.

spirit <condition> <amount>

triggers when your spirits match <condition> <amount>.
Multiple lines are treated as AND conditions.

weight <condition> <amount>[%]

triggers when your weight matches <condition> <amount> (absolute value) or <condition> <amount> percent (relative value).
Multiple lines are treated as AND conditions.

cartweight <condition> <amount>[%]

triggers when your cart weight matches <condition> <amount> (absolute value) or <condition> <amount> percent (relative value).
Multiple lines are treated as AND conditions.

zeny <condition> <amount>

triggers when your zeny amount matches <condition> <amount>.
Multiple lines are treated as AND conditions.

soldout <condition> <slots>

triggers when the amount of sold out item slots in your shop matches <condition> <slots>.
Multiple lines are treated as AND conditions.

status [not] <status> [, ...]

triggers when you are [not] <status>.
The statuses "dead" and "muted" are supported additionally.
Comma-separated arguments are treated as OR conditions.
Multiple lines are treated as AND conditions.

inventory "<item>" <condition> <amount> [, ...]

triggers when you have <condition> <amount> of <item> in your inventory.
Comma-separated arguments are treated as OR conditions.
Multiple lines are treated as AND conditions.

storage "<item>" <condition> <amount> [, ...]

triggers when you have <condition> <amount> of <item> in your storage.
Comma-separated arguments are treated as OR conditions.
Multiple lines are treated as AND conditions.

cart "<item>" <condition> <amount> [, ...]

triggers when you have <condition> <amount> of <item> in your cart.
Comma-separated arguments are treated as OR conditions.
Multiple lines are treated as AND conditions.

shop "<item>" <condition> <amount> [, ...]

triggers when you have <condition> <amount> of <item> in your shop.
Comma-separated arguments are treated as OR conditions.
Multiple lines are treated as AND conditions.

base <condition> <level>

triggers when your baselevel matches <condition> <level>.
Multiple lines are treated as AND conditions.

job <condition> <level>

triggers when your joblevel matches <condition> <level>.
Multiple lines are treated as AND conditions.

class <job>

triggers when your jobclass is <job>

spell <spell> [, ...]

triggers when someone casts <spell> on you or you are in it's scope.
Comma-separated arguments are treated as OR conditions.

monster <monstername> [, ...]

triggers when <monstername> is near.
When triggered the special variables $.lastMonster and $.lastMonsterPos are set.
Comma-separated arguments are treated as OR conditions.
Multiple lines are treated as AND conditions.

notMonster <monstername> [, ...]

triggers when a monster appears that is not in the list.
Comma-separated arguments are treaded as AND conditions.

aggressives <condition> <number>

triggers at <number> of aggressives.
Multiple lines are treated as AND conditions.

player "<playername>" [, <distance> ]

triggers when <playername> is on screen or not more than <distance> blocks away.
Multiple lines are treated as AND conditions.

equipped [<slot>] (<item>|none) [, ...]

triggers when <item> or none is equipped [in slot <slot>]
Slots are topHead, midHead, lowHead, leftHand, rightHand, robe, armor, shoes, leftAccessory, rightAccessory and arrow
Comma-separated arguments are treated as OR conditions.
Multiple lines are treated as AND conditions.

var <variable> (unset|<condition> <value>)

triggers when <variable> is either unset or matches <condition> <value>.
Multiple lines are treated as AND conditions.

varvar <nested variable> (unset|<condition> <value>)

triggers when <nested variable> is either unset or matches <condition> <value>.
Multiple lines are treated as AND conditions.

console ("<text>"|/<regexp>/[i])

triggers when <text> is received on console or the text received matches <regexp>.
The i switch means the regexp is case insensitive.
Sets $.lastLogMsg.

pm ("<text>"|/<regexp>/[i]) [, <player>]

triggers when <text> is received by pm [from <player>] or the text received matches <regexp>.
The i switch means the regexp is case insensitive.
Sets $.lastpm and $.lastpmMsg.

pubm ("<text>"|/<regexp>/[i]) [, <distance>]

triggers when a public message [within a distance of <distance>] is received and it is <text> or matches <regexp>
The i switch means the regexp is case insensitive.
Sets $.lastpub and $.lastpubMsg.

party ("<text>"|/<regexp>/[i])

triggers when <text> is received by partychat or the text received matches <regexp>.
The i switch means the regexp is case insensitive.
Sets $.lastparty and $.lastpartyMsg.

guild ("<text>"|/<regexp>/[i])

triggers when <text> is received by guildchat or the text received matches <regexp>.
The i switch means the regexp is case insensitive.
Sets $.lastguild and $.lastguildMsg.

hook <hookname>

triggers when openkore calls <hookname>.

saveN <hash key>

(use in combination with hook)
saves the value of <hash key> in a variable .hooksave1 to .hooksaveN

run-once (0|1)

When set to 1 the automacro will be deactivated after being triggered.
Use the macro command release to reenable this automacro.

overrideAI (0|1)

When set to 1 the macro ignores openkore's AI. This means it won't pause upon "move" or "status dead".

delay <n>

Waits for <n> seconds before calling the corresponding macro.

timeout <n>

Wait at least for <n> seconds before this automacro can be triggered again.

macro_delay <n>

Overrides the global macro_delay setting for the called macro.

priority <num>

Choose which automacros should be checked before others. The smaller <num> is is the sooner the automacro gets checked. If priority is not given, the priority is assumed to be 0 (zero: check first).

exclusive (0|1)

Automacros which have exclusive set cannot be interrupted by other automacros.
As of macro 1.3.0 running macros can be interrupted by automacros by default. To disallow that behaviour either set this option or use the command line option -exclusive

set <variable> <value>

Sets variable <variable> to <value> You can have multiple set lines per automacro.

call <name>

Calls macro <name> when the automacro is triggered.

call {
    <instructions>
}

Runs <instructions> when the automacro is triggered.

orphan <method>

Sets the method of how to deal with orphaned macros.

Automacro Example

automacro checkshop {
   location prontera
   soldout >= 3
   delay 60
   call reopenshop
}

macro reopenshop {
   do closeshop
}

This automacro is triggered when you have a shop open in Prontera and there are three or more items sold out. When triggered, it waits for one minute then calls the macro "reopenshop" which closes your shop. If you have shopAuto_open or autoshop set to 1, it will be re-opened after a certain time.
back to top

It may happen - for example by using ai clear while a macro is running - that a macro becomes orphaned. That means the macro object exists but cannot continue because it requires the AI queue to contain the entry "macro" (or "deal") at the first place. When the AI queue gets cleared, the "macro" entry vanishes.
Before 1.0.2 this problem had to be solved by manually typing "macro stop". With 1.0.2 and up you may select which mechanism should be used to resolve that issue. There are three methods:

terminate	terminates the macro (equivalent to macro stop)
reregister	re-registers to AI queue, overriding other entries. This means to force the continuation of the macro.
reregister_safe	re-registers to AI queue when AI gets idle. This means the macro will continue when all other tasks are done.

back to top

.. you may add the following line to your config.txt:

macro_readmanual red/chili

or the plugin will unload immediately.

Debugging is done by the cvsdebug.pm package (included).

Add macro_debug <level(s)> to your config.txt.
Debug levels are:

variable_trace

tracks variables

command_preparsed

unparsed command line

command_parsed

parsed command line

parser_steps

parser steps

function_call_macro

macro functions (low traffic)

function_call_auto

automacro functions (high traffic)

automacro_checks

automacro checks (high traffic)

developers

debugging messages (only?) useful for developers

full

full debug, all levels.

Debug levels are separated by pipes |
Example:

macro_debug variable_trace|parser_steps

back to top

• automacro check console ignores the following domains: macro and cvsdebug.
• do not use closing brackets ")" in keyword arguments unless it's the closing bracket for an argument.
  for example: @random ("foo", "bar", "@eval (4 + 5)", "yatta") is allowed, @random ("foo", "bar", ":-)", "yatta") is not.
• macro 1.3.x requires openkore 1.9.x or later

If there are any bugs, please report them to me. Use at your own risk, I won't give any guarantee that this script works as described. So if the example above buys 10.000 main gauche, I'm not responsible for this (this won't happen, but just to be on the safe side..^^). Hope that's all. Have fun.
back to top

Download macro plugin version 1.3.2
Download macro plugin version 0.9.3 (depreciated, documentation)
Download macro plugin version 0.8.1 (outdated)

See also this forum post for general information about how to install plugins.
back to top

The development version can be found in the OpenKore SVN repository.

Windows users should read the SVN guide.

Linux users can run the following commands to get the development version from SVN:

svn co https://svn.sourceforge.net/svnroot/openkore/macro/trunk/

back to top

The SVN version includes two extra files:

recorder.pl

a standalone plugin for openkore that can be used to record macros (only commandline).

mconv.pl

a (yet incomplete) program to convert 0.8.x and 0.9.x macros to 1.x.x.

back to top

When starting openkore the macro plugin tells me to read the documentation and unloads!

Then you should read the documentation. I won't give you a different answer.

Help! I installed the macro plugin but my macros won't show up!

Make sure you saved your macros to macros.txt in your control folder. The Windows Explorer sometimes hides well-known extensions like txt so check you haven't named that file macros.txt.txt accidentally.

Help! Openkore gives me some weird perl errors and tells me "a plugin failed to load"!

Never save your macros/automacros to a .pl file in your plugins folder. Put them in a file called macros.txt in your control folder.

I have some macros that worked fine with macro 0.9.x, but now I only get syntax errors.

The syntax has changed with macro 1.0.0. Read the documentation to learn about the new syntax. Most 0.8.x and 0.9.x macros can be converted using the mconv.pl utility.

Wh00t! I'm getting an error "Can't locate encoding.pm"!

Upgrade your openkore version to 1.9.x or higher. Openkore 1.6.x is no longer supported since macro 1.3.0.

Where can I get a macro that does [insert feature here]?

Search the forum. If you cannot find a macro for your purposes, write it. No spoonfeeding.

I have an automacro that checks for the amount of an item in my inventory / cart to be less than a given value or equal to zero (e.g. inventory "red potion" <= 30) but that automacro triggers also on map change. Why is that so and what should I do?

When you're changing the map all items vanish from your inventory for a short time. That happens with the official client, too. To avoid this, add an additional check for an item that you always carry with you, like inventory "Jellopy" > 0

back to top

For discussion and support, go to the macro plugin's forum.
back to top

The macro plugin is licensed under the GNU General Public License.
back to top

Written by arachno <arachnophobia at users dot sourceforge dot net>
back to top