Macro Plugin

Do you know about "Macro Plugin" yet ??

I take all of the explanation from here so if you still confused /wah better to look the real post.. /sob 

Installation in OpenKore.

1. Download the macro plugin. 
2. Go to your OpenKore folder (the folder which contains the file openkore.pl). 
3. In that folder, create a subfolder called plugins, if there isn't already one. 
4. Inside the Macro plugin's zipfile, you will find the file macro.pl and the folder Macro. Extract     them to your plugins folder. 
5. In your OpenKore control folder, create a blank file named macros.txt. In this file you will put your macros/automacros.

After installation, your OpenKore file tree should look like this (ignoring openkore's own files): 

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

Note (about Installation) : This only work in OpenKore v2.02 and up, there's no more VisualKore if i'm correct.. :/

Ok, after you done with the Installation now we can move to the Commands.

Commands 

macro [options] [-- parameter(s)] 

Runs macro .

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 version 

Print version number. 
macro reset [] 

Resets all run-once automacros or the specified automacro . 
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 

Configuration files 

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

Variable                            Value                       Description
macro_nowarn                  0               enable or disable the annoying warnings
                                             1               when not using call in your automacro(s) 
macro_orphans           terminate
                                       reregister                see orphaned macros section
                                  reregister_safe  
macro_file                  filename           file containing the macros ("macros.txt" by default) 
macro_allowDebug            0              console-check also processes openkore's debug messages
                                              1              (default: 0). Warning: slows down the plugin.

Before writing macros 

Make sure to read this manual entirely.
If you want to use openkore commands in your macro read about console commands. Note that few commands like manipulating the ai queue are not allowed.
Finally, read the announcements. They might contain useful examples of use. 

Macro syntax 
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  

Let openkore run . 
Example:

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



log  

Sends to console. 
Example:

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

pause [] 

Pauses for one or seconds. 
Example:

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



call [] 

Calls a macro [ times]. When is finished the current macro continues. 
release ( | all) 

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

Locks an automacro and disables it's checks. To locks all automacros, use lock all 
stop 

Immediately terminates the running macro 
set  

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 using $variable++ or $variable--.
For calculation use @eval. 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. 
Example:

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 
$.hooksave - value of a hash key (argument that's given with hook) 
$.weight - return the current weight of the character 
$.maxweight - return the maximum weight of the character 
Nested variables 

You can define dynamic or nested variables. 
Example:

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
}

Example:

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
}

Note: goto labels cannot contain anything other then letters and digits. Example: warp_to_payon does not work, it must be something like warpToPayon.

Conditions            Condition Meaning 
      <                                less than 
    <=                    less than or equal to 
     ==                              equal to 
     >=                  greater than or equal to 
     >                             greater than 
    !=                              not equal to 
      ~               is element of  

Special keywords 
@npc ( ) 
            Expands to NPC's ID who's located at (,), or to -1 if the NPC was not found. 
@inventory () 
            Searches your inventory for and returns ID or -1 if the item was not found. 
@Inventory () 
            same as @inventory but returns all matching IDs as a comma-separated list or -1 if the item was not found 
@cart () 
            searches your cart for and returns ID or -1 if the item was not found 
@Cart () 
            same as @cart but returns all matching IDs as a comma-separated list or -1 if the item was not found 
@storage () 
            searches your storage for and returns ID or -1 if the item was not found 
@Storage () 
            same as @storage but returns all matching IDs as a comma-separated list or -1 if the item was not found 
@player () 
            looks for a player and returns ID or -1 if the player was not found 
@vender () 
            looks for a vender and returns ID or -1 if the vender was not found 
@store () 
            looks for an item in a store and returns ID or -1 if the item was not found 
@random (""[, ""[, ...]]) 
            returns randomly one of the given arguments 
@rand (, ) 
            returns a random number between (and including) and  
@invamount () 
            returns the amount of the given in inventory 
@cartamount () 
            returns the amount of the given in cart 
@shopamount () 
            returns the amount of the given in shop 
@storamount () 
            returns the amount of the given in storage 
