Macro plugin

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

Installation in VisualKore

1. Download the macro plugin.
2. Inside the Macro plugin's zipfile, you will find the file macro.pl and the folder Macro. Extract them to C:\Program Files\VisualKore\plugins
3. Go to the VisualKore Profiles dialog. Select your profile and click "Edit Profile".
4. A folder window will now appear. In that folder, create a blank file named macros.txt. In this file you will put your macros/automacros.

To configure the plugin please refer to the Configuration files paragraph.

Notes:

• Each of your VisualKore profile folders correspond to the "control" folder as referenced by this manual.
• To use the same macro on multiple profiles, you must copy the required macros.txt (your macro) to each of your profiles you wish to use the macro with. Additionally, each profile's config.txt must have the line of code that prevents the plugin from unloading.

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

Runs macro <macroname>.

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 [<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

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

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

Example:

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

log <text>

Sends <text> to console.

Example:

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

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

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

"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

Example:

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:

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 (<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>"|/<regexp>/[i]) [, <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>.

save <hash key>

(use in combination with hook)

saves the value of <hash key> 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 <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

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.

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

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:

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

Download macro plugin version 2.0.2 for OpenKore/VisualKore 2.0.5 and up ONLY
Download macro plugin version 1.3.5 for OpenKore/VisualKore 1.9.x to 2.0.0
Download macro plugin version 1.2.0 for OpenKore/VisualKore up to 1.6.9

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

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/

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.