@eval () 
            evaluates the given  
@arg ("", ) 
            returns the th word of or an empty string if the word index is out of range 
@config () 
           returns the value of specified in config.txt 
@venderitem () 
           looks for an item in a players shop and returns ID or -1 if the item was not found. 
@venderprice () 
           looks for an item in a players shop and returns its price. 

"Chaining" commands 

You can run multiple commands one after another without having to wait for openkore's ai or macro_delay or whatever. Just enclose these commands with [ and ]. 
Example (with numbered lines):

0 macro foo {
1      do whatever
2      log yet another line
3     [
4             do something
5             do something else
6             log foo
7      ]
8      log done
9 }
 

Line 3 starts the chaining mode. This line has no delay. Lines 4, 5 and 6 are run as soon as the previous command has finished with no delay and they cannot be interrupted. Line 7 stops the chaining mode and line 8 will be run $macro_delay seconds after that. 

Simple macro example 
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 cont 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

Automacro syntax 
Example:

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

Automacros are macros that will be automatically triggered when certain given conditions match. 
map  
Triggers when your current map is . 

location [not] [ ]] [, ...]

Triggers when you are [not] at the specified location. 
           When neither nor are given it triggers when you are [not] on . 
           When are not given it triggers when you are [not] on at (,). 
           When both and are defined it triggers when you are on somewhere between , (upper left) and , (lower right, where < and >  
           Comma-separated arguments are treated as OR conditions: 
           Example:
                        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:
           Example:
                       location not geffen
                       location not prontera
           triggers when you are neither in geffen nor in prontera. 

mapchange (|any) [, ...] 
Triggers when changing map to . If the argument is any then it triggers on any map change. 
Comma-separated arguments are treated as OR conditions. 

hp [%] 
triggers when your hp match (absolute value) or percent (relative value). 
Multiple lines are treated as AND Conditions. 

sp [%] 
triggers when your sp match (absolute value) or percent (relative value). 
Multiple lines are treated as AND conditions. 

spirit  
triggers when your spirits match . 
Multiple lines are treated as AND conditions. 

weight [%] 
triggers when your weight matches (absolute value) or percent (relative value). 
Multiple lines are treated as AND conditions. 

cartweight [%] 
triggers when your cart weight matches (absolute value) or percent (relative value). 
Multiple lines are treated as AND conditions. 

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

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

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

inventory "" [, ...] 
triggers when you have of in your inventory. 
Comma-separated arguments are treated as OR conditions. 
Multiple lines are treated as AND conditions. 

storage "" [, ...] 
triggers when you have of in your storage. 
Comma-separated arguments are treated as OR conditions. 
Multiple lines are treated as AND conditions. 

cart "" [, ...] 
triggers when you have of in your cart. 
Comma-separated arguments are treated as OR conditions. 
Multiple lines are treated as AND conditions. 

shop "" [, ...] 
triggers when you have of in your shop. 
Comma-separated arguments are treated as OR conditions. 
Multiple lines are treated as AND conditions. 

base  
triggers when your baselevel matches . 
Multiple lines are treated as AND conditions. 

job  
triggers when your joblevel matches . 
Multiple lines are treated as AND conditions. 

class  
triggers when your jobclass is  

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

monster [, ...] 
triggers when 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 [, ...] 
triggers when a monster appears that is not in the list. 
Comma-separated arguments are treaded as AND conditions. 

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

player (""|//[i]) [, ] 
triggers when is on screen or not more than blocks away. 
Multiple lines are treated as AND conditions. 

equipped [] (|none) [, ...] 
triggers when or none is equipped [in 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 (unset| ) 
triggers when is either unset or matches . 
Multiple lines are treated as AND conditions. 

varvar (unset| ) 
triggers when is either unset or matches . 
Multiple lines are treated as AND conditions. 

console (""|//[i]) 
triggers when is received on console or the text received matches . 
The i switch means the regexp is case insensitive. 
Sets $.lastLogMsg. 

pm (""|//[i]) [, ] 
triggers when is received by pm [from ] or the text received matches . 
The i switch means the regexp is case insensitive. 
Sets $.lastpm and $.lastpmMsg. 

pubm (""|//[i]) [, ] 
triggers when a public message [within a distance of ] is received and it is or matches  
The i switch means the regexp is case insensitive. 
Sets $.lastpub and $.lastpubMsg. 

party (""|//[i]) 
triggers when is received by partychat or the text received matches . 
The i switch means the regexp is case insensitive. 
Sets $.lastparty and $.lastpartyMsg. 

guild (""|//[i]) 
triggers when is received by guildchat or the text received matches . 
The i switch means the regexp is case insensitive. 
Sets $.lastguild and $.lastguildMsg. 

hook  
triggers when openkore calls . 

save  
(use in combination with hook) 
saves the value of in a variable $.hooksave1 to $.hooksave 

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  
Waits for seconds before calling the corresponding macro. 

timeout  
Wait at least for seconds before this automacro can be triggered again. 

macro_delay  
Overrides the global macro delay setting for the called macro. 

priority  
Choose which automacros should be checked before others. The smaller 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  
Sets variable to . You can have multiple set lines per automacro. 

call  
Calls macro when the automacro is triggered. 

call { 
 
} 
Runs when the automacro is triggered. 

orphan  
Sets the method of how to deal with orphaned macros.

Automacro Example 
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.

Comments 

The macro files allow comments, i.e. lines that are ignored by the macro plugin. Lines starting with a # will be treated as comment. 
Example:

# this is a comment line

Orphaned macros 

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. 

Understanding and Writing Macros 

This is a supplement to this manual, and was initially posted by openkore129 here. Please post any relevant queries or comments on this section there. 

I assume you already know how to use console commands and understand how they work. If not, before going further read through all console commands and try out ones like a, ai, move, cart get, storage add, talk, deal, take, direction commands, sl, sm, relog, pm and others. 

Automacros 

Automacros are macro which automatically trigger when certain conditions are met, just like how blocks in config.txt trigger depending on the conditions set in them. 

The point of automacros is that you use them to check for conditions. When the condition is fulfilled you can either respond to it in the automacro or call a macro to do it. The format for automacros is... 
automacro {
  condition 1
  condition 2
  …...
  …...
  call {
  command 1
  command 2
  …..
  …..
  }
  timeout (if necessary)
}

For example, suppose you're playing manually but your slave priest is on Kore, and you want it to warn you if its running out of sp, you can use an automacro like this.... 
automacro sp {
  sp < 200
  call {
  do c sp low
  }
  timeout 10
}

Taking it line by line, 

automacro sp { - you need to put automacro to tell kore that its an automacro. Then you put the name of the macro, in this case its “sp”. Then you need to put an opening bracket “{“ which tells Kore that the automacro's code begins there. 

Sp < 200 – After the “{“, you put the conditions on successive lines. Here there is only one condition and I think its clear that the condition is that sp should be below 200. 

call { – The word “call” tells Kore that now you're going to be putting commands, not conditions. The opening bracket “{“ tells Kore that the commands will start now. These commands are the ones that will get carried out when the conditions are met, here when sp goes below 200. 

do c sp low – “Do” tells Kore that this is a commands, some to be done. After “do”, just leave a space and type in the console command you want to execute exactly the way you do in the Kore console. 

} – This closing bracket “}” tells Kore that the commands have ended. 

timeout 10 – This isn't a condition or a command, it works the same way it works in normal Kore blocks, so this automacro cannot trigger within 10 seconds of it already having been triggered. I ALWAYS put timeouts, so even if my conditions are faulty, the automacro doesn't spam and mess up whatever my bot is doing. Otherwise if your automacro is messed up then you could die or something, so its better to put an appropriate timeout. 

} – This closing bracker “}” tells Kore that your automacro code has ended. 

So basically whenever, the bot's sp goes below 200, it says in public chat “sp low”. This also has the advantage of making your bot not look like a bot =p. 

Here's another macro which illustrates how you can use macros to handle weird situations which Kore is not equipped to deal with. When fighting against metalings, the often strip you and then your oh-so-smart bot punches! To get around this, put the weapon you use in default auto equip and use this macro. 
automacro strip {
  status Strip Weapon
  call {
  do tele
  do relog 10
  }
  timeout 10
}

Taking it line by line.... 

automacro strip { - Tell Kore this is an automacro, and it's name is "strip". The '{' tells Kore the code of the automacro starts here. 

status Strip Weapon - The only condition in this macro. This checks your list of statuses for the status "Strip Weapon" 

call { - The word "call" and "{" tells Kore that the commands to be executed start after the '{' 

do tele - 'do' tells Kore that what comes after is a console command to be carried out. Here the command is "tele" so you teleport away from the Metaling, so that incase you lag or something, you aren't killed while executing the next instruction which is..... 

do relog 10 - Tells Kore to now relog, so that when you login again, your "strip weapon" status will be cleared. 

} - '}' Tells Kore the commands have ended. 

timeout 10 - Ensures automacro is not spammed, and 10 seconds is enough time to execute the automacro. So after 10 seconds, if for some reason you are still stripped, this automacro will trigger again. However, if you relogin and are stripped within 10 seconds, then macro will not trigger till the 10 seconds are up. 

} - '}' tells Kore the macro code has ended. 

Summarising, on being stripped, you teleport away from the monster and then relogin, with a timeout of 10 seconds to ensure that the automacro is not spammed. Since the weapon you're using is filled in in the default weapon option, after relogging Kore will automatically re-equip that weapon. 

Lets try a more complicated macro. If you have a priest, you would want it to warp back to its lockmap or the nearest warp-able map near its lockmap. This macro does it. From the savemap, the bot takes the same route to the lockmap. So the first map outside the town, just set it to move to a designated tile, and cast warp on a nearby tile, and then more to the tile. You will need delays to allow the spell to be cast and commands to be completed. 
automacro warp {
  map gef_fild07
  inventory "Blue Gemstone" > 0
  call {
  do ai manual
  pause 1
  do move 319 187
  do sl 27 316 188
  pause 2
  do warp 1
  pause 1
  do move 316 188
  do ai on
  }
  timeout 20
}

Taking it line by line, 

automacro warp { - As explained, the automacro's name is warp, and “{“ indicates that the automacro begins. 

map get_fild07 - The first condition, the automacro will only trigger if the map is gef_fild07. 

Inventory “Blue Gemstone” > 0 - Second condition, ensures there is atleast one blue gemstone in the inventory so that warp portal can be cast. Obviously you need a getAuto in config.txt for the gemstones. 

Call { - Tells Kore, that the commands start here. 

do ai manual - Frequently, I use this command in the more complicated and longer macros, so that Kore doesn't get diverted into doing something else while your macro is running, for example, attacking a monster or gathering up an item. 

Pause 1 - Inserts a delay of 1 second before the next command is carried out, VERY IMPORTANT. If you don't use delays then Kore can and will miss steps in the macro and the result is a mess. 

do move 319 187 - The “move” console command is used to move your bot to a set location. 

do sl 27 316 188 - The “sl” console command is used to make your priest cast warp portal on a convenient spot near your location, in this case (316,188). 

pause 2 - Very Important. A delay of 2 seconds is put, allowing enough time to cast warp portal. If you priest has low dex, this delay should be increased. 

Do warp 1 - Console command “warp” is used to select memo location 1. 

pause 1 - 1 second delay to allow the portal to form. 

do move 316 188 - Move to the portal and Voila! You have been warped to the map. 

Do ai on - You set ai to manual at the beginning of this macro, so now you need to turn it on. 

} - Closing bracket indication end of commands. 

Timeout 20 - Ensures that the bot does not spam the automacro. The timeout should be large enough to allow the completion of the automacro, so that the automacro does not trigger while the macro is executed. 

} - Closing bracket indicates end of automacro code. 

Note the use of appropriate delays and timeouts in this automacro. 


The macro plugin also has many useful built in variables which give you your position for example. Its all listed in the macro manual. I just want to show how to extract your position from these variables. 

$.pos gives you your position. Now to get your x and y coordinates the code is, 
  $px = @arg ("$.pos", 1)
  $py = @arg ("$.pos", 2)

If you have a “monster” condition in your automacro, $.lastmonsterpos gives the position of that monster. To extract the x and y coordinates the code is, 
  $mx = @arg ("$.lastMonsterPos", 1)
  $my = @arg ("$.lastMonsterPos", 2)

Run Once Frequently, the run once condition is used instead of a timeout. It allows the automacro to run only once, so that automacro isn't spammed. To get the automacro to be run again, a release command needs to be executed. However, sometimes due to a rogue situation the macro can hang and the release macro isn't executed. This means your automacro is effectively stuck. To get around this I use a timeout instead of using run-once. 


The normal macros In the 2 examples above, I've done everything using automacros. So you're probably wondering what the point of macros is, if everything can be done using automacros. Well, not everything can be done using automacros. For example, I don't think you can use macro variables such as $.pos in an automacro. So, if you get errors like “not an automacro variable” it means that cannot be done in an automacro and has to be done in a macro. 

Regular Expressions Sometimes, in a macro you need to compare say the names of characters near you to see if it matches a certain name. This is where regular expressions come in handy. If you're new to macros, you can read this later as it can be a bit complicated, the more advanced regexps can look hellish =P Visit http://www.regular-expressions.info/quickstart.html where its explained fairly well. I'm just going to put down some basics here. 
$.lastpubMsg = /(A|a)uto (S|s)torage/

Here $.lastpubMsg is your macro variable holding the last public chat message. A regular expression can just be plain text so it could have been /auto storage/ or /auto/ and Kore would have checked if the public chat contained "auto storage" or "auto". 

However here we have used the "|" symbol which means "or". Notice 'A' and 'a' are contained in brackets with a '|' between them. It means both 'auto' and 'Auto' are checked for. Similarly both 'storage' and 'storage' are checked for. Now suppose you want to check for repetition, say 'aauto storage' also, then you can use /(a+|A+)uto (S|s)torage/. Notice I've used a '+'. This tells Kore that the character it is directly after, here 'a' or 'A', should be present one or more times. So even if someone says "aaaaaaaaaauto storage' it will be valid. Other checks like the '+' are 
Match 0 or more times eg. /(a*|A*)uto Storage/ so "ato storage" will also work 

+ Match 1 or more times eg. as above ? Match 1 or 0 times eg /(a?|A?)uto Storage/ so "ato storage" and "auto storage" work but "aaaauto storage" won't 

So if you want to check for "Kobold" just do /Kobold/ and if "Kobold" is anywhere in the string, it will be valid. For Kobold-1 and Kobold-2 only it will be /Kobold-(1|2)/. 

Regexps can also come in handy when you're using the "console //" condition in automacros, if you need to check for a variety of trigger texts. 

These is just the basics, I recommend referring to link provided above if you need to make a more complicated regexp. 

How to write a macro Now that you have some idea of what a macro is, try writing one....
-Figure out under exactly what conditions you want your automacro to trigger
-Logically think out the steps your bot needs to perform in the automacro. Go step by step over this carefully.
-Ensure you have inserted appropriate pauses between the steps.
-Ensure you have a timeout or a run-once in your macro to prevent spamming of it.
-Now put the code in macros.txt and start the bot or reload macros.txt. If all is fine you won't get any error messages. But if there is a problem in the syntax, say you missed out a “}”, then you will get an error message and the macro won't work. Figure out what the error is, correct it, and reload macros.txt again to check if you corrected it properly or not.

Todos/Known bugs/Known limitations 
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. 

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.

Development version (SVN) 

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://openkore.svn.sourceforge.net/svnroot/openkore/plugins/macro/trunk/ 

Older releases: https://openkore.svn.sourceforge.net/svnroot/openkore/plugins/macro/tags/ 


Extras 

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.